Idempotência

Rede cai. Para poder repetir um pedido sem duplicar, mande o cabeçalho Idempotency-Key com um valor único por operação (o id do pedido no seu sistema, por exemplo). Em POST /mensagens, ele é obrigatório; você pode usar id_cliente (UUID) no corpo no lugar do cabeçalho.

Mesma chave e mesmo corpo em até 7 dias para envios (24 horas para outras operações): devolvemos a primeira resposta, com Idempotent-Replayed: true e Idempotent-Replayed-At, e nada é feito de novo. Depois do prazo, o mesmo identificador de mensagem ainda impede novo envio.
Mesma chave com corpo diferente: 409 idempotencia_conflito. Use uma chave nova para um pedido novo.
A chave tem de 1 a 200 caracteres visíveis, sem espaço (422 idempotencia_invalida).
A chave vale para a organização inteira (todas as chaves de API) e para uma operação só. Reaproveitar a mesma chave em outra rota também dá 409 idempotencia_conflito. Com mais de uma integração, use um prefixo por integração (erp-pedido-4821).

repetir com segurança

curl -X POST "https://chat.forsi.com.br/api/v1/mensagens" \
  -H "Authorization: Bearer $FORSI_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4821" \
  -d '{
    "telefone": "+55 31 98888-7777",
    "tipo": "texto",
    "texto": "Olá! Sua consulta está confirmada para amanhã às 9h."
  }'

Rotas que aceitam Idempotency-Key#

Rota	Operação
`POST /mensagens`	Enviar mensagem
`POST /contatos`	Criar contato
`POST /webhooks`	Criar webhook
`POST /webhooks/{id}/rotacionar`	Trocar o segredo
`POST /webhooks/{id}/testar`	Mandar um evento de teste
`POST /webhooks/entregas/{id}/reenviar`	Reenviar uma entrega
`POST /funis`	Criar funil
`POST /etapas`	Criar etapa
`POST /negocios`	Criar negócio
`POST /negocios/{id}/mover`	Mover para outra etapa
`POST /negocios/{id}/ganhar`	Marcar como ganho
`POST /negocios/{id}/perder`	Marcar como perdido
`POST /negocios/{id}/reabrir`	Reabrir negócio
`POST /negocios/{id}/notas`	Anotar no negócio
`POST /agendas`	Criar agenda
`POST /compromissos`	Marcar compromisso
`POST /compromissos/{id}/remarcar`	Remarcar compromisso
`POST /bloqueios`	Criar bloqueio
`POST /equipe/convites`	Convidar atendente
`POST /equipe/convites/{id}/reenviar`	Reenviar convite
`POST /equipe/equipes`	Criar equipe
`POST /conversas/{id}/atribuir`	Atribuir ou transferir conversa
`POST /regras-comentario`	Criar regra de comentário
`PATCH /regras-comentario/{id}`	Editar regra de comentário

As demais escritas são naturalmente seguras de repetir (atualizar com o mesmo valor, cancelar duas vezes) ou dão 409/404 na segunda vez.