Pular para o conteúdo

Novo: Diagnóstico técnico da sua arquitetura em 2 semanas. Saiba mais

Integrações Escaláveis

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:

  1. Quem chama precisa da resposta para continuar? Use API.
  2. O importante é garantir que a informação chegue, mesmo com atraso? Use fila.
  3. 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.

Continue lendo

Artigos relacionados