Referência interativa disponível

Para spec OpenAPI completa, schemas e "Try it" inline, use a API Reference — Consulta NF-e Distribuição. Esta página documenta o uso prático; a referência tem o contrato completo.

Endpoints /inbound/nfe (analítico/exportação)

Esta página cobre a API de NF-e sob /inbound/productinvoices. Há também a família mais recente GET /v2/companies/{companyId}/inbound/nfe[/{accessKey}][/xml|/pdf] — orientada a exportação analítica (CSV) e listagem — documentada na API Reference — NFS-e Inbound (Captura Fiscal), sob a tag NFe Inbound. Os dois caminhos consultam o mesmo acervo de NF-e recebidas. Resumo em Família /inbound/nfe.

Endpoints de NF-e

Referência dos endpoints HTTP do serviço NFe Inbound para operações com NF-e (modelo 55).

Sumário

• Buscar Metadados de uma NF-e
• Baixar XML de uma NF-e
• Baixar PDF (DANFE) de uma NF-e
• Buscar Dados de um Evento de NF-e
• Registrar Manifestação
• Eventos de manifestação da Reforma Tributária
• Reprocessar Webhook de uma NF-e
• Família /inbound/nfe (listagem e download para exportação)

Buscar Metadados de uma NF-e

Retorna os dados estruturados de uma NF-e pela sua chave de acesso.

GET /v2/companies/{company_id}/inbound/productinvoices/{access_key}
Authorization: ApiKey {api_key}

Parâmetros de URL:

• company_id: ID da sua empresa na nfe.io
• access_key: Chave de acesso de 44 dígitos da NF-e

Resposta de sucesso (200):

{
  "accessKey": "35240112345678000195550010000012341234567890",
  "createdOn": "2024-03-15T14:22:10Z",
  "nsu": "21825",
  "nsuParent": null,
  "nfeNumber": "1234",
  "nfeSerialNumber": "1",
  "issuedOn": "2024-03-15T10:00:00Z",
  "type": "productInvoice",
  "description": "Autorizado o uso da NF-e",
  "totalInvoiceAmount": "1500.00",
  "operationType": "Incoming",
  "issuer": {
    "federalTaxNumber": "12345678000195",
    "name": "Fornecedor LTDA"
  },
  "buyer": {
    "federalTaxNumber": "98765432000100",
    "name": "Minha Empresa S.A."
  },
  "company": {
    "id": "comp_123",
    "federalTaxNumber": "98765432000100"
  },
  "links": {
    "xml": "https://storage.nfe.io/temp/xml/...",
    "pdf": "https://storage.nfe.io/temp/pdf/..."
  }
}

Descrição dos campos:

Campo	Tipo	Descrição
accessKey	string	Chave de acesso 44 dígitos
createdOn	DateTime	Quando o documento entrou no sistema
nsu	string	Número Sequencial Único na SEFAZ
nfeNumber	string	Número da NF-e
nfeSerialNumber	string	Série da NF-e
issuedOn	DateTime	Data de emissão
type	string	productInvoice, productInvoiceEvent, productInvoiceSummary
description	string	Status da NF-e (ex: "Autorizado o uso da NF-e")
totalInvoiceAmount	string	Valor total em reais
operationType	string	Incoming (destinatário) ou Outgoing (emitente)
issuer	object	Dados do emitente (quem emitiu a NF-e)
buyer	object	Dados do destinatário (comprador)
links.xml	string	URL temporária para download do XML (expira em 1 hora)
links.pdf	string	URL temporária para download do PDF/DANFE

Baixar XML de uma NF-e

GET /v2/companies/{company_id}/inbound/{access_key}/xml
Authorization: ApiKey {api_key}

# Retorna 200 JSON: {"publicTemporaryUri": "https://...xml"}
# — não é o arquivo XML direto. Baixe o XML a partir dessa URL.

Alternativamente, use a URL temporária retornada em links.xml para download direto do storage (sem precisar passar pela API). Esse link expira em 1 hora.

Baixar PDF (DANFE) de uma NF-e

GET /v2/companies/{company_id}/inbound/{access_key}/pdf
Authorization: ApiKey {api_key}

# Retorna 200 JSON: {"publicTemporaryUri": "https://...pdf"}
# — não é o arquivo PDF direto. Baixe o PDF a partir dessa URL.

Buscar Dados de um Evento de NF-e

Eventos são ações sobre a NF-e: cancelamento, ciência, confirmação de operação, etc.

GET /v2/companies/{company_id}/inbound/productinvoices/{access_key}/events/{event_key}
Authorization: ApiKey {api_key}

O event_key tem 55 dígitos (chave de acesso da NF-e + código do evento + sequência).

Registrar Manifestação

A manifestação é o processo pelo qual o destinatário comunica à SEFAZ que tem conhecimento da NF-e. É obrigatória para NF-es de entrada.

POST /v2/companies/{company_id}/inbound/{access_key}/manifest?tpEvent=210210
Authorization: ApiKey {api_key}

Tipos de manifestação (tpEvent):

Código	Tipo	Descrição
210210	Ciência da Operação	"Estou ciente desta NF-e" (não confirma recebimento físico)
210200	Confirmação da Operação	"Recebi a mercadoria conforme NF-e"
210220	Desconhecimento da Operação	"Não reconheço esta operação"
210240	Operação não Realizada	"A operação não foi concluída"

Resposta (200):

"Manifestação registrada com sucesso"

Manifestação Automática: Se você configurou AutomaticManifesting.MinutesToWaitAwarenessOperation, o sistema registrará "Ciência da Operação" automaticamente após esse intervalo. Você não precisa chamar este endpoint para ciência se tiver auto-manifestação ativa.

Eventos de manifestação da Reforma Tributária (manifestation-events)

Os quatro códigos acima cobrem a manifestação do destinatário clássica. A NT 2025.002-RTC criou uma família nova de eventos (crédito presumido, imobilização, perecimento, sucessão de crédito IBS/CBS, cancelamento de evento), submetidos por um endpoint próprio — assíncrono:

POST /v2/companies/{companyId}/inbound/productinvoices/by-access-key/{accessKey}/manifestation-events
Authorization: ApiKey {api_key}
Content-Type: application/json

{
  "eventCode": 211128,
  "nSequencia": 1,
  "detail": { "indAceitacao": "1" }
}

Campo	Obrigatório	Descrição
eventCode	Sim	Código numérico do evento (tpEvento). Ver tabela completa
nSequencia	Não	Sequência do evento (nSeqEvento), default 1. Valores > 1 são para re-submissões legítimas de eventos multi-sequência. < 1 retorna 400
detail	Depende	Corpo específico do evento. null é aceito nos códigos que não têm campos próprios (210200, 210210, 210220)

Resposta 202 Accepted com o evento em status: Pending e o header Location apontando para o detalhe. A submissão à SEFAZ é feita em segundo plano — acompanhe por polling:

GET /v2/companies/{companyId}/inbound/productinvoices/by-access-key/{accessKey}/manifestation-events
GET /v2/companies/{companyId}/inbound/productinvoices/manifestation-events/{id}

A listagem vem em ordem decrescente de criação. O detalhe por id inclui os XMLs de request e response (gzip + base64) para auditoria e replay.

Estados: Pending → Accepted / Rejected / Failed.

Código	Quando
202	Aceito para submissão
400	eventCode desconhecido, código somente leitura do Fisco (412120/412130), 211120 (revogado), nSequencia < 1 ou detail inválido para o código
404	NF-e não encontrada para essa chave nesta empresa
409	Já existe um evento em voo para a mesma (accessKey, eventCode, nSequencia)

Idempotência é por (accessKey, eventCode, nSequencia)

Reenviar o mesmo evento com o mesmo nSequencia enquanto o anterior está em voo retorna 409 — não duplica a submissão à SEFAZ. Para uma re-submissão legítima de evento multi-sequência, incremente nSequencia.

Acesso cruzado entre contas responde 404

Consultar um manifestation-events/{id} de outra conta retorna 404, não 403 — por defesa em profundidade, para não vazar a existência do id entre contas.

Reprocessar Webhook de uma NF-e

Use quando o webhook não foi entregue ou precisa ser reenviado.

POST /v2/companies/{company_id}/inbound/productinvoices/{access_key}/processwebhook
Authorization: ApiKey {api_key}

# Ou por NSU:
POST /v2/companies/{company_id}/inbound/productinvoices/{nsu}/processwebhook

Família /inbound/nfe (listagem e download para exportação)

Caminho alternativo sobre o mesmo acervo, com paginação por página (em vez de por NSU) e download por redirect assinado. É o que alimenta o exportador analítico CSV e a listagem do console.

Método	Path	Propósito
GET	/v2/companies/{companyId}/inbound/nfe	Lista NF-e recebidas. Filtros: issuedBegin, issuedEnd, environmentType, pageIndex, pageCount
GET	.../inbound/nfe/{accessKey}	Detalhe de uma NF-e ou evento pela chave de 44 dígitos
GET	.../inbound/nfe/{accessKey}/xml	302 para URL assinada do XML
GET	.../inbound/nfe/{accessKey}/pdf	302 para URL assinada do DANFE

• pageCount: 0 usa o default de 50; acima de 200 retorna 400. pageIndex é 1-based. issuedBegin > issuedEnd retorna 400.
• Cada item da listagem traz relatedIds — os ids dos eventos vinculados à mesma chave de acesso. Resolva cada um pelo GET .../inbound/nfe/{accessKey} para montar a nota com seus eventos (é assim que o CSV analítico achata o evento primário na linha da nota).
• Os downloads respondem 302 com Location apontando para uma URL HMAC de mesma origem (evita o preflight CORS do redirect direto ao storage). Clientes HTTP e o fetch com redirect: 'follow' seguem o redirect de forma transparente. A URL assinada vale 60 minutos — não a cacheie.
• O DANFE só existe no modelo 55: eventos e modelo 65 (NFC-e) retornam 404 sem corpo. Diferente do XML, o DANFE é gerado de forma lazy — o endpoint garante a geração antes de emitir o redirect.

Veja também

• Endpoints de CT-e
• Webhook events + HMAC
• Tipos e enums
• Códigos HTTP e tratamento de erros
• Manifestar NF-e
• Ativar via API