← Voltar ao blog

Validação fiscal por API: como integrar seu ERP sem trocar de sistema

ERPs podem enviar XMLs ou operações em JSON para validação fiscal automatizada. Entenda como a integração por API funciona sem conectores proprietários.

O problema: cada ERP é uma ilha

Escritórios e empresas usam dezenas de ERPs diferentes. Cada um tem sua estrutura de dados, sua forma de exportar documentos fiscais e suas particularidades. Criar um conector específico para cada ERP é caro, lento e frágil — qualquer atualização do fornecedor pode quebrar a integração.

A alternativa é mais simples do que parece: se o ERP exporta XML fiscal, ele já pode integrar com um serviço de validação.

Dois caminhos de integração

1. XML/ZIP via HTTPS

O caminho mais direto. O ERP exporta os XMLs (NF-e, CT-e, NFC-e) e envia por HTTPS para a API de importação. Pode ser um arquivo individual ou um ZIP com centenas de documentos.

A API aceita o envio, retorna um 202 Accepted com o ID do lote e processa em segundo plano. O ERP consulta o status quando quiser ou configura um webhook para ser notificado na conclusão.

Pontos importantes:

2. JSON de operação tributária

Quando o ERP não tem o XML final (por exemplo, em uma simulação antes da emissão), ele pode enviar um JSON com os dados da operação: CNPJ, NCM, cClassTrib, alíquotas nominais, valores por item.

O JSON segue um contrato OpenAPI 3.1 próprio. A API traduz para os modelos de cálculo e retorna o diagnóstico. O resultado é classificado como diagnóstico de operação, nunca como "XML validado" — porque não existe XML nesse fluxo.

O que a API retorna

Para cada documento ou operação, o resultado inclui:

O ERP pode consumir esses dados para exibir ao usuário, alimentar relatórios internos ou disparar alertas.

Webhook com assinatura HMAC

Em vez de ficar consultando o status do lote, o ERP pode configurar um webhook. Quando o processamento termina, a API faz um POST para a URL cadastrada, com:

Sem conector proprietário

A integração é genérica. Não existe SDK para TOTVS, Omie, Sankhya ou Senior. Se o ERP exporta XML ou monta um JSON com os campos necessários, ele integra. Isso reduz a dependência e evita a armadilha do "conector que ninguém mantém".

Autenticação e limites

Cada tenant (conta SaaS) tem credenciais de integração separadas, com escopos configuráveis e rotação de tokens. Os limites de chamadas são por tenant, não globais, garantindo que um integrador pesado não afete os outros.

Começando pela forma mais simples

Se você está avaliando a integração, comece pelo XML/ZIP. É o caminho mais rápido para validar se o diagnóstico agrega valor para o seu fluxo. O JSON de operação e o webhook são o próximo passo, quando você quiser automatizar.

A API aceita XMLs de qualquer ERP. Sem trocar de sistema, sem instalar nada, sem esperar um conector. Exportou o XML, enviou, conferiu.