Idempotência

Redes falham. Às vezes o seu servidor manda a requisição, a TopTalking envia a mensagem, mas a resposta se perde no caminho. Se você simplesmente repetir, o cliente recebe a mensagem duas vezes.

O cabeçalho Idempotency-Key resolve isso: ele identifica a operação, e repetições com a mesma chave não são executadas de novo.

Como funciona

Envie Idempotency-Key: <um valor único> em requisições POST (é opcional).
Se a mesma chave chegar de novo com o mesmo corpo em até 24 horas, a API devolve a resposta original guardada, sem executar a ação de novo.
Se a mesma chave chegar com um corpo diferente, a API responde 409 com o código idempotency_conflict.
O valor pode ter até 255 caracteres. Depois de 24 horas, a chave pode ser reutilizada.

curl https://platform.toptalking.com.br/v1/messages \
  -H "Authorization: Bearer $TOPTALKING_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1234-saiu-para-entrega" \
  -d '{ "to": "5511999998888", "text": "Seu pedido #1234 saiu para entrega." }'

await fetch('https://platform.toptalking.com.br/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}`,
    'Content-Type': 'application/json',
    // Mesmo pedido + mesmo evento = mesma chave, em qualquer retentativa.
    'Idempotency-Key': `pedido-${pedido.id}-saiu-para-entrega`,
  },
  body: JSON.stringify({
    to: pedido.telefone,
    text: `Seu pedido #${pedido.id} saiu para entrega.`,
  }),
});

Como escolher a chave

A chave deve representar a intenção, não a tentativa:

Situação	Boa chave	Evite
Aviso de pedido despachado	`pedido-1234-despachado`	Um UUID novo a cada tentativa (não protege nada)
Boas-vindas a um lead do formulário	`lead-<id do lead>-boas-vindas`	O horário atual
Lembrete agendado de consulta	`consulta-987-lembrete-24h`	A mesma chave para clientes diferentes (gera `409`)
Fluxo do n8n com retentativa	`n8n-<id da execução>-<índice do item>`	Uma chave fixa para todo o fluxo

Se a sua operação não tem um ID natural, gere um UUID uma vez, guarde junto com a tarefa e reutilize-o em todas as tentativas.

Quando usar

Sempre em POST /messages e POST /scheduled-messages feitos por automações, filas ou agentes de IA — eles costumam repetir chamadas quando algo demora.
Em POST /contacts e POST /webhooks, quando o seu código faz retentativas automáticas.