Integração
Multi-CNPJ na API de NF-e: conta vs empresa (e por que isso importa)
Como modelar org key, company key, limite de notas da conta e emissão por CNPJ — o padrão que ERPs e emissores usam em 2026.
Software house que trata “um CNPJ = um cliente da API” quebra quando o mesmo grupo precisa de filiais. O modelo que escala é: uma conta (billing + login + plano) e N empresas (cada uma com CNPJ, certificado, série e chave de emissão).
Dois níveis, duas chaves
| Nível | Para quê | Não use para |
|---|---|---|
| Conta / org | Gerir empresas, membros, plano, limite mensal | Assinar e autorizar NF-e na SEFAZ |
| Empresa / CNPJ | Emitir, cancelar, CC-e, DANFE, certificado A1 | Trocar plano ou criar outro CNPJ sem permissão |
No NFER, a org key (nfer_org_…) é só gestão. A company key é a que emite. Misturar os dois no ERP é a forma mais rápida de vazamento de escopo e de nota no CNPJ errado.
Limite de notas: conta; operação: empresa
O teto de NF-e/mês do plano costuma ser da conta (soma de todas as empresas). Já o dashboard operacional — stats, atividade recente, certificado — deve ser da empresa ativa. Mostrar “tudo consolidado” sem seletor de CNPJ confunde o usuário e esconde cert expirando na filial.
Checklist para o ERP parceiro
- Um partnerRef → uma conta NFER (não N contas por CNPJ).
- Ao adicionar CNPJ, gravar a company API key e nunca a org key no fluxo de emissão.
- Troca de empresa = novo contexto (token/companyId), não filtro cosmético na UI.
- Webhooks e logs com companyId explícito.
