O pagamento foi aprovado, mas o pedido não mudou de status. Alguém tenta de novo e aparecem dois registros. Um projeto de integração precisa prever esse tipo de falha ao conectar duas APIs.
Ao avaliar a integração, teste o que acontece quando uma mensagem atrasa, se repete ou falha. Verificar apenas o caso em que tudo responde na hora não é suficiente.
Escolha quem manda em cada dado
Liste os campos que vão circular: cliente, pedido, valor, estoque e situação do pagamento. Para cada um, defina qual sistema mantém o registro principal e quem pode alterar a informação.
Se o comercial muda um endereço no CRM e o financeiro guarda uma cópia antiga, qual lado atualiza o outro? Sem essa decisão, uma sincronização nos dois sentidos pode ficar regravando alterações.
Guarde também os identificadores usados em cada sistema. O número do pedido no site pode ser diferente do código no ERP; a integração precisa reconhecer que ambos apontam para o mesmo pedido.
Avisos podem chegar de novo
Um webhook avisa outro sistema quando um evento acontece. Na documentação da Stripe, eventos podem ser entregues mais de uma vez e sua ordem não é garantida. A orientação inclui registrar eventos processados e verificar a assinatura recebida.
Essa é uma regra da Stripe, não uma promessa sobre qualquer fornecedor. Confira como cada plataforma entrega seus avisos. No seu aceite, peça um teste com repetição e outro com mensagens fora de ordem, observando o resultado de negócio.
O pedido deve continuar identificável mesmo depois de várias tentativas. Quem atende o cliente precisa enxergar o estado atual e saber se existe algo pendente.
Repetir sem cobrar duas vezes
Idempotência é conseguir repetir uma operação sem duplicar seu efeito. A API da Stripe aceita chaves de idempotência para tornar novas tentativas seguras em operações compatíveis.
Peça que o desenvolvedor explique como isso se aplica à ação que interessa: criar pedido, lançar recebimento ou enviar cobrança. A proteção precisa acompanhar o processamento do negócio; um aviso visual dizendo que o botão foi clicado não demonstra que a operação está protegida.
Inclua o teste em que o destino conclui a operação, mas a resposta não chega à origem. A nova tentativa deve reconciliar o resultado antes de criar outro registro.
Limites e falhas precisam aparecer
Uma API pode aplicar um limite de requisições. A MDN descreve o status HTTP 429 e o cabeçalho opcional Retry-After, que informa quanto esperar. Cada fornecedor define suas próprias regras.
Combine quais falhas serão tentadas novamente, qual espera será aplicada e quem será avisado quando a ação continuar pendente. Não deixe uma operação com erro parecer concluída na tela.
Peça uma rotina de conferência
No aceite, percorra um pedido normal, um repetido, uma falha temporária e uma rejeição que exige correção dos dados. Confira os registros em ambos os sistemas usando os identificadores combinados.
Peça uma lista de pendências e um procedimento para reprocessá-las sem duplicação. Os registros devem ajudar a localizar a falha sem expor senhas ou dados pessoais desnecessários. A integração estará pronta para operar quando alguém souber identificar e resolver um pedido parado, além de acompanhar os que deram certo.
Fontes
- Receive Stripe events in your webhook endpoint. Stripe. consultado em outubro de 2026.
- Idempotent requests. Stripe. consultado em outubro de 2026.
- 429 Too Many Requests. MDN Web Docs. consultado em outubro de 2026.