Idempotência

Redes falham. Esta página mostra como repetir uma chamada sem enviar a mesma mensagem duas vezes nem cobrar duas vezes.

Operações pagas: a cotação é de uso único

Cada cotação (quoteId) executa no máximo uma operação:

• Repetir a mesma chamada com o mesmo quoteId não dispara de novo nem cobra de novo.
• Usar o quoteId com um request diferente falha com 409 BILLING_QUOTE_MISMATCH (ou BILLING_IDEMPOTENCY_CONFLICT se ela já foi usada).
• Para enviar de novo de propósito, peça outra cotação.

Na prática, o quoteId funciona como chave de idempotência dos envios, campanhas, aquecimento e IA.

Respostas pelo atendimento: idempotency_key

SendConversationMessage aceita idempotency_key (8 a 128 caracteres ASCII). Repetir a mesma chave nunca reenvia; a mensagem fica registrada com essa chave no histórico (InboxMessage.idempotency_key), o que permite conferir depois. Gere um valor por mensagem (ex.: UUID) e reutilize-o nas novas tentativas.

curl -X POST "https://api.zynzap.com.br/v1/rpc/SendConversationMessage" \
  -H "Authorization: Bearer $ZYNZAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "request": {
    "conversation_id": "5f0e1d2c-3b4a-4596-8877-66554433aa11",
    "session_id": "8c1f7a52-4d1e-4b8a-9a43-2f6f5d0c9e11",
    "message_type": "text",
    "text": "Seu pedido foi aprovado!",
    "idempotency_key": "pedido-1234-aprovado"
  },
  "billing": {
    "quoteId": "0b8f2c1e-3a4d-4e5f-8a9b-1c2d3e4f5a6b"
  }
}'

Quando o resultado é incerto

Se um envio terminar com 503/504 e reason: OUTCOME_UNCERTAIN ou RPC_DEADLINE_EXCEEDED:

1. Não repita com uma cotação nova logo de cara.
2. Consulte o estado: ListMessages da conversa ou aguarde MessageSent/MessageStatusUpdated nos eventos.
3. Só se não houver registro, peça outra cotação e envie.

Demais operações

• Leituras (List*, Get*) podem ser repetidas à vontade.
• Alterações absolutas (UpdateContact, SetConversationStatus, SaveCrmTask com id) também: aplicar duas vezes dá o mesmo resultado.
• Criações (CreateContact, CreateCrmOpportunity, CreateGroup) podem duplicar. Antes de repetir, procure o item (ListContacts com search, por exemplo) ou trate o conflito (CONTACT_ALREADY_EXISTS).
• Operações com versão (AssignConversation com assignment_version, SaveDialogTree com revision) recusam alterações sobre um estado antigo com 409: releia e refaça.

Eventos repetidos

Webhooks são entregues pelo menos uma vez e o stream pode reenviar eventos após reconectar. Use o id do evento (cabeçalho X-Zynzap-Event-Id) para ignorar o que você já processou, e o cursor para ordenar.