Idempotência - Superlead

Falhas de rede acontecem: sua requisição pode ter chegado à Superlead mesmo que a resposta nunca tenha chegado a você. Sem proteção, repetir o envio duplicaria a mensagem para o lead. Para evitar isso, mande o header Idempotency-Key em POST /v1/whatsapp/messages com um valor único por operação (um UUID, ou o id da operação no seu sistema):

curl -X POST https://api.superlead.app/v1/whatsapp/messages \
  -H "Authorization: Bearer sk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-8734-confirmacao" \
  -d '{ "to": "+5511999999999", "type": "text", "text": { "body": "Pedido confirmado!" } }'

Comportamento

Situação	Resultado
Primeira requisição com a chave	Processada normalmente.
Repetição com a mesma chave e mesmo corpo	Retorna a mesma resposta original, sem enviar de novo.
Mesma chave com corpo diferente	`409 idempotency_conflict` — a chave identifica uma operação, não pode ser reutilizada.
Repetição enquanto a original ainda está em andamento	`409 idempotency_conflict` com header `Retry-After` — aguarde e repita.

As chaves de idempotência são escopadas por empresa e expiram em 24 horas. Depois disso, o mesmo valor é tratado como uma operação nova.
Respostas de erro determinísticas (4xx) também são memorizadas e repetidas no replay. Erros transitórios (5xx, falha de rede com o WhatsApp) liberam a chave, permitindo um retry real.

Recomendação

Derive a chave da operação de negócio, não do momento do envio: pedido-8734-confirmacao garante uma única mensagem de confirmação por pedido, mesmo que o seu fluxo rode duas vezes.