Integração com o seu ERP

Documentação da API aberta · versão de 7 de outubro de 2026.

O Nextributo confere a NF-e e a NFC-e a partir do XML. Qualquer ERP, emissor ou sistema interno pode se ligar a ele de três jeitos, do mais simples ao mais integrado. Todos usam uma chave de API da sua conta.

Jeito	Para quem	O que exige
Agente de pasta	Emissor local que grava o XML autorizado numa pasta	Nada no ERP: um programa lê a pasta e envia o que é novo
API	ERP ou integrador com equipe técnica	Duas chamadas HTTP: enviar o XML e, se quiser, validar antes de emitir
Webhook	Quem quer o resultado de volta no ERP	Uma URL que recebe o resumo assinado de cada conferência

Prefere que a gente faça? A equipe do Nextributo implanta a integração com o seu ERP, sob consulta.

Falar no WhatsApp · Omie e SAP Business One já têm integração nativa, sem código.

1. Chave de API

Em Configuração → Integrações → API para qualquer ERP, o administrador da conta cria uma chave (ntk_…). Ela aparece uma única vez; guarde-a no cofre do ERP. Toda chamada leva a chave no cabeçalho:

Authorization: Bearer ntk_...

Endereço base: https://app.nextributo.com.br/api/v1. A chave vale só para a sua conta e pode ser revogada a qualquer momento, com registro na trilha de acesso.

2. Enviar notas

POST /documents — multipart, campo files (um ou vários arquivos). Aceita XML de NF-e e NFC-e, eventos da SEFAZ (cancelamento, carta de correção) e ZIP com XMLs. PDF/DANFE não entra: ele não traz todos os dados que a conferência precisa.

curl -X POST "https://app.nextributo.com.br/api/v1/documents?source=api" \
  -H "Authorization: Bearer ntk_..." \
  -F "files=@nota.xml" -F "files=@lote.zip"

Resposta 202: um resumo do envio. Nota repetida (mesma chave de acesso ou mesmo arquivo) não entra duas vezes.

{"job_id": "…", "accepted": 12, "duplicates": 1, "rejected": 0,
 "details": [{"filename": "nota.xml", "status": "accepted"}, …]}

Opcional: o cabeçalho Idempotency-Key faz um reenvio idêntico voltar a mesma resposta. GET /jobs/{job_id} acompanha o andamento do lote.

Limites: XML até 10 MB; ZIP até 200 MB por envio.

3. Validar antes de emitir

POST /validate/operation — multipart, campo file com o XML montado pelo emissor, antes de mandar à SEFAZ. A resposta volta em segundos e não grava nada.

curl -X POST "https://app.nextributo.com.br/api/v1/validate/operation" \
  -H "Authorization: Bearer ntk_..." \
  -F "file=@nota-montada.xml"

{"status": "FAIL", "overall_status": "ERRO", "blocking": false,
 "summary": {"errors": 1, "alerts": 0, "potential_amount": "2.34", …},
 "findings": [{"severity": "CRITICAL", "result": "FAIL", "tax": "CBS", "item_line": 1,
               "title": "Base de cálculo IBS/CBS divergente", "message": "…", "action": "…"}]}

`status`	O que o emissor faz
`PASS`	Segue para a autorização.
`REVIEW_REQUIRED`	Segue, mas marca para o fiscal olhar (a nota entra como Alerta).
`FAIL`	Segura a nota e mostra os achados ao operador.
`ENGINE_ERROR`	Fonte oficial indisponível: segue e deixa a conferência para depois. O Nextributo nunca estima.

Cada achado traz o item, o imposto, o que foi encontrado, o que era esperado e o que fazer, em português. O campo code é um identificador estável do tipo de achado, útil para automatizar o tratamento no ERP.

4. Consultar resultados

GET /documents lista as notas com filtros (status, direction=saida|entrada, de, ate, model, q, page, page_size). GET /documents/{id} traz a nota; GET /documents/{id}/findings, os achados da conferência atual; GET /documents/{id}/danfe, o DANFE em PDF.

5. Webhook de resultado

Em Configuração → Integrações → Webhook de resultado, informe a URL do seu sistema e um segredo. Ao concluir cada conferência, o Nextributo faz um POST com o resumo e assina o corpo com HMAC-SHA256 no cabeçalho X-NexTributo-Signature: sha256=<hex>. Três tentativas; falhas aparecem na trilha de acesso. O corpo nunca leva o XML, dados do destinatário nem descrições de itens.

{"event": "analysis.completed",
 "document": {"access_key": "4226…", "number": "10918", "overall_status": "ATENCAO",
              "current_status": "ATENCAO", "findings_count": 1,
              "first_finding": "Item 1: …", "url": "https://app.nextributo.com.br/documentos/…"},
 "findings": [{"severity": "MEDIUM", "result": "REVIEW_REQUIRED", "tax": "CBS", "item_line": 1, "title": "…"}]}

Validação do segredo (Python):

import hashlib, hmac
esperado = "sha256=" + hmac.new(SEGREDO.encode(), corpo_bruto, hashlib.sha256).hexdigest()
ok = hmac.compare_digest(esperado, cabecalho_signature)

6. Agente de pasta

Para quem emite em sistema local: um programa pequeno (só Python padrão) lê a pasta onde o emissor salva o XML autorizado, envia o que é novo e lembra o que já mandou. Roda como tarefa agendada do Windows a cada 5 minutos; não apaga nem move nada. A equipe do Nextributo entrega o agente e o roteiro de instalação.

7. O que sai e o que não sai

Para a Calculadora Oficial da Receita vão só NCM, CST, cClassTrib, valores, município e data. Nunca CNPJ, nome ou descrição.
O XML original fica guardado, imutável, por 3 meses a partir do recebimento. A guarda legal continua no seu ERP.
Toda chamada com chave de API fica na trilha de acesso da conta.

Início · Termos de uso · Privacidade