Comece Aqui

Autenticação

API Key da empresa, org key e JWT do painel.

Todas as requisições à API da NFER são autenticadas via cabeçalhos HTTP criptografados em HTTPS. A plataforma adota um modelo de isolamento baseado em Company API Keys, garantindo que cada CNPJ emissor opere com credenciais exclusivas, tenant isolado e escopo estritamente delimitado.

Company API Key (Emissão & Operação)

Chave principal vinculada a um CNPJ emissor. Utilizada em todas as operações de emissão, consulta, cancelamento, cartas de correção e webhooks de NF-e, NFC-e, NFS-e, CT-e e DC-e.

Chave da Organização / Org Key (Multi-CNPJ & Provisionamento)

Chave com prefixo nfer_org_…. Localizada e rotacionável em Minha Conta (/dashboard/account). Utilizada para criar novas empresas filhas (POST /v1/companies) e operações multi-tenant nas rotas /v1/org/*.

1. Como obter suas credenciais

Você gerencia suas credenciais diretamente no Painel NFER de acordo com a finalidade:

Chave da Organização (Org Key): Acesse Configurações → Minha Conta (/dashboard/account). Nela você visualiza sua nfer_org_..., copia com 1 clique ou realiza a rotação de chave instantaneamente caso precise renovar credenciais.
Chave de Empresa (Company API Key): Acesse Configurações → Chaves de API para obter a chave isolada do CNPJ ativo, usada na emissão de NF-e, NFC-e, NFS-e e CT-e.
Via API (Provisionamento Automatizado de Empresas): Ao criar uma empresa filha via POST /v1/companies enviando o header X-Org-Key: nfer_org_..., a resposta retorna a apiKey própria gerada para aquele novo CNPJ.

Armazenamento Seguro da Chave

Por motivos de segurança criptográfica (hash com salt bcrypt de alta segurança no banco de dados), a chave secreta completa só é exibida uma única vez no momento da criação. Salve-a imediatamente em variáveis de ambiente (.env) ou em um gerenciador de segredos. Caso perca a chave, será necessário gerar uma nova chave diretamente pelo painel.

2. Autenticando requisições HTTP

Envie sua chave de API no cabeçalho X-API-Key de cada chamada. Todas as rotas exigem tráfego criptografado através de HTTPS.

curl -X POST https://api.nfer.me/v1/nfe \

-H "X-API-Key: a0eebc99.sk_live_9f83a71b4c82e01d67a5" \

-H "Content-Type: application/json" \

-d '{

"naturezaOperacao": "Venda de Mercadoria",

"customer": { "cpfCnpj": "12345678000195", "nome": "Cliente Exemplo" },

"itens": [ ... ]

Cabeçalhos de autenticação suportados

Método	Cabeçalho HTTP	Cenário de Uso
Header Principal (Recomendado)	`X-API-Key: <company_api_key>`	Padrão oficial para integrações de backend, ERPs, PDVs e e-commerces.
Bearer Token Compatível	`Authorization: Bearer <company_api_key>`	Alternativa padrão suportada por bibliotecas HTTP, SDKs e clientes REST.
Chave da Organização (Org Key)	`X-Org-Key: nfer_org_<token> ou X-API-Key`	Criação de empresas filhas (POST /v1/companies), White-Label e rotas de organização (/v1/org/*). Obtida em /dashboard/account.
Sessão Web (JWT)	`Authorization: Bearer <jwt_token>`	Sessões de operadores autenticados via login no Painel Web.

Por que a NFER não utiliza API Key em Query Parameter?

Por diretriz rigorosa de segurança (OWASP), a NFER não exige nem recomenda o envio de credenciais na query string da URL (?api_key=...). Chaves em URLs podem ser gravadas em logs de proxies, histórico de navegadores e relatórios de analytics.

Para download e visualização de DANFEs (PDF) e XMLs, a NFER gera URLs públicas e imutáveis baseadas na chave de acesso oficial da nota (https://danfe.nfer.me/:chave.pdf e https://xml.nfer.me/:chave.xml), dispensando qualquer exposição de credenciais no navegador do cliente final.

3. Anatomia da Company API Key

As chaves de empresa da NFER possuem uma estrutura delimitada por ponto (.) que garante isolamento de tenant em tempo constante sem expor dados confidenciais:

a0eebc99.sk_live_9f83a71b4c82e01d67a5...

a0eebc99: Prefixo público (mapeia a empresa emissora no banco com indexação rápida).

sk_live_...: Segredo criptográfico de alta entropia, protegido por hash bcrypt no servidor.

4. Exemplos em código

Node.js / TypeScript

const response = await fetch('https://api.nfer.me/v1/nfe', {

method: 'POST',

headers: {

'Content-Type': 'application/json',

'X-API-Key': process.env.NFER_API_KEY!,

body: JSON.stringify(payload),

});

Python

import os, requests

response = requests.post(

'https://api.nfer.me/v1/nfe',

headers={

'Content-Type': 'application/json',

'X-API-Key': os.getenv('NFER_API_KEY'),

json=payload,

)

5. Erros e códigos de status HTTP

Caso as credenciais não sejam validadas corretamente, a API retornará respostas padronizadas com códigos HTTP da família 4xx:

Código HTTP	Erro	Possível Causa e Solução
401 Unauthorized	Chave ausente ou formato inválido	O cabeçalho X-API-Key não foi fornecido, não possui o formato prefixo.segredo ou a chave informada está incorreta.
403 Forbidden	Acesso não autorizado	A empresa está inativa, o período de teste expirou ou foi usada uma chave de organização em rota exclusiva de empresa.
429 Too Many Requests	Limite de taxa excedido	O limite de requisições por minuto contratado no seu plano foi atingido. Aguarde o tempo indicado no cabeçalho Retry-After.

{

"statusCode": 401,

"error": "Unauthorized",

"message": "Chave de API inválida"

}

6. Endpoints públicos (sem autenticação)

As seguintes rotas não exigem chave de API no cabeçalho e podem ser consumidas livremente:

Operação	Método e Rota	Referência Técnica
Health Check da API	GET /health	Ver Health Check →
Status dos Servidores SEFAZ	GET /v1/tools/status-sefaz	Ver Status SEFAZ →
Consulta e Validação de CFOP	GET /v1/tools/cfop	Ver CFOPs →
Consulta e Validação de CNAE	GET /v1/tools/cnae	Ver CNAEs →
Pré-validação de CPF, CNPJ e IE	POST /v1/tools/validate-document	Ver Validações →
Autenticação de Usuário (JWT)	POST /v1/auth/login	Ver JWT Bearer →