O que é idempotência em APIs
Uma operação é idempotente quando repeti-la tem o mesmo efeito que fazê-la uma vez. Em APIs, isso se consegue com uma chave de idempotência: o cliente manda o mesmo identificador em cada tentativa e o servidor reconhece a repetição em vez de executar de novo.
Atualizado em
Idempotência é a propriedade de uma operação que pode ser repetida sem mudar o resultado além da primeira vez. Consultar um pedido é naturalmente idempotente: pode consultar dez vezes que nada muda. Enviar uma mensagem, não: cada repetição é uma mensagem a mais no celular do cliente. Uma API idempotente oferece um jeito de repetir esse tipo de chamada com segurança.
Por que repetições acontecem
Em sistemas reais, a mesma requisição é enviada mais de uma vez com frequência, e quase nunca por descuido:
- Timeout. O servidor recebeu e processou o pedido, mas a resposta não chegou a tempo. Para o seu sistema, a chamada falhou.
- Retentativa automática. O cliente HTTP ou a fila de jobs tenta de novo depois de um erro de rede.
- Job reprocessado. Um worker cai no meio do processamento e o job volta para a fila.
Nos três casos, o seu sistema não tem como saber se a primeira tentativa funcionou. Sem idempotência, a escolha é ruim: não tentar de novo e arriscar perder a mensagem, ou tentar e arriscar duplicá-la.
Chave de idempotência
A solução mais comum é a chave de idempotência: um identificador que o cliente gera uma vez por operação e repete em todas as tentativas daquela operação. O servidor guarda as chaves já vistas; quando a mesma chave chega de novo, devolve o resultado original em vez de executar outra vez.
Na apiwpp, essa chave é o campo clientRef do envio, com até 200 caracteres. Use algo que já identifica a operação no seu sistema, como o id do pedido:
curl -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/send \
-H "Authorization: Bearer $APIWPP_KEY" \
-H "Content-Type: application/json" \
-d '{ "to": "5511988887777", "message": "Pedido 1042 confirmado!", "clientRef": "pedido-1042-confirmacao" }'
A primeira chamada responde 202 com jobId, scheduledAt e position. Se o seu sistema repetir a chamada com o mesmo clientRef, a resposta é 200 com o job original e "duplicate": true, e nada novo entra na fila. A chave fica reservada por 7 dias.
Exemplo: o timeout que não duplica
Imagine a confirmação do pedido 1042. O seu sistema chama /send, a apiwpp enfileira a mensagem, mas a conexão cai antes de a resposta chegar. O job do seu sistema falha e é reprocessado um minuto depois.
- Sem
clientRef: a segunda chamada enfileira outra mensagem, e o cliente recebe a confirmação duas vezes. - Com
clientRef: "pedido-1042-confirmacao": a segunda chamada devolve o job da primeira comduplicate: true. O cliente recebe uma mensagem só, e o seu sistema fica sabendo qual job acompanhar.
O mesmo clientRef volta nos eventos message.outgoing, message.delivery e message.send_failed do webhook, o que liga cada evento ao registro certo no seu banco. Se você quiser reenviar de propósito, gere um clientRef novo.
Idempotência vale também no caminho de volta: a entrega de webhooks é at-least-once, então o seu código deve ignorar eventos que já processou. Os detalhes estão em idempotência com clientRef e no post como evitar mensagens duplicadas no WhatsApp.
Perguntas frequentes
Qual valor usar como chave de idempotência?
Um identificador que já existe no seu sistema e é único por operação, como o id do pedido somado ao tipo da mensagem (pedido-1042-confirmacao). Evite gerar um valor aleatório a cada tentativa: assim a chave muda e a repetição deixa de ser reconhecida.
Por quanto tempo o clientRef protege contra duplicação?
Na apiwpp, cada clientRef fica reservado por 7 dias. Dentro desse prazo, qualquer repetição devolve o job original em vez de enfileirar outra mensagem.
Idempotência é o mesmo que evitar retentativas?
Não. A idempotência existe justamente para que você possa tentar de novo sem medo. Retente à vontade depois de um timeout ou erro de rede, desde que use a mesma chave em todas as tentativas.
Outros termos
Todos: Glossário →Webhook é uma chamada HTTP que um serviço faz para um endereço do seu sistema quando um evento acontece, como uma mensagem recebida. Em vez de perguntar de tempos em tempos se há novidades, o seu sistema é avisado na hora.
Aquecimento de número (ou de chip) é o período depois de conectar um WhatsApp em que os limites de envio começam baixos e sobem aos poucos, para o número ganhar histórico antes de chegar ao volume normal. Na apiwpp, ele dura 14 dias e é aplicado pela fila.
QR code de pareamento é o código que o celular escaneia para ligar o número de WhatsApp a um aparelho conectado, como o WhatsApp Web ou uma API. Ele muda a cada poucos segundos e pode ser trocado por um código de 8 caracteres.