O problema real de integração não é técnico
Conectar dois sistemas via HTTP é trivial. Qualquer desenvolvedor faz em uma tarde.
O que separa uma integração que funciona de uma que dá dor de cabeça por anos é o que acontece quando algo dá errado — e algo sempre dá errado:
- O parceiro fica 40 segundos sem responder e sua requisição estoura o timeout. O pedido foi criado do outro lado ou não?
- O webhook chega duas vezes porque o parceiro não recebeu seu 200 a tempo. Você cobrou o cliente duas vezes?
- Chega o evento de “pagamento confirmado” antes do evento de “pedido criado”. Seu sistema aceita ou rejeita?
- O parceiro muda um campo de string para inteiro sem avisar. Sua integração quebra em silêncio às 3h da manhã.
Esses casos são a integração. O caminho feliz é 20% do trabalho.
Como construímos
Idempotência por padrão
Todo endpoint que causa efeito colateral — criar pedido, lançar cobrança, dar baixa em estoque — aceita uma chave de idempotência. Se a mesma chave chegar de novo, devolvemos o resultado original em vez de executar de novo. Isso transforma retry de risco em segurança.
Fila entre receber e processar
Webhook recebido não é webhook processado. Recebemos, validamos a assinatura, gravamos e respondemos 200 imediatamente. O processamento acontece em worker separado, com retry controlado. O parceiro nunca fica esperando sua regra de negócio rodar.
Contrato antes do código
Publicamos a especificação OpenAPI e um sandbox antes de implementar. O time do outro lado começa a integrar em paralelo, e as divergências de entendimento aparecem em uma reunião de trinta minutos em vez de em duas semanas de retrabalho.
Log que responde pergunta de negócio
Log de integração não serve para desenvolvedor. Serve para o atendimento responder “o que aconteceu com o pedido 48291?” sem abrir chamado. Estruturamos o log com identificador de correlação para que essa consulta leve dez segundos.
Cenários que já resolvemos
- Processamento de transações e integração com gateways em plataforma de pagamento de alta disponibilidade
- Sincronização de catálogo e disponibilidade entre sistema interno e portais externos no mercado imobiliário
- Integração com sistemas de terceiros em plataformas de proteção veicular
- Monitoramento e rastreamento de peças integrando chão de fábrica e sistema de controle de produção na indústria automotiva
- APIs de consulta e verificação em sistemas do setor público