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
• Rota legada POST /manifest (depreciada)
• Empresa com inbound de NF-e desativado
• 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",
  "direction": "Received",
  "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 (texto, não número)
nsuParent	string	NSU da NF-e referenciada (eventos)
nfeNumber	string	Número da NF-e
nfeSerialNumber	string	Série da NF-e
issuedOn	DateTime	NF-e completa (productInvoice): data de emissão (dhEmi). Resumos (productInvoiceSummary / productInvoiceEventSummary): data de recebimento na SEFAZ (dhRecbto) / data do evento (dhEvento). Veja issuedOn dos resumos
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)
direction	string	Received (nota recebida de terceiro) ou Issued (nota emitida pela própria empresa que retornou na distribuição)
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
blobUrl	string	Referência interna de armazenamento. Não dependa deste campo; para baixar arquivos use as rotas /xml e /pdf

issuedOn dos resumos de NF-e

Nos resumos (productInvoiceSummary, productInvoiceEventSummary) o issuedOn vem de dhRecbto (recebimento na SEFAZ) ou de dhEvento, e não de dhEmi. É por desenho: o resumo não traz a data de emissão. Com webhookVersion 3, o valor sai no offset do XML (ex.: 2026-09-22T10:15:30-03:00); um defeito que deslocava esse valor em +3h foi corrigido. Com webhookVersion 2 ou anterior, o formato segue inalterado (+00:00). A NF-e completa (productInvoice) usa dhEmi.

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.

Para um resumo (productInvoiceSummary), o XML disponível é o do resumo (resNFe). O XML completo (procNFe) só é liberado pela SEFAZ depois da manifestação do destinatário. Veja Resumo ou documento completo.

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.

O DANFE só existe para a NF-e completa (type: productInvoice). Se a chave corresponde a um resumo (productInvoiceSummary) ou a um evento e ainda não há PDF gerado, a rota responde 422 (antes respondia 500). Não adianta repetir a chamada: o DANFE depende do XML completo, que só é liberado depois da manifestação do destinatário (veja Registrar Manifestação). Com o inbound de NF-e não ativo na empresa, a rota responde 403.

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.

A rota recomendada é manifestation-events. Ela cobre a manifestação do destinatário clássica e também os eventos da NT 2025.002-RTC (crédito presumido, imobilização, perecimento, sucessão de crédito IBS/CBS, cancelamento de evento). O processamento é assíncrono:

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

{
  "eventCode": 210210,
  "nSequencia": 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. Opcional nos códigos sem campos próprios (210200, 210210, 210220). Para 210240, detail.justification com 15 a 255 caracteres é obrigatório

Tipos de manifestação do destinatário (eventCode):

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" — exige detail.justification

Exemplo com evento da NT 2025.002-RTC:

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

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. Não há webhook de conclusão: acompanhe por polling.

GET /v2/companies/{company_id}/inbound/productinvoices/by-access-key/{access_key}/manifestation-events
GET /v2/companies/{company_id}/inbound/productinvoices/manifestation-events/{id}

A listagem devolve { "items": [...] }, do mais recente para o mais antigo. O detalhe por id inclui o XML enviado (requestXmlGZipB64) e a resposta da SEFAZ (responseXmlGZipB64), ambos em GZip + Base64.

{
  "id": "66f0a1b2c3d4e5f601234567",
  "companyId": "comp_123",
  "accessKey": "35240112345678000195550010000012341234567890",
  "eventCode": 210210,
  "eventType": "CienciaOperacao",
  "nSequencia": 1,
  "status": "Pending",
  "environment": "Production",
  "attemptCount": 0,
  "createdOn": "2026-09-22T14:00:00Z"
}

Campos: id, companyId, accessKey, eventCode, eventType, nSequencia, status, environment (Production ou Test), attemptCount, createdOn, submittedAt, acceptedAt, errorCode, errorMessage. Campos nulos são omitidos.

Estados: Pending → Accepted / Rejected / Failed.

status	Significado
Pending	Na fila, ainda não concluído
Accepted	Registrado na SEFAZ (cStat 135/136, ou 573 — duplicidade, tratada como sucesso idempotente)
Rejected	Recusado pela SEFAZ — qualquer outro cStat, inclusive 596 (evento fora do prazo) (errorCode = BadRequest) — ou recusado na montagem do XML (errorCode = VALIDATION)
Failed	Falha antes do envio: errorCode = CERT_NOT_FOUND, CERT_LOAD_FAILED, CERT_EXPIRED, COMPANY_NOT_FOUND, AUTOR_UF_UNRESOLVED, STRATEGY_NOT_FOUND ou MAX_ATTEMPTS_EXCEEDED

errorMessage é texto livre (ex.: o motivo devolvido pela SEFAZ) — não faça parsing dele.

Código	Quando
202	Aceito para submissão
400	Chave sem 44 dígitos, eventCode não aceito, código somente leitura do Fisco (412120/412130), 211120 (removido), nSequencia < 1, detail inválido para o código (ex.: 210240 sem justificativa de 15 a 255 caracteres — validado na hora; antes era aceito e o evento terminava Rejected) ou inbound de NF-e não ativo na empresa
409	Já existe um evento Pending ou Accepted para a mesma (accessKey, eventCode, nSequencia)

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

Reenviar o mesmo evento com o mesmo nSequencia enquanto já existe um evento Pending ou Accepted retorna 409 — não duplica a submissão à SEFAZ. Eventos Rejected ou Failed podem ser reenviados. 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.

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.

Rota legada POST /manifest (depreciada)

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

Mantida por compatibilidade. Sem corpo: o evento vem de tpEvent (default 210210) e a sequência é sempre 1.

• Assíncrona: com o motor padrão (engine=v2), responde 200 com o evento em status: "Pending" — não uma mensagem da SEFAZ. Acompanhe pelas rotas GET acima.
• As mesmas validações e o mesmo 409 da rota manifestation-events se aplicam.
• tpEvent=210240 responde 400: o evento exige justificativa e esta rota não tem corpo para enviá-la. Use manifestation-events com detail.justification.
• engine=v1 (caminho síncrono antigo) está depreciado e não funciona no runtime atual — não use.

Empresa com inbound de NF-e desativado

Quando o inbound de NF-e não está ativo na empresa (nunca habilitado ou desativado via DELETE /v2/companies/{company_id}/inbound/productinvoices), as leituras de NF-e respondem 403 com corpo { "errors": [...] } (antes respondiam 500):

• GET .../inbound/productinvoices/{access_key}, .../productinvoices/{access_key}/json e .../productinvoices/{access_key}/events/{event_key}
• GET .../inbound/{access_key}, .../inbound/{access_key}/events/{event_key} e .../inbound/{access_key}/pdf

Exceção: GET .../inbound/{access_key}/xml segue respondendo 400 nesse caso. Repetir o DELETE /productinvoices numa empresa já desativada também responde 403.

Desativar não apaga os documentos já capturados: eles continuam armazenados, mas as rotas de leitura ficam indisponíveis enquanto o inbound estiver desativado. Para reativar, chame de novo o POST /v2/companies/{company_id}/inbound/productinvoices (veja Ativar via API); o startFromDate informado não pode ser anterior a 90 dias.

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