Redes não entregam certeza instantânea. Uma solicitação pode chegar duas vezes, uma resposta pode se perder e um webhook mais antigo pode ser processado depois do novo. Integração resiliente não tenta apagar essa realidade; identifica uma intenção única, limita repetição e reconcilia estado.
Para o operador, a diferença aparece na linguagem: “recebido” não é “concluído”. Para a arquitetura, aparece em chaves idempotentes, timestamps, timeouts, backoff, circuit breaker e evidência.
Em uma frase
Preserve uma única intenção através de tentativas e estados, confirmando o resultado no sistema responsável antes de anunciar sucesso.
O timeout que cria duas ordens
O sistema envia “criar ordem” e não recebe resposta. Se repetir com novo identificador, talvez crie outra. Se não repetir, talvez deixe a pessoa esperando por uma ação que já ocorreu. O erro é tratar ausência de resposta como prova de ausência de efeito.
Webhooks têm problema semelhante: o provedor repete até obter confirmação, e eventos podem chegar fora de ordem. Polling evita depender do evento, mas cria atraso e carga. A escolha precisa considerar contrato do provedor e consequência do processo.
Padrões públicos tornam a repetição previsível
A documentação da Stripe mostra um padrão concreto: uma chave identifica a criação ou alteração e tentativas seguintes retornam o resultado armazenado, evitando repetir o efeito. A retenção e a semântica são específicas da API, mas o conceito é geral.
A AWS recomenda limitar retries, usar backoff exponencial com jitter e não repetir erros previsivelmente permanentes. A documentação oficial da Meta observa que estados de mensagens podem chegar fora de ordem, devendo ser interpretados pelo timestamp.
Exemplo composto: confirmação de entrega
Uma motorista fictícia confirma entrega em área de sinal instável. O aplicativo associa uma chave à intenção e mostra “enviando”. A primeira chamada chega ao TMS, mas a resposta não volta. A repetição usa a mesma chave; o destino informa o registro já existente. Apenas então a interface mostra “confirmado”.
Se o TMS continua indisponível, o circuit breaker evita novas rajadas e o pedido expira conforme regra. A equipe recebe caminho de contingência, e a evidência distingue captura local, envio, execução e confirmação. O cenário é ilustrativo.
Escolha eventos, consultas e repetição pelo contrato
Webhook é adequado quando o provedor emite eventos e aceita reentrega; valide assinatura, deduplique e armazene posição. Polling serve quando não há evento ou para reconciliação, com intervalo e cursor. Em fluxos críticos, use ambos: evento acelera e consulta confirma.
Idempotência identifica efeito, não apenas requisição HTTP. Timeout precisa ser menor que a paciência do usuário e coerente com o destino. Retry só vale para falhas transitórias. Circuit breaker suspende chamadas a dependência degradada e volta de forma controlada. Dead letter guarda o que exige análise.
Casos que o teste deve forçar
- Mesma mensagem entregue duas vezes e com atraso.
- Resposta perdida depois de a ação ter sido concluída.
- Eventos de estados diferentes chegando fora de ordem.
- Erro permanente de permissão versus indisponibilidade transitória.
- Retorno do serviço após circuit breaker, fila acumulada e pedido expirado.
Como a Uiless ajuda
A Uiless mantém uma intenção e uma evidência através do canal, da aprovação e da chamada. Integrações usam idempotência, timeouts, retries controlados e circuit breaker, com diagnóstico no painel para diferenciar bloqueio, falha e estado desconhecido.
A pessoa recebe o estado operacional correto sem interpretar código HTTP. Isso permite conectar ERP, CRM, WMS, TMS e WhatsApp com padrões de resiliência reutilizados, em vez de implementar um comportamento diferente em cada bot.
Veja como desenhar rollback e fail-closed e por que uma boa mensagem de erro orienta recuperação.
