Integrar com o ERP: o que o sistema do outro lado decide por você

"Tem API?" é a pergunta errada#

Quando uma empresa contrata um sistema novo que vai conviver com o ERP que ela já usa, a primeira pergunta técnica é quase sempre a mesma: "tem API?". A resposta é sim ou não, e nenhuma das duas informa o que decide o projeto.

Construímos três integrações com sistemas de terceiros, todas em produção:

• NextFit, o ERP de uma rede de academias, de onde lemos as vendas que alimentam a meta comercial da rede.
• Altimus, o sistema de estoque de veículos de uma revenda, de onde lemos os veículos que entram num financiamento.
• Controlle, o ERP financeiro que a nossa própria empresa usa, de onde lemos lançamentos e saldos para o painel dos sócios.

Os três responderam coisas diferentes às perguntas abaixo — e cada resposta negativa virou código nosso.

Nenhuma dessas perguntas cabe num "tem API?". Todas mudam prazo, e algumas mudam escopo.

Como saber que mudou alguma coisa do outro lado#

Nenhuma das três fontes avisa quando algo acontece. Não há webhook em nenhuma delas, então as três integrações são o que o catálogo Enterprise Integration Patterns, de Gregor Hohpe e Bobby Woolf, chama de Polling Consumer: é o seu sistema que pergunta, no ritmo que ele escolhe.

A partir daí, cada fonte permite um nível diferente de precisão:

• Quando a fonte aceita filtrar por data de alteração, você pede só o que mudou desde a última leitura. É o caso da NextFit.
• Quando ela aceita um intervalo de datas, você trabalha com uma janela móvel e reprocessa o intervalo inteiro. É o caso do Controlle.
• Quando ela não filtra nada, você lê a base toda e compara registro a registro com o que já tem gravado. É o caso do Altimus.

O detalhe que costuma escapar aparece no primeiro caso. A janela da NextFit é por data, sem hora — então, a cada leitura, ela devolve o dia inteiro de novo. Gravar tudo outra vez seria trabalho jogado fora, então recortamos localmente o que mudou desde a última sincronização, com uma margem de alguns minutos para trás. A margem cobre defasagem de relógio e o registro alterado no exato instante em que a leitura anterior terminava. Reler é inofensivo porque a gravação é idempotente — o mesmo registro lido duas vezes produz o mesmo resultado —, que é o padrão Idempotent Receiver do mesmo catálogo.

E há um buraco que aparece meses depois, quando ninguém está olhando: sincronização incremental não recupera o que você perdeu. Se um registro antigo deixou de ser gravado por qualquer motivo, a data de alteração dele já ficou para trás, e nenhuma leitura incremental futura vai trazê-lo de volta. Os dois projetos que usam incremental tiveram que ganhar um irmão: na rede de academias, um modo de carga completa do período; no painel financeiro, uma recarga total semanal que ignora o incremental e varre meses para trás.

A regra que tiramos disso: todo sync incremental precisa de um irmão que ignora o incremental. Sem ele, o erro silencioso é permanente.

Como saber que apagaram alguma coisa do outro lado#

Essa é a pergunta que quase nunca entra no escopo, e é a que mais dá problema. Uma fonte de dados diz bem o que existe; quase nenhuma diz o que deixou de existir.

A saída é a reconciliação por ausência: o que não veio na leitura completa é marcado como inativo do seu lado. É assim que sabemos que um veículo saiu do estoque da revenda — o sistema de origem nunca envia "removido", ele simplesmente para de mandar aquele registro.

Só que a mesma técnica, aplicada sem cuidado, apaga o que não devia:

• Se a leitura é de uma janela, a desativação tem que ser escopada à mesma janela. No painel financeiro, um lançamento sumir da janela dos últimos meses significa que ele foi removido; um lançamento de três anos atrás não aparecer ali significa apenas que ele está fora do recorte. Desativar por ausência sem escopo apagaria o histórico inteiro.
• A desativação só pode acontecer depois da leitura terminar inteira. Uma carga interrompida no meio não pode ser interpretada como "sumiu tudo o que faltava".

Quando o ERP não tem API#

A revenda de veículos usa o Altimus para controlar o estoque. Pedimos acesso à API. O Altimus não tem, e não libera — é decisão do fornecedor, e ele não tem obrigação nenhuma de mudar isso porque um cliente pediu.

O que existia era um endereço que devolve o estoque inteiro em JSON. Isso não é uma API: não filtra por data, não avisa remoção, não tem contrato publicado. A decisão de trabalhar em cima dele foi tomada em conjunto com o cliente — modelar o que fazia sentido com o que existia e sincronizar periodicamente, em vez de esperar por uma abertura que não viria.

O que essa integração comprou foi específico e valioso: acabou o recadastro de veículo. Quem monta um financiamento digita a placa ou o chassi, e o resto dos dados do veículo chega preenchido. Deixou de existir a etapa de copiar à mão, de um sistema para o outro, dados que já estavam digitados.

O que ela cobrou, em código que não existiria se houvesse uma API:

• o cálculo do que mudou, comparando a data de atualização de cada item com a que está gravada;
• a reconciliação por ausência, para descobrir o que saiu do estoque;
• as fotos baixadas e re-hospedadas na nuvem do cliente, porque endereço de imagem de terceiro está fora do seu controle;
• tolerância a erro por item, para que um registro estranho não derrube a carga inteira;
• progresso visível e botão de parar, porque a carga é longa o suficiente para alguém precisar interrompê-la.

O "não" que vale registrar: exportação não é integração — mas resolve. O erro não é aceitar a exportação; é tratá-la como equivalente a uma API na hora de fechar o escopo.

Quanto do seu produto o ERP decide#

Essa é a parte cara, e é a que quase nenhum material sobre integração menciona.

Na revenda, o plano não era parar no estoque. A integração ia alcançar também a base de clientes, e a partir dela outros fluxos entre os dois sistemas. Ficou no estoque, porque estoque era o único dado que a fonte entregava. O limite do fornecedor virou limite do produto.

Isso aparece até hoje na tela: o módulo de estoque é inteiramente alimentado pelo Altimus — não existe cadastro manual de veículo lá dentro. Mas nem todo veículo financiado está no Altimus. Então o financiamento aceita um veículo que só existe dentro dele, e o atalho para a ficha completa do estoque simplesmente não aparece nesses casos. É a marca, na interface, de uma fonte que não cobre tudo.

No outro extremo, a rede de academias mostra o que dá para fazer quando a fonte entrega: como a NextFit tem API de verdade, foi possível estabelecer que nenhuma venda entra no sistema novo a não ser pela NextFit. O ERP continua sendo o dono do dado, e a plataforma nova nunca aceita lançamento manual daquele dado. É isso que faz o número parar de depender de quem digitou.

Mesmo com API, a fonte reserva armadilhas. Nessa integração, uma venda de convênio chega marcada com a mesma característica que identifica uma venda de plano — e a ordem em que você testa as condições decide se o convênio entra ou não no cálculo da meta. Uma classificação escrita na ordem intuitiva teria inflado a meta de todas as unidades, silenciosamente e para sempre. Descobrir isso não é ler documentação: é abrir os dados reais antes de escrever a regra.

Como a integração falha sem derrubar o seu sistema#

O sistema do outro lado vai sair do ar, mudar um campo sem avisar ou devolver erro por uma hora. Isso não é hipótese, é rotina. O que se projeta é o comportamento do seu sistema quando acontece:

1. A sincronização nunca derruba o processo. Ela registra a falha, guarda a mensagem e devolve o resultado como "não deu certo" — enquanto as telas continuam servindo o último dado sincronizado.
2. O erro é tratado por item, não por carga. Um registro com formato inesperado é registrado e pulado; os outros milhares continuam.
3. O alerta dispara por falhas consecutivas, e uma vez só. No painel financeiro, o aviso sai quando o contador de falhas seguidas atinge o limite — e não se repete a cada nova falha. Alerta que repete vira alerta ignorado.
4. Execução órfã precisa ser limpa. Um processo que morre no meio deixa a sincronização marcada como "em andamento" para sempre, e a trava que evita execuções simultâneas passa a bloquear todas as próximas. O painel financeiro resolve isso liberando execuções presas na inicialização.
5. Nada de corpo de resposta no log. Quando o dado é financeiro, o registro guarda rota, status e duração — nunca o conteúdo nem a credencial.

De quanto em quanto tempo sincronizar#

Não existe "a frequência da integração". Existe uma frequência por tipo de dado, e isso fica evidente no painel financeiro, onde os três ritmos convivem:

Dois critérios fecham a escolha, e nenhum deles é técnico.

O primeiro é o horário da operação. Na rede de academias a leitura é de poucos em poucos minutos, mas só em horário comercial: academia não vende de madrugada, e varrer a noite inteira gera leitura vazia — trabalho e custo sem informação nova.

O segundo é a natureza do dado. Dado financeiro tem futuro: parcela a vencer e lançamento previsto existem no sistema antes de acontecerem. Por isso a janela do painel financeiro olha para trás e para a frente, enquanto a janela de vendas só olha para trás — venda futura não existe. Não é a API que define a janela do seu sync; é a natureza do que você está lendo.

Vale uma nota sobre custo: quando o acesso à fonte é pago, a sincronização automática das duas integrações vem desligada por padrão e é ligada de forma consciente, em vez de começar a consumir sozinha no primeiro deploy.

Perguntas frequentes#

O sistema novo pode substituir o ERP que eu já uso?#

Pode, mas raramente é o que compensa. Um ERP consolidado carrega anos de regra fiscal, contábil e operacional que ninguém quer reescrever. O padrão que dá certo é o oposto: o ERP continua sendo o dono do dado que já é dele, e o sistema novo resolve o que o ERP não resolve — a leitura, a meta, o painel, o fluxo que a operação faz por fora. Quando o dado tem dono claro, os dois convivem sem divergir.

E se o meu ERP não tiver API?#

Ainda dá para integrar, com menos alcance. Muitos sistemas oferecem alguma forma de exportação — um arquivo, um endereço que devolve a base inteira, um relatório agendado. Isso não é uma API: não avisa o que mudou nem o que foi apagado, então esse trabalho passa a ser seu. Funciona bem para dado que muda devagar e é lido muito mais do que escrito, como um catálogo ou um estoque. Não funciona para fluxo que precisa de resposta imediata.

De quanto em quanto tempo os dados ficam atualizados?#

Depende do tipo de dado, não da integração. Numa mesma aplicação, faz sentido atualizar catálogo uma vez por dia, movimento de hora em hora e recarregar tudo uma vez por semana. Dado que a operação olha para tomar decisão no mesmo turno pede minutos; dado de cadastro pede um ciclo diário. Escolher uma frequência única para tudo desperdiça leitura de um lado e atrasa do outro.

A integração pode sobrecarregar o meu ERP?#

Pode, e é o risco mais subestimado. Se cada tela do sistema novo consultar o ERP ao vivo, o pico de uso do sistema novo vira pico de requisição no sistema de que a empresa inteira depende. A forma segura é espelhar: um processo lê o ERP em ritmo controlado, grava uma cópia local, e todas as telas leem a cópia. O ERP passa a receber um volume previsível, independente de quantas pessoas abriram o painel.

O que acontece com o meu sistema se o ERP sair do ar?#

Se a arquitetura for de espelho, quase nada: as telas continuam servindo o último dado sincronizado, e o sistema registra que a sincronização falhou em vez de quebrar. O que não pode acontecer é a falha do terceiro derrubar o seu processo — nem virar silêncio. A regra que usamos é alertar depois de algumas falhas seguidas, uma única vez, para o aviso continuar significando alguma coisa.

Fontes#

• Enterprise Integration Patterns — "Idempotent Receiver", de Gregor Hohpe e Bobby Woolf, sobre receber a mesma mensagem mais de uma vez sem efeito colateral — https://www.enterpriseintegrationpatterns.com/patterns/messaging/IdempotentReceiver.html
• Enterprise Integration Patterns — "Polling Consumer", dos mesmos autores, sobre o consumidor que decide quando buscar — https://www.enterpriseintegrationpatterns.com/patterns/messaging/PollingConsumer.html

Próximo passo#

Antes de fechar o escopo de qualquer sistema que vai conviver com um ERP, faça as seis perguntas do começo deste texto ao fornecedor da fonte, e por escrito. Elas custam um e-mail e decidem semanas de trabalho — inclusive a possibilidade de descobrir, como descobrimos, que a resposta é "não temos e não vamos abrir".

Os dois casos citados aqui estão publicados: a rede de academias, cuja meta comercial passou a vir direto do ERP, e a revenda, cuja plataforma de financiamento lê o estoque do sistema de gestão. É o tipo de trabalho que tratamos em integrações e APIs — e, se o seu caso é menos "conviver" e mais "trocar", vale ler quando o sistema legado precisa ser substituído.