Integração de sistemas na operação: quando usar API, arquivo em lote ou acesso ao banco

Toda operação que cresce chega ao mesmo ponto: o sistema de campo não conversa com o financeiro, o cadastro de clientes vive em três lugares com três versões diferentes e alguém, todo mês, exporta uma planilha de um lado para colar do outro. Essa pessoa é a integração da empresa. E ela tira férias, erra a coluna e um dia sai.

Integrar sistemas é substituir esse trabalho manual por uma troca combinada entre duas partes. A parte difícil raramente é a tecnologia. É decidir o que vai ser trocado, com que frequência, quem é dono de cada informação e o que acontece quando dá errado. Quem responde isso antes contrata bem. Quem deixa para depois descobre o custo na virada.

O que integrar significa (e o que não significa)

Integrar dois sistemas é fazer com que eles troquem informação de forma automática, sem digitação intermediária. É importante separar isso de duas coisas parecidas:

• Não é unificar sistemas. Integração mantém dois sistemas vivos, cada um com sua função. Se a intenção real é ter um só, o projeto é de substituição, não de integração, e a conversa muda inteira.
• Não é copiar tudo de um lado para o outro. Integração boa move o mínimo necessário para a decisão do outro lado. Copiar a base inteira "por garantia" cria duas fontes de verdade e, com dado pessoal, cria também exposição desnecessária.

O conceito que aparece nos documentos oficiais para esse tipo de troca é interoperabilidade. O portal Governo Digital resume o objetivo de forma direta ao descrever a política federal: "desonerar o cidadão de peregrinar entre órgãos para apresentar comprovantes". Troque "cidadão" por "sua equipe" e a frase descreve exatamente o que uma integração interna deveria resolver.

Onde as organizações brasileiras estão nessa conversa

Dois retratos ajudam a dimensionar o assunto, um do lado privado e outro do lado público.

No setor privado, a pesquisa TIC Empresas 2024, do Cetic.br (ligado ao NIC.br e ao CGI.br), mediu quantas empresas usaram pacotes de software do tipo ERP para integrar dados e processos de seus departamentos em um sistema único nos doze meses anteriores. O resultado geral foi de 34% das empresas, com forte diferença por porte: 30% entre as de 10 a 49 pessoas ocupadas, 59% entre as de 50 a 249 e 72% entre as de 250 ou mais. A leitura honesta desses números não é "a maioria não integra nada": é que, quanto menor a empresa, maior a chance de que a integração ainda seja uma pessoa copiando dados entre telas.

No setor público federal, a Lei nº 14.129/2021, conhecida como Lei do Governo Digital, colocou "a interoperabilidade de sistemas e a promoção de dados abertos" entre as diretrizes do governo digital. O braço operacional dessa diretriz é o programa Conecta gov.br, descrito pelo próprio governo como um programa que "promove a troca automática e segura de informações entre os sistemas" para que o cidadão não precise reapresentar dados que a administração já tem. Em sua página oficial, o programa divulga números acumulados de economia e de transações processadas na casa dos bilhões, o que dá a escala do que se ganha quando a conferência manual deixa de existir.

Aqui vale uma distinção que evita expectativa errada: o Conecta gov.br atende órgãos da administração pública federal, com acesso limitado para entes estaduais em alguns conjuntos de dados. Empresas privadas e cidadãos não consultam o barramento diretamente. O que serve de referência para todo mundo é o modelo, não o acesso.

Os quatro caminhos e quando cada um faz sentido

Na prática, quase toda integração cabe em um destes quatro formatos, ou em uma combinação deles. A escolha não é questão de gosto: depende de frequência, volume e de quanto o outro lado se dispõe a garantir.

Uma regra prática que funciona bem: API para pouco e agora, arquivo para muito e depois, evento para reagir, banco só em último caso. Se alguém propõe puxar milhões de registros por API de página em página todo dia, o que está sendo feito é um arquivo em lote pelo caminho mais caro. Se alguém propõe um arquivo diário para validar um cadastro na hora do atendimento, a resposta vai chegar sempre um dia atrasada.

Cinco perguntas antes de aprovar qualquer integração

Estas são as perguntas que separam um projeto de integração de uma promessa de integração. Nenhuma delas é técnica a ponto de o gestor não poder fazer.

1. Qual é a chave que liga os dois lados?

Integração é, antes de tudo, um acordo sobre identidade. Se um sistema identifica a empresa por CNPJ e o outro por um código interno, alguém precisa manter a tabela que liga os dois. Sem chave definida, a integração vira um exercício de casar nome e endereço, que erra sempre em algum percentual e cria duplicidade. Discutimos esse ponto em detalhe ao tratar de como usar CNPJ e CNAE na gestão.

2. Com que frequência e em qual janela?

"Em tempo real" é a resposta mais cara e quase nunca a necessária. Pergunte qual decisão depende do dado e em quanto tempo ela é tomada. Se o relatório é semanal, uma carga diária já é folga. Defina também a janela: um arquivo que chega às 6h resolve a operação que começa às 8h e não resolve a que começa às 5h.

3. Qual o volume esperado e qual o limite do outro lado?

Toda API tem limite de chamadas, e todo canal de arquivo tem limite de tamanho. Levante o volume no pico, não na média, e confirme o limite por escrito. Integração que funciona em teste com cem registros e falha em produção com cem mil é um dos motivos mais comuns de projeto atrasado.

4. O que acontece quando um registro falha?

Esta é a pergunta que quase ninguém faz e que define se a integração é confiável. Registro rejeitado fica parado onde? Alguém é avisado? Dá para reenviar só o que falhou, sem duplicar o que já passou? Um canal que aceita 99% e perde 1% em silêncio produz, em poucos meses, uma base que ninguém confia mais.

5. Quem avisa quem quando algo muda?

Layouts mudam, versões de API são descontinuadas, campos ganham novos valores. O que precisa estar combinado é o aviso: quem comunica, com quanto tempo de antecedência e por qual canal. Sem isso, a primeira notícia da mudança é o erro em produção.

O que costuma quebrar depois da virada

A integração raramente falha no dia da entrega. Ela falha semanas depois, por motivos repetitivos:

• Premissa sobre o formato de um identificador. É o exemplo mais atual no Brasil: a Receita Federal instituiu o CNPJ alfanumérico pela Instrução Normativa RFB nº 2.229/2024, com atribuição às novas inscrições a partir de julho de 2026, mantendo válidos os números já existentes. Qualquer campo, validação ou relatório que assuma que CNPJ é sempre um número passa a recusar cadastros legítimos. Vale a pena revisar onde a sua operação faz essa suposição.
• Formato de data e fuso. Um lado grava a data local, o outro grava em fuso universal, e o relatório do dia 1º aparece com movimentos do dia 31.
• Codificação de caracteres. Acentos que viram símbolos estranhos no arquivo é sintoma de encoding não combinado, e costuma aparecer só quando um nome com cedilha entra na base.
• Reenvio sem controle. Quando o canal cai e a remessa é enviada de novo, sem uma marca que identifique o registro já processado, o resultado é duplicidade em massa.
• Ninguém olhando. Sem um painel simples com enviados, aceitos e rejeitados por dia, a falha é descoberta por reclamação.

Repare que nenhum desses itens é resolvido por escolher a ferramenta "certa". Todos são resolvidos por combinar antes e registrar depois, que é a mesma lógica que sustenta a governança de atividades dentro da operação.

Dado pessoal muda a conversa

Quando a troca envolve dados pessoais, a pergunta deixa de ser apenas "como integrar" e passa a incluir "com qual finalidade e por quanto tempo". A própria política federal de interoperabilidade condiciona o compartilhamento de dados pessoais ao ambiente seguro e à observância da Lei Geral de Proteção de Dados.

Na prática, isso se traduz em três decisões concretas no desenho da integração: enviar só os campos necessários para a finalidade declarada, definir por quanto tempo o destino guarda o que recebeu, e registrar quem acessou o quê. Vale a leitura complementar sobre o que a LGPD muda no registro de dados em campo, porque os mesmos princípios se aplicam ao dado que trafega entre sistemas.

Por onde começar sem virar projeto de um ano

Integração não precisa nascer completa. Um caminho que costuma funcionar:

• Escolha uma dor com nome. "Ninguém digita mais o cadastro do cliente duas vezes" é um escopo. "Integrar os sistemas" não é.
• Comece pelo sentido único. Um lado envia, o outro recebe. Troca nos dois sentidos dobra as regras de conflito e é melhor deixar para a segunda etapa.
• Rode em paralelo antes de desligar o manual. Por algumas semanas, mantenha o processo antigo e compare os resultados. A divergência que aparecer nesse período é exatamente a regra que faltou combinar.
• Publique os três números. Enviados, aceitos e rejeitados, visíveis para quem opera, desde o primeiro dia.

Se a operação ainda depende de exportações manuais entre planilhas para funcionar, o problema anterior à integração pode ser outro: a ausência de um sistema de registro único. Tratamos dos sinais desse ponto na matéria sobre quando a planilha já passou do ponto.