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.
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. |
Empresa
Configuração da empresa da API Key, para sistemas que não usam o portal. Detalhes na seção Configurar a empresa.
| Método | Caminho | Descrição |
|---|---|---|
GET | /empresa | Dados da empresa, numeração, tributação e certificado. Nunca devolve a senha do certificado nem o token do CSC. |
PUT | /empresa | Atualiza qualquer subconjunto dos dados. O CNPJ não muda. |
PUT | /empresa/certificado | Envia o certificado A1 (.pfx/.p12) e a senha, em multipart. |
DELETE | /empresa/certificado | Remove o certificado. |
Contador
Envio dos XMLs do mês ao contador.
| Método | Caminho | Descrição |
|---|---|---|
GET | /empresa/contador | CNPJ, e-mails, envio automático e dia do envio. |
PUT | /empresa/contador | Grava a configuração. Vários e-mails separados por ponto e vírgula. |
POST | /empresa/contador/enviar | Envia o pacote de uma competência agora (mes_ano: YYYY-MM). |
GET | /empresa/contador/envios | Últimos envios (parâmetro limite, padrão 12). |
Consultas auxiliares
Têm cota própria, separada da de notas.
| Método | Caminho | Descrição |
|---|---|---|
GET | /cnpj/{cnpj} | Dados cadastrais na Receita Federal, com a inscrição estadual (ie, ie_situacao e inscricoes_estaduais). |
GET | /cadastro/{uf}/{cnpj} | Cadastro do contribuinte na SEFAZ da UF (IE, situação, regime), com o certificado da empresa. Conta na cota de CNPJ. |
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. |
| cest | não | 7 dígitos. Obrigatório em produto com substituição tributária (CSOSN 500). Vale para NF-e e NFC-e. |
| 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). |
| icms | não | NF-e: ICMS destacado. Informe cst (Regime Normal) ou csosn (Simples), mais vbc, picms e vicms. |
| ipi | não | NF-e: IPI do item (cst, cenq, vbc, pipi, vipi). |
| imposto_devol | não | NF-e de devolução (finalidade 4): pdevol (%) e vipidevol. |
Notas referenciadas
notas_referenciadas é uma lista de até 10 chaves de acesso (44 dígitos, com o dígito verificador correto) que vão no grupo NFref da nota. Use com finalidade: "4" (devolução) para apontar a nota original. Sem o campo, a nota sai como antes.
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.
Formas: 01 dinheiro, 03 cartão de crédito, 04 cartão de débito, 17 PIX.
Configurar a empresa
Um PDV pode preparar a empresa inteira pela API, sem passar pelo portal. Os nomes dos campos são em snake_case.
PUT /empresa
Aceita qualquer subconjunto de razao_social, nome_fantasia, ie, im, cep, logradouro, numero, complemento, bairro, cidade, uf, cod_municipio, ambiente, ambiente_nfe, serie_nfce, serie_nfe, pis, cofins, cfop_padrao, csc_id e csc_token. Campo fora da lista, e o cnpj, são recusados com 400.
ultima_nfce e ultima_nfe servem para migrar a numeração de outro emissor: só podem aumentar (ou ficar iguais). Informar um número menor que o atual devolve 400.
PUT /empresa/certificado
Multipart com arquivo (.pfx ou .p12, até 2 MB) e senha. O NotaHUB abre o arquivo, confere o CNPJ (a raiz de 8 dígitos precisa ser a da empresa) e a validade, e só então grava. A resposta é { nome, validade, cnpj }.
Erros (400): CERT_SENHA_INCORRETA, CERT_ARQUIVO_INVALIDO, CERT_CNPJ_DIFERENTE e CERT_VENCIDO. Certificado em formato antigo devolve CERT_FORMATO_NAO_SUPORTADO: reexporte o .pfx com AES-256.
Contador
PUT /empresa/contador aceita cnpj_contador, email_contador (vários separados por ;), envio_automatico e dia_envio (1 a 28). Para ligar o envio automático é preciso ter e-mail. POST /empresa/contador/enviar devolve enviado, sem_notas, quantidade, tamanho e, se falhou, erro.
GET /cadastro/{uf}/{cnpj}
Consulta o cadastro do contribuinte na SEFAZ da UF informada. Devolve ie, razao_social, situacao, regime (CRT, quando a SEFAZ informa) e endereco. Nem toda UF oferece o serviço: nesse caso a resposta é 400 com "UF sem consulta de cadastro".
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.
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.