NF-e

Nota Fiscal Eletrônica

Modelo 55. Todas as rotas abaixo exigem um token com a NF-e habilitada na empresa. Use um ref seu na emissão e reutilize o mesmo valor nas outras chamadas.

Fluxo recomendado

POST para emitir → GET até status autorizado ou erro_autorizacao → GET .xml e .pdf → POST /email para reenviar → DELETE se precisar cancelar. Carta de correção e inutilização serão documentadas na próxima fase.

Resumo das rotas

Método	Rota	Função
POST	`/v2/nfe?ref={ref}`	Emitir
GET	`/v2/nfe/{ref}`	Consultar
GET	`/v2/nfe/{ref}.xml`	Baixar XML
GET	`/v2/nfe/{ref}.pdf`	Baixar DANFE
POST	`/v2/nfe/{ref}/email`	Enviar por e-mail
DELETE	`/v2/nfe/{ref}`	Cancelar

POST/v2/nfe?ref=pedido-1001

Emitir NF-e

Envia uma NF-e para autorização na SEFAZ. O identificador da nota no seu sistema é o ref, informado na query string.

O mesmo ref não emite duas vezes

Se o ref já existir e a nota não estiver em erro_autorizacao, a API devolve o documento já gravado (HTTP 200) em vez de criar outro.

Parâmetros

Nome	Onde	Tipo	Uso	Descrição
`ref`	query	string	Obrigatório	Identificador único no seu sistema. Letras, números, ponto, hífen ou underscore. Máximo de 80 caracteres.

Corpo JSON

Campo	Tipo	Uso	Descrição
`natureza_operacao`	string	Obrigatório	Natureza da operação, por exemplo Venda de mercadoria.
`cnpj_destinatario`	string	Opcional	CNPJ do destinatário. Informe este campo ou cpf_destinatario.
`cpf_destinatario`	string	Opcional	CPF do destinatário, quando a nota não for para CNPJ.
`nome_destinatario`	string	Obrigatório	Razão social ou nome do destinatário.
`logradouro_destinatario`	string	Obrigatório	Logradouro do destinatário.
`numero_destinatario`	string	Opcional	Número do endereço. Se omitido, a API usa S/N.
`bairro_destinatario`	string	Obrigatório	Bairro do destinatário.
`municipio_destinatario`	string	Obrigatório	Município do destinatário. A API resolve o código IBGE.
`uf_destinatario`	string	Obrigatório	UF do destinatário, com 2 letras.
`cep_destinatario`	string	Opcional	CEP do destinatário, com ou sem máscara.
`email_destinatario`	string	Opcional	E-mail do destinatário. Se o envio automático estiver ligado na empresa, a API usa este endereço após a autorização.
`items`	array	Obrigatório	Lista de itens. Também aceita a chave itens. Cada item precisa de descricao, codigo_ncm e cfop.
`serie`	number	Opcional	Série da NF-e. Se omitida, usa a numeração padrão da empresa no ambiente do token.
`numero`	number	Opcional	Número da NF-e. Se omitido, a API incrementa a numeração da empresa.

Exemplo de requisição

curl -X POST "https://api.nfintegrada.com.br/v2/nfe?ref=pedido-1001" \
  -u "SEU_TOKEN:" \
  -H "Content-Type: application/json" \
  -d '{
    "natureza_operacao": "Venda de mercadoria",
    "cnpj_destinatario": "00000000000191",
    "nome_destinatario": "Empresa Destinataria LTDA",
    "logradouro_destinatario": "Rua das Flores",
    "numero_destinatario": "100",
    "bairro_destinatario": "Centro",
    "municipio_destinatario": "Sao Paulo",
    "uf_destinatario": "SP",
    "cep_destinatario": "01001000",
    "email_destinatario": "cliente@exemplo.com",
    "items": [
        {
            "numero_item": 1,
            "codigo_produto": "001",
            "descricao": "Produto exemplo",
            "codigo_ncm": "61091000",
            "cfop": "5102",
            "unidade_comercial": "UN",
            "quantidade_comercial": "1.0000",
            "valor_unitario_comercial": "10.00"
        }
    ]
}'

Respostas

HTTP	Situação	O que acontece
201	Autorizada	A SEFAZ autorizou a NF-e. status fica autorizado e os caminhos de XML e DANFE são preenchidos.
202	Em processamento	O lote foi recebido, mas a autorização ainda não chegou. Consulte o mesmo ref em seguida.
200	Já existente	O ref já tinha sido usado e a nota não está em erro_autorizacao. A API devolve o documento atual.

{
    "cnpj_emitente": "12345678000199",
    "ref": "pedido-1001",
    "status": "autorizado",
    "status_sefaz": "100",
    "mensagem_sefaz": "Autorizado o uso da NF-e",
    "chave_nfe": "35260912345678000199550010000000011234567890",
    "numero": 1,
    "serie": 1,
    "caminho_xml_nota_fiscal": "/v2/nfe/pedido-1001.xml",
    "caminho_danfe": "/v2/nfe/pedido-1001.pdf",
    "mensagem": "Autorizado o uso da NF-e"
}

Erros comuns

HTTP	Código	Mensagem
401	`token_invalido`	Token ausente, inválido ou inativo.
403	`documento_nao_habilitado`	A NF-e não está habilitada para esta empresa.
422	`ref_invalida`	O ref não foi informado ou contém caracteres inválidos.
422	`json_invalido`	O corpo não é um objeto JSON.
422	`pending_operation`	A nota deste ref ainda está em processamento.
422	`erro_validacao_schema`	Campos obrigatórios ausentes ou inválidos. A resposta traz o array erros.
422	`certificado_ausente`	A empresa não possui certificado A1 ativo ou o certificado está vencido.
422	`erro_autorizacao`	A SEFAZ rejeitou o documento. Reenvie o mesmo ref após corrigir os dados.

GET/v2/nfe/pedido-1001

Consultar NF-e

Retorna o documento pelo ref. Se a nota ainda estiver em processamento, a API consulta a SEFAZ de novo antes de responder.

Parâmetros

Nome	Onde	Tipo	Uso	Descrição
`ref`	path	string	Obrigatório	O mesmo ref usado na emissão. Também aceita ?ref= na query string.

Exemplo de requisição

curl -X GET "https://api.nfintegrada.com.br/v2/nfe/pedido-1001" \
  -u "SEU_TOKEN:"

Respostas

HTTP	Situação	O que acontece
200	Encontrada	Devolve o JSON do documento, com o status atualizado.

{
    "cnpj_emitente": "12345678000199",
    "ref": "pedido-1001",
    "status": "processando_autorizacao",
    "status_sefaz": "103",
    "mensagem_sefaz": "Lote recebido, aguardando processamento.",
    "chave_nfe": "35260912345678000199550010000000011234567890",
    "numero": 1,
    "serie": 1,
    "caminho_xml_nota_fiscal": null,
    "caminho_danfe": null,
    "mensagem": "Lote recebido, aguardando processamento."
}

Erros comuns

HTTP	Código	Mensagem
404	`nao_encontrado`	Não existe documento com este ref para o token e o ambiente atuais.
422	`ref_invalida`	Informe o ref na URL (/v2/nfe/{ref}) ou na query (?ref=).

GET/v2/nfe/pedido-1001.xml

Baixar XML

Baixa o XML autorizado da NF-e. A resposta não é JSON: o Content-Type é application/xml.

Quando o arquivo existe

O XML só fica disponível depois que a nota é autorizada. O campo caminho_xml_nota_fiscal da consulta aponta para esta URL.

Parâmetros

Nome	Onde	Tipo	Uso	Descrição
`ref`	path	string	Obrigatório	Identificador da nota, com o sufixo .xml.

Exemplo de requisição

curl -X GET "https://api.nfintegrada.com.br/v2/nfe/pedido-1001.xml" \
  -u "SEU_TOKEN:"

Respostas

HTTP	Situação	O que acontece
200	Arquivo XML	Corpo em application/xml, com Content-Disposition para download.

Erros comuns

HTTP	Código	Mensagem
404	`nao_encontrado`	Documento não encontrado para este ref.
404	`xml_nao_encontrado`	O XML deste documento ainda não está disponível.

GET/v2/nfe/pedido-1001.pdf

Baixar DANFE

Gera ou devolve o PDF da DANFE. O Content-Type é application/pdf.

Parâmetros

Nome	Onde	Tipo	Uso	Descrição
`ref`	path	string	Obrigatório	Identificador da nota, com o sufixo .pdf.

Exemplo de requisição

curl -X GET "https://api.nfintegrada.com.br/v2/nfe/pedido-1001.pdf" \
  -u "SEU_TOKEN:"

Respostas

HTTP	Situação	O que acontece
200	Arquivo PDF	Corpo em application/pdf, exibido inline no navegador.

Erros comuns

HTTP	Código	Mensagem
404	`nao_encontrado`	Documento não encontrado para este ref.
404	`pdf_nao_encontrado`	O DANFE deste documento ainda não está disponível.

POST/v2/nfe/pedido-1001/email

Enviar NF-e por e-mail

Envia o XML e o DANFE da NF-e para até 10 destinatários. Só funciona com status autorizado. A API confirma o recebimento; o envio usa o correio do servidor.

Mesmo contrato da Focus

O corpo é {"emails":["cliente@exemplo.com"]}. Se a empresa estiver com “Enviar email ao destinatário” ligado, a autorização também dispara o envio para email_destinatario informado na emissão.

Parâmetros

Nome	Onde	Tipo	Uso	Descrição
`ref`	path	string	Obrigatório	O mesmo ref usado na emissão.

Corpo JSON

Campo	Tipo	Uso	Descrição
`emails`	array	Obrigatório	Lista de e-mails que receberão XML e DANFE. Máximo de 10 endereços.

Exemplo de requisição

curl -X POST "https://api.nfintegrada.com.br/v2/nfe/pedido-1001/email" \
  -u "SEU_TOKEN:" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
        "cliente@exemplo.com",
        "financeiro@exemplo.com"
    ]
}'

Respostas

HTTP	Situação	O que acontece
200	Agendado	Os e-mails foram aceitos e enviados. A resposta confirma os destinatários.

{
    "mensagem": "Emails agendados para envio",
    "emails": [
        "cliente@exemplo.com",
        "financeiro@exemplo.com"
    ]
}

Erros comuns

HTTP	Código	Mensagem
400	`requisicao_invalida`	Parâmetro "emails" não informado.
400	`nfe_nao_autorizada`	NF-e não autorizada.
404	`nao_encontrado`	Documento não encontrado para este ref.
405	`metodo_nao_permitido`	Use POST em /v2/nfe/{ref}/email.

DELETE/v2/nfe/pedido-1001

Cancelar NF-e

Envia o evento de cancelamento para a SEFAZ. Só é possível cancelar uma NF-e com status autorizado.

Corpo JSON

Campo	Tipo	Uso	Descrição
`justificativa`	string	Obrigatório	Motivo do cancelamento. Mínimo de 15 caracteres.

Exemplo de requisição

curl -X DELETE "https://api.nfintegrada.com.br/v2/nfe/pedido-1001" \
  -u "SEU_TOKEN:" \
  -H "Content-Type: application/json" \
  -d '{
    "justificativa": "Cancelamento solicitado pelo destinatario"
}'

Respostas

HTTP	Situação	O que acontece
200	Cancelada	A SEFAZ aceitou o cancelamento, ou a nota já estava cancelada. status passa para cancelado.

{
    "cnpj_emitente": "12345678000199",
    "ref": "pedido-1001",
    "status": "cancelado",
    "status_sefaz": "135",
    "mensagem_sefaz": "Evento registrado e vinculado a NF-e",
    "chave_nfe": "35260912345678000199550010000000011234567890",
    "numero": 1,
    "serie": 1,
    "caminho_xml_nota_fiscal": "/v2/nfe/pedido-1001.xml",
    "caminho_danfe": "/v2/nfe/pedido-1001.pdf",
    "mensagem": "Evento registrado e vinculado a NF-e"
}

Erros comuns

HTTP	Código	Mensagem
404	`nao_encontrado`	Documento não encontrado para este ref.
422	`justificativa_invalida`	A justificativa do cancelamento deve ter no mínimo 15 caracteres.
422	`nao_autorizado`	Só é possível cancelar uma NF-e autorizada.