Começar

Conceitos

Estes conceitos se repetem em todos os endpoints. Entenda o ref, o ambiente do token, os status da nota e o formato de erro antes de emitir a primeira NF-e.

ref

O ref é o identificador da nota no seu sistema. Você escolhe o valor na emissão (?ref=pedido-1001) e usa o mesmo valor para consultar, baixar XML/PDF e cancelar.

Regra	Detalhe
Tamanho	De 1 a 80 caracteres.
Caracteres	Letras, números, ponto, hífen e underscore.
Escopo	Único por empresa, tipo de documento (nfe) e ambiente do token.
Onde vai	Na emissão: query string. Nas demais chamadas: path /v2/nfe/{ref}, /v2/nfe/{ref}.xml, /v2/nfe/{ref}.pdf ou /v2/nfe/{ref}/email.

Idempotência

Reenviar o mesmo ref não cria outra nota, exceto se o status atual for erro_autorizacao — nesse caso a API tenta autorizar de novo com o JSON novo.

Ambiente

Homologação e produção não se misturam. O token define o ambiente; documentos, numeração e consultas ficam separados. Uma consulta com token de homologação nunca encontra uma nota emitida em produção.

Status do documento

O campo status descreve o ciclo da NF-e. Use também status_sefaz e mensagem_sefaz para o retorno da SEFAZ.

status	Significado	O que fazer
`processando_autorizacao`	Lote enviado, autorização ainda não confirmada.	Consulte o mesmo ref até o status mudar.
`autorizado`	NF-e autorizada na SEFAZ.	Baixe XML e DANFE, ou envie por e-mail. Cancele só neste status.
`erro_autorizacao`	A SEFAZ rejeitou ou houve falha no envio.	Corrija o JSON e reenvie com o mesmo ref.
`denegado`	Uso denegado pela SEFAZ.	Não reprocessa automaticamente. Trate o caso no seu sistema.
`cancelado`	Cancelamento autorizado.	A nota permanece consultável, agora cancelada.
`erro_cancelamento`	Falha ao cancelar na SEFAZ.	Verifique a justificativa e tente o DELETE novamente.

Campos da resposta

A consulta e a emissão devolvem o mesmo objeto de documento:

Campo	Descrição
`cnpj_emitente`	CNPJ da empresa do token.
`ref`	Identificador que você enviou.
`status`	Status interno da API, conforme a tabela acima.
`status_sefaz`	Código cStat devolvido pela SEFAZ, quando houver.
`mensagem_sefaz`	Texto da SEFAZ ou mensagem interna do processamento.
`chave_nfe`	Chave de 44 dígitos, ou null se ainda não existir.
`numero`	Número da NF-e atribuído na emissão.
`serie`	Série da NF-e.
`caminho_xml_nota_fiscal`	Path relativo do XML, preenchido após autorização.
`caminho_danfe`	Path relativo do PDF da DANFE, preenchido após autorização.
`mensagem`	Mensagem resumida, em geral igual à da SEFAZ.

Formato de erro

Erros usam HTTP 4xx/5xx e um JSON com codigo e mensagem. Códigos HTTP usados pela API:

HTTP	Uso
200	Consulta, cancelamento, ou reenvio de um ref já existente.
201	NF-e autorizada na emissão.
202	NF-e aceita e ainda em processamento.
401	Falha de autenticação.
403	Documento fiscal não habilitado para a empresa.
404	Documento, XML ou PDF não encontrado.
405	Método HTTP não permitido na rota.
422	Validação, rejeição da SEFAZ ou operação incompatível com o status.
500	Erro interno ao gravar o documento.

{
    "codigo": "erro_validacao_schema",
    "mensagem": "Erro na validação dos dados da NF-e.",
    "erros": [
        {
            "campo": "natureza_operacao",
            "mensagem": "Informe a natureza da operação."
        },
        {
            "campo": "items[1].cfop",
            "mensagem": "Informe o CFOP do item 1."
        }
    ]
}

XML e PDF não são JSON

As rotas .xml e .pdf devolvem o arquivo binário/texto correspondente. Trate 404 em JSON e 200 como download.