Guia · Idempotência
Idempotência em APIs de SMS: como evitar duplicidade
Idempotência transforma repetição de transporte em recuperação do mesmo comando. A chave deve representar a intenção do negócio, não cada tentativa de rede.
Escolha uma chave ligada à intenção
Combine um identificador estável do evento com o propósito da mensagem, como order-123-confirmation. Não use um UUID novo a cada retry, porque isso cria comandos diferentes para a API.
Repita exatamente o mesmo comando
Depois de um timeout, preserve destino, corpo, tipo, metadados e chave. Se precisar alterar o conteúdo, trate como outra intenção e avalie se o envio anterior pode ter ocorrido.
Detecte reutilização incompatível
O servidor deve vincular a chave a uma representação estável do comando. A mesma chave com conteúdo diferente precisa falhar com conflito, em vez de aceitar silenciosamente uma mutação.
Idempotência também no consumidor de webhook
Provedores e filas podem entregar o mesmo evento mais de uma vez. Persista event_id antes de aplicar efeitos e responda sucesso para eventos já processados quando o conteúdo for compatível.