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:
- Idempotência: uma chave de idempotência evita que o mesmo lote seja processado duas vezes se a chamada for repetida
- Erro por arquivo: um XML malformado no lote não derruba os outros. O sistema isola o erro e continua
- Deduplicação: se o mesmo documento já foi recebido (mesmo hash SHA-256), ele é vinculado ao existente, não duplicado
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:
- Status de validação: com achados, sem achados nas verificações executadas, inconclusivo, não suportado ou falha técnica
- Achados por item: código, severidade, campo/caminho XML, fonte da regra, versão do motor e evidência (valor declarado vs. calculado)
- Cobertura: quais verificações foram executadas e quais não foram, com motivo
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:
- O payload do resultado
- Uma assinatura HMAC no header, que o ERP pode verificar para garantir que a chamada veio do Conventus
- Retries automáticos em caso de falha
- Tratamento idempotente — o mesmo evento pode chegar mais de uma vez sem causar duplicação
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.