NF-e
Query NF-e
Returns status, invoice data and DANFE / XML download links.
/openapi/v2/empresas/{empresaId}/nf-e/{nfeId}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
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.
{"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.
{"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.
{"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.
{"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=…"}
linkDanfe and linkDownloadXml look like https://api.v2.tffiscal.com/openapi/files/{kind}/{ref}?token=… and need no signature headers: a plain GET that follows the 302 redirect is enough. Every query issues new links; an expired link returns 401 + 10009036. Validity and the remaining errors are described in File download.
tipoDocument type
| Values | Meaning |
|---|---|
| NF-e | Electronic invoice; always this value |
statusInvoice 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 |
ambienteEmissaoIssue environment
| Values | Meaning |
|---|---|
| Homologacao | SEFAZ test environment; the invoice has no legal effect |
| Producao | Official environment |
finalidadeInvoice 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.presencaConsumidorBuyer 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.tipoPayment timing
| Values | Meaning |
|---|---|
| PagamentoAVista | Cash on the spot |
| PagamentoAPrazo | On credit |
pedido.pagamento.formas[].tipoPayment 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.indicadorContribuinteICMSBuyer 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.tipoPessoaBuyer type
| Values | Meaning |
|---|---|
| F | Individual; 11-digit CPF |
| J | Company; 14-digit CNPJ |
cliente.endereco.ufBuyer 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.modalidadeFreight 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[].origemProduct 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.situacaoTributariaICMS CST (regular regime, CRT 2 / 3)
| Values | Meaning |
|---|---|
| 00 | Fully taxed. Send aliquota; CRT 3 without a rate uses the platform table |
| 02 | Own single-phase (fuels). Requires monofasico and the combustivel block |
| 10 | Taxed with ST withholding. Requires aliquota and substituicaoTributaria; taxpayer buyer; partilha optional; motivoDesoneracaoSt optional |
| 15 | Own single-phase with withholding (fuels). Requires monofasico with own and withholding rates |
| 20 | With base reduction. Requires aliquota, percentualReducaoBase and codigoBeneficioFiscal; motivoDesoneracao optional |
| 30 | Exempt or not taxed, with ST withholding. Requires substituicaoTributaria and codigoBeneficioFiscal; taxpayer buyer; motivoDesoneracao optional |
| 40 | Exempt. Requires codigoBeneficioFiscal; motivoDesoneracao optional |
| 41 | Not taxed. Requires codigoBeneficioFiscal; interstate ST pass-through sends substituicaoTributariaDestino with retencaoAnterior; motivoDesoneracao optional |
| 50 | Suspended. Requires codigoBeneficioFiscal; motivoDesoneracao optional |
| 51 | Deferral. Requires aliquota, percentualDiferimento and codigoBeneficioFiscal; with aliquotaFcp requires percentualDiferimentoFcp; with reduction, codigoBeneficioFiscalReducaoBase optional |
| 53 | Single-phase with deferral (fuels). Requires monofasico; the deferred share goes in percentualDiferimento |
| 60 | ICMS already withheld upstream by ST. retencaoAnterior optional; tributacaoEfetiva and substituicaoTributariaDestino as the state requires |
| 61 | Single-phase already charged upstream (fuels). Requires monofasico with the rate already charged |
| 70 | With base reduction and ST withholding. Requires aliquota, percentualReducaoBase, codigoBeneficioFiscal and substituicaoTributaria; taxpayer buyer; motivoDesoneracao and motivoDesoneracaoSt optional |
| 90 | Other. Requires codigoBeneficioFiscal; substituicaoTributaria and partilha optional; motivoDesoneracao and motivoDesoneracaoSt optional |
itens[].impostos.icms.situacaoTributariaICMS CSOSN (Simples Nacional, CRT 1 / 4)
| Values | Meaning |
|---|---|
| 101 | Taxed, buyer may take credit. Requires percentualCreditoSimples; taxpayer buyer |
| 102 | Taxed, no credit. Nothing else in ICMS; codigoBeneficioFiscal and creditosPresumidos as the state requires |
| 103 | Exempt by gross-revenue band. Nothing else in ICMS; codigoBeneficioFiscal and creditosPresumidos as the state requires |
| 201 | Taxed with credit and ST withholding. Requires percentualCreditoSimples and substituicaoTributaria; taxpayer buyer |
| 202 | Taxed without credit, with ST withholding. Requires substituicaoTributaria; taxpayer buyer |
| 203 | Exempt by revenue band, with ST withholding. Requires substituicaoTributaria; taxpayer buyer |
| 300 | Constitutionally immune. Nothing else in ICMS; codigoBeneficioFiscal and creditosPresumidos as the state requires |
| 400 | Not taxed. Nothing else in ICMS; codigoBeneficioFiscal and creditosPresumidos as the state requires |
| 500 | ICMS already withheld upstream by ST. retencaoAnterior optional |
| 900 | Other. substituicaoTributaria optional |
itens[].impostos.pis.situacaoTributariaPIS 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 (returns only) |
| 71 | Inbound exempt (returns only) |
| 72 | Inbound suspended (returns only) |
| 73 | Inbound at zero rate (returns only) |
| 74 | Inbound not levied (returns only) |
| 75 | Inbound under tax substitution (returns only) |
| 98 | Other inbound operations (returns only) |
| 99 | Other operations |
itens[].impostos.cofins.situacaoTributariaCOFINS 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 (returns only) |
| 71 | Inbound exempt (returns only) |
| 72 | Inbound suspended (returns only) |
| 73 | Inbound at zero rate (returns only) |
| 74 | Inbound not levied (returns only) |
| 75 | Inbound under tax substitution (returns only) |
| 98 | Other inbound operations (returns only) |
| 99 | Other operations |
itens[].impostos.ipi.situacaoTributariaIPI 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 |
itens[].impostos.ibsCbs.situacaoTributariaIBS/CBS CST
Before numbering only; echoed from issuance.
| Values | Meaning |
|---|---|
| 000 | Full taxation. Nothing beyond CST and classification |
| 200 | Reduced rate. The reduction comes from the classification; 200022 / 200024 require tributacaoRegular |
| 410 | Immunity or non-incidence. Only CST and classification |
| 510 | Deferral. Requires percentualDiferimento |
| 515 | Deferral with reduced rate. Requires percentualDiferimento |
| 550 | Suspension. Requires tributacaoRegular |
| 620 | Single-phase taxation (fuels). Requires monofasico and the combustivel block |
| 800 | Credit transfer. Requires transferenciaCredito |
| 810 | Manaus Free Zone presumed credit. Requires zonaFrancaManaus |
| 811 | Adjustment of earlier periods. Requires ajuste |
itens[].impostos.ibsCbs.classificacaoTributariaIBS/CBS tax classification
Before numbering only; echoed from issuance.
| Values | Meaning |
|---|---|
| 000001 | Situations fully taxed by IBS and CBS |
| 000003 | Automotive regime, incentivised projects (art. 311); allows creditoPresumido |
| 000004 | Automotive regime, incentivised projects (art. 312); allows creditoPresumido |
| 000005 | Anhydrous ethanol meant for blending with gasoline A but sold for another use |
| 200002 | Supply or import for non-taxpayer rural producer or TAC; 100 % reduction |
| 200003 | Sale of products for human consumption (Annex I); 100 % reduction |
| 200004 | Supply of medical devices (Annex XII); 100 % reduction |
| 200005 | Medical devices for public bodies and immune health entities (Annex XII); 100 % reduction |
| 200006 | Public health emergency recognised by the government; 100 % reduction |
| 200007 | Accessibility devices for people with disabilities (Annex XIII); 100 % reduction |
| 200008 | Accessibility devices bought by public bodies; 100 % reduction |
| 200009 | Supply of medicines registered at Anvisa; 100 % reduction |
| 200010 | Anvisa-registered medicines bought by public bodies; 100 % reduction |
| 200011 | Enteral and parenteral nutrition bought by public bodies; 100 % reduction |
| 200012 | Public health emergency recognised by the government; 100 % reduction |
| 200013 | Supply of tampons and sanitary pads; 100 % reduction |
| 200014 | Vegetables, fruit and eggs (Annex XV); 100 % reduction |
| 200015 | Domestic passenger cars bought by professional drivers or people with disabilities; 100 % reduction |
| 200020 | Operation by cooperatives under the specific IBS/CBS regime; 100 % reduction |
| 200022 | Industrialised goods sent from outside the Manaus Free Zone to a taxpayer inside it; 100 % reduction, requires tributacaoRegular |
| 200023 | Intermediate goods between incentivised industries; 100 % reduction |
| 200024 | Goods sent from outside the Free Trade Areas to a taxpayer inside them; 100 % reduction, requires tributacaoRegular |
| 200030 | Sale of medical devices (Annex IV); 60 % reduction |
| 200031 | Accessibility devices for people with disabilities (Annex V); 60 % reduction |
| 200032 | Anvisa-registered or compounded medicines, except those in Annex XIV; 60 % reduction |
| 200033 | Enteral and parenteral nutrition (Annex VI); 60 % reduction |
| 200034 | Food for human consumption (Annex VII); 60 % reduction |
| 200035 | Personal hygiene and cleaning products (Annex VIII); 60 % reduction |
| 200036 | Unprocessed agricultural, aquaculture, fishing, forestry and plant-extraction products; 60 % reduction |
| 200038 | Agricultural and aquaculture inputs (Annex IX); 60 % reduction |
| 200039 | National artistic, cultural, event, journalistic and audiovisual productions; 60 % reduction |
| 200043 | Sovereignty and security goods and services for the public administration (Annex XI); 60 % reduction |
| 200047 | Bars and restaurants; 40 % reduction |
| 200053 | Anvisa-registered medicines classified as sera or vaccines; 100 % reduction |
| 200054 | Goods supplied by an agricultural cooperative to a member outside the regular regime; 100 % reduction |
| 410001 | Bonuses stated on the invoice that do not depend on a later event |
| 410002 | Transfers between establishments of the same taxpayer |
| 410003 | Donations without consideration benefiting the donor |
| 410004 | Export of goods and services |
| 410005 | Supplies by the Union, states, Federal District and municipalities |
| 410006 | Supplies by religious entities and temples |
| 410007 | Supplies by political parties, unions and non-profit education or welfare institutions |
| 410008 | Books, newspapers, periodicals and the paper to print them |
| 410009 | Music recordings and music videos produced in Brazil |
| 410012 | Supply by a condominium outside the regular regime |
| 410013 | Fuel exports |
| 410014 | Supply by a non-taxpayer rural producer; allows creditoPresumido |
| 410016 | Supply or purchase of solid waste; allows creditoPresumido |
| 410017 | Purchase of movable goods with presumed credit conditional on resale |
| 410019 | Tips excluded from the tax base of food supply |
| 410020 | Intermediation fee excluded from the tax base of food supply |
| 410026 | Donation with credit reversal |
| 410027 | Export of services or intangible goods |
| 410029 | Operations covered only by ICMS |
| 410030 | Credit reversal for perishing, deterioration, theft or loss |
| 410031 | Supply before IBS and CBS came into force |
| 410035 | Supply by a nano-entrepreneur |
| 410999 | Other non-onerous operations without taxation, not listed above |
| 510001 | Deferred operations with electricity: import, generation, sale, distribution and transmission |
| 515001 | Deferred operations with agricultural and aquaculture inputs (Annex IX); 60 % reduction |
| 550001 | Export of tangible goods; requires tributacaoRegular |
| 550002 | Transit regime; requires tributacaoRegular |
| 550003 | Warehouse regimes (art. 85); requires tributacaoRegular |
| 550004 | Warehouse regimes (art. 87); requires tributacaoRegular |
| 550005 | Warehouse regimes (art. 87, sole paragraph); requires tributacaoRegular |
| 550006 | Temporary admission regimes; requires tributacaoRegular |
| 550007 | Processing regimes; requires tributacaoRegular |
| 550008 | Import of goods under Repetro-Temporário; requires tributacaoRegular |
| 550009 | GNL-Temporário; requires tributacaoRegular |
| 550010 | Repetro-Permanente; requires tributacaoRegular |
| 550011 | Repetro-Industrialização; requires tributacaoRegular |
| 550012 | Repetro-Nacional; requires tributacaoRegular |
| 550013 | Repetro-Entreposto; requires tributacaoRegular |
| 550014 | Export Processing Zone; requires tributacaoRegular |
| 550015 | Tax regime for port modernisation and expansion (Reporto); requires tributacaoRegular |
| 550016 | Special regime of incentives for infrastructure development (Reidi); requires tributacaoRegular |
| 550017 | Tax regime for the naval industry (Renaval); requires tributacaoRegular |
| 550018 | Relief on the purchase of capital goods; requires tributacaoRegular |
| 550019 | Import of goods by an incentivised industry for use in the Manaus Free Zone; requires tributacaoRegular |
| 550020 | Free trade areas; requires tributacaoRegular |
| 550021 | Manufacturing destined for export; requires tributacaoRegular |
| 550022 | Special regime for low-carbon hydrogen production (Rehidro); requires tributacaoRegular |
| 550023 | Non-fuel liquid hydrocarbons from oil or natural gas, including naphtha; requires tributacaoRegular |
| 620001 | Single-phase taxation on fuels |
| 620002 | Single-phase taxation with withholding responsibility on fuels |
| 620003 | Single-phase taxation with withholding by third parties |
| 620004 | Single-phase taxation on ethanol-gasoline blend above the mandatory share |
| 620005 | Single-phase taxation on ethanol-gasoline blend below the mandatory share |
| 620006 | Single-phase taxation on fuels already charged upstream |
| 620007 | Perishing, deterioration, theft or loss under the single-phase regime |
| 800001 | Merger, spin-off or incorporation |
| 800002 | Credit transfer from a member, including single cooperatives |
| 810001 | Presumed credit on supplies from the Manaus Free Zone |
| 811001 | Credit reversal for immune or exempt outputs |
| 811002 | Debits of invoices not processed in the assessment |
| 811003 | Exit from Simples Nacional |
| 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. |
