Legado sem API: quatro caminhos que funcionam de verdade

Todo projeto de automação encontra o mesmo muro em algum momento: o sistema que guarda o dado mais importante da empresa não tem API. Às vezes é um ERP de 2009 sem documentação. Às vezes é um sistema em nuvem cujo fornecedor cobra por integração e não devolve prazo. Às vezes é um executável que só roda numa máquina específica na sala do financeiro. O muro é real, e existem quatro caminhos que atravessam ele. Este artigo descreve os quatro, com o que cada um custa e onde cada um quebra.

O problema, dito com precisão

Sistema legado, neste artigo, é qualquer software em produção que a empresa depende e não pode substituir no prazo do projeto atual. A idade não é o critério. Um sistema em nuvem lançado no ano passado, sem API pública e com fornecedor que não responde, é tão legado quanto um programa em Delphi rodando sobre banco local.

O que se quer, quase sempre, é uma das quatro coisas: ler um dado que está lá dentro, escrever um registro novo, saber quando algo mudou, ou disparar uma ação que o sistema já sabe fazer. Ler é fácil. Saber quando mudou é onde a maior parte da complexidade se esconde, e é o requisito que mais gente esquece de declarar no começo.

Vale separar o problema técnico do contratual. Tecnicamente, quase tudo é integrável. Contratualmente, nem tudo é permitido, e um caminho tecnicamente elegante que fere o contrato de suporte do fornecedor é um caminho que a empresa vai abandonar no primeiro incidente.

Quatro perguntas de triagem

Antes de discutir arquitetura, responda quatro perguntas. Elas eliminam a maior parte das opções e transformam uma discussão longa em uma decisão de meia hora.

1. Você tem acesso ao banco de dados? Com credencial própria, mesmo que só de leitura. Se sim, o caminho 1 entra na disputa e costuma ganhar.
2. O sistema exporta ou importa arquivo? Relatório agendado, exportação em CSV, importação de lote. Se sim, o caminho 2 entra, e ele é mais estável do que parece.
3. Precisa escrever ou só ler? Escrita muda tudo, porque regra de negócio, validação e numeração de documento moram dentro do sistema, não no banco.
4. Qual é a latência aceitável? Cinco minutos, uma hora ou de madrugada? Muita gente pede tempo real e precisa de meia hora, e essa diferença muda o custo por três.

Caminho 1: o banco como interface

Conectar direto ao banco de dados do sistema é o caminho mais rápido para leitura. Uma credencial somente de leitura, um conjunto de consultas e você tem acesso ao dado real, sem intermediário e sem depender do fornecedor. Em SQL Server, Postgres, Oracle ou MySQL, isso é trabalho de dias, não de meses.

Para leitura, é o padrão que recomendamos quando o acesso existe. Cuidados que valem sempre: usuário próprio da integração, permissão apenas nas tabelas necessárias, consulta feita em réplica quando houver, e limite de tempo de execução para que uma consulta mal escrita não trave o sistema de quem está trabalhando.

Para saber quando algo mudou, há três técnicas, em ordem de preferência. Coluna de data de alteração, quando o sistema mantém uma. Tabela de controle própria, comparando o que já foi processado. E, por último, gatilho no banco que grava a mudança numa fila. O gatilho é o mais confiável e o mais invasivo, e costuma ser o que o fornecedor mais reclama.

Caminho 2: arquivo em pasta observada

Quase todo sistema corporativo sabe exportar relatório e importar lote. Isso é uma interface, mesmo que ninguém a chame assim. O padrão é simples: o sistema deposita arquivo numa pasta, um processo observa a pasta, lê o arquivo, faz o que precisa e move o arquivo para uma pasta de processados.

Parece antiquado e é justamente por isso que funciona. Não depende de rede estável, tolera indisponibilidade dos dois lados, deixa rastro natural de cada troca e é fácil de auditar, porque o arquivo fica lá. Para escrita, é frequentemente o caminho oficial: a importação de lote passa pelas mesmas validações da tela.

Os cuidados são conhecidos e todos resolvidos há décadas. Escrever o arquivo com nome temporário e renomear no fim, para que ninguém leia pela metade. Nunca apagar o original antes de confirmar o processamento. Guardar o que foi processado, para que reprocessar não duplique. E definir o que acontece com o arquivo que falhou, porque ele vai existir.

A limitação honesta é a latência. Um ciclo de exportação de meia em meia hora entrega meia hora de atraso, e não há truque que resolva isso sem mudar o mecanismo. Se o requisito real é tempo real, este caminho está fora, e vale checar se o requisito real é mesmo tempo real.

Caminho 3: automação de tela

Automação de interface, conhecida como RPA, é um programa que opera o sistema como um usuário faria: abre a tela, preenche o campo, clica no botão, lê o resultado. É o caminho quando não há banco acessível, não há arquivo e não há API. Funciona, e é o mais frágil dos quatro.

A fragilidade tem causa específica: o programa depende da posição e do nome dos elementos da tela. Uma atualização do sistema que mova um campo quebra a automação, e ela quebra silenciosamente, continuando a rodar e produzindo resultado errado. Por isso, automação de tela sem verificação de resultado é pior do que não automatizar.

Quando é a escolha certa, três medidas reduzem a dor. Ancorar nos identificadores mais estáveis que a tela oferecer, nunca em coordenada de pixel. Verificar o resultado depois de cada operação, lendo de volta o que foi gravado. E manter um teste diário que executa um caso conhecido e avisa quando o resultado muda, para descobrir a quebra antes do usuário.

Vale ainda considerar a credencial. A automação precisa de um usuário próprio no sistema, nomeado como tal, e não da conta de uma pessoa. Sem isso, a trilha do sistema atribui a ação a alguém que não a fez, e isso é um problema de auditoria antes de ser um problema técnico.

Caminho 4: fachada de API por fora

O quarto caminho não é uma forma diferente de tocar o legado: é uma camada que embrulha um dos três anteriores e oferece, para o resto da empresa, a API que o sistema não tem. Por dentro ela lê o banco, escreve arquivo ou opera a tela. Por fora, entrega rotas limpas, documentadas e versionadas.

O ganho aparece a partir da segunda integração. Sem a fachada, cada novo projeto reimplementa o acesso ao legado, com pequenas diferenças de interpretação, e a empresa passa a ter três versões incompatíveis da mesma regra. Com a fachada, existe um lugar só onde a regra mora, e um lugar só para corrigir quando o legado mudar.

É também o que torna a substituição futura viável. No dia em que o sistema antigo for trocado, quem consome a fachada não precisa saber. A troca acontece por dentro, rota por rota, sem parar a operação. É a diferença entre um projeto de migração e uma reforma permanente.

A fachada não é sobre elegância. É sobre ter um único lugar para consertar quando o legado mudar, porque ele vai mudar.

Os quatro lado a lado

A tabela resume o que cada caminho entrega e cobra. Os prazos são ordem de grandeza para um escopo de leitura simples, com acesso já concedido, e servem para calibrar expectativa, não para orçar.

Caminho	Leitura	Escrita	Latência típica	Fragilidade	Prazo até o primeiro fluxo
Banco direto	Excelente	Não recomendada	Segundos	Baixa	Dias
Arquivo em pasta	Boa	Boa, usa a validação do sistema	Minutos a horas	Baixa	Dias
Automação de tela	Razoável	Razoável, respeita a regra do sistema	Segundos a minutos	Alta	Semanas
Fachada de API	Herda do caminho embaixo	Herda do caminho embaixo	Herda do caminho embaixo	Concentrada em um lugar	Semanas

Quando o fornecedor proíbe

Muito contrato de software proíbe acesso direto ao banco e prevê perda de suporte em caso de alteração no esquema. Ignorar isso é transferir um risco jurídico para dentro de um projeto técnico, e costuma cobrar no pior momento: durante um incidente, quando você mais precisa do suporte.

Três movimentos costumam destravar. O primeiro é distinguir leitura de escrita na conversa: muitos contratos que proíbem alteração aceitam leitura em réplica, e essa distinção raramente é feita antes de alguém perguntar por escrito.

O segundo é pedir o que existe. Muito sistema tem uma integração pouco divulgada, um serviço de exportação, um módulo de importação vendido à parte. Perguntar diretamente ao suporte técnico, e não ao comercial, costuma revelar caminho oficial que ninguém sabia que existia.

O terceiro é registrar a resposta. Um pedido formal por escrito, com a resposta do fornecedor anexada, transforma uma escolha arriscada em uma decisão documentada. Se a resposta for negativa e a empresa decidir seguir mesmo assim, ao menos a decisão terá dono e data.

Segurança e LGPD na integração

Integrar um sistema legado quase sempre significa mover dado pessoal de um lugar para outro, e isso coloca a integração dentro do escopo da Lei Geral de Proteção de Dados. Não é burocracia opcional: é o tipo de coisa que trava o projeto na revisão jurídica se não estiver resolvida no desenho.

• Leve só o campo necessário. Se o fluxo precisa do CPF para localizar o cadastro, ele não precisa do endereço junto. Minimização é a defesa mais barata que existe.
• Não crie um segundo banco de dado pessoal sem querer. Cache de integração é banco, e banco de dado pessoal tem obrigações próprias.
• Registre quem acessou o quê. A trilha de auditoria da integração é o que responde à pergunta do titular sobre quem tratou o dado dele.
• Defina prazo de descarte. Arquivo processado que fica para sempre na pasta vira passivo. Um prazo de retenção escrito resolve.
• Credencial da integração é nominal. Usuário próprio, com permissão mínima, nunca a conta pessoal de alguém do time.

Lote ou evento

Depois de escolher por onde tocar o sistema, falta escolher o ritmo. Lote significa processar tudo o que mudou em intervalos fixos. Evento significa reagir a cada mudança assim que ela acontece. A escolha muda o custo, a complexidade e o tipo de defeito que você vai depurar em produção.

Aspecto	Lote	Evento
Complexidade	Baixa, um agendamento resolve	Alta, exige fila e tratamento de repetição
Latência	O intervalo escolhido	Segundos
Falha típica	Rodada que não executou	Mensagem processada duas vezes
Reprocessar	Simples, roda de novo	Exige controle de idempotência
Carga no legado	Concentrada, previsível	Difusa, difícil de prever
Quando escolher	Requisito tolera minutos ou horas	A ação depende da resposta imediata

Uma nota que economiza discussão: mesmo em fluxo por evento, você vai precisar de uma rodada em lote de reconciliação. É ela que encontra a mensagem que se perdeu, o registro que ficou pela metade e a divergência de contagem entre os dois lados. Quem só tem evento descobre a divergência pelo cliente.

Um exemplo do começo ao fim

Vale ver o desenho inteiro em um caso concreto. O pedido é comum: o cliente pergunta pelo WhatsApp o andamento do pedido dele, e a resposta está num ERP sem API, com banco em SQL Server e um módulo de importação por arquivo.

1. Leitura pelo banco. Usuário próprio, somente leitura, restrito às tabelas de pedido, item e situação. Consulta com limite de tempo, feita na réplica de relatórios para não competir com quem opera.
2. Identificação do cliente. O número de telefone que chega na conversa é cruzado com o cadastro. Sem correspondência, o fluxo pede um dado adicional em vez de adivinhar.
3. Resposta ancorada. O texto devolvido cita apenas o que veio da consulta: número, situação e data prevista. Nada é inferido, porque o custo de errar a data é uma reclamação.
4. Escrita pelo caminho oficial. Se o cliente pede alteração, o fluxo gera um arquivo de solicitação para o módulo de importação do ERP, que aplica as mesmas validações da tela.
5. Registro de tudo. Cada consulta e cada arquivo gerado entram na trilha, com quem pediu, o que foi consultado e o que voltou.
6. Repasse por regra. Pedido atrasado, valor acima do limite ou cliente sem correspondência no cadastro vão para uma pessoa, sempre.

Repare que o ERP nunca foi alterado, nenhuma tabela recebeu gatilho e nenhum registro foi inserido por fora. O sistema legado continua sendo a autoridade sobre o próprio dado, e a integração se comporta como um leitor educado com um canal de entrada oficial. É esse desenho que sobrevive à próxima atualização do fornecedor.

Como decidir em uma tarde

A decisão não precisa de projeto de descoberta. Com as pessoas certas na sala e quatro horas, dá para sair com o caminho escolhido, o risco nomeado e o primeiro fluxo especificado.

1. Escolha um fluxo só. O de maior volume e menor risco. Integração se prova em um caminho estreito, não em um mapa completo.
2. Responda as quatro perguntas de triagem. Acesso ao banco, arquivo disponível, precisa escrever, latência aceitável.
3. Leia o contrato do fornecedor. Especificamente as cláusulas sobre acesso a banco e suporte. Dez minutos que evitam meses de discussão.
4. Prove a leitura no mesmo dia. Uma consulta, uma exportação ou uma tela lida. Se o acesso não se prova em uma tarde, ele é o verdadeiro projeto.
5. Escreva pelo caminho oficial. Importação de lote, módulo do próprio sistema ou automação de tela. Banco, não.
6. Defina como saber que quebrou. Alerta de fluxo que não rodou, contagem que não bate, arquivo que ficou parado. Antes de publicar, não depois.

Erros que custam caro

Estes são os erros que mais vimos custar retrabalho em projetos de integração com legado. Todos são evitáveis na fase de desenho, e nenhum é evitável depois.

• Escrever no banco para ganhar tempo. Ganha duas semanas no começo e devolve um mês no fechamento contábil.
• Pedir tempo real por reflexo. Metade dos requisitos de tempo real vira meia hora quando alguém pergunta o que acontece se demorar.
• Deixar a detecção de mudança para o final. Saber o que mudou costuma ser mais difícil que ler o dado, e descobrir isso tarde reordena o projeto inteiro.
• Automatizar a tela antes de procurar arquivo. Muita gente parte para o caminho frágil sem ter perguntado se existe exportação agendada.
• Não tratar reprocessamento. Todo fluxo vai rodar duas vezes algum dia. Se rodar duas vezes duplicar pedido, o fluxo está errado.
• Integrar dez fluxos de uma vez. O primeiro fluxo ensina o que os outros nove precisam, e ele ensina rápido.

Perguntas frequentes

Dá para integrar um sistema sem nenhuma documentação?

Dá, e é o caso mais comum. O caminho é reconstruir o entendimento a partir do que existe: esquema do banco, arquivos que o sistema gera e observação do que a tela faz. É trabalho de investigação, e costuma levar de alguns dias a duas semanas para um fluxo específico.

Automação de tela é sempre má ideia?

Não, é o último recurso legítimo. Quando não há banco acessível, nem arquivo, nem API, ela é a diferença entre automatizar e não automatizar. O que a torna sustentável é verificação de resultado depois de cada operação e um teste diário que detecta quebra antes do usuário.

Quanto tempo leva para o primeiro fluxo entrar no ar?

Com acesso já concedido e um fluxo de leitura bem escolhido, dias. O que costuma dominar o prazo não é o desenvolvimento, é a liberação de acesso: credencial, regra de rede e autorização interna. Vale começar por esse pedido no primeiro dia.

O fornecedor pode cancelar meu suporte por causa da integração?

Depende do contrato, e muitos preveem exatamente isso para acesso direto ao banco ou alteração de esquema. Por isso a leitura do contrato entra antes da escolha técnica, e o pedido formal ao suporte, com resposta por escrito, entra antes da implementação.

Como saber quando um registro mudou sem gatilho no banco?

Pela coluna de data de alteração, quando existir, ou por uma tabela de controle própria que guarda o que já foi processado e compara. A comparação periódica é mais lenta e mais barata em risco, porque não altera nada dentro do sistema do fornecedor.

Vale a pena trocar o sistema em vez de integrar?

Raramente como primeiro movimento. Substituir um sistema central é um projeto de muitos meses com risco alto, enquanto integrar entrega resultado em semanas. A fachada de API é justamente o caminho que permite integrar agora e substituir depois, sem refazer o trabalho.

Um agente de IA pode operar o sistema legado direto?

Pode, e é o mesmo problema com outro nome. O agente precisa de um caminho de acesso, e esse caminho é um dos quatro deste artigo. O que muda é a exigência de trilha e de permissão por ação, porque a decisão de agir deixa de ser de uma pessoa.

Próximo passo

Escolha um fluxo, responda as quatro perguntas de triagem e tente ler o dado hoje. Se a leitura funcionar em uma tarde, o projeto é de semanas. Se não funcionar, você acabou de descobrir onde está o verdadeiro trabalho, e descobrir isso no primeiro dia vale mais do que qualquer estimativa.

Continuando pelo blog: Trilha de auditoria de agentes de IA em Postgres mostra como registrar cada ação da integração, e Agente ou automação ajuda a decidir o que colocar em cima desse acesso.

Fontes e leitura

• Brasil, Lei 13.709 de 2018, Lei Geral de Proteção de Dados Pessoais.
• Autoridade Nacional de Proteção de Dados, orientações e guias.