Integração de sistemas: APIs, webhooks, filas e reconciliação

Empresas raramente operam em um único sistema. CRM, ERP, pagamentos, documentos, comunicação e ferramentas internas precisam compartilhar eventos e dados sem transformar pessoas em conectores manuais.

O desenho começa por uma pergunta: quem é responsável por cada dado e o que deve acontecer quando a outra ponta não responde?

API síncrona

Use chamada síncrona quando o fluxo precisa da resposta para continuar, como validar uma informação ou autorizar uma operação. Defina timeout, autenticação, limite de chamadas e comportamento de indisponibilidade.

Retentar automaticamente não é sempre seguro. Consultas podem repetir; comandos precisam de idempotência ou de uma forma de confirmar se foram aplicados.

Webhooks

Webhooks comunicam eventos sem consulta constante. O receptor deve:

1. preservar o corpo exigido pelo mecanismo de assinatura;
2. validar assinatura e origem antes de aceitar o evento;
3. registrar um identificador para detectar duplicidade;
4. persistir ou enfileirar o evento antes de confirmar quando a garantia do fluxo exigir;
5. processar fora da requisição se o trabalho for demorado;
6. manter histórico de falha e reprocessamento.

Responder rapidamente é importante, mas nunca deve acontecer antes das validações mínimas do protocolo e da durabilidade necessária.

Filas e workers

Filas ajudam a absorver picos, desacoplar indisponibilidade e aplicar retentativas. Elas não garantem por si só que um evento será processado exatamente uma vez.

Na prática, trate consumo repetido como possível. Use chaves idempotentes, estados transacionais ou padrões como outbox conforme a criticidade. Mensagens que excedem as tentativas precisam de fila de erro, alerta e procedimento de análise.

Sincronização em lote

Arquivos, exportações ou consultas periódicas continuam adequados quando a latência aceita é maior. Registre janela de sincronização, watermark, versão do formato e resultado de cada lote.

Não avance o marcador da última sincronização se parte do lote falhou sem uma estratégia explícita para recuperar os registros.

A fonte oficial precisa estar definida

Integrações bidirecionais criam conflito: os dois sistemas podem alterar o mesmo campo. Defina propriedade por entidade ou atributo, regra de precedência e tratamento de atualização concorrente.

Para cadastros de clientes, por exemplo, o CRM pode ser fonte de relacionamento enquanto o ERP é fonte fiscal. Uma visão consolidada não elimina essas responsabilidades.

Reconciliação é parte da arquitetura

Mesmo com eventos, compare periodicamente origem e destino. Reconciliação encontra mensagens perdidas, transformações incorretas e alterações manuais.

Registre pelo menos:

• identificador interno e externo;
• versão ou instante da origem;
• status e número de tentativas;
• erro classificado sem expor segredo ou dado sensível;
• próxima ação e responsável.

Observabilidade orientada ao processo

Além de latência HTTP, acompanhe:

• tempo desde o último evento concluído;
• idade e tamanho da fila;
• taxa de falha por tipo e parceiro;
• itens aguardando intervenção;
• divergências encontradas na reconciliação;
• tempo do evento de negócio entre origem e destino.

Uma integração pode responder 200 e ainda produzir dados errados. A métrica técnica precisa chegar ao resultado operacional.

Antes de estimar

Liste sistemas, responsáveis, documentação disponível, ambientes de teste, volumes, frequência, dados sensíveis e custo de uma falha. A calculadora de custo de integração ajuda a organizar variáveis, sem substituir a análise das APIs reais.

Conclusão

A conexão feliz costuma ser a menor parte do trabalho. Integrações duráveis explicitam contratos, duplicidade, indisponibilidade, reconciliação e quem age quando a automação não consegue seguir sozinha.