NF-e

Query NF-e

Returns status, invoice data and DANFE / XML download links.

GET/openapi/v2/empresas/{empresaId}/nf-e/{nfeId}

Requires the token, timestamp and sign signature headers, see Authentication.

nfeId is the id sent at issuance. The response echoes the issuance request in the same shape, plus the data SEFAZ returned. Authentication errors (10009xxx) are listed under Authentication.

Path parameters

`empresaId*`	string	Company identifier
`nfeId*`	string	Invoice identifier

* Required field

200

Invoice found.

`id`	string	Request identifier
`tipo`	string	Document type
`status`	string	Invoice status
`motivoStatus`	string	Denial reason
`ambienteEmissao`	string	Environment
`enviadaPorEmail`	bool	Sent by e-mail
`dataCriacao`	string	Acceptance time
`dataUltimaAlteracao`	string	Last change
`forcarEmissaoContingencia`	bool	Forced contingency
	object	Order
	object	Buyer
`numero`	string	Invoice number
`serie`	string	Invoice series
`dataEmissao`	string	Issue time
`chaveAcesso`	string	Access key
	object	Transport
`dataAutorizacao`	string	Authorization time
`linkDanfe`	string	DANFE link
`linkDownloadXml`	string	Authorized XML link
`linkConsultaPorChaveAcesso`	string	Public lookup
	object	Authorization protocol
`emitidaEmContingencia`	bool	Issued in contingency
`finalidade`	string	Purpose
`naturezaOperacao`	string	Nature of the operation
	object	Original invoice
	array	Items
`valorTotal`	number	Invoice total
`informacoesAdicionais`	string	Invoice remarks
`informacoesAdicionaisFisco`	string	Remarks to the tax authority

The invoice stays in AguardandoAutorizacao until SEFAZ replies, then ends in Autorizada, Negada or Cancelada. In final states the platform discards the request parameters: pedido, remarks, naturezaOperacao and tax parameters beyond code and rate stop coming.

AguardandoAutorizacao: processing

From acceptance until SEFAZ replies. No number, key, protocol or links; pedido, cliente and every tax parameter are echoed as sent. Query again or wait for the callback.

json

{
  "id": "NFe-000014553",
  "status": "AguardandoAutorizacao",
  "numero": null,
  "chaveAcesso": null,
  "dataAutorizacao": null,
  "linkDanfe": null,
  "linkDownloadXml": null,
  "pedido": { "presencaConsumidor": "OperacaoPelaInternet", "pagamento": { "tipo": "PagamentoAVista", "formas": [ { "tipo": "CartaoDeCredito", "valor": 28.47 } ] } },
  "itens": [ { "cfop": "6102", "codigo": "000068", "origem": 0, "impostos": { "icms": { "situacaoTributaria": "102" }, "pis": { "situacaoTributaria": "49", "aliquota": 0 }, "cofins": { "situacaoTributaria": "49", "aliquota": 0 } } } ]
}

Autorizada: authorized by SEFAZ

Number, key, dataAutorizacao, protocolo and both links filled. Every query issues fresh links.

json

{
  "id": "NFe-000014553",
  "status": "Autorizada",
  "numero": "262",
  "serie": "2",
  "chaveAcesso": "35241104893402000113550020000002621202427463",
  "dataAutorizacao": "2024-11-27T20:56:55Z",
  "protocolo": { "numero": "135240009194753" },
  "linkDanfe": "https://api.v2.tffiscal.com/openapi/files/danfe/35241104893402000113550020000002621202427463?token=…",
  "linkDownloadXml": "https://api.v2.tffiscal.com/openapi/files/xml/8801?token=…"
}

Negada: refused by SEFAZ

motivoStatus carries the SEFAZ code and reason. No DANFE; the number, if already allocated, is reused by the next issuances, with no skipped numbers. Fix the request and issue again.

json

{
  "id": "NFe-000014553",
  "status": "Negada",
  "motivoStatus": "778 - Rejeicao: NCM inexistente",
  "linkDanfe": null,
  "linkDownloadXml": null
}

Cancelada: cancelled after authorization

After Cancel NF-e. Number, key and protocol remain; the DANFE stops coming and the XML remains available.

json

{
  "id": "NFe-000014553",
  "status": "Cancelada",
  "numero": "262",
  "chaveAcesso": "35241104893402000113550020000002621202427463",
  "protocolo": { "numero": "135240009194753" },
  "linkDanfe": null,
  "linkDownloadXml": "https://api.v2.tffiscal.com/openapi/files/xml/8801?token=…"
}

`status`Invoice status

Values	Meaning
AguardandoAutorizacao	Accepted, waiting for the SEFAZ reply
Autorizada	Authorized by SEFAZ; DANFE and XML available
Negada	Refused by SEFAZ; reason in `motivoStatus`
Cancelada	Cancelled after authorization

`ambienteEmissao`Issue environment

Values	Meaning
Homologacao	SEFAZ test environment; the invoice has no legal effect
Producao	Official environment

`finalidade`Invoice purpose

Values	Meaning
Normal	Ordinary sale
Complementar	Complementary invoice to an already authorized invoice
Ajuste	Adjustment invoice to an already authorized invoice
Devolucao	Return of an already authorized invoice; carries `notaReferenciada`

`pedido.presencaConsumidor`Buyer presence

Values	Meaning
NaoSeAplica	Not applicable; returns
OperacaoPresencial	In-person sale at the shop
OperacaoPelaInternet	Online sale
OperacaoPorTelefone	Telesale
EntregaEmDomicilio	Sale closed at home delivery
OperacaoPresencialForaDoEstabelecimento	In-person sale outside the shop
Outros	Other

`pedido.pagamento.tipo`Payment timing

Values	Meaning
PagamentoAVista	Cash on the spot
PagamentoAPrazo	On credit

`pedido.pagamento.formas[].tipo`Payment method

Values	Meaning
Dinheiro	Cash
Cheque	Cheque
CartaoDeCredito	Credit card
CartaoDeDebito	Debit card
CreditoLoja	Store credit
ValeAlimentacao	Food voucher
ValeRefeicao	Meal voucher
ValePresente	Gift voucher
ValeCombustivel	Fuel voucher
BoletoBancario	Bank slip
DepositoBancario	Bank deposit
PagamentoInstantaneoPix	Pix instant payment
TransferenciaBancaria	Bank transfer
ProgramaDeFidelidade	Loyalty programme or cashback
PagamentoInstantaneoPixEstatico	Static Pix
CreditoEmLoja	In-store balance
PagamentoEletronicoNaoInformado	Electronic payment not reported
PagamentoInstantaneoPixAutomatico	Automatic Pix
TransferenciaTefBookTransfer	Same-bank TEF transfer
SemPagamento	No payment; returns
PagamentoPosterior	Deferred payment
Outros	Other

`cliente.indicadorContribuinteICMS`Buyer ICMS status

After the final state only ContribuinteICMS (CNPJ with state registration) or NaoContribuinte.

Values	Meaning
ContribuinteICMS	Taxpayer with state registration
ContribuinteIsento	Exempt from state registration
NaoContribuinte	Non-taxpayer

`cliente.tipoPessoa`Buyer type

Values	Meaning
F	Individual; 11-digit CPF
J	Company; 14-digit CNPJ

`cliente.endereco.uf`Buyer state

EX only on export invoices.

Values	Meaning
AC	Acre
AL	Alagoas
AP	Amapá
AM	Amazonas
BA	Bahia
CE	Ceará
DF	Distrito Federal
ES	Espírito Santo
GO	Goiás
MA	Maranhão
MT	Mato Grosso
MS	Mato Grosso do Sul
MG	Minas Gerais
PA	Pará
PB	Paraíba
PR	Paraná
PE	Pernambuco
PI	Piauí
RJ	Rio de Janeiro
RN	Rio Grande do Norte
RS	Rio Grande do Sul
RO	Rondônia
RR	Roraima
SC	Santa Catarina
SP	São Paulo
SE	Sergipe
TO	Tocantins
EX	Abroad (export invoice)

`transporte.frete.modalidade`Freight modality

Values	Meaning
SemFrete	No freight
PorContaDoEmitente	Freight paid by the seller
PorContaDoDestinatario	Freight paid by the buyer
PorContaDeTerceiros	Freight paid by a third party
TransporteProprioPorContaDoRemetente	Seller own transport
TransporteProprioPorContaDoDestinatario	Buyer own transport

`itens[].origem`Product origin

Values	Meaning
0	Domestic
1	Directly imported
2	Imported, bought domestically
3	Domestic with over 40 % imported content
4	Domestic by basic production process
5	Domestic with up to 40 % imported content
6	Directly imported, no domestic equivalent
7	Imported from the domestic market, no domestic equivalent
8	Domestic with over 70 % imported content

`itens[].impostos.icms.situacaoTributaria`ICMS CST (regular regime, CRT 2 / 3)

Values	Meaning
00	Fully taxed
02	Own single-phase (fuels)
10	Taxed with ST withholding
15	Own single-phase with withholding (fuels)
20	With base reduction
30	Exempt or not taxed, with ST withholding
40	Exempt
41	Not taxed
50	Suspended
51	Deferral
53	Single-phase with deferral (fuels)
60	ICMS already withheld upstream by ST
61	Single-phase already charged upstream (fuels)
70	With base reduction and ST withholding
90	Other

`itens[].impostos.icms.situacaoTributaria`ICMS CSOSN (Simples Nacional, CRT 1 / 4)

Values	Meaning
101	Taxed, buyer may take credit
102	Taxed, no credit
103	Exempt by gross-revenue band
201	Taxed with credit and ST withholding
202	Taxed without credit, with ST withholding
203	Exempt by revenue band, with ST withholding
300	Constitutionally immune
400	Not taxed
500	ICMS already withheld upstream by ST
900	Other

`itens[].impostos.pis.situacaoTributaria`PIS CST

Values	Meaning
01	Taxable at the basic rate
02	Taxable at a differentiated rate
03	Taxable by quantity
04	Single-phase, resale at zero rate
05	Tax substitution
06	Zero rate
07	Exempt
08	Not levied (export)
09	Suspended
49	Other outbound operations
50–56	Inbound with credit right, by revenue type (returns only)
60–66	Inbound with presumed credit, by revenue type (returns only)
67	Presumed credit, other operations (returns only)
70	Inbound without credit right
71	Inbound exempt
72	Inbound suspended
73	Inbound at zero rate
74	Inbound not levied
75	Inbound under tax substitution
98	Other inbound operations
99	Other operations

`itens[].impostos.cofins.situacaoTributaria`COFINS CST

Same table as PIS.

Values	Meaning
01	Taxable at the basic rate
02	Taxable at a differentiated rate
03	Taxable by quantity
04	Single-phase, resale at zero rate
05	Tax substitution
06	Zero rate
07	Exempt
08	Not levied (export)
09	Suspended
49	Other outbound operations
50–56	Inbound with credit right, by revenue type (returns only)
60–66	Inbound with presumed credit, by revenue type (returns only)
67	Presumed credit, other operations (returns only)
70	Inbound without credit right
71	Inbound exempt
72	Inbound suspended
73	Inbound at zero rate
74	Inbound not levied
75	Inbound under tax substitution
98	Other inbound operations
99	Other operations

`itens[].impostos.ipi.situacaoTributaria`IPI CST

Values	Meaning
00	Inbound with credit recovery
01	Inbound at zero rate
02	Inbound exempt
03	Inbound not taxed
04	Inbound immune
05	Inbound suspended
49	Other inbound
50	Outbound taxed
51	Outbound at zero rate
52	Outbound exempt
53	Outbound not taxed
54	Outbound immune
55	Outbound suspended
99	Other outbound

Code	HTTP
10004000	404	The `nfeId` does not exist. Check the id sent at issuance and the `empresaId`.
10004001	404	The `nfeId` does not exist. Check the id sent at issuance and the `empresaId`.
10003000	404	`empresaId` does not exist or does not belong to this application.

Query NF-e

Parameters

Path parameters

Responses

What comes in each status4 blocks

AguardandoAutorizacao: processing

Autorizada: authorized by SEFAZ

Negada: refused by SEFAZ

Cancelada: cancelled after authorization

Download links

Enumerations16 tables

statusInvoice status

ambienteEmissaoIssue environment

finalidadeInvoice purpose

pedido.presencaConsumidorBuyer presence

pedido.pagamento.tipoPayment timing

pedido.pagamento.formas[].tipoPayment method

cliente.indicadorContribuinteICMSBuyer ICMS status

cliente.tipoPessoaBuyer type

cliente.endereco.ufBuyer state

transporte.frete.modalidadeFreight modality

itens[].origemProduct origin

itens[].impostos.icms.situacaoTributariaICMS CST (regular regime, CRT 2 / 3)

itens[].impostos.icms.situacaoTributariaICMS CSOSN (Simples Nacional, CRT 1 / 4)

itens[].impostos.pis.situacaoTributariaPIS CST

itens[].impostos.cofins.situacaoTributariaCOFINS CST

itens[].impostos.ipi.situacaoTributariaIPI CST

Errors3 items

`status`Invoice status

`ambienteEmissao`Issue environment

`finalidade`Invoice purpose

`pedido.presencaConsumidor`Buyer presence

`pedido.pagamento.tipo`Payment timing

`pedido.pagamento.formas[].tipo`Payment method

`cliente.indicadorContribuinteICMS`Buyer ICMS status

`cliente.tipoPessoa`Buyer type

`cliente.endereco.uf`Buyer state

`transporte.frete.modalidade`Freight modality

`itens[].origem`Product origin

`itens[].impostos.icms.situacaoTributaria`ICMS CST (regular regime, CRT 2 / 3)

`itens[].impostos.icms.situacaoTributaria`ICMS CSOSN (Simples Nacional, CRT 1 / 4)

`itens[].impostos.pis.situacaoTributaria`PIS CST

`itens[].impostos.cofins.situacaoTributaria`COFINS CST

`itens[].impostos.ipi.situacaoTributaria`IPI CST