Idempotência

Repetir a chamada sem repetir o efeito.

O problema

Você manda POST /v1/messages. A rede cai antes da resposta chegar. Agora você não tem como saber se a mensagem saiu — e as duas escolhas são ruins: não reenviar pode perder o aviso, reenviar pode mandar dois. A segunda chega ao cliente final.

Como usar

Mande Idempotency-Key com um valor seu, único por operação. Repetir a mesma chamada devolve a mesma resposta, sem executar nada de novo.

Terminal

curl https://api.amivu.com.br/v1/messages \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Idempotency-Key: pedido-8291-saiu-para-entrega" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
    "type": "text",
    "text": "Seu pedido saiu para entrega."
  }'

A repetição vem com Idempotent-Replayed: true — assim o seu log distingue a primeira execução da repetição, mesmo com corpos idênticos.

Vale nas escritas: POST /v1/messages, POST /v1/contacts e POST /v1/conversations. A chave vale por 24 horas. POST /v1/uploads a ignora: o corpo multipart muda a cada tentativa, e subir de novo só cria outro anexo, que vence sem uso — a idempotência que importa é a do envio.

As três respostas

Situação	Resposta
Chave nova	Executa, guarda a resposta, devolve.
Chave conhecida, MESMO corpo	Devolve a resposta guardada, sem executar. É a repetição legítima.
Chave conhecida, corpo DIFERENTE	`409 idempotency_key_reuse`

Corpo diferente com a mesma chave não é repetição — é reúso, e adivinhar qual das duas intenções vale seria pior do que recusar.

Duas chamadas ao mesmo tempo

Se duas requisições com a mesma chave chegarem antes de qualquer uma terminar, a segunda recebe 409 idempotency_in_progress. É honesto: ela não sabe o resultado ainda, e executar de novo seria exatamente o que a idempotência existe para impedir. Tente de novo em instantes.

Chamada que falhou não guarda a chave. Retentativa depois de falha é justamente o caso em que ela precisa funcionar — o que a idempotência protege é o sucesso duplicado.

Escolhendo a chave

Use algo que descreva a operação, não a tentativa. Um UUID novo a cada tentativa não protege nada.

bom     pedido-8291-saiu-para-entrega
bom     contato-sync-customer_8291-2026-08-26
ruim    550e8400-e29b-41d4-a716-446655440000   (novo a cada tentativa)
ruim    mensagem                                (colide com tudo)

Ela é única por organização e aceita até 255 caracteres.

Escrevemos sobre operação de atendimento, canais e IA no blog da Amivu.