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étodoCaminhoDescrição
    POST
    /nfe/emitirEmite NF-e (modelo 55).
    POST
    /nfce/emitirEmite NFC-e (modelo 65).

    Eventos

    MétodoCaminhoDescrição
    POST
    /cancelarCancela uma nota autorizada.
    POST
    /carta-correcaoCorrige dados que não alteram valores nem destinatário.
    POST
    /inutilizarInutiliza uma faixa de numeração não usada.

    Consultas

    Não consomem cota de notas.

    MétodoCaminhoDescrição
    GET
    /consultar/{chave}Situação atual da nota na SEFAZ.
    GET
    /statusDisponibilidade do serviço da SEFAZ.
    GET
    /cotasUso e limite do plano no mês.

    Arquivos

    MétodoCaminhoDescrição
    POST
    /nota/{chave}/xmlXML autorizado da nota.
    POST
    /nota/{chave}/pdfDANFE em PDF.
    POST
    /nota/{chave}/evento/{tipo}/xmlXML do evento (cancelamento, carta de correção).
    POST
    /nota/{chave}/evento/{tipo}/pdfPDF do evento.

    Notas recebidas

    Notas que terceiros emitiram contra o seu CNPJ.

    MétodoCaminhoDescrição
    GET
    /recebidasLista as notas capturadas.
    POST
    /recebidas/sincronizarBusca novidades na SEFAZ agora.
    POST
    /recebidas/{chave}/manifestarManifestação do destinatário.
    GET
    /recebidas/{chave}/xmlXML da nota recebida.

    Contingência

    MétodoCaminhoDescrição
    GET
    /contingenciaSituação atual e tamanho da fila.
    GET
    /contingencia/pendentesNotas aguardando transmissão.
    POST
    /contingencia/ativarEntra em contingência.
    POST
    /contingencia/desativarVolta à 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étodoCaminhoDescrição
    GET
    /empresaDados da empresa, numeração, tributação e certificado. Nunca devolve a senha do certificado nem o token do CSC.
    PUT
    /empresaAtualiza qualquer subconjunto dos dados. O CNPJ não muda.
    PUT
    /empresa/certificadoEnvia o certificado A1 (.pfx/.p12) e a senha, em multipart.
    DELETE
    /empresa/certificadoRemove o certificado.

    Contador

    Envio dos XMLs do mês ao contador.

    MétodoCaminhoDescrição
    GET
    /empresa/contadorCNPJ, e-mails, envio automático e dia do envio.
    PUT
    /empresa/contadorGrava a configuração. Vários e-mails separados por ponto e vírgula.
    POST
    /empresa/contador/enviarEnvia 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étodoCaminhoDescriçã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/usoUso 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

    CampoObrigatórioObservação
    descricaosimDescrição do produto, como sai na DANFE.
    quantidadesimNumérico. Aceita fração conforme a unidade.
    valor_unitariosimNumérico, em reais.
    ncmsim8 dígitos. Errar aqui é a rejeição mais comum.
    cfopnãoPadrão 5102 (venda dentro do estado).
    codigonãoSeu código interno do produto.
    unidadenãoUN, KG, CX… Padrão UN.
    eannãoCódigo de barras, se houver.
    cestnão7 dígitos. Obrigatório em produto com substituição tributária (CSOSN 500). Vale para NF-e e NFC-e.
    csosnnãoSimples Nacional. Padrão 102.
    descontonãoValor absoluto do desconto no item.
    ibs_cbsnãoGrupos da reforma tributária (NT 2025.002).
    icmsnãoNF-e: ICMS destacado. Informe cst (Regime Normal) ou csosn (Simples), mais vbc, picms e vicms.
    ipinãoNF-e: IPI do item (cst, cenq, vbc, pipi, vipi).
    imposto_devolnãoNF-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.

    trecho
    {
      "finalidade": "4",
      "notas_referenciadas": ["35260112345678000195550010000000011000000011"]
    }

    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.

    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 }.

    curl
    curl -X PUT https://notahub.api.br/api/v1/empresa/certificado \
      -H "Authorization: Bearer SUA_API_KEY" \
      -F "arquivo=@certificado.pfx" -F "senha=SUA_SENHA"

    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

    HTTPQuando acontece
    401API Key ausente, inválida ou desativada.
    403Empresa bloqueada, pendente de ativação, ou cota de notas do mês esgotada.
    400Payload inválido, ou a SEFAZ rejeitou a nota. A mensagem traz o motivo.
    404Nota não encontrada, ou não pertence à empresa da sua API Key.
    500Falha 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.