Referência da API

Endpoints, campos obrigatórios e códigos de erro. Base: https://notahub.api.br/api/v1

Como chamar

É HTTP e JSON, sem SDK obrigatório. Toda rota exige a API Key e todas respondem no mesmo envelope.

envelope de resposta

// sucesso
{ "success": true, "data": { … } }

// erro
{ "success": false, "error": { "code": "…", "message": "…", "details": … } }

Autenticação por Authorization: Bearer <chave> ou X-API-Key: <chave>. A chave identifica o emitente, por isso nenhuma rota recebe CNPJ do emitente.

Endpoints

Emissão

Consomem cota de notas do plano.

Método	Caminho	Descrição
POST	/nfe/emitir	Emite NF-e (modelo 55).
POST	/nfce/emitir	Emite NFC-e (modelo 65).

Eventos

Método	Caminho	Descrição
POST	/cancelar	Cancela uma nota autorizada.
POST	/carta-correcao	Corrige dados que não alteram valores nem destinatário.
POST	/inutilizar	Inutiliza uma faixa de numeração não usada.

Consultas

Não consomem cota de notas.

Método	Caminho	Descrição
GET	/consultar/{chave}	Situação atual da nota na SEFAZ.
GET	/status	Disponibilidade do serviço da SEFAZ.
GET	/cotas	Uso e limite do plano no mês.

Arquivos

Método	Caminho	Descrição
POST	/nota/{chave}/xml	XML autorizado da nota.
POST	/nota/{chave}/pdf	DANFE em PDF.
POST	/nota/{chave}/evento/{tipo}/xml	XML do evento (cancelamento, carta de correção).
POST	/nota/{chave}/evento/{tipo}/pdf	PDF do evento.

Notas recebidas

Notas que terceiros emitiram contra o seu CNPJ.

Método	Caminho	Descrição
GET	/recebidas	Lista as notas capturadas.
POST	/recebidas/sincronizar	Busca novidades na SEFAZ agora.
POST	/recebidas/{chave}/manifestar	Manifestação do destinatário.
GET	/recebidas/{chave}/xml	XML da nota recebida.

Contingência

Método	Caminho	Descrição
GET	/contingencia	Situação atual e tamanho da fila.
GET	/contingencia/pendentes	Notas aguardando transmissão.
POST	/contingencia/ativar	Entra em contingência.
POST	/contingencia/desativar	Volta à emissão normal.

Consultas auxiliares

Têm cota própria, separada da de notas.

Método	Caminho	Descrição
GET	/cnpj/{cnpj}	Dados cadastrais na Receita Federal.
GET	/cep/{cep}	Endereço a partir do CEP.
GET	/consultas/uso	Uso de consultas no mês.

POST /nfe/emitir

Só destinatario e itens são obrigatórios. O restante tem padrão.

Destinatário

nome, logradouro, numero, bairro, cidade, uf e cep são obrigatórios, mais cnpj ou cpf. Se você não mandar cod_municipio, ele é herdado do município do emitente.

Itens

Campo	Obrigatório	Observação
descricao	sim	Descrição do produto, como sai na DANFE.
quantidade	sim	Numérico. Aceita fração conforme a unidade.
valor_unitario	sim	Numérico, em reais.
ncm	sim	8 dígitos. Errar aqui é a rejeição mais comum.
cfop	não	Padrão 5102 (venda dentro do estado).
codigo	não	Seu código interno do produto.
unidade	não	UN, KG, CX… Padrão UN.
ean	não	Código de barras, se houver.
csosn	não	Simples Nacional. Padrão 102.
desconto	não	Valor absoluto do desconto no item.
ibs_cbs	não	Grupos da reforma tributária (NT 2025.002).

POST /nfce/emitir

Venda ao consumidor final. O destinatário é opcional (nota sem identificação); em compensação pagamentos importa, porque a NFC-e exige a forma de pagamento. Requer CSC configurado.

corpo

{
  "itens": [
    { "descricao": "Café 500g", "quantidade": 1, "valor_unitario": 32.90, "ncm": "09012100" }
  ],
  "pagamentos": [
    { "forma": "17", "valor": 32.90 }
  ],
  "consumidor": { "cpf": "123.456.789-00" }
}

Formas: 01 dinheiro, 03 cartão de crédito, 04 cartão de débito, 17 PIX.

Erros

HTTP	Quando acontece
401	API Key ausente, inválida ou desativada.
403	Empresa bloqueada, pendente de ativação, ou cota de notas do mês esgotada.
400	Payload inválido, ou a SEFAZ rejeitou a nota. A mensagem traz o motivo.
404	Nota não encontrada, ou não pertence à empresa da sua API Key.
500	Falha interna. Consulte a nota pela chave antes de tentar de novo.

Rejeição da SEFAZ chega como 400 com o texto original dela em error.message — inclusive o número da rejeição, que é o que você pesquisa para entender a causa.

Webhooks

Em vez de consultar a nota em laço, cadastre uma URL no portal e receba a mudança de status. Cada entrega leva uma assinatura HMAC-SHA256 do corpo, com o segredo que aparece só na criação do endpoint.

headers da entrega

X-NotaHub-Evento: nota_autorizada
X-NotaHub-Entrega: 4821
X-NotaHub-Tentativa: 1
X-NotaHub-Assinatura: sha256=a3f1…

Confira a assinatura antes de confiar no corpo. Reentrega com espera crescente de 1 minuto a 6 horas; depois de 20 falhas seguidas o endpoint é desativado.

Voltar ao guia de início rápido Falar com o suporte