Referência da API

Introdução à Referência da API

Visão geral técnica da API REST NFER: convenções de comunicação, autenticação, ambientes, padronização de erros, paginação e limites de taxa.

A API REST NFER permite a integração direta de sistemas de gestão (ERP, PDV, CRM e e-commerce) com os servidores autorizadores da SEFAZ e com o Ambiente de Dados Nacional (ADN). Todas as requisições devem ser feitas exclusivamente via protocolo HTTPS.

Base URL da API

HTTPShttps://api.nfer.me/v1

Recomenda-se o uso de TLS 1.2 ou superior. As requisições que enviam corpo JSON devem incluir o cabeçalho Content-Type: application/json.

Autenticação

A autenticação é feita enviando sua chave de API no cabeçalho HTTP X-API-Key em todas as chamadas operacionais.

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

-H "X-API-Key: sua_chave_de_api" \

-H "Content-Type: application/json"

Gestão de Chaves

Para entender como obter, rotacionar e gerenciar chaves de empresa e de organização, consulte o guia completo de Autenticação.

Ambientes (Homologação × Produção)

A NFER suporta emissão nos dois ambientes fiscais disponibilizados pelos órgãos autorizadores:

homologacao

Ambiente de testes conectado aos servidores de homologação da SEFAZ e ADN. As notas emitidas não possuem valor fiscal e levam a marca d'água de homologação. Ideal para testes de integração e validação de layouts.

producao

Ambiente de emissão oficial. As notas geradas são transmitidas aos servidores de produção da SEFAZ/Receita Federal e possuem validade fiscal e jurídica plena.

O ambiente pode ser informado individualmente no payload de emissão através do campo ambiente: "homologacao" | "producao" ou configurado como padrão no cadastro da empresa.

Formato de Erro

Quando uma requisição não pode ser processada, a API responde com o código de status HTTP correspondente e um corpo JSON estruturado com os detalhes da falha:

{

"error": "validation_error",

"message": "Parâmetros obrigatórios ausentes ou inválidos.",

"details": [

{

"field": "destinatario.cpfCnpj",

"error": "CPF ou CNPJ informado é inválido."

}

]

}

Códigos de Status HTTP Frequentes

Código	Nome	Significado
200 / 201	OK / Created	Operação processada com sucesso.
400	Bad Request	Payload JSON malformado ou parâmetros inválidos.
401	Unauthorized	Chave de API ausente, inválida ou expirada no cabeçalho X-API-Key.
403	Forbidden	Credencial sem permissão para acessar o recurso da empresa solicitada.
404	Not Found	Recurso fiscal, empresa ou documento não encontrado.
422	Unprocessable Entity	Falha em regra fiscal de negócio ou rejeição de esquema da SEFAZ.
429	Too Many Requests	Limite de requisições por segundo ou por minuto excedido.
500	Internal Server Error	Falha interna inesperada no processamento da API.
502	Bad Gateway	Servidor autorizador da SEFAZ ou ADN offline ou instável.

Paginação

Endpoints que retornam múltiplos registros (como listagem de notas, clientes ou produtos) adotam paginação via query parameters:

Parâmetro	Tipo	Padrão	Descrição
`page`	integer	1	Número da página desejada (base 1).
`limit`	integer	20	Quantidade máxima de itens por página (máximo 100).
`offset`	integer	0	Deslocamento inicial alternativo para paginação baseada em cursor.

{

"data": [

{ "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "numero": 101, "status": "autorizada" },

{ "id": "c3a1d94f-5192-4e63-8a3b-9e4a8b7c9120", "numero": 102, "status": "autorizada" }

"meta": {

"page": 1,

"limit": 20,

"total": 142,

"totalPages": 8

}

Limites de Requisição (Rate Limit)

Para garantir alta disponibilidade e proteção contra picos excessivos, a API NFER aplica limites de taxa baseados no plano contratado. Todas as respostas HTTP incluem cabeçalhos informando o estado da sua cota:

Cabeçalho HTTP	Descrição
`X-RateLimit-Limit`	Número máximo de requisições permitidas dentro da janela de tempo atual.
`X-RateLimit-Remaining`	Quantidade de requisições restantes que você ainda pode executar na janela vigente.
`X-RateLimit-Reset`	Timestamp em segundos (Unix Epoch UTC) em que a janela de limite será reiniciada.
`Retry-After`	Retornado quando o status é 429 Too Many Requests, indicando quantos segundos seu cliente deve aguardar antes de tentar novamente.

Boas Práticas para Evitar Erros 429

Para operações de emissão em lote ou filas de alto volume, implemente retentativas automáticas com recuo exponencial (exponential backoff) e respeite o valor do cabeçalho Retry-After.