Como integrar dois sistemas através de API

O pedido chega simples: “preciso ligar o sistema A no sistema B”. Na reunião seguinte aparecem formato diferente do documento, horário em que o B não responde, registro duplicado e a dúvida se o lote de ontem entrou ou não.

O problema

Cada sistema foi feito para o próprio processo. A ponte precisa traduzir dado, respeitar limite, confirmar recebimento e sobreviver a pico. Sem isso, a integração vira planilha no meio ou um cron que “às vezes funciona”.

Como funciona uma integração que aguenta produção

• Contrato claro para campos, autenticação e idempotência.
• Tempos de espera e novas tentativas com limites definidos.
• Filas quando o sistema de destino é mais lento que o de origem.
• Registros suficientes para rastrear cada identificador.
• Reprocessamento controlado dos dados que falharam.

API ou webhook?

API é você perguntar ou enviar quando precisa. Webhook é o outro sistema avisar quando algo aconteceu. Os dois falham em produção se ninguém tratou timeout, assinatura, ordem dos eventos e o que fazer com aviso duplicado. A escolha depende de quem é o dono do evento, não de qual palavra parece mais moderna.

Por que integrações falham em produção

No teste, cinco mensagens. Em produção, rajada. O banco trava na consulta que era “rápida”. O HTTP estoura o tempo. Quem enviou tenta de novo e cria duplicata. Quem recebeu processa duas vezes. Sem fila, sem idempotência e sem observabilidade, o sintoma vira “a API está instável” — quando o desenho é que não previa carga.

Experiência prática

Em projetos de rastreamento e coleta contínua, dispositivos não esperam o banco respirar. Chegam pacotes em volume, com documentação que não bate com o byte real, com modelo de equipamento diferente do esperado. Timeout mal dimensionado descarta o que deveria ir para reprocessamento. Fila mal dimensionada esconde o atraso até o cliente reclamar da posição. O conserto não é “subir a máquina”. É tratar ingestão, persistência e consulta como partes que falham de jeitos diferentes — e medir cada uma.

Erros comuns

• Integrar pelo banco direto porque “é mais rápido”.
• Assumir que o parceiro documentou o protocolo completo.
• Ignorar fuso, encoding e campo opcional que um dia vem preenchido.
• Não ter dono da integração depois do go-live.

Quando utilizar uma API nova em sistema existente

Quando o legado precisa falar com canal, IA, mobile ou outro ERP sem reescrever o núcleo de uma vez. A API é a costura. O sistema antigo continua; o mundo novo não precisa entrar pela porta dos fundos do banco.