Fontes de dados e API

Como enviar registos para uma fonte de dados com a API do Sendtric

Última atualização

Com uma fonte de dados API, o teu próprio sistema envia registos JSON para o Sendtric sempre que os teus dados forem alterados. O Sendtric guarda-os como dados alojados e as tuas imagens consultam o registo de cada subscritor quando um e-mail é aberto.

Este guia destina-se a quem escreve o código que envia os dados. Se preferires que o Sendtric recupere os dados da tua API sempre que a página for aberta, consulta como ligar uma fonte de dados à tua própria API.

Cria a fonte de dados

  1. Na barra lateral esquerda, clica em Fontes de dadose, em seguida, Nova fonte de dados.
  2. Em API, escolhe API e clica em Continuar.
  3. Escolhe Enviar dados para a Sendtric e clica em Continuar.
  4. Preenche:
    • Nome da fonte de dados: por exemplo, «Membros do programa de fidelidade».
    • Campo de identificador único: o campo JSON que identifica cada registo, como customer_id ou email. Todos os registos que enviares têm de o incluir.
    • Descrição (opcional).
  5. Clica em Guardar fonte de dados. A fonte de dados é criada e a etapa da API mostra os teus endpoints e a tua chave API.
  6. Copia o que precisares e, depois, clica em Continuar para concluir.
A secção da API de uma nova fonte de dados, que mostra os pontos de extremidade para inserção/atualização de um único registo e em massa, a chave da API e exemplos de pedidos

Podes voltar a encontrar os endpoints a qualquer momento na guia «Detalhes da API» da fonte de dados.

Autenticar

Envia a tua chave no Authorization cabeçalho de cada pedido:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

A Chave da API da fonte de dados só serve para enviar registos da fonte de dados, por isso podes fornecê-la a um programador ou a uma ferramenta de automatização sem problemas. Se tiveres um plano de API, a tua chave de API atual também funciona nestes pontos de acesso.

Não coloques a tua chave no código front-end nem em repositórios públicos. Se alguma vez for exposta, regenera-a em Definições → Chaves de API → Chave API da fonte de dadose, em seguida, atualiza tudo o que a utiliza.

Criar ou atualizar registos

ENVIA um único objeto JSON, ou um conjunto de objetos, para o ponto de acesso indicado no Sendtric. Um registo:

POST <your data source endpoint>
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "customer_id": "CUST_1001",
  "first_name": "Sarah",
  "points": 1250
}

Vários registos numa única solicitação:

POST <your data source endpoint>
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

[
  { "customer_id": "CUST_1001", "first_name": "Sarah", "points": 1250 },
  { "customer_id": "CUST_1002", "first_name": "James", "points": 300 }
]

Como é que os registos são guardados:

  • Se ainda não existir nenhum registo com esse identificador, é criado um novo.
  • Se o fizeres, é substituído pelo que enviares. Os campos que não preencheres são removidos, por isso envia sempre o registo completo.
  • Os registos novos e atualizados ficam normalmente disponíveis em cerca de um minuto.
  • Os identificadores são comparados sem distinção entre maiúsculas e minúsculas.

Uma solicitação bem-sucedida devolve 200 um breve resumo, por exemplo {"status":"ok","records":2}.

Podes aninhar objetos dentro de um registo, por exemplo "address": { "city": "Leeds" }, e selecionar campos aninhados no editor de imagens.

Apagar registos

Apaga um registo adicionando o seu identificador ao final do endpoint:

DELETE <your data source endpoint>/cust_1001
Authorization: Bearer YOUR_API_KEY

Apaga vários enviando um conjunto de identificadores:

DELETE <your data source endpoint>
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

["cust_1001", "cust_1002"]

Limites

LimiteValor
Registos por pedido10 000
Tamanho do pedido10 MB
Valor do identificador255 caracteres
Qualquer valor de texto único10 KB
Profundidade de encaixe20 níveis

Envia os registos em lotes, em vez de fazeres um pedido por registo. Para milhares de registos, vê como enviar grandes quantidades de dados para uma fonte de dados.

Respostas e erros

EstadoO que isso significaO que fazer
200Registos aceitesNada. Se alguns registos foram ignorados, o cabeçalho «X-Skipped-Records» indica quantos
400O corpo da mensagem não é JSON válidoVerifica o corpo da solicitação
401Chave API em falta ou erradaVerifica o cabeçalho «Authorization»
404Não foi encontrada a fonte de dados para esta chaveVerifica o endpoint e se a chave pertence à mesma conta
413Demasiados registos ou demasiado grandesDividir o pedido em lotes mais pequenos
422Não foi possível guardar o registoA mensagem indica quais são os registos que não têm o campo de identificador ou que são demasiado grandes
503O Sendtric está ocupadoEspera o número de segundos indicado no cabeçalho «Retry-After» e, depois, envia a mesma solicitação outra vez

Quando apenas alguns registos de um pedido não são válidos, os válidos continuam a ser guardados e os restantes são ignorados.

Verifica os teus registos

Abre a fonte de dados e vai até à guia «Registos» . Faz uma pesquisa pelo valor do identificador e clica num registo para veres o JSON completo armazenado pelo Sendtric.

Próximo passo

Este artigo foi útil?

Clica na imagem para ampliar. Arrasta ou desliza para ver o resto.