Em um setor onde cada mensagem não entregada representa perda financeira direta para o cliente, a startup brasileira AraraHQ desenvolveu uma arquitetura de proteção que está chamando a atenção do mercado de APIs de comunicação. A empresa, que oferece uma API para WhatsApp Business, enfrentou o desafio crítico de garantir que seus clientes nunca perdessem dinheiro quando ocorressem falhas no pipeline de envio de mensagens.
O problema do pré-pagamento em APIs de mensageria
O modelo de negócios baseado em carteira virtual (wallet) com pré-pagamento cria um cenário de risco elevado para os clientes. No fluxo típico de envio de mensagens via API, primeiro ocorre a cobrança dos créditos do cliente, e somente depois a mensagem passa por diversas etapas até a entrega final. Qualquer falha após a cobrança — seja na fila de processamento, na comunicação com provedores como Twilio, ou na entrega pela Meta — resulta em prejuízo direto para quem contratou o serviço.
“Em uma API de mensageria, isso acontece em escala — milhares de mensagens por dia”, explica o fundador da AraraHQ. “Se você cobrou e não entregou, o cliente perdeu dinheiro. E essa perda não é insignificante quando se trata de comunicações empresariais críticas.”
A arquitetura de três camadas de proteção
A solução implementada pela AraraHQ consiste em um sistema de “checkpoints de estorno” distribuídos ao longo de todo o pipeline de envio. Cada ponto de falha potencial recebe uma camada específica de proteção, garantindo que o cliente seja reembolsado automaticamente sempre que a entrega não puder ser completada.
Primeira camada: falhas na publicação na fila
A primeira linha de defesa ocorre imediatamente após a cobrança inicial. Quando o sistema tenta publicar a mensagem na fila SQS (Simple Queue Service da Amazon) e encontra problemas — como fila cheia, payload inválido ou timeout — o estorno acontece em tempo real. O worker que recebeu a requisição HTTP original detecta a exceção e aciona o serviço de carteira para devolver os créditos antes mesmo que a mensagem entre no fluxo principal de processamento.
“Essa camada lida com falhas que ocorrem nos primeiros milissegundos após a cobrança”, detalha o desenvolvedor. “São erros que impedem a mensagem de sequer entrar no pipeline, então o estorno precisa ser imediato e automático.”
Segunda camada: falhas no envio ao provedor
A segunda camada é mais sofisticada e exige inteligência na classificação de erros. Quando o worker SQS pega a mensagem da fila e tenta enviá-la ao provedor (Twilio, que depois encaminha à Meta), diferentes tipos de falhas exigem comportamentos distintos. Erros fatais, como templates inválidos ou variáveis faltando, recebem estorno imediato sem novas tentativas. Erros transitórios, como timeouts de rede, também geram estorno, mas permitem retentativas automáticas.
“A distinção entre TwilioFatalException e Exception genérica é o que evita um loop infinito de retry em erros que nunca vão funcionar”, explica o arquiteto do sistema. “Classificar corretamente os erros é fundamental para a eficiência do pipeline e para a experiência do cliente.”
Terceira camada: falhas reportadas pelo webhook de status
A camada mais complexa lida com falhas que só são descobertas minutos ou até meia hora após o envio aparentemente bem-sucedido. Quando o webhook de status retorna com “failed” porque o número não existe, a Meta recusou o template ou o destinatário bloqueou a conta, o sistema precisa estornar valores de forma assíncrona.
“Essa é a mais traiçoeira”, admite o desenvolvedor. “A mensagem já saiu do pipeline principal, foi aceita pelo Twilio, mas falhou na etapa final. O estorno acontece quando o webhook chega, e só se aplica a mensagens em modo LIVE com custo associado.”
O desafio do estorno duplo e a solução de idempotência
Durante o desenvolvimento do sistema, um problema particularmente difícil emergiu: a possibilidade de estornos duplicados. Se a camada 2 estorna por timeout, mas o Twilio realmente recebeu e processou a mensagem, e depois o webhook retorna com “delivered”, o cliente receberia dinheiro de graça. O inverso também era possível — estorno na camada 2 seguido por estorno na camada 3 para a mesma falha.
A solução implementada foi um mecanismo de idempotência baseado no messageId. O serviço de carteira verifica se já existe um estorno registrado para aquela mensagem específica antes de processar qualquer nova solicitação de reembolso.
“Idempotência em tudo que envolve dinheiro é não negociável”, enfatiza o fundador. “Webhooks podem chegar duplicados, workers podem reprocessar, timeouts mentem. O messageId como chave de deduplicação salvou nosso sistema de billing.”
Auditoria e reconciliação financeira
Além do sistema de estornos, a AraraHQ mantém um PartnerLedger separado que registra todos os custos reais pagos aos provedores. Esta estrutura permite reconciliação financeira completa: “cobrei R$ X do cliente, paguei R$ Y pro Twilio, estornei R$ Z”. Qualquer discrepância nos números aciona alertas imediatos para a equipe de operações.
“Manter trilhas de auditoria separadas é essencial para detectar problemas antes que se tornem prejuízos reais”, explica o responsável pela infraestrutura financeira. “Se os números não batem, algo está errado no pipeline, e podemos investigar e corrigir rapidamente.”
Lições aprendidas e melhores práticas
A experiência da AraraHQ gerou aprendizados valiosos para qualquer empresa que opere APIs com modelo pré-pago. A primeira lição é óbvia, mas frequentemente negligenciada: se possível, cobre depois, não antes. Quando o modelo de negócios exige pré-pagamento, cada ponto de falha potencial precisa de um checkpoint de estorno.
A classificação inteligente de erros — distinguindo entre fatais e transitórios — muda completamente o comportamento do sistema e a eficiência do pipeline. Erros que nunca serão resolvidos com novas tentativas devem interromper o fluxo imediatamente, enquanto problemas temporários merecem retentativas automáticas.
Finalmente, a implementação rigorosa de idempotência em todas as operações financeiras é fundamental em sistemas distribuídos, onde mensagens podem ser duplicadas, processos podem falhar e retomar, e diferentes partes do sistema podem ter visões inconsistentes do estado de uma transação.
O sistema desenvolvido pela AraraHQ está em produção desde o início do ano e já processou milhões de mensagens, com uma taxa de estorno automático que protege integralmente os clientes contra perdas por falhas técnicas. A arquitetura serve como modelo para outras empresas que enfrentam desafios similares em APIs de pagamento pré-pago, demonstrando que é possível conciliar eficiência operacional com proteção financeira completa para o usuário final. Em um mercado onde a confiança é o ativo mais valioso, sistemas como este não são apenas técnicos — são fundamentais para a sustentabilidade do negócio.
