Integração de sistemas: API, fila ou arquivo? Como escolher
Quando integrar sistemas por API, por fila de mensagens ou por troca de arquivos, e os cuidados que evitam pedidos duplicados e dados perdidos.
5 min de leitura
Integração de sistemas é o tipo de projeto que parece pequeno no começo (“é só chamar a API deles”) e vira o maior foco de incidentes depois. Pedido duplicado, nota fiscal que não chegou, estoque que diverge entre o ERP e a loja: quase sempre a causa está em como a integração foi desenhada, não na tecnologia escolhida.
A primeira decisão é o meio de transporte: API, fila de mensagens ou arquivo. Cada um resolve um problema diferente.
API: quando a resposta precisa ser imediata
Numa integração por API, um sistema chama o outro e espera a resposta na hora. É o modelo mais conhecido e o certo quando quem chama precisa do resultado para continuar.
Bons usos:
- Consultar o preço ou o estoque no momento da compra.
- Validar um CPF, um CEP ou um cartão antes de seguir.
- Autorizar um pagamento.
O ponto fraco: os dois sistemas precisam estar no ar ao mesmo tempo. Se o outro lado estiver lento ou fora, o seu sistema fica lento ou fora junto. Por isso toda chamada de API precisa de timeout curto, novas tentativas com intervalo crescente e um plano para quando a resposta não vier.
Fila de mensagens: quando o importante é não perder nada
Na fila, um sistema publica uma mensagem (“pedido 123 criado”) e segue a vida. O outro consome quando puder. Os dois não precisam estar disponíveis no mesmo instante.
Bons usos:
- Avisar o ERP, o financeiro e a logística de que um pedido foi criado.
- Processar tarefas pesadas sem travar a tela do usuário (gerar PDF, enviar e-mail).
- Absorver picos: a fila acumula e o consumidor processa no próprio ritmo.
O preço é a complexidade operacional: é mais uma peça de infraestrutura para manter (RabbitMQ, Amazon SQS, Kafka, entre outras), e o resultado deixa de ser imediato. Quem publicou não sabe na hora se deu certo.
Arquivo: quando o parceiro só fala essa língua
Trocar arquivos (CSV, XML, CNAB de banco, planilhas num SFTP) parece antiquado, mas continua sendo o padrão em vários setores. É a escolha certa quando:
- O outro lado só oferece essa opção, como muitos bancos e órgãos públicos.
- O volume é grande e não precisa ser em tempo real, como uma conciliação diária.
- A integração é com um sistema que não tem API nenhuma.
Os riscos são conhecidos: arquivo pela metade, processado duas vezes, com formato que mudou sem aviso. Tudo isso se resolve com validação na entrada e controle de quais arquivos já foram processados.
Comparando lado a lado
| Critério | API | Fila | Arquivo |
|---|---|---|---|
| Resposta | Imediata | Assíncrona | Em lote |
| Se o outro lado cair | Você é afetado | A fila segura | Processa depois |
| Volume alto | Exige escala dos dois lados | Absorve picos | Lida bem |
| Complexidade | Baixa | Média | Baixa a média |
| Rastreabilidade | Logs das chamadas | Mensagens na fila | O próprio arquivo |
Os cuidados que valem para qualquer modelo
O meio de transporte importa menos do que estes quatro cuidados. São eles que separam uma integração que funciona de uma que gera incidente toda semana.
Idempotência
Em algum momento a mesma mensagem vai chegar duas vezes: uma nova tentativa depois de um timeout, um arquivo reenviado, uma fila que entregou de novo. A integração precisa reconhecer que já processou aquilo e não fazer de novo. Na prática, cada operação carrega um identificador único, e o sistema que recebe guarda os que já viu.
Sem isso, nova tentativa vira pedido duplicado, cobrança duplicada ou estoque baixado duas vezes.
Novas tentativas com limite
Falhas temporárias acontecem. Tente de novo, com intervalos crescentes (1 segundo, depois 5, depois 30). Mas defina um limite: depois de algumas tentativas, a mensagem vai para uma fila de erros onde alguém consegue ver, corrigir e reprocessar. Tentar para sempre só esconde o problema.
Contrato explícito
Documente o formato exato do que é trocado: campos, tipos, o que é obrigatório e o que acontece com valor inválido. Quando o contrato muda, a mudança precisa ser compatível com a versão anterior ou anunciada com antecedência. Boa parte dos incidentes de integração começa com “eles mudaram o formato e ninguém avisou”.
Observabilidade
Você precisa conseguir responder, em minutos, perguntas como “o pedido 123 chegou no ERP?” e “quantas mensagens falharam hoje?”. Isso exige:
- Um identificador de correlação que acompanha a operação por todos os sistemas.
- Logs de cada etapa, com esse identificador.
- Alertas quando a fila de erros cresce ou quando o volume cai de repente.
Como decidir no seu caso
Uma regra prática para começar:
- Quem chama precisa da resposta para continuar? Use API.
- O importante é garantir que a informação chegue, mesmo com atraso? Use fila.
- O parceiro só oferece arquivo, ou o processo é diário por natureza? Use arquivo, com validação e controle de reprocessamento.
E, qualquer que seja a escolha, implemente idempotência, novas tentativas com limite, contrato explícito e observabilidade desde o primeiro dia. Adicionar isso depois, com a integração já em produção, custa bem mais.