Integração
Como integrar seu ERP com uma API de NF-e (passo a passo)
Fluxo de referência: cadastro, certificado A1, create/send, webhook HMAC e tratamento de rejeição SEFAZ.
·8 min de leitura
Integração fiscal boa é chata de propósito: poucos endpoints, estados explícitos, zero magia. Este é o playbook que usamos com ERPs parceiros.
Arquitetura recomendada
- ERP cria cliente/produto no NFER (ou espelha IDs)
- ERP cria rascunho da NF-e (número reservado)
- ERP chama /send → 202 + jobId
- NFER autoriza na SEFAZ e dispara webhook
- ERP baixa XML/DANFE e arquiva
# 1) criar nota
curl -X POST https://api.nfer.me/v1/nfe \
-H "X-API-Key: $NFER_KEY" \
-H "Content-Type: application/json" \
-d @nfe.json
# 2) enfileirar
curl -X POST https://api.nfer.me/v1/nfe/$ID/send \
-H "X-API-Key: $NFER_KEY"
# 3) webhook (recomendado) ou GET /api/nfe/$ID
Webhooks > polling
Cadastre HTTPS em POST /api/webhooks e valide X-NFER-Signature (HMAC-SHA256 de {timestamp}.{rawBody}). Eventos: nfe.autorizada, nfe.erro, nfe.denegada, nfe.cancelada. O JSON traz nfeId, status, chaveAcesso e protocolo. Polling no GET continua como fallback.
Dados que mais rejeitam na SEFAZ
- cMun IBGE incoerente com UF (nunca fallback SP genérico)
- NCM inexistente / desatualizado
- modFrete errado sem transportadora
- IE destinatário vs indIEDest inconsistente
llms-full.txt para o seu agente
Cole no Cursor/ChatGPT e implemente o fluxo sem inventar endpoints.
Abrir llms-full.txt
