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/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/messages \
-H "Authorization: Bearer sl_live_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.