Como integrar seu ERP com uma API de NF-e (passo a passo)

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

1. ERP cria cliente/produto no NFER (ou espelha IDs)
2. ERP cria rascunho da NF-e (número reservado)
3. ERP chama /send → 202 + jobId
4. NFER autoriza na SEFAZ e dispara webhook
5. 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