Como integrar um sistema legado que não tem API

Toda empresa com alguns anos de estrada tem um sistema que ninguém quer tocar e ninguém consegue desligar. Um ERP antigo em Delphi, um faturamento em Visual Basic no servidor da sala dos fundos. Ele funciona, carrega regras que só ele conhece e não fala com mais nada.

Aí o e-commerce precisa do estoque, o app dos vendedores precisa da tabela de preços, o financeiro quer um painel. E a primeira resposta é "esse sistema não tem API".

Não ter API não significa não ter integração. Significa que você vai precisar escolher a porta de entrada com mais cuidado. Este texto apresenta as técnicas em ordem crescente de risco e mostra como esconder o legado atrás de uma camada que entrega ao resto da empresa uma interface limpa.

O sistema antigo não vai sair tão cedo, e precisa conversar

Substituir o legado quase nunca é a solução imediata. Reescrever leva tempo, arrisca perder regras que ninguém documentou e raramente cabe no prazo da necessidade que apareceu agora. Discutimos esse dilema em detalhe no texto sobre reescrever ou refatorar um sistema legado.

Enquanto isso, o negócio continua. Então a pergunta prática é outra: como fazer o sistema antigo participar do ecossistema novo sem que ele caia, sem corromper dados e sem prender todo o resto às limitações dele?

Três perguntas orientam a escolha da técnica:

• Direção. Você só precisa ler do legado, ou também escrever nele (criar pedido, baixar título)? Leitura é muito mais segura que escrita.
• Frequência. Uma sincronização por noite resolve, ou o dado precisa chegar em segundos?
• Acesso. Banco de dados, arquivos gerados, código-fonte, fornecedor? Muitas vezes a técnica é decidida pelo que está disponível, não pelo que é ideal.

Se o sistema chegou até você sem documentação e sem ninguém que conheça o funcionamento interno, comece pelo levantamento descrito em herdou um sistema sem documentação. Integrar às cegas é a receita para descobrir as regras escondidas em produção.

Troca de arquivos: simples, antiga e muitas vezes suficiente

Muitos sistemas legados já exportam e importam arquivos: TXT de layout fixo, CSV, XML, planilhas. Era a forma padrão de conversar com banco, contabilidade e fisco.

A integração por arquivo é a de menor risco para o legado, porque usa um caminho que ele já oferece e que já foi testado por anos de uso. O sistema gera o arquivo numa pasta, um serviço de integração pega, valida, transforma e envia para onde precisa. No sentido contrário, o serviço deposita um arquivo no formato que o legado sabe importar.

Funciona bem quando:

• a sincronização pode ser periódica (de hora em hora, diária);
• o volume cabe em lote;
• o layout do arquivo é estável e conhecido.

Os cuidados que fazem a diferença entre uma integração por arquivo confiável e uma fonte de incidentes:

• Nunca leia um arquivo que ainda está sendo escrito. Use um arquivo de controle, renomeie ao final ou espere o tamanho estabilizar.
• Mova o arquivo processado para outra pasta, com registro de data e resultado. Reprocessar sem querer é um dos erros mais comuns.
• Valide antes de aplicar. Quantidade de linhas, campos obrigatórios, totais de controle. Arquivo pela metade tem que ser rejeitado inteiro.
• Guarde os arquivos originais por um período definido. Quando alguém perguntar "o que o legado mandou naquele dia", a resposta precisa existir.

Não é glamoroso, mas uma integração por arquivo bem feita roda anos sem ninguém lembrar que ela existe.

Ler direto do banco sem derrubar o sistema

Quando você tem acesso ao banco de dados do legado (SQL Server, Oracle, Firebird, PostgreSQL, às vezes até arquivos Paradox ou DBF), a tentação é conectar e ler. Funciona, mas tem armadilhas.

A primeira é performance. Uma consulta pesada no horário de pico pode travar o caixa ou o faturamento. Por isso a regra de ouro é: leitura de integração vai para uma réplica, não para o banco de produção. Se o banco suporta replicação, configure uma cópia de leitura. Se não suporta, programe as extrações para janelas de baixo uso e limite o volume por consulta.

A segunda é semântica. O banco não é a regra de negócio. Um pedido com status = 3 pode significar "faturado" em uma filial e "cancelado com estorno pendente" em outra, porque alguém reaproveitou o código anos atrás. Cada leitura precisa ser validada contra o que a tela do sistema mostra para o mesmo registro.

A terceira é acoplamento. Se dez sistemas leem diretamente as tabelas do legado, qualquer mudança de estrutura quebra os dez. Por isso a leitura deve ficar concentrada num único ponto, a camada de integração de que falamos adiante, e nunca espalhada.

Boas práticas para leitura direta:

• usuário de banco exclusivo para a integração, somente leitura, com acesso só às tabelas necessárias;
• consultas incrementais por data de alteração ou chave sequencial, em vez de ler tudo toda vez;
• registro de cada extração (quando rodou, quantos registros, quanto tempo levou);
• testes que comparam uma amostra do dado extraído com o que o sistema exibe.

Captura de mudanças: reagir ao que muda no legado

A leitura periódica tem um limite: ela descobre as mudanças com atraso e precisa perguntar "o que mudou desde a última vez?". Quando o legado não tem uma coluna confiável de data de alteração, essa pergunta nem tem resposta boa.

Captura de mudanças (CDC, de Change Data Capture) resolve isso lendo o próprio registro de transações do banco. Toda inserção, alteração e exclusão vira um evento, que é publicado numa fila. Ferramentas como Debezium fazem isso para vários bancos, e alguns bancos têm recursos nativos de captura de mudanças.

As vantagens são concretas:

• o dado chega em segundos, não em horas;
• o legado não precisa ser alterado, e a carga no banco é muito menor do que a de consultas repetidas;
• exclusões ficam visíveis, o que a leitura por data de alteração geralmente não captura.

Sem log de transações acessível, a alternativa são triggers que gravam as mudanças numa tabela de eventos. Funciona, mas mexe no banco do legado e adiciona carga a cada escrita.

O cuidado principal: os eventos refletem as tabelas, não o negócio. Uma venda pode alterar seis tabelas, em ordem nem sempre previsível. Montar a partir disso o evento que interessa ("pedido faturado") é trabalho da camada de integração, não dos consumidores.

Escrever no legado sem quebrar regras escondidas

Ler é seguro. Escrever é onde integrações com legado dão errado.

Quando um usuário cria um pedido pela tela, o sistema faz muito mais do que um INSERT na tabela de pedidos. Reserva estoque, calcula impostos, atualiza o limite de crédito, gera o número sequencial, grava histórico. Nada disso está visível. Se você grava direto na tabela, pula todas essas etapas e cria um registro que parece válido, mas deixa o sistema inconsistente.

A ordem de preferência para escrita:

1. Importação nativa. Se o legado importa arquivos de pedido, cadastro ou lançamento, use. É o caminho que passa pelas regras do sistema.
2. Procedimentos do próprio sistema. Muitos legados têm stored procedures que a própria aplicação chama. Descobrir e reaproveitar esses procedimentos é mais seguro do que reproduzir a lógica.
3. Procedimento controlado escrito para a integração, validado linha a linha contra o que a tela faz, com testes que comparam o resultado da gravação pela integração com o da gravação manual.
4. Automação de tela, como último recurso.

Automação de tela passa por todas as regras do sistema, porque usa a mesma interface do usuário. Em compensação, é frágil diante de mudanças de layout, lenta e difícil de monitorar. Comparamos essas opções no texto sobre RPA ou integração via API. Use quando não há outra porta, e trate como solução com prazo para acabar.

Em qualquer das opções, escrita no legado exige três proteções:

• Idempotência. Se a mesma solicitação chegar duas vezes, o legado não pode criar dois pedidos. Guarde um identificador externo e verifique antes de gravar.
• Confirmação. Não basta enviar: a integração precisa verificar que o registro foi criado e com os dados certos.
• Fila de erros com tratamento humano. Parte das gravações vai falhar por motivo de negócio (cliente bloqueado, produto inativo). Esses casos precisam aparecer para alguém resolver, não sumir num log.

Camada anticorrupção: uma API limpa na frente do legado

Usadas soltas, todas essas técnicas espalham o jeito do legado pelo resto da empresa. O e-commerce passa a conhecer o código de status 3, o app passa a saber que o cliente tem dois cadastros por causa de uma migração antiga, o painel de BI replica uma regra de cálculo esquisita.

A solução de arquitetura é a camada anticorrupção, um termo que vem do Domain-Driven Design. É um serviço que fica entre o legado e todos os outros sistemas e faz três coisas:

• Traduz. Recebe a estrutura bagunçada do legado e expõe um modelo limpo: Pedido, Cliente, Produto, com nomes claros e significados únicos.
• Isola. Os consumidores só conhecem a API da camada. Se amanhã a leitura muda de arquivo para CDC, ou se o legado é substituído, só a camada muda.
• Protege. Controla a carga sobre o legado, aplica cache onde faz sentido, enfileira escritas e aplica as regras de validação antes que um dado ruim chegue ao sistema antigo.

Na prática, a camada combina as técnicas que vimos. Uma arquitetura comum tem este desenho:

Repare na escrita assíncrona: o consumidor envia o pedido, recebe um identificador e é avisado quando o legado confirmar. Isso respeita um sistema que pode estar ocupado, em backup à noite ou lento no fechamento do mês.

Decisões que costumam funcionar bem: contrato de API documentado (OpenAPI, por exemplo) antes de qualquer código; autenticação por sistema consumidor, para saber quem pediu o quê; observabilidade desde o início, com alerta quando a fila de escrita acumula; e, se o legado roda num servidor local, um componente na mesma rede, conversando de forma segura com a parte que fica na nuvem.

Quando a integração vira o primeiro passo da modernização

Existe um efeito colateral valioso da camada anticorrupção: ela é o começo natural de uma modernização gradual.

Com todos os sistemas conversando com o legado através da camada, você pode substituir partes dele sem que os consumidores percebam: o cadastro de clientes passa para um serviço novo, depois os pedidos. Um contexto de cada vez, com reversão possível. É o padrão de estrangulamento aplicado com calma, e é o caminho que descrevemos para quem precisa migrar um sistema desktop para a web sem parar a operação.

Nem sempre a modernização vai acontecer, e tudo bem. Às vezes o legado faz bem o que faz, e a camada é tudo o que a empresa precisa por anos.

Erros comuns

• Cada sistema integrando do seu jeito. Ninguém sabe quantas integrações existem até uma parar.
• Escrever direto nas tabelas sem entender o que a aplicação faz ao gravar.
• Não tratar falhas de negócio, deixando registros rejeitados em silêncio.
• Não envolver quem conhece o legado. O usuário antigo costuma saber de regras que nenhum código explica.

Como saber se a integração está funcionando

Depois de colocar em produção, acompanhe:

• Divergências entre o legado e os sistemas consumidores, com uma conciliação periódica automática.
• Tempo entre a mudança no legado e a chegada no destino.
• Taxa de falhas de escrita e tempo até alguém tratar cada uma.
• Carga no banco do legado, comparada com o período anterior à integração.
• Trabalho manual eliminado: planilhas e redigitação que deixaram de existir.

Passo a passo para começar

1. Liste o que precisa sair e o que precisa entrar no legado, com frequência e volume.
2. Levante os acessos disponíveis: arquivos, banco, código, fornecedor.
3. Mapeie as regras de gravação observando a tela e o banco lado a lado.
4. Escolha a técnica de menor risco para cada fluxo.
5. Defina o contrato da API da camada antes de implementar.
6. Comece por um fluxo de leitura, meça e só depois ataque a escrita.
7. Coloque monitoramento e conciliação antes de ampliar.

Como a Pervian Tech entra nessa história

Integração com legado é trabalho de arquitetura de software antes de ser trabalho de código. Começamos com um diagnóstico: entendemos o sistema antigo, os acessos disponíveis e os fluxos que importam para o negócio. A partir disso desenhamos a camada de integração sob medida, começando pelo fluxo de menor risco e maior retorno, e evoluímos por fases.

Como cada legado é diferente, o investimento e o cronograma são definidos sob consulta, depois que entendemos o contexto. Se o seu sistema antigo precisa conversar com o resto da empresa, conte para a gente o que está travando.