A API do ERP: o que ela expõe, o que ela esconde e o que perguntar antes de assinar

"Tem API" é a resposta que encerra a reunião comercial e abre o problema técnico. A frase é verdadeira para quase todo ERP vendido hoje e não diz nada sobre o que importa: se a API lê o que você precisa ler, se escreve o que você precisa escrever, e sob quais condições. Integração que começa com "tem API" e termina com "mas não essa parte" é a mais comum que existe — e a mais evitável, porque tudo que a derruba dava para perguntar antes de assinar.

Ler é uma coisa, escrever é outra

A primeira separação a fazer é entre consultar e gravar. Boa parte das APIs de ERP nasceu para alimentar relatório: entrega cliente, produto e pedido para leitura, e para por aí. Gravar é outro produto, às vezes outro módulo, às vezes só para parceiro.

E quando a escrita existe, vale olhar o que ela pula. O ERP aplica regra ao gravar pela tela — limite de crédito, tabela de preço por região, bloqueio de cliente inadimplente. Nem toda API passa pelo mesmo caminho. Uma que grava pedido sem checar crédito não é uma integração pronta: é uma porta lateral, e o pedido que entra por ela vai aparecer no financeiro como surpresa. A pergunta certa não é "dá para criar pedido", é "o pedido criado pela API passa pelas mesmas regras do pedido digitado".

Quais entidades, e até que profundidade

Cadastro de cliente e de produto quase sempre estão lá. O que costuma faltar é justamente o que a operação quer integrar: título financeiro, saldo de estoque por depósito, nota fiscal com o XML, movimentação, condição de pagamento. Cada uma dessas ausências vira um contorno, e cada contorno é uma coisa a manter.

Depois vem a profundidade. Um pedido tem itens, os itens têm desconto, o desconto tem origem. A API devolve o pedido inteiro ou só o cabeçalho, com os itens em outra chamada? Devolve o campo personalizado que a sua empresa criou há três anos e que hoje segura a regra de comissão? Campo customizado fora da API é dos problemas mais frequentes e menos previstos — a empresa construiu a operação em cima dele, e o fornecedor não o considera parte do produto.

O exercício que resolve isso é curto: listar as entidades que precisam atravessar, em que direção, e conferir uma a uma contra a documentação. É a mesma lista que alimenta o de-para de dados, então não é trabalho perdido.

Eventos ou só consulta

Saber que algo mudou é diferente de poder perguntar se mudou. API que só responde a consulta obriga o outro lado a varrer — de tantos em tantos minutos, para cada entidade — e a varredura custa requisição, esbarra em limite de chamadas e atrasa por definição. API que emite evento avisa quando o pedido muda de status, e a integração reage.

A maioria oferece consulta; uma parte menor oferece webhook e, dentro dessa parte, poucas cobrem todas as entidades. É comum ter evento de pedido e não ter de estoque, que é exatamente o que mais muda. O arranjo que funciona costuma usar os dois — evento para reagir rápido, varredura para conferir o que o evento perdeu —, e a comparação entre webhook e consulta periódica detalha o porquê. O que interessa aqui é saber, antes, qual dos dois você vai ter.

As condições que não estão na documentação

A documentação técnica descreve o caminho feliz. O que decide o projeto está em outro documento, e às vezes em nenhum:

• A API é módulo pago? Em muitos ERPs é, e o valor não aparece na proposta até alguém perguntar. Há também cobrança por volume de chamadas, que transforma a varredura da seção anterior em linha de custo.
• Só para parceiro homologado? Nesse caso quem integra precisa entrar no programa, e o prazo do projeto passa a incluir o prazo da homologação.
• Existe ambiente de teste? E ele se comporta como produção — mesmas regras, mesmos limites — ou é um espelho simplificado? Ambiente de teste permissivo é onde a integração passa e produção é onde ela falha.
• De quem é a credencial? Se a chave pertence a um usuário, ela vai junto quando ele sair, e o problema tem hora marcada — é o assunto de a credencial que vence de madrugada.

Nenhuma dessas respostas é técnica, e todas mudam o orçamento. Pedir por escrito, ao suporte e não ao vendedor, é a diferença entre saber e supor.

Versão, mudança e quem avisa

API é contrato, e contrato muda. A pergunta é como. Há fornecedor que versiona — a v1 continua respondendo enquanto a v2 existe, com prazo anunciado para desligar — e há fornecedor que altera o formato de resposta numa atualização de sexta à noite. O segundo não é raro, e a integração que depende dele não quebra com erro: quebra com dado errado, que é a falha mais cara de todas.

O que pedir: política de versão escrita, registro de mudanças da última atualização e um canal nomeado que avisa antes. Se os três existem, qualquer lacuna da API é contornável. Se nenhum existe, a informação é sobre o fornecedor, não sobre a API — e ela pesa na decisão entre integrar ou trocar o ERP.

O teste antes de assinar

Nada acima precisa ser aceito na palavra. Peça uma credencial de ambiente de teste — se não houver, a resposta já veio — e faça três chamadas, nesta ordem:

1. Ler um cliente, e conferir se o retorno traz os campos que a sua operação usa, inclusive os personalizados.
2. Criar um pedido para um cliente com crédito bloqueado. A API tem que recusar. Se aceitar, você acabou de descobrir a porta lateral.
3. Alterar o status desse pedido pela tela e ver se algum evento chega. Se não chega, a integração vai ser por varredura, e o custo dela entra na conta agora.

Meia hora com essas três chamadas diz mais que a documentação inteira, e o resultado é o ponto de partida do levantamento de integração. Quando a API reprova em duas das três, o projeto não está perdido — ele só vai seguir por outra via, e é melhor saber disso antes do contrato do que depois do cutover.