Functional Documentation: NF-e/NFC-e Issuance API (v3)

Document Version: 1.0 Last Revision Date: October 24, 2025

---

1. Introduction

1.1. Objective

This document serves as a complete functional guide for using the API for issuing Product Invoices (NF-e, model 55) and Consumer Invoices (NFC-e, model 65). The objective is to detail the structure of the request body (payload), the purpose of each group and property, business rules, validations, and the context for filling out each field.

This documentation is intended for developers, system analysts, and any professional who needs to integrate third-party systems with the tax document issuance platform.

1.2. Reference Documents

The structure of this API was developed based on the following official documents:

• Taxpayer Orientation Manual (MOC): Mainly "ANNEX I - Layout and Validation Rule - NF-e and NFC-e".
• Technical Note 2025.002 (v1.31): Details the adjustments for the Consumption Tax Reform (RTC), including the new taxes IBS, CBS, and IS.
• Official XSD Schemas: Such as tiposBasico_v4.00.xsd and the NF-e layout.

Throughout the document, the API fields are mapped to their respective fields in the SEFAZ XML (e.g., (natOp)), facilitating association for those already familiar with the official layout.

1.3. General Concepts

• Issuance Environment: The API operates in two distinct environments:
  • Test (Homologation): For integration testing, with no fiscal validity.
  • Production: For issuing documents with fiscal validity.
• Document Models:
  • NF-e (model 55): Electronic Invoice, used to document operations of goods circulation between legal entities or between a legal entity and an individual.
  • NFC-e (model 65): Electronic Consumer Invoice, used in in-person sales operations or for home delivery to the final consumer.

---

2. General Request Structure

The issuance of an invoice is performed via a POST request to the /v2/companies/:companyId/productinvoices endpoint. The request body is a JSON object that represents the entire invoice. Below, we detail each main group of this object.

2.1. Invoice Identification Group

This group contains the information that uniquely identifies the invoice and defines its main characteristics, such as the nature of the operation, dates, and purpose.

• serie (integer): Invoice Series (serie). A number that controls the numbering sequence.
  • Validations: Value between 0 and 999. For NFC-e, series 890-899 are for exclusive use in contingency issuance (SCAN).
• number (integer): Invoice Number (nNF). Sequential number of the invoice within the series.
  • Validations: Cannot be duplicated for the same issuer, model, and series.
• issuedOn (string): Issue Date and Time (dhEmi). Date and time the fiscal document was issued. Format YYYY-MM-DDThh:mm:ssTZD. Optional. When omitted, the API uses the value of operationOn; when both are omitted, it uses the processing date and time. The same date defines the year/month (YYMM) of the access key. Should not be filled for NFC-e (model 65) — for NFC-e the issue date is always the processing date. The value actually used is returned in the issuedOn field when querying the invoice.
  • Validations: Cannot be more than 5 minutes in the future (SEFAZ rejection 703) nor, on normal issuance, more than 30 days in the past (rejection 228). On an outgoing NF-e, the operationOn date cannot be earlier than the issuedOn date (rejection 506). The API refuses the payload with 400 before consuming numbering.
• operationOn (string): Date and Time of Exit/Entry (dhSaiEnt). The date and time the goods left the establishment (for outgoing invoices) or entered (for incoming invoices). Format YYYY-MM-DDThh:mm:ssTZD. Should not be filled for NFC-e (model 65).
  • Validations: Cannot be later than the processing date. Without issuedOn, operationOn takes the role of issue date and receives the 703/228 validations. On an outgoing NF-e, its date cannot be earlier than the issuedOn date (rejection 506).
• operationNature (string): Description of the Nature of the Operation (natOp). Text describing the operation (e.g., "Sale of goods", "Shipment for repair"). This field must be consistent with the CFOP used in the items.
  • Validations: Minimum of 2 characters.
• operationType (enum): Type of Fiscal Document (tpNF). Defines whether the invoice is Incoming or Outgoing.
  • Validations: A return invoice (purposeType = Devolution) must be of type Incoming. A credit note (finNFe=5) must be of type Incoming.
• destination (enum): Destination Location Identifier (idDest). Indicates whether the operation is Internal_Operation (within the same state), Interstate_Operation (between states), or International_Operation (with a foreign country).
  • Validations: If the recipient's state is the same as the issuer's, it must be Internal_Operation. If different, Interstate_Operation. If the country is not Brazil, International_Operation.
• printType (enum): DANFE Print Format (tpImp). Defines the print layout of the Auxiliary Document of the Electronic Invoice.
• purposeType (enum): Purpose of Issuance (finNFe). Indicates the purpose of the invoice: Normal, Complement (complementary), Adjustment, Devolution (return), CreditInvoice (credit note, finNFe=5) or DebitInvoice (debit note, finNFe=6). For credit and debit notes, the subtype goes in creditType or debitType. See §11.1.3.
  • Validations: A complementary invoice (finNFe=2) must reference the original NF-e (NT 2025.002, rule B25-30, rejection 254). A return (finNFe=4) references the source invoice per item, in items[].referencedDFe (rule VC02-14). For a credit note, the reference depends on creditType: type 03 requires the referenced NF-e (rule B25-30), sent in additionalInformation.taxDocumentsReference ([V-CN-02]); type 06 references per item (rule VC02-10, [V-CN-03]); type 02 must not reference any document (rule B25-65, rejection 1027). The API also rejects a reference on type 05 ([V-CN-11]). See §11.1.5.
• debitType (enum): Type of Debit Note (tpNFDebito). Used in debit notes (finNFe=6) for specific Tax Reform scenarios, such as FinesAndInterest.
  • Validations: Can only be informed if the invoice purpose (purposeType) is DebitInvoice (purpose 6).
• creditType (enum): Type of Credit Note (tpNFCredito). Used in credit notes (finNFe=5) for scenarios like the refusal of goods on delivery (RefusedDeliveryTotalOrNotFound, RefusedDeliveryPartial). See §11.1.5.
  • Validations: Can only be informed if the invoice purpose (purposeType) is CreditInvoice (purpose 5).
• consumerType (enum): Final Consumer Operation Indicator (indFinal).
  • FinalConsumer: The sale is to a final consumer.
  • Normal: The sale is not to a final consumer.
  • Default Rule: If this field is not provided, the value will be set based on the buyer's federalTaxNumber: "Normal" for CNPJ and "FinalConsumer" for CPF/NIF.
• presenceType (enum): Buyer Presence Indicator (indPres). Indicates how the commercial operation occurred (e.g., Presence for in-person, Internet for non-presential via the internet). Essential for differentiating in-store sales from e-commerce.
  • Validations: For NFC-e, the allowed values are Presence or Delivery (home delivery).
• contingencyOn (string) and contingencyJustification (string): Contingency Entry (dhCont, xJust). Used for issuance in contingency mode when the SEFAZ environment is unavailable.
  • Validations: The justification must have at least 15 characters.

Layout fields that are not part of the request. The city of the taxable event (cMunFG) and the NF-e total with IBS/CBS (vNFTot) are filled in by the platform. The expected delivery date (dPrevEntrega), the city of the IBS/CBS taxable event (cMunFGIBS), the invoice-level government purchase group (gCompraGov) and the Selective Tax (IS and ISTot) are not yet accepted by the API: values sent are ignored. The expected delivery date can be informed after authorization, with the ExpectedDeliveryUpdate event.

2.2. Buyer Group (buyer)

Contains all information about the recipient of the goods. Mandatory group for NF-e (model 55).

• name (string): Name or Corporate Name (xNome).
• federalTaxNumber (integer): CNPJ or CPF. For foreign operations, it can be the NIF (Tax Identification Number).
  • Validations: For internal or interstate operations, it must be a valid CNPJ or CPF. If a CNPJ is provided, the State Tax Number (stateTaxNumber) may be mandatory depending on the state.
• tradeName (string): Trade Name (xFant).
• stateTaxNumber (string): State Tax Number (IE).
  • Validations: If stateTaxNumberIndicator is TaxPayer, the IE must be provided and valid for the recipient's state. If NonTaxPayer, it should not be provided.
• stateTaxNumberIndicator (enum): Recipient's IE Indicator (indIEDest). Defines the recipient's relationship with ICMS. This field is crucial for the correct calculation of taxes like DIFAL.
  • TaxPayer: ICMS taxpayer.
  • Exempt: Taxpayer exempt from State Tax Number.
  • NonTaxPayer: Not an ICMS taxpayer.
• address (object): Recipient's Address (enderDest). Object containing the complete address data.
  • Validations: The municipality code (city.code) must correspond to the state (state).

2.3. Delivery and Withdrawal Location Groups

• delivery (object): Delivery Location Identification (entrega). Used only when the delivery location is different from the recipient's address. If it is the same, this group should not be filled.
  • Validations: The CNPJ/CPF of the delivery location cannot be the same as the issuer's.
• withdrawal (object): Withdrawal Location Identification (retirada). Used only when the goods are picked up at a location different from the issuer's address.

2.4. Items Group (items)

This is an array of objects, where each object represents a product or service on the invoice. It is the most important and complex section of the fiscal document.

2.4.1. Item Properties

• code (string): Product or Service Code (cProd). Internal product code in the issuer's system.
• codeGTIN (string): GTIN (cEAN). Barcode of the product, if any.
• description (string): Product or Service Description (xProd).
  • Validations: Cannot be filled with generic terms like "MISCELLANEOUS".
• ncm (string): NCM Code (NCM). Mercosur Common Nomenclature. A fundamental field for correct taxation.
  • Validations: Must be a valid NCM code from the official table. For some products, the full 8-digit NCM is mandatory.
• cest (string): CEST Code (CEST). Specifier Code for Tax Substitution. Mandatory for products listed in ICMS-ST agreements.
  • Validations: Mandatory if the product is subject to tax substitution, according to ICMS agreements.
• cfop (integer): Fiscal Code of Operations and Services (CFOP). A numeric code that defines the nature of the item's operation (sale, shipment, return, etc.) and its taxation.
  • Validations: Must be a valid code. The first digit must be compatible with the operation type (e.g., 5 or 6 for outgoing, 1 or 2 for incoming).
• quantity (number): Commercial Quantity (qCom).
• unit (string): Commercial Unit (uCom) (e.g., "UN", "BOX", "KG").
• unitAmount (number): Commercial Unit Price (vUnCom).
• totalAmount (number): Gross Total Product Value (vProd). Result of quantity * unitAmount.
  • Validations: The value must be the result of multiplying the quantity by the unit price, with a small tolerance for rounding.
• freightAmount, insuranceAmount, othersAmount (number): Values for freight, insurance, and other ancillary expenses that are prorated and make up the total item value.
• totalIndicator (boolean): Totalization Indicator (indTot). Indicates if the item's value (vProd) is included in the calculation of the total NF-e value.
  • Validations: For an adjustment NF-e (purposeType = Adjustment), this field must be false.
• usedMovableGood (boolean, optional): Used Movable Good Indicator (indBemMovelUsado). Send true when the item is a used movable good — typical case: resale of used vehicles. The tag is emitted only when true; with false or omitted the tag is not written to the XML (the layout has no value for new good). Available since 2026-08-19.
• numberOrderBuy (string): Purchase Order Number (xPed).

2.4.2. Item Tax Group (tax)

Within each item, the tax object details all taxes levied on the product or service.

• totalTax (number): Approximate Total Taxes (vTotTrib). Estimated tax value according to the Transparency Law.

• Old Regime Taxes:

  • icms (object): ICMS Group. Contains ICMS taxation, with fields like origin, cst, baseTax, rate, and amount. The internal structure varies according to the CST.
    • Validations: Only one of the ICMS taxation groups (ICMS00, ICMS10, ICMS20, etc.) can be filled, according to the informed CST.
  • ipi (object): IPI Group. Details the taxation of the Tax on Industrialized Products.
  • pis (object): PIS Group.
  • cofins (object): COFINS Group.

• Tax Reform (RTC) Taxes:

  • IBSCBS (object): IBS and CBS Group. The central group of the RTC. Under NT 2025.002-RTC v1.51 (rule UB12-10), omitting the group triggers rejection 1115 in homologation for CRT 3 (Regime Normal) issuers on invoices issued from 07/01/2026 on; in production, the rule is a future implementation (v1.51 revoked the dates previously set: 08/03/2026 for CRT 3 and 01/04/2027 for CRT 1, 2 and 4). We recommend sending the group on every item from now on.
    • situationCode (string): Tax Situation Code for IBS/CBS.
    • classCode (string): Tax Classification Code, which defines the specific regime of the item (e.g., general taxation, exemption, reduced rate).
      • Validations: The classCode must be a valid code from the official table and compatible with the informed situationCode.
    • basis (number): Unified tax base.
    • calculationMode (enum): Tax calculation mode. Allows choosing between manual filling (Manual, default value) or automatic calculation via an official service (OfficialService). When OfficialService is used, only situationCode and classCode are necessary, and the other tax fields are filled by the service. The classCode is mandatory in OfficialService: without it, the platform discards the item's entire IBSCBS group and the invoice goes on without IBS/CBS. In Manual mode, the informed values are checked by the API (see §11.4.1).
    • state (object): Details the calculation of State IBS (rate, amount, deferment, reduction).
    • municipal (object): Details the calculation of Municipal IBS.
    • cbs (object): Details the calculation of CBS.
      • Validations: The amount values in each subgroup must be calculated correctly based on the basis and the respective rates and benefits.
      • Validations (RTC): For credit and debit notes (finNFe = 5 or 6), NT 2025.002 (rule B25-80, rejection 1001) forbids the old-regime tax groups (ICMS, IPI, II, PIS, COFINS, ICMS UF Destino and others). The rule does not apply to credit notes 03, 04 and 06 or to debit note 07; debit note 06 accepts PIS and COFINS in 2026, and IPI. See rejection 1001 in Appendix D.
    • Optional subgroups like monophase (monophasic taxation), operationalPresumedCredit, governmentPurchase, etc.

• taxDetermination (object): Group for Automatic Tax Determination. If filled, the tax engine determines the item's current-regime taxes (ICMS, IPI, PIS and COFINS) based on information like operationCode, issuerTaxProfile, and buyerTaxProfile. IBS and CBS are not calculated by this group: they come from tax.IBSCBS and, for automatic calculation, require calculationMode = OfficialService. An item with taxDetermination and an IBSCBS group in Manual mode is rejected with 400 ("IBSCBS manual mode does not allow TaxDetermination.").

2.5. Transport Group (transport)

Contains information about the transportation of the goods.

• freightModality (enum): Freight Modality (modFrete). Defines who is responsible for the freight (e.g., ByIssuer - CIF, ByReceiver - FOB, Free).
  • Validations: If the modality is Free, the carrier, vehicle, and volume groups should not be filled.
• transportGroup (object): Carrier Data (transporta). Information such as name, federalTaxNumber, stateTaxNumber, and address.
• transportVehicle (object): Vehicle Data (veicTransp). License plate (plate) and state of the vehicle.
• reboque (object): Trailer Data.
• volume (object): Transported Volumes Data (vol). Information such as quantity (volumeQuantity), species (species), net weight (netWeight), and gross weight (grossWeight).

2.6. Payment Group (payment)

Array of objects detailing the payment methods.

• paymentDetail (array): Payment details.
  • method (enum): Payment Method (tPag) (e.g., Cash, CreditCard, InstantPayment for PIX).
  • amount (number): Payment Amount (vPag).
    • Validations: The sum of the values of all payments must be equal to the total value of the invoice.
  • paymentType (enum): Payment Form Indicator (indPag): InCash (cash/upfront) or Term (installments).
  • card (object): If payment is by card, this group contains transaction data, such as the flag (flag), the acquirer's CNPJ, and the authorization number.
    • Validations: Mandatory if the payment method is CreditCard or DebitCard.
• payBack (number): Change Amount (vTroco).

2.7. Billing Group (billing)

Used to detail the commercial billing of the operation.

• bill (object): Invoice (fat). Contains number (number), original amount (originalAmount), discount (discountAmount), and net amount (netAmount).
• duplicates (array): Installments (dup). Array with the invoice installments, each with a number (number), due date (expirationOn), and amount (amount).

2.8. Totals Group (totals)

Summarizes the total values of the invoice. Most of these fields are calculated by the system based on the items, but it is important that the source system also calculates them for validation.

• icms (object): ICMS Totals (ICMSTot). Contains the sum of tax bases, ICMS values, ICMS-ST, total value of products, freight, insurance, discount, and the total invoice amount (invoiceAmount) according to the old regime.
  • Validations: Each field in this group must correspond to the sum of the respective field from all items on the invoice.
• issqn (object): ISSQN Totals (ISSQNtot). Sums related to the Tax on Services.
• withheldTaxes (object): Withheld Taxes (retTrib). Withheld amounts of PIS, COFINS, CSLL, IRRF, and Social Security.
• ibsCbs (object): IBS and CBS Totals (IBSCBSTot). Consolidates the totals of the tax base, IBS values (state and municipal), CBS, deferrals, returns, etc.
  • Validations: The values in this group must be the sum of the corresponding values from the IBSCBS group of each item.

2.9. Additional Information Group (additionalInformation)

Free text fields and references for complementary information.

• fisco (string): Additional Information for the Tax Authority (infAdFisco).
• taxpayer (string): Complementary Information for the Taxpayer (infCpl).
• xmlAuthorized (array): Authorized to Download XML (autXML). List of CNPJs or CPFs of third parties (e.g., accountant) authorized to access the document's XML.
  • Validations: Must be valid CNPJs or CPFs. Maximum of 10 authorizations.
• taxDocumentsReference (array): Referenced Fiscal Documents (NFref). Used to reference access keys of other invoices (e.g., in a return). Each item may contain one of three types:
  • documentElectronicInvoice: Referenced NF-e/NFC-e (44-digit access key in accessKey).
  • documentInvoiceReference: Referenced model 1/1A invoice (fields state, yearMonth, federalTaxNumber, model, series, number).
  • taxCouponInformation: Referenced fiscal coupon (fields modelDocumentFiscal, orderECF, orderCountOperation).
  • Validations: The referenced access key must be valid and exist in the SEFAZ database.
• advancePayment (array): Advance Payment Notes (gPagAntecipado). ⚠️ Not accepted by the API: values sent are ignored and the gPagAntecipado group is not generated in the XML.
• taxpayerComments (array): Fiscal Observations (obsCont). List of field/text pairs for free-form taxpayer observations.
• referencedProcess (array): Referenced Processes (procRef). To inform numbers of judicial or administrative processes that support the operation. Each item contains:
  • identifierConcessory (string): Identifier of the concession act.
  • identifierOrigin (integer): Process origin indicator (1=SEFAZ, 2=Federal Justice, 3=State Justice, 9=Others).
  • concessionActType (integer): Type of the concession act.

2.10. Issuer Group (issuer) — Response Only

Note: Unlike most groups, issuer is not sent in the issuance request — the only exception is issuer.stStateTaxNumber (IEST). It is determined automatically from the company registry (companyId in the URL) and populated by the API in responses. This group is detailed here for reference when consuming query endpoints.

Identifies the NF-e issuer (emit in XML).

• name (string): Name or Corporate Name (xNome).
• federalTaxNumber (integer): Issuer's CNPJ.
• tradeName (string): Trade Name (xFant).
• regionalTaxNumber (integer): State Registration (IE) at the SEFAZ of the issuer's UF.
• regionalSTTaxNumber (integer): legal-entity registry field exposed in the response. The platform does not use it in the XML: the issuer IEST tag comes only from stStateTaxNumber.
• municipalTaxNumber (string): Municipal Registration (IM/CCM).
• companyRegistryNumber (integer): Commercial Board Registration Number (nIRE).
• address (AddressResource): Issuer's address (enderEmit).
• taxRegime (enum TaxRegime): Tax Regime Code (CRT). See §11.3.1.
• specialTaxRegime (enum SpecialTaxRegime): Special tax regime (indRegTrib). See §11.3.2.
• legalNature (enum LegalNature): Company's legal nature. See §11.10.
• economicActivities (array): List of company CNAEs, each item with type (Main/Secondary) and code (numeric code).
• openningDate (string): Company opening date (dIniAtiv).
• stStateTaxNumber (string): Tax Substitute IE (IEST) — the only issuer field accepted in the request, as issuer.stStateTaxNumber (IEST tag).

2.11. Purchase Information Group (purchaseInformation)

Details commercial references of the operation. Mainly applicable to sales to public agencies.

• commitmentNote (string): Commitment Note (xNEmp). Identification of the commitment when dealing with public purchases. Min. 1, max. 22 characters.
• purchaseOrder (string): Purchase Order (xPed). Purchase order identification. Min. 1, max. 60 characters.
• contractNumber (string): Contract (xCont). Contract identification. Min. 1, max. 60 characters.

Difference vs. additionalInformation.order / contract: Fields in additionalInformation are generic free text. The purchaseInformation group is structured and maps directly to the compra group in XML — preferable for government purchases.

2.12. Export Group (export)

Applicable only to operations with destination = InternationalOperation.

• state (enum StateCode): UF abbreviation of embarkation or border crossing.
• office (string): Embarkation Place (xLocExporta). Description of the physical exit location of the goods (e.g., "Port of Santos", "Guarulhos Airport").
• local (string): Customs Clearance Place (xLocDespacho). Customs clearance location.

2.13. Transaction Intermediate Group (transactionIntermediate)

Applicable when the sale is made through a marketplace, delivery platform, or broker.

• federalTaxNumber (integer): Intermediator CNPJ (CNPJ). CNPJ of the intermediating platform.
• identifier (string): Identifier in the Intermediator (idCadIntTran). Internal seller/store ID on the intermediating platform.

When to fill: Whenever the transaction was originated/processed by a third party (Marketplace), even if the payment was made directly to the issuer. SEFAZ uses this group for fiscal reconciliation between the issuer and the platform.

2.14. Contingency Group (contingencyOn / contingencyJustification)

When SEFAZ is unavailable (timeout, 5xx error, degraded service status), the NF-e can be issued in contingency mode:

• contingencyOn (string, ISO 8601): Date and time of entry into contingency (dhCont).
• contingencyJustification (string): Textual justification of entry into contingency (xJust). Minimum 15 characters, maximum 1,000.

The invoice is processed locally and later synchronized with SEFAZ. The NF-e status is IssuedContingency until synchronization is successful.

Recommendation: Configure the issuer to manage contingency automatically via the State Registration registry instead of filling manually — see §9.4.

2.15. Special Item Subgroups

In addition to the basic fields described in §2.4.1 and §2.4.2, each item may contain specific subgroups for product/operation types:

2.15.1. vehicleDetail — New Vehicles

Applicable when the item is a brand-new (0 km) vehicle. Full detail in §6.22 (all fields J02–J26 of the official layout).

2.15.2. fuelDetail — Fuels

Applicable when the item is a fuel subject to ANP control.

"fuelDetail": {
  "codeANP": "210203001",
  "percentageNG": 50.0,
  "descriptionANP": "GLP",
  "percentageGLP": 40.0,
  "percentageNGn": 30.0,
  "percentageGNi": 20.0,
  "startingAmount": 100.0,
  "codif": "CODIF-123",
  "amountTemp": 10.0,
  "stateBuyer": "RJ",
  "cide": { "bc": 10.0, "rate": 5.0, "cideAmount": 0.5 },
  "pump": { "spoutNumber": 1, "number": 1, "tankNumber": 1, "beginningAmount": 1000.0, "endAmount": 1010.0, "percentageBio": 10.0 },
  "fuelOrigin": { "indImport": 1, "cUFOrig": 35, "pOrig": 10.0 }
}

• codeANP: ANP product code (cProdANP).
• descriptionANP: Product description per ANP (descANP).
• percentageNG, percentageGLP, percentageNGn, percentageGNi: Mixture percentages for the GLP product (cProdANP=210203001).
• startingAmount: Starting value (vPart).
• codif: CODIF authorization code.
• amountTemp: Quantity invoiced at ambient temperature (qTemp).
• stateBuyer: Consumption UF abbreviation (UFCons).
• cide: CIDE (Contribution for Intervention in the Economic Domain) group with bc (BC), rate (rate), cideAmount (amount).
• pump: Fuel pump data for stations:
  • spoutNumber/number/tankNumber: Physical identification (spout, pump, tank).
  • beginningAmount/endAmount: Initial and final pump reading of the supply.
  • percentageBio: Biodiesel B100 mixture percentage in B Diesel.
• fuelOrigin: Fuel origin:
  • indImport: Import indicator.
  • cUFOrig: Origin UF code.
  • pOrig: Originating percentage for the UF.

Mutual exclusion: vehicleDetail, fuelDetail (and medicineDetail when applicable) are mutually exclusive. If more than one is sent, the order of precedence prevails: medicine > vehicle > fuel.

2.15.3. presumedCredit — Per-Item Presumed Credit (ICMS regime)

This field is not accepted by the API: the item has no presumedCredit field, values sent are ignored and the gCred group is not generated in the XML. The Tax Reform presumed credit goes in items[].tax.IBSCBS.operationalPresumedCredit (§4.5.2).

2.15.4. importDeclarations — Import Declarations (DI)

Array of DIs linked to the item. Each DI contains:

• code: Import Document Number (nDI).
• registeredOn: DI/DSI/DA registration date (dDI).
• customsClearanceName: Customs clearance location (xLocDesemb).
• customsClearanceState (enum StateCode): Clearance UF (UFDesemb).
• customsClearancedOn: Clearance date (dDesemb).
• additions: Array of additions with code (no.), manufacturer (manuf. code), amount (vDescDI), drawback (concession act no.).
• exporter: Exporter code (cExportador).
• internationalTransport (enum InternationalTransportType): DI transport mode. See §11.6.3.
• intermediation (enum IntermediationType): Intermediation form. See §11.6.2.
• acquirerFederalTaxNumber: Acquirer/orderer's CNPJ/CPF.
• stateThird: Acquirer/orderer's UF.

2.15.5. exportDetails — Per-Item Export Detail

Item linkage to an Export Registry (RE) or DEC (Common Export Declaration).

• drawback: Concession act number (nDraw).
• hintInformation:
  • registryId: RE number (nRE).
  • accessKey: Access key of the NF-e received for export (chNFe).
  • quantity: Quantity actually exported (qExport).

2.15.6. referencedDFe — Referenced Electronic Fiscal Document

Item-by-item reference to a specific item of another DF-e (typical use: return invoice referencing the original NF-e).

• accessKey (string, 44 chars): Access key of the referenced DF-e.
• itemNumber (integer 1–999): Item number in the original DF-e (nItem).

2.15.7. taxDetermination — Automatic Tax Calculation

When filled, replaces the manual fill of tax and triggers automatic calculation via the internal Tax Engine:

Tax calculation is billed separately

Sending taxDetermination triggers the Tax Calculation Engine, a service billed separately from invoice issuance. To issue without the engine, fill in the taxes in the tax group and do not send taxDetermination. Pricing and billing terms are defined in your commercial plan.

• operationCode (integer): Internal code for determining the operation nature.
• issuerTaxProfile (string): Seller (origin) tax profile — e.g., industry, retail, wholesale.
• buyerTaxProfile (string): Buyer (destination) tax profile — e.g., final_consumer_non_icms_contributor, industry_icms_contributor.
• origin (string): Goods origin (same enum as tax.icms.origin).
• acquisitionPurpose (string): Acquisition purpose.

How the two groups combine:

1. taxDetermination filled → automatic calculation of ICMS, IPI, PIS and COFINS. IBS/CBS is not part of this calculation.
2. tax.IBSCBS with calculationMode = OfficialService → automatic calculation of IBS/CBS only. It can (and should) be combined with taxDetermination: this is the recommended combination for full automatic calculation.
3. Without taxDetermination, all tax fields must be filled manually. An IBSCBS group in Manual mode (default) does not accept taxDetermination on the same item (400) and has its values checked by the API (§11.4.1).

---

3. Appendix A: Main Group Mapping

The table below summarizes the mapping of the main groups from the API's JSON to the SEFAZ XML groups.

API Group (JSON)	SEFAZ XML Group	Description
(root of object)	ide	NF-e Identification
issuer	emit	Issuer Data
buyer	dest	Recipient Data
delivery	entrega	Delivery Location
withdrawal	retirada	Withdrawal Location
items	det	Detail of Products and Services (Items)
items.tax	imposto	Taxes incident on the item
items.tax.icms	ICMS	ICMS Group
items.tax.ipi	IPI	IPI Group
items.tax.pis	PIS	PIS Group
items.tax.cofins	COFINS	COFINS Group
items.tax.IBSCBS	IBSCBS	IBS and CBS Group (RTC)
totals	total	Total Values Group
totals.icms	ICMSTot	ICMS Totals
totals.issqn	ISSQNtot	ISSQN Totals
totals.ibsCbs	IBSCBSTot	IBS and CBS Totals (RTC)
transport	transp	Transport Data
billing	cobr	Billing Data (Invoice and Installments)
payment	pag	Payment Data
additionalInformation	infAdic	Additional Information
purchaseInformation	compra	Purchase Information (commitment, order)
export	exporta	Export Information
transactionIntermediate	infIntermed	Transaction Intermediary Information

---

4. Appendix B: Detailed Structure of New Tax Reform Groups

4.1. items.tax.IS (Selective Tax)

This group is not accepted by the API: values sent in the request are ignored. The platform does not calculate the Selective Tax yet, and the ISTot group is not generated in the XML.

4.2. items.tax.IBSCBS

"IBSCBS": {
  "situationCode": "000",
  "classCode": "000001",
  "basis": 2002.0,
  "state": {
    "rate": 0.1,      // 0.1% in 2026 (NT 2025.002, rule UB18-10)
    "amount": 2.00
  },
  "municipal": {
    "rate": 0.0,      // 0% in 2026 (NT 2025.002, rule UB37-10)
    "amount": 0.00
  },
  "cbs": {
    "rate": 0.9,      // 0.9% in 2026 (NT 2025.002, rule UB56-10)
    "amount": 18.02
  },
  "ibsTotalAmount": 2.00
}

CST 000 (cClassTrib 000001, full taxation) does not allow deferment (deferment) or rate reduction (reduction): NT 2025.002 rejects these groups when the CST indicator does not allow them (rules UB22-10 and UB26-10, rejections 1029 and 1032). Check the CST and cClassTrib indicator table before sending a subgroup.

• Purpose: To declare the new consumption taxes, IBS and CBS.
• situationCode and classCode: Keys to determine the item's tax regime.
• basis: Common tax base for the taxes.
• state and municipal: Detail the IBS, which is a dual tax. They contain the nominal rate (rate), the final amount (amount), and, when the CST allows it, subgroups for benefits like deferment (deferment) or rate reduction (reduction).
• cbs: Details the CBS, which is a single federal tax.
• amount of each sphere: basis × rate / 100 − deferment − returned amount. The rate is rate or, when reduction is present, reduction.effectiveRate (NT 2025.002, rules UB35-10, UB54-10 and UB67-10, rejections 1041, 1052 and 1069; tolerance of 0.01).
• ibsTotalAmount: Sum of state.amount and municipal.amount, minus the presumed credit when the cCredPres has indDeduzCredPres=1 (rule UB54a-10).

Platform limitation in Manual mode: the API currently requires municipal.rate and municipal.amount equal to 0 and ibsTotalAmount equal to state.amount, in any issuance year. From 2027 the NT sets the municipal IBS at 0.05% (rule UB37-10), and this API check does not follow that change yet. The check does not apply to CSTs 410, 810, 930, 800, 620 and 811.

4.3. totals.ibsCbs

"totals": {
  // ... other totals
  "ibsCbs": {
    "basis": 2002.0,
    "ibs": {
      "state": { "amount": 2.00 },
      "municipal": { "amount": 0.00 },
      "totalAmount": 2.00
    },
    "cbs": {
      "amount": 18.02
    }
  }
}

• Purpose: To consolidate the total values of the new taxes for the entire invoice.
• ibsCbs: Aggregates the tax bases and values of IBS and CBS from all items, separating totals by sphere (state, municipal, federal) and by benefit type (deferment, return).
• Complementary invoice (purposeType = Complement): the totals of a complementary invoice are not aggregated from the items. If any item carries the IBSCBS group, send a filled totals.ibsCbs, unless some item uses calculationMode = OfficialService with classCode informed (then the platform aggregates the total). An OfficialService item without classCode has its group dropped: it neither requires nor waives the total, and the invoice goes out without IBS/CBS on that item. Without totals.ibsCbs, when it is required, the API rejects the invoice with 400 (code 40007): the XML would go out without IBSCBSTot and SEFAZ would reject it with 1119 (rule W34-20).
• vNFTot: 🔒 Not part of the request: the platform fills the NF-e total. Under NT 2025.002 (rules VB01-10 and W60-10), vNFTot is the sum of vItem, and in 2025 and 2026 vItem does not add IBS, CBS and IS. That is why, today, vNFTot equals totals.icms.invoiceAmount (vNF). From 2027 on, IBS, CBS and IS become part of the total.

4.4. IBS/CBS Tax Benefit Subgroups

Both state and municipal (IBS) and cbs (CBS) share the same internal structure to represent tax benefits that reduce the tax due. Each may optionally contain three subgroups:

4.4.1. deferment — Deferment (gDif)

Represents tax deferment: the tax is calculated but its payment is postponed to a later stage in the chain.

"deferment": {
  "rate": 1.0,        // Deferment percentage (pDif)
  "amount": 20.02     // Deferred value (vICMSDif)
}

• rate: Percentage of the rate being deferred.
• amount: Deferment amount: basis × (sphere rate / 100) × (deferment.rate / 100), using the effective rate when reduction is present (NT 2025.002, rule UB23-10, for the state IBS).
• When it appears in XML: Only when cClassTrib indicates deferment (CST 510).

4.4.2. reduction — Rate Reduction (gRed)

Represents rate reduction (not of the calculation base). The effective rate applied is lower than the nominal one.

"reduction": {
  "rateReduction": 40.0,    // Reduction percentage (pRedAliq)
  "effectiveRate": 0.06     // Effective rate after reduction (pAliqEfet)
}

• rateReduction: Percentage of the reduction applied to the nominal rate (e.g., 40 means 40% reduction).
• effectiveRate: Effective rate resulting after the reduction (rate * (1 - rateReduction/100)).
• Critical invariant: The rate field at the top level (state.rate, municipal.rate, cbs.rate) must always be the nominal rate, never the effective one. The effective rate stays exclusively in reduction.effectiveRate. This separation is enforced by the API.

4.4.3. returnedAmount — Tax Return (gDevTrib)

Represents tax return to the acquirer in cases such as goods return or accounting adjustment.

"returnedAmount": {
  "amount": 10.0    // Amount to return (vDevTrib)
}

4.5. Special IBS/CBS Subgroups

In addition to per-jurisdiction tax benefits, IBSCBS accepts special subgroups for specific tax regimes.

4.5.1. monophase — Monophasic Taxation (gMonofasicoIBSCBS)

Applicable to fuels and other products subject to monophasic taxation (ad rem rate per taxable unit, art. 172-180 LC 214/2025).

"monophase": {
  "standard": {
    "quantityBasis": 10.0,
    "ibsAdRemRate": 15.0,
    "cbsAdRemRate": 25.0,
    "ibsAmount": 150.0,
    "cbsAmount": 250.0
  },
  "withholding": { /* monophasic taxation subject to withholding */ },
  "previouslyWithheld": { /* monophasic previously withheld */ },
  "deferment": { /* monophasic deferment (biofuels) */ },
  "ibsAmount": 140.0,    // Total monophasic IBS for the item (vTotIBSMonoItem)
  "cbsAmount": 255.0     // Total monophasic CBS for the item (vTotCBSMonoItem)
}

• standard (gMonofasicoPadrao): Monophasic taxation applied in the chain in a single stage.
  • quantityBasis: Taxed base quantity (qBCMono).
  • ibsAdRemRate / cbsAdRemRate: Ad rem rate in BRL per taxable unit.
  • ibsAmount / cbsAmount: quantityBasis * adRemRate.
• withholding (gMonofasicoRetido): Monophasic taxation in which the issuer is responsible for withholding.
• previouslyWithheld (gMonofasicoRetidoAnt): Monophasic taxation that was withheld in a previous stage of the chain (informational, no effect on the final value).
• deferment (gMonofasicoDif): Deferment specifically applicable to biofuels in monophasic taxation.
• ibsAmount / cbsAmount: Consolidated item totals for monophasic IBS and CBS.

4.5.2. operationalPresumedCredit — Operational Presumed Credit (gCredPresOper)

Presumed credit on specific operations (non-taxpayer rural producer, recycling from individuals, used goods from individuals for resale, etc.).

"operationalPresumedCredit": {
  "basis": 1000.0,
  "classificationCode": "RuralProducerNonTaxpayer",
  "ibs": {
    "rate": 10.0,
    "amount": 100.0,
    "suspensiveConditionAmount": 10.0
  },
  "cbs": {
    "rate": 5.0,
    "amount": 50.0,
    "suspensiveConditionAmount": 5.0
  }
}

• basis: Calculation base of the presumed credit (vBC).
• classificationCode: Type of presumed credit (see enum PresumedCreditClassificationCode in Appendix H).
• ibs / cbs:
  • rate: Presumed credit percentage (pCredPres).
  • amount: Presumed credit value (vCredPres).
  • suspensiveConditionAmount: Portion of the credit subject to suspensive condition (vCredPresCondSus). Materializes only when the condition is met.

4.5.3. creditTransfer — Credit Transfer (gTransfCred)

Applicable in merger, spin-off, incorporation, or transfer between cooperatives and members (CST 800).

"creditTransfer": {
  "ibsAmount": 50.0,    // IBS to transfer (vIBS)
  "cbsAmount": 30.0     // CBS to transfer (vCBS)
}

4.5.4. creditReversal — Credit Reversal (gEstornoCred)

Applicable when there is prohibition or obligation of credit reversal as per cClassTrib (ind_gEstornoCred field in the table).

"creditReversal": {
  "ibsReversalAmount": 2.0,    // IBS to reverse (vIBSEstCred)
  "cbsReversalAmount": 1.0     // CBS to reverse (vCBSEstCred)
}

4.5.5. governmentPurchase — Government Purchase Composition (gTribCompraGov)

Details how IBS and CBS are composed in sales to direct public administration agencies, autarchies, and foundations (art. 472/370 LC 214/2025).

⚠️ NT 2025.002 (rule UB82a-30) rejects this group when the invoice-level government purchase group (gCompraGov) is not informed (rejection 1144). Since the API does not accept gCompraGov yet (§6.5), do not send this group.

"governmentPurchase": {
  "stateRate": 8.0,       "stateAmount": 160.16,
  "municipalRate": 4.0,   "municipalAmount": 80.08,
  "cbsRate": 10.0,        "cbsAmount": 200.2
}

• Repeats the rate/amount structure for the three jurisdictions (UF, Municipality, CBS), but considering the pRedutor reduction applied to the government purchase.

4.5.6. regularTaxation — Hypothetical Regular Taxation

When there is a resolutive or suspensive condition (e.g., zero rate conditioned to specific destination), declare here what the taxation would be if the condition is not met. Important for assessment and audit.

"regularTaxation": {
  "situationCode": "000",
  "classCode": "000001",
  "stateEffectiveRate": 10.0,    "amount": 200.2,
  "municipalEffectiveRate": 5.0, "municipalAmount": 100.1,
  "cbsEffectiveRate": 12.0,      "cbsAmount": 240.24
}

• situationCode (CSTReg): CST that would apply if the resolutive/suspensive condition fell.
• classCode (cClassTribReg): Regular tax classification.
• Pairs stateEffectiveRate/amount, municipalEffectiveRate/municipalAmount, cbsEffectiveRate/cbsAmount: Effective rate and value that would be assessed.

4.5.7. zfmPresumedCredit — ZFM Presumed Credit (gCredPresIBSZFM)

Presumed credit specific to supplies from the Manaus Free Trade Zone (art. 450 LC 214/2025).

"zfmPresumedCredit": {
  "classificationCode": "IntermediateGoods",   // tpCredPresIBSZFM
  "amount": 123.45                              // vCredPresIBSZFM
}

• classificationCode: Determines the applicable percentage (55%, 75%, 90.25%, 100% — see enum IbsZfmPresumedCreditClassification in Appendix H).
• amount: Value of the presumed credit. Mandatory when creditType = 02.

4.6. donationIndicator and competenceAdjustment

4.6.1. donationIndicator — Donation Indicator (indDoacao)

When the operation is a donation (e.g., donation to a charitable entity, transfer without consideration), inform this field in IBSCBS so that the assessment correctly handles debits/reversals. Send "1" when the operation is a donation and omit the field otherwise: the NF-e schema only accepts the value 1 (NT 2025.002, field UB14a).

4.6.2. competenceAdjustment — Competence Adjustment (gAjusteCompet)

Reopens a previous fiscal competence period to include an IBS/CBS adjustment. The group sits inside items[].tax.IBSCBS:

"IBSCBS": {
  "situationCode": "811",
  "classCode": "811001",
  "competenceAdjustment": {
    "competence": "2026-08",   // YYYY-MM (competApur)
    "ibsAmount": 5.0,          // adjustment vIBS
    "cbsAmount": 3.0           // adjustment vCBS
  }
}

The group is only emitted on CST 811 items (cClassTrib 811001, 811002 or 811003). In the API, it is used in debit notes (purposeType = DebitInvoice) of types CancelCreditsExemptImmuneSales (02), UnprocessedInvoicesDebits (03) and SnDisqualification (08), which require at least one CST 811 item with competence and ibsAmount and/or cbsAmount ([V-DN-09]). NT 2025.002 (rule UB14-70) ties these types to cClassTrib 811001, 811002 and 811003.

---

5. Final Considerations

The API structure was designed to be flexible and accommodate both the current tax system and the new model of the Tax Reform. During the transition period, the old tax groups (ICMS, PIS, COFINS) and the new ones (IS, IBSCBS) will coexist.

It is crucial that issuing systems consult the official tables (CST, cClassTrib, etc.) and follow the validation rules described in the Taxpayer Manual and Technical Notes to ensure the correct issuance and authorization of fiscal documents.

For more details on specific validation rules, consult the SEFAZ documentation and current Technical Notes.

---

6. Appendix C: Detailed Resource Objects

This appendix details the structure of the main objects and sub-objects referenced in the API request body.

6.1. AddressResource

Defines the structure of an address, used in the buyer, delivery, withdrawal, and transportGroup groups.

• street (string): Street Address (xLgr).
• number (string): Address Number (nro).
• additionalInformation (string): Address Complement (xCpl).
• district (string): Neighborhood (xBairro).
• city (CityResource): Object containing the municipality code (code) and name (name).
• state (string): State abbreviation.
• postalCode (string): Postal Code (CEP).
• country (string): Country code or name.
• phone (string): Phone number.

6.2. BuyerResource

Contains the registration information of the invoice recipient.

• name (string): Name or Corporate Name (xNome).
• federalTaxNumber (integer): CNPJ or CPF.
• tradeName (string): Trade Name (xFant).
• stateTaxNumber (string): State Tax Number (IE).
• stateTaxNumberIndicator (enum): Recipient's IE Indicator (TaxPayer, Exempt, NonTaxPayer).
• address (AddressResource): Object with the recipient's address data.
• email (string): Recipient's email.
• type (enum): Person type (NaturalPerson, LegalEntity).
• taxRegime (enum): Tax regime.

6.3. DeliveryInformationResource

Defines the delivery location, if and only if it is different from the recipient's address.

• federalTaxNumber (integer): CNPJ or CPF of the delivery location.
• name (string): Name or Corporate Name.
• stateTaxNumber (string): State Tax Number.
• address (AddressResource): Object with the complete delivery address data.

6.4. WithdrawalInformationResource

Defines the withdrawal location, if and only if it is different from the issuer's address.

• federalTaxNumber (integer): CNPJ or CPF of the withdrawal location.
• name (string): Name or Corporate Name.
• address (AddressResource): Object with the complete withdrawal address data.

6.5. GovernmentPurchaseResource

Invoice-level government purchase group (gCompraGov). This group is not accepted by the API: values sent in the request are ignored. Without it, the item-level government purchase group (items[].tax.IBSCBS.governmentPurchase, §4.5.5) cannot be sent either: SEFAZ rejects it (NT 2025.002, rule UB82a-30, rejection 1144).

6.6. TransportInformationResource

Groups all information related to the transportation of the goods.

• freightModality (enum): Freight modality (ByIssuer, ByReceiver, etc.). (modFrete)
• transportGroup (TransportGroupResource): Carrier data. (transporta)
• transportVehicle (TransportVehicleResource): Main vehicle data. (veicTransp)
• reboque (ReboqueResource): Trailer vehicle data. (reboque)
• volume (VolumeResource): Information about transported volumes. (vol)
• transpRate (TransportRateResource): Transport ICMS retention data. (retTransp)
• sealNumber (string): Seal numbers.

6.6.1. TransportGroupResource

• name (string): Carrier's Name/Corporate Name.
• federalTaxNumber (integer): Carrier's CNPJ/CPF.
• stateTaxNumber (string): Carrier's State Tax Number.
• address (AddressResource): Carrier's full address.

6.6.2. TransportVehicleResource

• plate (string): Vehicle license plate. (placa)
• state (string): Vehicle registration state.
• rntc (string): National Registry of Road Freight Carriers.

6.6.3. ReboqueResource

• plate (string): Trailer license plate.
• state (string): Trailer registration state.
• rntc (string): Trailer's RNTRC.

6.6.4. VolumeResource

• volumeQuantity (integer): Quantity of volumes. (qVol)
• species (string): Species of volumes. (esp)
• brand (string): Brand of volumes. (marca)
• netWeight (number): Total net weight (in Kg). (pesoL)
• grossWeight (number): Total gross weight (in Kg). (pesoB)

6.7. PaymentResource and PaymentDetailResource

Structure for detailing the forms and amounts of payment for the operation.

• PaymentResource:
  • paymentDetail (array[PaymentDetailResource]): List of payment details.
  • payBack (number): Change amount.
• PaymentDetailResource:
  • method (enum): Payment method (Cash, CreditCard, InstantPayment).
  • amount (number): Payment amount.
  • paymentType (enum): Payment form indicator (InCash, Term).
  • card (CardResource): Card transaction details.

6.7.1. CardResource

• federalTaxNumber (string): CNPJ of the card acquirer.
• flag (enum): Card brand (e.g., Visa, Mastercard). (tBand)
• authorization (string): Transaction authorization number for cards, PIX, bank slips, and other electronic payments. (cAut)
• integrationPaymentType (enum): Integration type (Integrated, NotIntegrated). (tpIntegra)

6.8. BillingResource

Contains commercial billing data, such as invoice and installments.

• bill (BillResource): Invoice data.
• duplicates (array[DuplicateResource]): List of installments.

6.8.1. BillResource

• number (string): Invoice number. (nFat)
• originalAmount (number): Original invoice amount. (vOrig)
• discountAmount (number): Discount amount. (vDesc)
• netAmount (number): Net invoice amount. (vLiq)

6.8.2. DuplicateResource

• number (string): Installment number. (nDup)
• expirationOn (string): Due date. (dVenc)
• amount (number): Installment amount. (vDup)

6.9. AdditionalInformationResource

Groups complementary information, such as notes for the tax authority, referenced documents, and processes.

• fisco (string): Information for the Tax Authority.
• taxpayer (string): Information for the taxpayer.
• xmlAuthorized (array[integer]): List of CNPJs/CPFs authorized to download the XML.
• taxDocumentsReference (array[TaxDocumentsReferenceResource]): Referenced fiscal documents.
• referencedProcess (array[ReferencedProcessResource]): Referenced judicial/administrative processes.

6.9.1. TaxDocumentsReferenceResource

• documentElectronicInvoice (object): Contains the access key (accessKey) of a referenced NF-e/NFC-e.
• documentInvoiceReference (object): Contains data from a referenced model 1/1A invoice.
• taxCouponInformation (object): Contains data from a referenced fiscal coupon.

6.9.2. ReferencedProcessResource

• identifierConcessory (string): Process identifier.
• identifierOrigin (integer): Indicator of the process origin (e.g., SEFAZ, Federal Justice).

6.10. InvoiceItemResource

Details an item on the invoice.

• code (string): Product code.
• description (string): Product description.
• ncm (string): NCM code.
• cfop (integer): CFOP code.
• quantity (number): Quantity.
• unit (string): Unit of measure.
• unitAmount (number): Unit price.
• totalAmount (number): Gross total amount.
• usedMovableGood (boolean, optional): Used movable good indicator (indBemMovelUsado). The tag is emitted only when true.
• tax (InvoiceItemTaxResource): Object with all item taxes.
• vehicleDetail (VehicleDetailResource): Specific details for items representing new vehicles. See section 6.22. VehicleDetailResource for the complete field reference.
• fuelDetail (FuelResource): Details if the item is a fuel.
• importDeclarations (array[ImportDeclarationResource]): Import details.
• taxDetermination (TaxDeterminationResource): Group for automatic tax calculation.

6.11. InvoiceItemTaxResource

Groups all taxes incident on an item.

• totalTax (number): Approximate total tax amount (Transparency Law).
• icms (IcmsTaxResource): ICMS taxation.
• ipi (IPITaxResource): IPI taxation.
• pis (PISTaxResource): PIS taxation.
• cofins (CofinsTaxResource): COFINS taxation.
• IBSCBS (IBSCBSTaxResource): IBS and CBS taxation.

6.11.1. IcmsTaxResource

• origin (string): Origin of the goods.
• cst (string): ICMS Tax Situation Code.
• baseTax (number): ICMS tax base.
• rate (number): ICMS rate (%).
• amount (number): ICMS amount.
• ...other fields for ST, reduction, deferment, etc.

6.11.2. IPITaxResource

• cst (string): IPI Tax Situation Code.
• base (number): IPI tax base.
• rate (number): IPI rate (%).
• amount (number): IPI amount.

6.11.3. PISTaxResource and CofinsTaxResource

• cst (string): PIS/COFINS Tax Situation Code.
• baseTax (number): Tax base.
• rate (number): Rate (%).
• amount (number): Tax amount.

6.12. ISTaxResource

Item Selective Tax group. This group is not accepted by the API: values sent in the request are ignored.

6.13. IBSCBSTaxResource

Details the IBS and CBS taxation for an item, according to the Tax Reform.

• situationCode (string): IBS/CBS Tax Situation Code.
• classCode (string): Tax Classification Code.
• basis (number): Tax base.
• state (IBSStateTaxResource): State IBS details.
• municipal (IBSMunicipalTaxResource): Municipal IBS details.
• cbs (CBSTaxResource): CBS details.
• monophase (MonophaseIBSCBSTaxResource): Details for monophasic taxation.
• operationalPresumedCredit (OperationalPresumedCreditResource): Presumed credit details.

6.13.1. IBSStateTaxResource and IBSMunicipalTaxResource

• rate (number): IBS rate (%).
• amount (number): IBS amount.
• deferment (object): Contains rate and amount of the deferment.
• reduction (object): Contains rateReduction and effectiveRate of the reduction.

6.13.2. CBSTaxResource

• rate (number): CBS rate (%).
• amount (number): CBS amount.
• deferment (object): Contains rate and amount of the deferment.
• reduction (object): Contains rateReduction and effectiveRate of the reduction.

6.14. Total (Totals Schema)

Groups the consolidated total values of the entire invoice.

• icms (ICMSTotal): ICMS totals.
• issqn (ISSQNTotal): ISSQN totals.
• withheldTaxes (TotalsWithholdings): Totals of withheld taxes.
• ibsCbs (IBSCBSTotalsResource): IBS and CBS totals.

6.14.1. ICMSTotal

• baseTax (number): Sum of the ICMS tax base.
• icmsAmount (number): Sum of the ICMS amount.
• stCalculationBasisAmount (number): Sum of the ICMS-ST tax base.
• stAmount (number): Sum of the ICMS-ST amount.
• productAmount (number): Sum of the product amounts.
• invoiceAmount (number): Total invoice amount (old regime).

6.14.2. TotalsWithholdings

• pisAmount (number): Withheld PIS amount.
• cofinsAmount (number): Withheld COFINS amount.
• ...other fields for CSLL, IRRF, etc.

6.15. ISTotalsResource

Selective Tax totals (ISTot). This group is not accepted by the API: values sent in the request are ignored.

6.16. IBSCBSTotalsResource

• basis (number): Sum of the IBS/CBS tax base.
• ibs (IBSTotalsResource): Object with IBS totals.
• cbs (CBSTotalsResource): Object with CBS totals.
• monophase (MonophaseTotalsResource): Object with monophasic taxation totals.

6.17. IBSTotalsResource

Aggregates IBS totals.

• state (IBSStateTotalsResource): State IBS totals.
• municipal (IBSMunicipalTotalsResource): Municipal IBS totals.
• totalAmount (number): Total IBS amount.
• presumedCreditAmount (number): Total presumed credit amount.

6.18. CBSTotalsResource

Aggregates CBS totals.

• defermentAmount (number): Total deferment amount.
• returnedAmount (number): Total return amount.
• amount (number): Total CBS amount.
• presumedCreditAmount (number): Total presumed credit amount.

6.19. PurchaseInformationResource

Groups purchase information.

• commitmentNote (string): Commitment Note.
• purchaseOrder (string): Purchase Order.
• contractNumber (string): Contract Number.

6.20. ExportResource

Contains information about the export of goods.

• state (string): Abbreviation of the shipping state.
• office (string): Shipping location.
• local (string): Dispatch location.

6.21. IntermediateResource

Contains information of the transaction intermediary (marketplace, delivery platform, etc.).

• federalTaxNumber (integer): Intermediary's CNPJ.
• identifier (string): Identifier registered with the intermediary.

6.22. VehicleDetailResource

This group contains specific information for items representing new vehicles on the invoice. It corresponds to the veicProd group (fields J01 through J26) from the official NF-e layout, as defined in the XSD leiauteNFe_v4.00.xsd.

When to use: This group must be filled in exclusively when the invoice item is a brand-new vehicle (0 km). It is mandatory for sales operations conducted by dealerships, manufacturers, and authorized resellers of new vehicles. Each invoice item may contain only one product-specific group (vehicleDetail, fuelDetail, or medicineDetail). If more than one is provided, only the first one found will be used, following the order of precedence: medicine, vehicle, fuel.

Fields:

• operationType (integer): Operation Type (tpOp — field J02). Defines the commercial context of the vehicle sale. This field indicates how the sale transaction is being carried out and affects billing and tax rules.

  • 0 = Others (operations that do not fit the other categories)
  • 1 = Dealership sale (sale made by an authorized dealership)
  • 2 = Direct billing to end consumer (direct sale from the manufacturer to the consumer)
  • 3 = Direct sale to large consumers (e.g., fleet operators, government, car rental companies)
  • Validations: Required. Must be one of the values above (0, 1, 2, or 3).

• chassis (string): Vehicle Chassis — VIN (chassi — field J03). The Vehicle Identification Number, stamped on the chassis. This is the unique and universal identifier for the vehicle, used for tracking, registration, and documentation worldwide.

  • Validations: Required. Must contain exactly 17 alphanumeric characters (uppercase letters A to Z and digits 0 to 9). Pattern: [A-Z0-9]{17}.
  • Example: 9BWZZZ377VT004251

• colorCode (string): Vehicle Color Code (cCor — field J04). Internal code used by the manufacturer to identify the vehicle's color. Each manufacturer has its own color code table.

  • Validations: Required. Maximum of 4 characters.
  • Example: A1B2

• colorDescription (string): Color Description (xCor — field J05). Full name of the vehicle's color in plain language. Must match the code provided in colorCode.

  • Validations: Required. Maximum of 40 characters.
  • Example: Lunar Silver Metallic

• enginePower (string): Engine Power (pot — field J06). Maximum engine power expressed in horsepower (HP/CV). This value is listed on the vehicle's registration certificate.

  • Validations: Required. Maximum of 4 characters.
  • Example: 150 (equals 150 HP)

• engineDisplacement (string): Engine Displacement (cilin — field J07). Engine displacement expressed in cubic centimeters (CC). Indicates the total volume of the engine's cylinders.

  • Validations: Required. Maximum of 4 characters.
  • Example: 1998 (equals a 2.0-liter engine)

• netWeight (string): Net Weight (pesoL — field J08). Vehicle weight without cargo, passengers, or optional accessories, expressed in kilograms.

  • Validations: Required. Maximum of 9 characters.
  • Example: 1250

• grossWeight (string): Gross Weight (pesoB — field J09). Total vehicle weight including maximum permitted cargo capacity, expressed in kilograms.

  • Validations: Required. Maximum of 9 characters.
  • Example: 1650

• serialNumber (string): Serial Number (nSerie — field J10). Vehicle serial number assigned by the manufacturer. Serves as an additional production identifier.

  • Validations: Required. Maximum of 9 characters.
  • Example: ABC123456

• fuelType (string): Fuel Type (tpComb — field J11). Numeric code identifying the type of fuel used by the vehicle, as defined in the RENAVAM Table. The most common codes are:

  • 01 = Alcohol (Ethanol)
  • 02 = Gasoline
  • 03 = Diesel
  • 08 = Electric
  • 16 = Alcohol/Gasoline (flex-fuel)
  • 17 = Gasoline/Alcohol/CNG (flex-fuel + compressed natural gas)
  • 18 = Gasoline/Electric (hybrid)
  • Validations: Required. Maximum of 2 characters. Must match a valid code from the RENAVAM Table.

• engineNumber (string): Engine Number (nMotor — field J12). Engine identification number stamped on the engine block by the manufacturer.

  • Validations: Required. Maximum of 21 characters.
  • Example: MOT123456789012

• maximumTractionCapacity (string): Maximum Traction Capacity — CMT (CMT — field J13). Maximum weight the vehicle can tow, including its own weight and the trailer's load, expressed in metric tons with up to 4 decimal places.

  • Validations: Required. Maximum of 9 characters.
  • Example: 1.5000 (equals 1.5 metric tons)

• wheelBase (string): Wheelbase (dist — field J14). Distance measured between the center of the front axle and the center of the rear axle, expressed in millimeters.

  • Validations: Required. Maximum of 4 characters.
  • Example: 2620 (equals 2,620 mm)

• modelYear (integer): Model Year (anoMod — field J16). The model year of the vehicle, as defined by the manufacturer. The model year may differ from the manufacture year (e.g., a vehicle manufactured in 2025 with a 2026 model year).

  • Validations: Required. Must contain exactly 4 digits.
  • Example: 2026

• manufactureYear (integer): Manufacture Year (anoFab — field J17). The year in which the vehicle was actually produced on the assembly line.

  • Validations: Required. Must contain exactly 4 digits.
  • Example: 2025

• paintType (string): Paint Type (tpPint — field J18). Code identifying the paint finish type (e.g., solid, metallic, pearlescent).

  • Validations: Required. Exactly 1 character.
  • Example: M (Metallic)

• vehicleType (string): Vehicle Type (tpVeic — field J19). Numeric code classifying the vehicle type according to the RENAVAM Table (e.g., automobile, truck, motorcycle). The most common codes are:

  • 02 = Moped
  • 03 = Motor scooter
  • 04 = Motorcycle
  • 05 = Tricycle
  • 06 = Automobile
  • 13 = Pickup truck
  • 14 = Truck
  • 17 = Minibus
  • 22 = Truck-tractor
  • Validations: Required. Maximum of 2 characters. Must match a valid code from the RENAVAM Table.

• vehicleSpecies (integer): Vehicle Species (espVeic — field J20). Numeric code classifying the vehicle's intended purpose according to the RENAVAM Table:

  • 1 = Passenger
  • 2 = Cargo
  • 3 = Mixed (passenger and cargo)
  • 4 = Racing
  • 5 = Traction
  • 6 = Special purpose
  • Validations: Required. Must be a valid digit from the table above.

• vinCondition (string): VIN Condition (VIN — field J21). Indicates whether the vehicle's chassis number (VIN) has been re-stamped or is in its original factory condition. Re-stamping occurs when the original chassis was damaged and needed to be re-engraved by the vehicle registration authority (DETRAN).

  • R = Re-stamped (re-engraved chassis)
  • N = Normal (original factory chassis)
  • Validations: Required. Must be R or N.

• vehicleCondition (integer): Vehicle Condition (condVeic — field J22). Indicates the vehicle's state of completion at the time of sale. Unfinished or semi-finished vehicles are typically sold between manufacturers and body builders for completion.

  • 1 = Finished (vehicle ready for use, with all components)
  • 2 = Unfinished (vehicle missing an essential component, requiring completion)
  • 3 = Semi-finished (partially assembled vehicle, such as chassis-cabin)
  • Validations: Required. Must be 1, 2, or 3.

• brandModelCode (string): Brand/Model Code (cMod — field J23). Numeric code identifying the vehicle's brand and model combination in the RENAVAM Table. Each vehicle has a unique code that identifies, for example, "Volkswagen Gol 1.0" or "Toyota Corolla 2.0".

  • Validations: Required. Maximum of 6 numeric characters.
  • Example: 123456

• denatranColorCode (string): DENATRAN Color Code (cCorDENATRAN — field J24). Standardized color code defined by DENATRAN (National Traffic Department). Unlike colorCode (which is manufacturer-specific), this code is the official color classification for vehicle registration and documentation:

  • 01 = Yellow | 02 = Blue | 03 = Beige | 04 = White
  • 05 = Gray | 06 = Gold | 07 = Maroon | 08 = Orange
  • 09 = Brown | 10 = Silver | 11 = Black | 12 = Pink
  • 13 = Purple | 14 = Green | 15 = Red | 16 = Fantasy
  • Validations: Required. Maximum of 2 numeric characters. Must be one of the codes above.

• seatingCapacity (integer): Seating Capacity (lota — field J25). Maximum number of seated passengers the vehicle can carry, including the driver. This value is listed on the vehicle's registration certificate.

  • Validations: Required. Maximum of 3 digits.
  • Example: 5 (standard automobile with 5 seats)

• restrictionType (integer): Restriction Type (tpRest — field J26). Indicates whether there is any legal or financial restriction on the vehicle that limits its sale or ownership transfer:

  • 0 = No restriction (vehicle is free for sale and transfer)
  • 1 = Fiduciary alienation (vehicle used as collateral in financing)
  • 2 = Financial lease (vehicle under a leasing contract)
  • 3 = Ownership reserve (seller retains ownership until full payment)
  • 4 = Vehicle pledge (vehicle used as collateral for a loan)
  • 9 = Other restrictions
  • Validations: Required. Must be one of the values above (0, 1, 2, 3, 4, or 9).

Important Note: The vehicleDetail group is mutually exclusive with fuelDetail (fuel) and medicineDetail (medicine). Each invoice item may contain at most one of these product-specific groups. If more than one is provided by mistake, the API will follow the order of precedence: medicine > vehicle > fuel.

---

7. Appendix D: Common Errors and Their Solutions

This section describes the most common rejections during the NF-e/NFC-e issuance process and provides guidance on how to correct them.

7.1. General Rejections

Rejection 204: Duplicate NF-e

• What it means: An invoice with the same number, series, and issuer's CNPJ already exists in the SEFAZ database.
• Common Cause: Attempting to resend an invoice that has already been authorized or is being processed, or an error in sequential numbering control.
• How to Fix: Check the status of the original invoice. If it has already been authorized, do not resend it. If you need to issue a new invoice, increment the number field to the next available value in the serie sequence.

Rejection 225: XML Schema Failure

• What it means: The structure of the sent JSON does not match the layout expected by the API.
• Common Cause: Fields with incorrect data types (e.g., sending text where a number is expected), incorrect property names, or incorrect nested object structure.
• How to Fix: Review the request body and compare it with the OpenAPI specification and the examples provided in this documentation. Pay special attention to data types and object hierarchy.

Rejection 210: Invalid recipient's IE

• What it means: The State Tax Number (stateTaxNumber) provided for the buyer (buyer) is not valid for the destination state.
• Common Cause: Typo, non-existent IE, or an IE from a different state than the one in the buyer's address.
• How to Fix: Confirm the correct State Tax Number of the recipient. If the recipient is exempt or not a taxpayer, adjust the stateTaxNumberIndicator field to Exempt or NonTaxPayer and do not send the stateTaxNumber field.

Rejection 610: Total NF-e value differs from the sum of the values that compose the total value

• What it means: The totals.icms.invoiceAmount field does not match the sum of the item values and other fields that make up the total.
• Common Cause: Calculation error in the sum of items.totalAmount plus freight, insurance, ancillary expenses, taxes, and subtracting discounts.
• How to Fix: Recalculate the total invoice amount. The basic formula is: vProd (sum of totalAmount of items) - vDesc + vST + vFrete + vSeg + vOutro + vIPI + vIPIDevol. Fixing totals.icms.invoiceAmount already resolves vNFTot, which the platform derives from it automatically.

Rejection 321: Goods return NF-e does not have a referenced fiscal document

• What it means: The invoice was issued with purposeType = Devolution, but the access key of the original invoice being returned was not provided.
• Common Cause: Forgetting to fill in the additionalInformation.taxDocumentsReference group.
• How to Fix: Add the taxDocumentsReference group within additionalInformation, containing a documentElectronicInvoice object with the accessKey of the NF-e that originated the return.

7.2. Tax Reform (RTC) Rejections

Rejection 1115: IBS/CBS not informed

• What it means: For an operation under the new regime, the IBSCBS group was not informed in one or more items. Under NT 2025.002-RTC v1.51 (rule UB12-10), the rejection applies in homologation to CRT 3 issuers on invoices issued from 07/01/2026 on; in production, the rule is a future implementation.
• Common Cause: The operation already falls under the RTC rules, but the issuing system is not yet sending the items.tax.IBSCBS group.
• How to Fix: For each item on the invoice, add the IBSCBS object within tax, filling in the mandatory fields such as situationCode, classCode, basis, and the subgroups state, municipal, and cbs. Alternatively, send the group with calculationMode: "OfficialService", situationCode and classCode, and the platform calculates the remaining fields.

Rejection 1023: Informed IBS/CBS Tax Classification does not exist

• What it means: The code provided in items.tax.IBSCBS.classCode does not exist in the official cClassTrib table of SEFAZ.
• Common Cause: Typo or use of an outdated code.
• How to Fix: Consult the latest cClassTrib table, available on the National NF-e Portal, and use a valid code that corresponds to the item's taxation.

Rejection 1024: IBS and CBS Tax Classification incompatible with the informed CST

• What it means: The combination between situationCode (CST) and classCode (Tax Classification) is not allowed.
• Common Cause: A classCode representing an exemption was combined with a situationCode for full taxation, for example.
• How to Fix: Check the cClassTrib table. It contains the valid combinations between CST and Tax Classification. Adjust one of the two fields so that the combination is valid.

Rejection 1104: IBS and CBS tax base value differs from the sum of the values that compose it

• What it means: The value provided in items.tax.IBSCBS.basis does not correspond to the sum of the values that form the item's tax base.
• Common Cause: Error in calculating the tax base. Under NT 2025.002 (rule UB16-10, still future implementation at SEFAZ), the base is vProd + vServ + vFrete + vSeg + vOutro + vII − vDesc − vPIS − vCOFINS − vICMS − vICMSUFDest − vFCP − vFCPUFDest − vICMSMono − vISSQN + vIS; IPI is not included. In Manual mode, the API already rejects with 400 a basis that differs from the composition it computes from the item: vProd + vFrete + vSeg + vOutro + vII + ICMS-ST + FCP-ST − vDesc − vICMS − vICMSUFDest − vFCPUFDest − vFCP − vICMSMono − vPIS − vCOFINS.
• How to Fix: Recalculate the basis field for each item, ensuring it reflects the correct sum of the values that compose the tax base for the new taxes.

Rejection 1026: Invalid State IBS rate

• What it means: The state IBS rate (items.tax.IBSCBS.state.rate) does not correspond to the rate in effect for the issuance period.
• Common Cause: Use of an incorrect rate. During the transition period, the rates are fixed (e.g., 0.1% for 2025/2026).
• How to Fix: Adjust the rate to the correct value defined in the Tax Reform legislation for the year of invoice issuance. Consult the documentation for the current values.

Rejection 1001: NF-e with debit or credit purpose only for IBS/CBS

⚠️ API limitation: in Manual mode (the default), the API requires icms, pis and cofins on the item to compute the IBS/CBS base, except for CSTs 410, 810, 930, 800, 620 and 811. For notes subject to rule B25-80 whose item uses a regular-taxation CST (for example, debit 04 or 06, which do not restrict the cClassTrib), omitting those groups returns 400 (ICMS is required to compute IBS/CBS basis.). In those cases, use calculationMode: OfficialService.

• What it means: Under NT 2025.002 (rule B25-80), a credit note (purposeType = CreditInvoice, finNFe=5) or debit note (purposeType = DebitInvoice, finNFe=6) must not carry ICMS, ISSQN, IPI, II, PIS, PIS-ST, COFINS, COFINS-ST, ICMS UF Destino or Returned Tax (impostoDevol). The API does not strip these groups: whatever you send in items[].tax goes into the XML.
• When the rule does not apply (B25-80, Exception 1): credit notes RefusedDeliveryTotalOrNotFound (03) and RefusedDeliveryPartial (06), credit note 04 (value reduction, not yet accepted by the API) and debit note InventoryLoss (07). Debit note AdvancePayment (06) may carry PIS, PIS-ST, COFINS and COFINS-ST on an NF-e issued in 2026 (Exception 2) and IPI (Exception 3).
• Common Cause: A credit or debit note of a type subject to the rule sent with old-regime groups, for example copied from the original NF-e.
• How to Fix: For the types subject to the rule, remove icms, ipi, ii, pis, cofins and icmsDestination from the tax object of every item. For the Exception 1 types, these groups remain allowed.
• Incorrect Example (debit note TransferCreditsToCooperatives, type 01, subject to the rule):

  {
    "purposeType": "DebitInvoice",
    "debitType": "TransferCreditsToCooperatives",
    "operationType": "Outgoing",
    "operationNature": "Transferência de créditos para cooperativa",
    "additionalInformation": {
      "taxDocumentsReference": [
        { "documentElectronicInvoice": { "accessKey": "35260911222333000181550010000012341000012341" } }
      ]
    },
    // ... other invoice data
    "items": [
      {
        // ... item data
        "tax": {
          // INCORRECT: old-regime groups on debit note 01 (rejection 1001)
          "icms": { "origin": "0", "cst": "90" },
          "pis": { "cst": "99" },
          "cofins": { "cst": "99" },
          "IBSCBS": {
            "situationCode": "800",
            "classCode": "800002", // tpNFDebito 01 requires cClassTrib 800002 (NT 2025.002, rule UB14-70)
            "creditTransfer": { "ibsAmount": 150.00, "cbsAmount": 90.00 }
          }
        }
      }
    ]
  }

• Corrected Example:

  {
    "purposeType": "DebitInvoice",
    "debitType": "TransferCreditsToCooperatives",
    "operationType": "Outgoing",
    "operationNature": "Transferência de créditos para cooperativa",
    "additionalInformation": {
      "taxDocumentsReference": [
        { "documentElectronicInvoice": { "accessKey": "35260911222333000181550010000012341000012341" } }
      ]
    },
    // ... other invoice data
    "items": [
      {
        // ... item data
        "tax": {
          // CORRECT: only the IBSCBS group is sent
          "IBSCBS": {
            "situationCode": "800",
            "classCode": "800002", // tpNFDebito 01 requires cClassTrib 800002 (NT 2025.002, rule UB14-70)
            "creditTransfer": { "ibsAmount": 150.00, "cbsAmount": 90.00 }
          }
        }
      }
    ]
  }

  Debit note 01 requires operationType = Outgoing ([V-DN-05]), the original NF-e in additionalInformation.taxDocumentsReference ([V-DN-02]) and a non-empty operationNature ([V-DN-07]).

---

9. Appendix F: Best Practices for Integration

To ensure a more efficient, robust, and resilient integration with the NF-e issuance API, we recommend following the practices listed below.

9.1. Numbering and Series Control

• The control of the sequential numbering (number) for each series (serie) can be handled by either the client system or our system. Regardless of who handles the control, it is essential to avoid "Rejection 204: Duplicate NF-e". Additionally, the client system must always check for gaps in the numerical sequence. If a number is not used, it is necessary to request its invalidation to avoid problems with the Tax Authority.
• Changing Series: Whenever it is necessary to change or start using a new fiscal series, it is a mandatory requirement that the issuer's State Tax Number registration be previously updated in the NFE.io system for the use of this new series. This obligation exists regardless of which system controls the numbering.

9.2. Pre-Submission Data Validation

• Reduce Unnecessary Calls: Before sending data to the API, perform as many validations as possible in your system. This includes:
  • Validation of Registration and Address Data: To ensure the validity of the issuer's and recipient's registration data, we recommend using our query APIs. They allow you to check if CNPJs and CPFs are valid, if the State Tax Number is active and linked to the correct CNPJ, and also to query addresses from the CEP. Using these APIs avoids rejections due to incorrect registration or address data.
  • Ensuring that mandatory fields are filled according to the operation (e.g., CFOP, NCM).

9.3. Error and Rejection Handling

• Detailed Logs: Our system maintains a complete and detailed history of all requests (sent JSON) and responses (received JSON) for a long period. In case of errors, these logs are a powerful tool for analysis and debugging, facilitating the identification of the root cause of the problem and speeding up technical support.
• Retry Mechanism: For network errors or momentary SEFAZ instability (e.g., timeouts, 5xx errors), our system already has a retry mechanism with exponential backoff. This prevents the client from having to worry about implementing this logic, as we automatically manage retry attempts in case of temporary failures.

9.4. NF-e Lifecycle Management

• Status Query (Webhooks): After sending an invoice, the initial status may be "Processing". To get the final status (such as "Issued" or "Error"), our system works with the concept of webhooks. Instead of implementing a periodic query routine, you should configure an endpoint in your system to receive our automatic notifications as soon as the processing is complete. This makes communication more efficient and real-time.
• Local Storage: Although the legal responsibility for storage lies with the issuer, our system stores all data and the XML file of each authorized NF-e for a minimum period of 5 years. You can download the XML and DANFE in PDF at any time through our platform, ensuring fiscal compliance.
• Be Prepared for Contingency: SEFAZ systems can become unavailable. To simplify your integration, the contingency issuance mode can be configured directly in your State Tax Number registration on our platform. With this configuration, our system automatically manages entering and exiting contingency mode when necessary, allowing your business operation to continue without interruption. If you prefer, you can still manage contingency manually.

9.5. Performance and Efficiency

• Keep Auxiliary Tables Updated: Maintain a local and updated copy of the reference tables published by the government, such as NCM, CEST, CFOP, and especially the new Tax Reform tables (cClassTrib, cCredPres). This avoids the need for external queries for each issuance.
• Avoid Unnecessary Data: Send only the fields and groups necessary for your operation. Omitting optional groups that do not apply (like delivery if the delivery is at the buyer's address) makes the payload cleaner and validation faster.

9.6. Security

• Protect Your Credentials: Treat API access keys and digital certificates as highly sensitive information. Do not expose them in the client-side source code (frontend) and store them securely in your backend.

8. Appendix E: Cancellation, Invalidation, and Return

It is common to have doubts about which procedure to adopt to correct or annul a fiscal operation. This appendix clarifies the difference between the three main mechanisms.

8.1. Cancellation

• What it is: It is the act of invalidating an authorized NF-e, making it fiscally void.
• When to use: When the commercial operation did not materialize (e.g., purchase cancellation) and, crucially, the goods have not yet circulated.
• Main Rules:
  • Must be requested within a legal deadline, usually 24 hours after authorization.
  • The goods must not have left the issuing establishment.
  • The recipient must not have performed the "Acknowledgment of Issuance".

8.2. Number Invalidation

• What it is: It is the process of communicating to SEFAZ that a range of NF-e numbers was not and will not be used.
• When to use: When there is a gap in the sequence of invoice numbering. For example, invoice 100 was issued and the next to be issued is 102, leaving number 101 vacant.
• Main Rules:
  • Invalidation applies only to numbers that have not been used in any NF-e (not even in a rejected or denied invoice).
  • It serves for the Tax Authority to know that the "gap" in the sequence is not tax evasion, but a technical or operational failure.

8.3. Return Invoice

• What it is: It is the issuance of a new NF-e (with purposeType = Devolution) to nullify the effects of a previous operation.
• When to use: When the goods have circulated and the recipient is returning them, either due to refusal upon receipt or return after delivery. It is the only way to annul an operation after the goods have circulated.
• Main Rules:
  • It is an incoming invoice (operationType = Incoming) for the original issuer.
  • It must reference the access key of the original NF-e being returned.
  • The taxes are "mirrored" to nullify the debit of the outgoing invoice.

---

10. Appendix G: Reference Table - CST and Tax Classification (IBS/CBS)

The following table details the Tax Situation Codes (situationCode) and Tax Classification Codes (classCode) for IBS and CBS, according to the Tax Reform. The correct combination of these codes is essential for the validation of the NF-e in the new regime.

SituationCode (CST)	CST Description	ClassCode (cClassTrib)	ClassCode Description
000	Full taxation	000001	Situations fully taxed by IBS and CBS.
000	Full taxation	000002	Road exploration, observing art. 11 of Complementary Law No. 214, of 2025.
000	Full taxation	000003	Automotive regime - incentivized projects, observing art. 311 of Complementary Law No. 214, of 2025.
000	Full taxation	000004	Automotive regime - incentivized projects, observing art. 312 of Complementary Law No. 214, of 2025.
010	Taxation with uniform rates - FGTS operations	010001	FGTS operations not carried out by Caixa Econômica Federal, observing art. 212 of Complementary Law No. 214, of 2025.
011	Taxation with uniform rates reduced by 60%	011001	Funeral assistance plans, observing art. 236 of Complementary Law No. 214, of 2025.
011	Taxation with uniform rates reduced by 60%	011002	Health assistance plans, observing art. 237 of Complementary Law No. 214, of 2025.
011	Taxation with uniform rates reduced by 60%	011003	Intermediation of health assistance plans, observing art. 240 of Complementary Law No. 214, of 2025.
011	Taxation with uniform rates	011004	Contests and lotteries, observing art. 246 of Complementary Law No. 214, of 2025.
011	Taxation with uniform rates reduced by 30%	011005	Pet health assistance plans, observing art. 243 of Complementary Law No. 214, of 2025.
200	Zero rate	200001	Acquisitions of machinery, apparatus, instruments, equipment, raw materials, intermediate products, and packaging materials between companies authorized to operate in export processing zones, observing art. 103 of Complementary Law No. 214, of 2025.
200	Zero rate	200002	Supply or import of tractors, agricultural machinery and implements, intended for non-taxpayer rural producers, and cargo transport vehicles intended for non-taxpayer individual autonomous cargo transporters, observing art. 110 of Complementary Law No. 214, of 2025.
200	Zero rate	200003	Sales of products for human consumption listed in Annex I of Complementary Law No. 214, of 2025, with the specification of the respective NCM/SH classifications, which make up the National Basic Food Basket, created under art. 8 of Constitutional Amendment No. 132, of December 20, 2023, observing art. 125 of Complementary Law No. 214, of 2025.
200	Zero rate	200004	Sale of medical devices with the specification of the respective NCM/SH classifications provided for in Annex XII of Complementary Law No. 214, of 2025, observing art. 144 of Complementary Law No. 214, of 2025.
200	Zero rate	200005	Sale of medical devices with the specification of the respective NCM/SH classifications provided for in Annex IV of Complementary Law No. 214, of 2025, when acquired by direct public administration bodies, autarchies, and public foundations, observing art. 144 of Complementary Law No. 214, of 2025.
200	Zero rate	200006	In a public health emergency situation recognized by the competent federal, state, district, or municipal legislative power, a joint act of the Minister of Finance and the IBS Management Committee may be issued at any time to include devices not listed in Annex XIII of Complementary Law No. 214, of 2025, with the benefit's validity limited to the period and locality of the public health emergency, observing art. 144 of Complementary Law No. 214, of 2025.
200	Zero rate	200007	Supply of accessibility devices for people with disabilities listed in Annex XIV of Complementary Law No. 214, of 2025, with the specification of the respective NCM/SH classifications, observing art. 145 of Complementary Law No. 214, of 2025.
200	Zero rate	200008	Supply of accessibility devices for people with disabilities listed in Annex V of Complementary Law No. 214, of 2025, with the specification of the respective NCM/SH classifications, when acquired by direct public administration bodies, autarchies, public foundations, and immune entities, observing art. 145 of Complementary Law No. 214, of 2025.
200	Zero rate	200009	Supply of medicines listed in Annex XIV of Complementary Law No. 214, of 2025, with the specification of the respective NCM/SH classifications, observing art. 146 of Complementary Law No. 214, of 2025.
200	Zero rate	200010	Supply of medicines registered with Anvisa, when acquired by direct public administration bodies, autarchies, public foundations, and immune entities, observing art. 146 of Complementary Law No. 214, of 2025.
200	Zero rate	200011	Supply of compositions for enteral and parenteral nutrition, special compositions, and nutritional formulas for people with inborn errors of metabolism listed in Annex VI of Complementary Law No. 214, of 2025, with the specification of the respective NCM/SH classifications, when acquired by direct public administration bodies, autarchies, and public foundations, observing art. 146 of Complementary Law No. 214, of 2025.
200	Zero rate	200012	In a public health emergency situation recognized by the competent federal, state, district, or municipal legislative power, a joint act of the Minister of Finance and the IBS Management Committee may be issued at any time to include devices not listed in Annex XIV of Complementary Law No. 214, of 2025, with the benefit's validity limited to the period and locality of the public health emergency, observing art. 146 of Complementary Law No. 214, of 2025.
200	Zero rate	200013	Supply of tampons, internal or external sanitary napkins, disposable or reusable, absorbent panties, and menstrual cups, observing art. 147 of Complementary Law No. 214, of 2025.
200	Zero rate	200014	Supply of horticultural products, fruits, and eggs, listed in Annex XV of Complementary Law No. 214, of 2025, with the specification of the respective NCM/SH classifications and provided they are not cooked, observing art. 148 of Complementary Law No. 214, of 2025.
200	Zero rate	200015	Sale of nationally manufactured passenger cars with at least 4 (four) doors, including the trunk access door, when acquired by professional drivers who demonstrably exercise, in a car they own, the activity of an autonomous passenger driver, as a holder of an authorization, permission, or concession from the public authority, and who destine the car for use in the rental category (taxi), or by people with physical, visual, auditory disabilities, severe or profound mental disability, autism spectrum disorder, with impairments in social communication and in restricted or repetitive patterns of behavior of moderate or severe level, under the terms of the relevant legislation, observing the provisions of art. 149 of Complementary Law No. 214, of 2025.
200	Zero rate	200016	Provision of research and development services by a non-profit Scientific, Technological, and Innovation Institution (ICT) to the direct public administration, autarchies, and public foundations or to a taxpayer subject to the regular IBS and CBS regime, observing the provisions of art. 156 of Complementary Law No. 214, of 2025.
200	Zero rate	200017	Operations related to the FGTS, considering those necessary for the application of Law No. 8,036, of 1990, carried out by the Board of Trustees or Executive Secretariat of the FGTS, observing art. 212 of Complementary Law No. 214, of 2025.
200	Zero rate	200018	Reinsurance and retrocession operations are subject to a zero rate, including when reinsurance and retrocession premiums are ceded abroad, observing art. 223 of Complementary Law No. 214, of 2025.
200	Zero rate	200019	If the importer of financial services is a taxpayer who carries out the operations referred to in items I to V of the caput of art. 182, a zero rate will be applied on importation, without prejudice to the maintenance of the right to deduct these expenses from the IBS and CBS tax base, observing art. 231 of Complementary Law No. 214, of 2025.
200	Zero rate	200020	Operation carried out by cooperative societies opting for a specific IBS and CBS regime, when the member assigns a good or service to the cooperative they participate in, and the cooperative supplies a good or service to the member subject to the regular IBS and CBS regime, observing art. 271 of Complementary Law No. 214, of 2025.
200	Zero rate	200021	Urban, semi-urban, and metropolitan public collective passenger rail and waterway transport services, observing art. 285 of Complementary Law No. 214, of 2025.
200	Zero rate	200022	Operation originating outside the Manaus Free Trade Zone that destines a nationally produced industrialized tangible good to a taxpayer established in the Manaus Free Trade Zone who is qualified under art. 442 of Complementary Law No. 214, of 2025, and subject to the regular IBS and CBS regime or opting for the Simples Nacional regime under art. 12 of Complementary Law No. 123, of 2006, observing art. 445 of Complementary Law No. 214, of 2025.
200	Zero rate	200023	Operation carried out by an incentivized industry that destines an intermediate tangible good to another incentivized industry in the Manaus Free Trade Zone, provided that the delivery or availability of the goods occurs within said area, observing art. 448 of Complementary Law No. 214, of 2025.
200	Zero rate	200024	Operation originating outside the Free Trade Areas that destines a nationally produced industrialized tangible good to a taxpayer established in the Free Trade Areas who is qualified under art. 456 of Complementary Law No. 214, of 2025, and subject to the regular IBS and CBS regime or opting for the Simples Nacional regime under art. 12 of Complementary Law No. 123, of 2006, observing art. 463 of Complementary Law No. 214, of 2025.
200	Zero rate for CBS only and reduced by 60% for IBS	200025	Supply of education services related to the University for All Program (Prouni), established by Law No. 11,096, of January 13, 2005, observing art. 308 of Complementary Law No. 214, of 2025.
200	Rate reduced by 80%	200026	Leasing of properties located in rehabilitated zones, for a period of 5 (five) years, counted from the date of issuance of the occupancy permit, and related to urban rehabilitation projects of historic zones and critical areas for recovery and urban reconversion of Municipalities or the Federal District, to be delimited by municipal or district law, observing art. 158 of Complementary Law No. 214, of 2025.
200	Rate reduced by 70%	200027	Operations of leasing, onerous assignment, and rental of real estate, observing art. 261 of Complementary Law No. 214, of 2025.
200	Rate reduced by 60%	200028	Supply of education services listed in Annex II of Complementary Law No. 214, of 2025, with the specification of the respective classifications of the Brazilian Nomenclature of Services, Intangibles, and Other Operations that Produce Variations in Equity (NBS), observing art. 129 of Complementary Law No. 214, of 2025.
200	Rate reduced by 60%	200029	Supply of human health services listed in Annex III of Complementary Law No. 214, of 2025, with the specification of the respective NBS classifications, observing art. 130 of Complementary Law No. 214, of 2025.
200	Rate reduced by 60%	200030	Sale of medical devices listed in Annex IV of Complementary Law No. 214, of 2025, with the specification of the respective NCM/SH classifications, observing art. 131 of Complementary Law No. 214, of 2025.
200	Rate reduced by 60%	200031	Supply of accessibility devices for people with disabilities listed in Annex V of Complementary Law No. 214, of 2025, with the specification of the respective NCM/SH classifications, observing art. 132 of Complementary Law No. 214, of 2025.
200	Rate reduced by 60%	200032	Supply of medicines registered with Anvisa or produced by compounding pharmacies, except for medicines subject to the zero rate under art. 141 of Complementary Law No. 214, of 2025, observing art. 133 of Complementary Law No. 214, of 2025.
200	Rate reduced by 60%	200033	Supply of compositions for enteral and parenteral nutrition, special compositions, and nutritional formulas for people with inborn errors of metabolism listed in Annex VI of Complementary Law No. 214, of 2025, with the specification of the respective NCM/SH classifications, observing art. 133 of Complementary Law No. 214, of 2025.
200	Rate reduced by 60%	200034	Supply of food for human consumption listed in Annex VII of Complementary Law No. 214, of 2025, with the specification of the respective NCM/SH classifications, observing art. 135 of Complementary Law No. 214, of 2025.
200	Rate reduced by 60%	200035	Supply of personal hygiene and cleaning products listed in Annex VIII of Complementary Law No. 214, of 2025, with the specification of the respective NCM/SH classifications, observing art. 136 of Complementary Law No. 214, of 2025.
200	Rate reduced by 60%	200036	Supply of agricultural, aquaculture, fishery, forestry, and plant extractive products in natura, observing art. 137 of Complementary Law No. 214, of 2025.
200	Rate reduced by 60%	200037	Supply of environmental services for the conservation or recovery of native vegetation, even if provided in the form of sustainable management of agricultural, agroforestry, and agrosilvopastoral systems, in accordance with the definitions and requirements of specific legislation, observing art. 137 of Complementary Law No. 214, of 2025.
200	Rate reduced by 60%	200038	Supply of agricultural and aquaculture inputs listed in Annex IX of Complementary Law No. 214, of 2025, with the specification of the respective NCM/SH and NBS classifications, observing art. 138 of Complementary Law No. 214, of 2025.
200	Rate reduced by 60%	200039	Supply of services and the licensing or assignment of rights listed in Annex X of Complementary Law No. 214, of 2025, with the specification of the respective NBS classifications, when intended for the following national artistic, cultural, event, journalistic, and audiovisual productions: theatrical, circus, and dance shows, musical concerts, carnival or folkloric parades, academic and scientific events, such as congresses, conferences, and symposiums, business fairs, exhibitions, cultural, artistic, and literary fairs and shows; auditorium or journalistic programs, films, documentaries, series, soap operas, interviews, and music videos, observing art. 139 of Complementary Law No. 214, of 2025.
200	Rate reduced by 60%	200040	Supply of the following institutional communication services to the direct public administration, autarchies, and public foundations: services aimed at the planning, creation, programming, and maintenance of electronic pages of the public administration, monitoring and management of their social networks, and optimization of pages and digital channels for search engines and production of messages, infographics, interactive panels, and institutional content, press relations services, which bring together organizational strategies to promote and reinforce the communication of the contracting bodies and entities with their stakeholders, through interaction with press professionals, and public relations services, which comprise the planned, cohesive, and continuous communication effort aimed at establishing an adequate perception of the institutional performance and objectives, from the stimulus to mutual understanding and the maintenance of relationship patterns and information flows between the contracting bodies and entities and their stakeholders, in the country and abroad, observing art. 140 of Complementary Law No. 214, of 2025.
200	Rate reduced by 60%	200041	Operations related to the following sports activities: provision of sports education service, classified under code 1.2205.12.00 of the NBS, and management and exploitation of sports by associations and sports clubs affiliated with the state or federal body responsible for coordinating sports, including through the sale of tickets for sports events, onerous or non-onerous supply of goods and services, including tickets, through supporter programs, assignment of athletes' sports rights, and transfer of athletes to another sports entity or their return to activity in another sports entity, observing art. 141 of Complementary Law No. 214, of 2025.
200	Rate reduced by 60%	200042	Operations related to the provision of sports education service, classified under code 1.2205.12.00 of the NBS, observing art. 141 of Complementary Law No. 214, of 2025.
200	Rate reduced by 60%	200043	Supply to the direct public administration, autarchies, and public foundations of services and goods related to sovereignty and national security, information security, and cybersecurity listed in Annex XI of Complementary Law No. 214, of 2025, with the specification of the respective NBS and NCM/SH classifications, observing art. 142 of Complementary Law No. 214, of 2025.
200	Rate reduced by 60%	200044	Operations and provision of information security and cybersecurity services developed by a company that has a Brazilian partner with a minimum of 20% (twenty percent) of its capital stock, listed in Annex XI of Complementary Law No. 214, of 2025, with the specification of the respective NBS and NCM/SH classifications, observing art. 142 of Complementary Law No. 214, of 2025.
200	Rate reduced by 60%	200045	Operations related to urban rehabilitation projects of historic zones and critical areas for recovery and urban reconversion of Municipalities or the Federal District, to be delimited by municipal or district law, observing art. 158 of Complementary Law No. 214, of 2025.
200	Rate reduced by 50%	200046	Operations with real estate, observing art. 261 of Complementary Law No. 214, of 2025.
200	Rate reduced by 40%	200047	Bars and Restaurants, observing art. 275 of Complementary Law No. 214, of 2025.
200	Rate reduced by 40%	200048	Hospitality, Amusement Parks, and Theme Parks, observing art. 281 of Complementary Law No. 214, of 2025.
200	Rate reduced by 40%	200049	Intermunicipal and interstate collective passenger road, rail, and waterway transport, observing art. 286 of Complementary Law No. 214, of 2025.
200	Rate reduced by 40%	200450	Regional collective passenger or cargo air transport services, observing art. 287 of Complementary Law No. 214, of 2025.
200	Rate reduced by 40%	200051	Tourism Agencies, observing art. 289 of Complementary Law No. 214, of 2025.
200	Rate reduced by 30%	200052	Provision of services of the following intellectual professions of a scientific, literary, or artistic nature, subject to supervision by a professional council: administrators, lawyers, architects and urban planners, social workers, librarians, biologists, accountants, economists, home economists, physical education professionals, engineers and agronomists, statisticians, veterinarians and zootechnicians, museologists, chemists, public relations professionals, industrial technicians, and agricultural technicians, observing art. 127 of Complementary Law No. 214, of 2025.
210	Rate reduced by 50% with tax base reducer	210001	Social reducer applied once in the sale of a new residential property, observing art. 259 of Complementary Law No. 214, of 2025.
210	Rate reduced by 50% with tax base reducer	210002	Social reducer applied once in the sale of a residential lot, observing art. 259 of Complementary Law No. 214, of 2025.
210	Rate reduced by 70% with tax base reducer	210003	Social reducer in operations of leasing, onerous assignment, and rental of residential real estate, observing art. 260 of Complementary Law No. 214, of 2025.
220	Fixed rate	220001	Real estate development subject to the special taxation regime, observing art. 485 of Complementary Law No. 214, of 2025.
220	Fixed rate	220002	Real estate development subject to the special taxation regime, observing art. 485 of Complementary Law No. 214, of 2025.
220	Fixed rate	220003	Sale of property resulting from land subdivision, observing art. 486 of Complementary Law No. 214, of 2025.
221	Proportional fixed rate	221001	Leasing, onerous assignment, or rental of real estate with a rate on gross revenue, observing art. 487 of Complementary Law No. 214, of 2025.
400	Exemption	400001	Provision of urban, semi-urban, and metropolitan public collective passenger road and metro transport services, under a public authorization, permission, or concession regime, observing art. 157 of Complementary Law No. 214, of 2025.
410	Immunity and non-incidence	410001	Provision of bonuses when they are included in the respective fiscal document and do not depend on a subsequent event, observing art. 5 of Complementary Law No. 214, of 2025.
410	Immunity and non-incidence	410002	Transfers between establishments belonging to the same taxpayer, observing art. 6 of Complementary Law No. 214, of 2025.
410	Immunity and non-incidence	410003	Donations, observing art. 6 of Complementary Law No. 214, of 2025.
410	Immunity and non-incidence	410004	Exports of goods and services, observing art. 8 of Complementary Law No. 214, of 2025.
410	Immunity and non-incidence	410005	Supplies made by the Union, States, Federal District, and Municipalities, observing art. 9 of Complementary Law No. 214, of 2025.
410	Immunity and non-incidence	410006	Supplies made by religious entities and temples of any cult, including their assistance and charitable organizations, observing art. 9 of Complementary Law No. 214, of 2025.
410	Immunity and non-incidence	410007	Supplies made by political parties, including their foundations, workers' trade union entities, and non-profit education and social assistance institutions, observing art. 9 of Complementary Law No. 214, of 2025.
410	Immunity and non-incidence	410008	Supplies of books, newspapers, periodicals, and the paper intended for their printing, observing art. 9 of Complementary Law No. 214, of 2025.
410	Immunity and non-incidence	410009	Supplies of phonograms and musical videograms produced in Brazil containing musical or literary-musical works by Brazilian authors and/or works in general interpreted by Brazilian artists, as well as the material supports or digital files that contain them, except in the industrial replication stage of laser-read optical media, observing art. 9 of Complementary Law No. 214, of 2025.
410	Immunity and non-incidence	410010	Supplies of communication services in the modalities of sound broadcasting and free and open reception of sound and images, observing art. 9 of Complementary Law No. 214, of 2025.
410	Immunity and non-incidence	410011	Supplies of gold, when defined in law as a financial asset or exchange instrument, observing art. 9 of Complementary Law No. 214, of 2025.
410	Immunity and non-incidence	410012	Supply by a condominium not opting for the regular regime, observing art. 26 of Complementary Law No. 214, of 2025.
410	Immunity and non-incidence	410013	Exports of fuels, observing art. 98 of Complementary Law No. 214, of 2025.
410	Immunity and non-incidence	410014	Supply by a non-taxpayer rural producer, observing art. 164 of Complementary Law No. 214, of 2025.
410	Immunity and non-incidence	410015	Supply by a non-taxpayer autonomous transporter, observing art. 169 of Complementary Law No. 214, of 2025.
410	Immunity and non-incidence	410016	Supply or acquisition of solid waste, observing art. 170 of Complementary Law No. 214, of 2025.
410	Immunity and non-incidence	410017	Acquisition of movable property with presumed credit subject to the condition of resale, observing art. 171 of Complementary Law No. 214, of 2025.
410	Immunity and non-incidence	410018	Operations related to guarantor and executor funds of public policies, including housing, provided for by law, understood as services provided to the fund by its operating agent and by the entity in charge of its administration, observing art. 213 of Complementary Law No. 214, of 2025.
410	Immunity and non-incidence	410019	Exclusion of tips from the tax base in the supply of food, observing art. 274 of Complementary Law No. 214, of 2025.
410	Immunity and non-incidence	410020	Exclusion of the intermediation value from the tax base in the supply of food, observing art. 274 of Complementary Law No. 214, of 2025.
510	Deferment	510001	Operations, subject to deferment, with electricity or related rights, concerning generation, commercialization, distribution, and transmission, observing art. 28 of Complementary Law No. 214, of 2025.
510	Deferment	510002	Operations, subject to deferment, with agricultural and aquaculture inputs intended for a taxpayer rural producer, observing art. 138 of Complementary Law No. 214, of 2025.
550	Suspension	550001	Exports of tangible goods, observing art. 82 of Complementary Law No. 214, of 2025.
550	Suspension	550002	Transit Regime, observing art. 84 of Complementary Law No. 214, of 2025.
550	Suspension	550003	Deposit Regimes, observing art. 85 of Complementary Law No. 214, of 2025.
550	Suspension	550004	Deposit Regimes, observing art. 87 of Complementary Law No. 214, of 2025.
550	Suspension	550005	Deposit Regimes, observing art. 87 of Complementary Law No. 214, of 2025.
550	Suspension	550006	Temporary Stay Regimes, observing art. 88 of Complementary Law No. 214, of 2025.
550	Suspension	550007	Improvement Regimes, observing art. 90 of Complementary Law No. 214, of 2025.
550	Suspension	550008	Import of goods for the Temporary Repetro Regime, as per item I of art. 93 of Complementary Law No. 214, of 2025.
550	Suspension	550009	Temporary GNL, as per item II of art. 93 of Complementary Law No. 214, of 2025.
550	Suspension	550010	Permanent Repetro, as per item III of art. 93 of Complementary Law No. 214, of 2025.
550	Suspension	550011	Repetro-Industrialization, as per item IV of art. 93 of Complementary Law No. 214, of 2025.
550	Suspension	550012	Repetro-National, as per item V of art. 93 of Complementary Law No. 214, of 2025.
550	Suspension	550013	Repetro-Warehouse, as per item VI of art. 93 of Complementary Law No. 214, of 2025.
550	Suspension	550014	Export Processing Zone, observing arts. 99, 100, and 102 of Complementary Law No. 214, of 2025.
550	Suspension	550015	Tax Regime for Incentive to Modernization and Expansion of Port Structure - Reporto, observing art. 105 of Complementary Law No. 214, of 2025.
550	Suspension	550016	Special Incentive Regime for Infrastructure Development - Reidi, observing art. 106 of Complementary Law No. 214, of 2025.
550	Suspension	550017	Tax Regime for Incentive to Naval Economic Activity – Renaval, observing art. 107 of Complementary Law No. 214, of 2025.
550	Suspension	550018	Exemption from the acquisition of capital goods, observing art. 109 of Complementary Law No. 214, of 2025.
550	Suspension	550019	Import of tangible goods by an incentivized industry for use in the Manaus Free Trade Zone, observing art. 443 of Complementary Law No. 214, of 2025.
550	Suspension	550020	Free trade areas, observing art. 461 of Complementary Law No. 214, of 2025.
620	Monophasic taxation	620001	Monophasic taxation on fuels, observing art. 172 and art. 179 I of Complementary Law No. 214, of 2025.
620	Monophasic taxation	620002	Monophasic taxation with responsibility for withholding on fuels, observing art. 178 of Complementary Law No. 214, of 2025.
620	Monophasic taxation	620003	Monophasic taxation with taxes withheld by responsibility on fuels, observing art. 178 of Complementary Law No. 214, of 2025.
620	Monophasic taxation	620004	Monophasic taxation on a mixture of EAC with gasoline A in a percentage higher or lower than the mandatory one, observing art. 179 of Complementary Law No. 214, of 2025.
620	Monophasic taxation	620005	Monophasic taxation on fuels previously charged, observing art. 180 of Complementary Law No. 214, of 2025.
800	Credit transfer	800001	Merger, spin-off, or incorporation, observing art. 55 of Complementary Law No. 214, of 2025.
800	Credit transfer	800002	Transfer of credit from the member, including single cooperatives, to the cooperative they participate in from operations preceding the operations in which they supply goods and services and the presumed credits, observing art. 272 of Complementary Law No. 214, of 2025.
810	Adjustments	810001	Presumed credit on the value calculated in supplies from the Manaus Free Trade Zone, observing art. 450 of Complementary Law No. 214, of 2025.
820	Taxation in a specific regime declaration	820001	Document with information on the provision of health assistance plan services, but with taxation carried out by other means, observing art. 235 of Complementary Law No. 214, of 2025.
820	Taxation in a specific regime declaration	820002	Document with information on the provision of funeral assistance plan services, but with taxation carried out by other means, observing art. 236 of Complementary Law No. 214, of 2025.
820	Taxation in a specific regime declaration	820003	Document with information on the provision of pet health assistance plan services, but with taxation carried out by other means, observing art. 243 of Complementary Law No. 214, of 2025.
820	Taxation in a specific regime declaration	820004	Document with information on the provision of lottery contest services, but with taxation carried out by other means, observing art. 248 of Complementary Law No. 214, of 2025.
820	Taxation in a specific regime declaration	820005	Document with information on the sale of real estate, but with taxation carried out by other means, observing art. 254 of Complementary Law No. 214, of 2025.

---

11. Appendix H: Complete Enumeration (Enum) Reference

This appendix documents all enumerations used by the API, with the mapping between the JSON value, the corresponding SEFAZ XML value (when applicable), and the description of each value's meaning.

11.1. Operation Identification Enums

11.1.1. OperationType — Operation Type (tpNF)

Identifies whether the NF-e/NFC-e represents an inflow or outflow of goods from the issuer's establishment.

JSON Value	SEFAZ Value	Description	When to use
Outgoing	1	Outflow	Sales, shipments, outgoing transfers, exports. Default.
Incoming	0	Inflow	Received returns, returns, complementary inflow NF-e, credit NF-e.

Rule: Invoices with purposeType = Devolution or creditType informed must mandatorily be Incoming.

11.1.2. Destination — Destination Location Identifier (idDest)

Indicates where the goods are destined for purposes of interstate taxation and DIFAL/IBS-CBS calculation.

JSON Value	SEFAZ Value	Description
None	—	Not defined (do not use in production).
InternalOperation	1	Internal operation — recipient's UF equal to issuer's UF. Default.
InterstateOperation	2	Interstate operation — recipient's UF different from issuer's UF.
InternationalOperation	3	Operation with foreign country — recipient in country other than Brazil.

Legacy aliases: Internal_Operation, Interstate_Operation, International_Operation (with underscore) are accepted for compatibility, but the form without underscore is preferred.

11.1.3. PurposeType — Issuance Purpose (finNFe)

Defines the fiscal nature of the NF-e/NFC-e and governs which groups can/must be filled.

JSON Value	SEFAZ Value	Description	Restrictions
None	0	Not defined	Do not use.
Normal	1	Normal NF-e	Default. Standard fiscal operation.
Complement	2	Complementary NF-e	Must reference an original NF-e in additionalInformation.taxDocumentsReference.
Adjustment	3	Adjustment NF-e	Must reference original NF-e. Items' totalIndicator must be false.
Devolution	4	Goods return	Must be operationType = Incoming and reference the original NF-e.
CreditInvoice	5	Credit note (RTC)	Requires creditType (§11.1.5).
DebitInvoice	6	Debit note (RTC)	Requires debitType (§11.1.4).

RTC: the credit/debit purpose goes in purposeType (finNFe 5 or 6, NT 2025.002) and the subtype in creditType (tpNFCredito) or debitType (tpNFDebito).

11.1.4. DebitType — Debit Note Type (tpNFDebito)

Applicable only when purposeType = DebitInvoice (finNFe 6). Details the debit reason according to the Tax Reform.

JSON Value	SEFAZ Value	Description
TransferCreditsToCooperatives	01	Credit transfer to cooperatives
CancelCreditsExemptImmuneSales	02	Credit cancellation for exempt/immune sales
UnprocessedInvoicesDebits	03	Debits of invoices not processed in the calculation
FinesAndInterest	04	Fines and interest
TransferInheritanceCredit	05	Credit transfer in succession
AdvancePayment	06	Advance payment
InventoryLoss	07	Inventory loss
SnDisqualification	08	Simples Nacional disqualification

API requirements per type: 02, 03 and 08 require at least one CST 811 item with items[].tax.IBSCBS.competenceAdjustment ([V-DN-09]); 03 and 04 require the per-item reference in items[].referencedDFe ([V-DN-10], NT 2025.002, rule VC02-10); 07 requires at least one CST 410 item with creditReversal ([V-DN-11]); 01 requires the original NF-e in additionalInformation.taxDocumentsReference and operationType = Outgoing ([V-DN-02], [V-DN-05]).

11.1.5. CreditType — Credit Note Type (tpNFCredito)

Applicable only when purposeType = CreditInvoice (finNFe 5).

JSON Value	SEFAZ Value	Description
IbsPresumedCreditAppropriationZfm	02	Appropriation of IBS presumed credit on the debit balance in the ZFM
RefusedDeliveryTotalOrNotFound	03	Return due to total refusal on delivery or recipient not found
TransferCreditSuccession	05	Credit transfer in succession
RefusedDeliveryPartial	06	Return due to partial refusal on delivery

NT 2025.002: the standard also defines types 01 (Fines and interest) and 04 (Value reduction), which are not yet accepted by the API. The availability of each type is described in Credit and Debit Notes.

11.2. Consumer / Buyer Enums

11.2.1. ConsumerType — Final Consumer Indicator (indFinal)

JSON Value	SEFAZ Value	Description
Normal	0	Operation not intended for final consumer (resale, industrialization, etc.). Default for CNPJ.
FinalConsumer	1	Operation intended for final consumer. Default for CPF/NIF.

Inference rule: If omitted, the system uses buyer.federalTaxNumber: CNPJ → Normal; CPF/NIF → FinalConsumer.

11.2.2. ConsumerPresenceType — Presence Indicator (indPres)

Characterizes the channel/modality of the commercial operation.

JSON Value	SEFAZ Value	Description
None	0	Not applicable (complementary or adjustment NF-e).
Presence	1	In-person operation (physical POS).
Internet	2	Non-presence operation via Internet (e-commerce). Default.
Telephone	3	Non-presence operation via telesales.
Delivery	4	NFC-e in operation with home delivery.
OthersNonPresenceOperation	9	Others, non-presence operation.

NFC-e: Only Presence and Delivery are accepted.

11.2.3. PersonType — Person Type

JSON Value	Numeric Value	Description
Undefined	0	Undefined.
NaturalPerson	2	Natural Person (PF).
LegalEntity	4	Legal Entity (PJ).
Company	8	(obsolete, internal use) Service provider.
Customer	16	(obsolete, internal use) Customer.

Decimal flags: This enum uses [Flags], but in practice only NaturalPerson and LegalEntity are used in the external payload.

11.2.4. ReceiverStateTaxIndicator — Recipient IE Indicator (indIEDest)

Defines the recipient's relationship with ICMS — critical field for DIFAL calculation and IE validation.

JSON Value	SEFAZ Value	Description	IE Behavior
None	—	Not defined	Do not use.
TaxPayer	1	ICMS Taxpayer	stateTaxNumber must be informed and valid.
Exempt	2	Taxpayer exempt from registration	stateTaxNumber must not be informed.
NonTaxPayer	9	Non-Taxpayer	stateTaxNumber optional (may or may not have IE).

11.3. Tax and Regime Enums

11.3.1. TaxRegime — Tax Regime Code (CRT)

JSON Value	SEFAZ Value	Description
None	—	Not defined.
LucroReal	3	Real Profit.
LucroPresumido	3	Presumed Profit (same CRT as Real Profit — categorized as "Normal Regime").
SimplesNacional	1	Simples Nacional.
SimplesNacionalExcessoSublimite	2	Simples Nacional — gross revenue sublimit excess.
MicroempreendedorIndividual	4	Individual Microentrepreneur (MEI).
Isento	—	Exempt.

11.3.2. SpecialTaxRegime — Special Tax Regime (indRegTrib)

JSON Value	Description
Nenhum	None
MicroempresaMunicipal	Municipal Microenterprise
Estimativa	Estimative
SociedadeDeProfissionais	Society of Professionals
MicroempreendedorIndividual	Individual Microentrepreneur (MEI)
MicroempresarioEmpresaPequenoPorte	Microentrepreneur and Small Business (ME/EPP)
Automatico	Automatic

11.3.3. ExemptReason — ICMS Exemption Reason (motDesICMS)

JSON Value	SEFAZ Value	Description
Agriculture	3	Use in agriculture
Others	9	Others
DevelopmentEntities	12	Agricultural development and promotion entity

11.3.4. DuductionIndicator — Exempted ICMS Deduction Indicator (indDeducao)

JSON Value	SEFAZ Value	Description
NotDeduct	0	The exempted ICMS amount does not deduct from the NF-e total.
Deduce	1	The exempted ICMS amount deducts from the NF-e total.

11.4. IBS/CBS Enums (Tax Reform)

11.4.1. TaxCalculationMode — IBS/CBS Calculation Mode

Defines how IBS/CBS fields are filled.

JSON Value	Numeric Value	Description
Manual	0	Manual fill of all tax fields. Default. The API checks the values and rejects the item with 400 when: taxDetermination is present on the same item; icms, pis or cofins is missing (they are part of the base); basis differs from the composition computed by the platform (0.01 tolerance); municipal.rate or municipal.amount is not 0; or ibsTotalAmount differs from state.amount. The checks do not apply to CSTs 410, 810 and 930; for CSTs 800, 620 and 811 only the taxDetermination prohibition applies.
OfficialService	1	Automatic calculation via official service. Only situationCode and classCode are needed; other tax fields are ignored on input and filled by the calculation service. The classCode is mandatory: without it, the platform discards the item's entire IBSCBS group and the invoice goes on without IBS/CBS.

11.4.2. IbsZfmPresumedCreditClassification — ZFM Presumed Credit Classification (tpCredPresIBSZFM)

For calculating IBS presumed credit on supplies from the Manaus Free Trade Zone (art. 450 LC 214/2025).

JSON Value	Percentage	Description
NoPresumedCredit	0%	No presumed credit.
FinalConsumptionGoods	55%	Final consumption goods.
CapitalGoods	75%	Capital goods.
IntermediateGoods	90.25%	Intermediate goods.
ItAndOtherGoods	100%	IT and other goods defined in legislation.

11.4.3. PresumedCreditClassificationCode — Operational Presumed Credit (cCredPres)

Classifies the operation that grants the operational presumed credit.

JSON Value	SEFAZ Value	Description
RuralProducerNonTaxpayer	01	Non-taxpayer rural producer (art. 168 LC 214/2025)
TacPfTransportServiceNonTaxpayer	02	Non-taxpayer PF transport service TAC (art. 169)
RecyclingFromIndividual	03	Recycling from individual (art. 170)
UsedMovableGoodsFromIndividualForResale	04	Used movable goods from PF for resale (art. 171)
OptionalRegimeForCooperative	—	Optional regime for cooperative

cCredPres table: The official table (Technical Note 2025.002) has 13 codes (01–13), including the automotive regime (05–06) and the Manaus Free Trade Zone / Free Trade Areas (07–13). The OptionalRegimeForCooperative value does not map to a direct cCredPres code and is handled by the cooperatives' specific regime.

11.4.4. GovernmentPurchaseEntityType — Government Entity Type (tpEnteGov)

Used by the gCompraGov group, which is not yet accepted by the API (§6.5).

JSON Value	SEFAZ Value	Description
Union	1	Union
State	2	State
FederalDistrict	3	Federal District
Municipality	4	Municipality

11.4.5. GovernmentPurchaseOperationType — Government Operation Type (tpOperGov)

Used by the gCompraGov group, which is not yet accepted by the API (§6.5).

JSON Value	SEFAZ Value	Description
Supply	1	Supply
Payment	2	Payment receipt
SupplyThenPay	—	Simultaneous supply and payment
PayForPastSupply	—	Payment for past supply
SupplyAfterPay	—	Supply after payment
PayNowSupplyLater	—	Pay now, supply later
SupplyAndPayNow	—	Supply and pay now

tpOperGov field: In NT 2025.002 (including v1.40), the SEFAZ field accepts only 1 (Supply) and 2 (Payment receipt). The other values are NFe.io API abstractions, resolved to 1 or 2 according to the IBS/CBS taxable event — combined scenarios are handled by validation rules and the refDFeAnt field, not by new codes.

11.5. Payment Enums

11.5.1. PaymentMethod — Payment Method (tPag)

Complete list of payment methods accepted by SEFAZ.

JSON Value	SEFAZ Value	Description
Cash	01	Cash
Cheque	02	Check
CreditCard	03	Credit Card
DebitCard	04	Debit Card
StoreCredict	05	Store Credit
FoodVouchers	10	Food Vouchers
MealVouchers	11	Meal Vouchers
GiftVouchers	12	Gift Vouchers
FuelVouchers	13	Fuel Vouchers
MercantileDuplicate	14	Mercantile Duplicate
BankBill	15	Bank Slip
BankDeposit	16	Bank Deposit
InstantPayment	17	Instant Payment (PIX) — dynamic
WireTransfer	18	Bank Transfer / Digital Wallet
Cashback	19	Loyalty Program / Cashback / Virtual Credit
StaticInstantPayment	20	Static PIX
StoreCredit	21	Store Credit
ElectronicPaymentNotInformed	22	Electronic Payment Not Informed
WithoutPayment	90	No Payment (e.g., shipment, bonification)
Others	99	Others

Validation: When method = CreditCard or DebitCard, the card group is mandatory.

11.5.2. PaymentType — Payment Form Indicator (indPag)

JSON Value	SEFAZ Value	Description
InCash	0	Cash payment (upfront)
Term	1	Term payment (installments)

11.5.3. IntegrationPaymentType — Integration Type (tpIntegra)

Applicable inside the card group.

JSON Value	SEFAZ Value	Description
Integrated	1	Payment integrated with the company's automation system (e.g., TEF, E-commerce).
NotIntegrated	2	Payment not integrated (e.g., independent POS equipment).

11.5.4. FlagCard — Card Flag (tBand)

JSON Value	SEFAZ Value	Flag
None	00	Not defined
Visa	01	Visa
Mastercard	02	Mastercard
AmericanExpress	03	American Express
Sorocred	04	Sorocred
DinersClub	05	Diners Club
Elo	06	Elo
Hipercard	07	Hipercard
Aura	08	Aura
Cabal	09	Cabal
Alelo	10	Alelo
BanesCard	11	Banescard
CalCard	12	Calcard
Credz	13	Credz
Discover	14	Discover
GoodCard	15	Good Card
GreenCard	16	Green Card
Hiper	17	Hiper
JCB	18	JCB
Mais	19	Mais
MaxVan	20	Maxvan
Policard	21	Policard
RedeCompras	22	Rede Compras
Sodexo	23	Sodexo
ValeCard	24	ValeCard
Verocheque	25	Verocheque
VR	26	VR
Ticket	27	Ticket
Other	99	Others

11.6. Transport and Import Enums

11.6.1. ShippingModality — Freight Modality (modFrete)

JSON Value	SEFAZ Value	Description
ByIssuer	0	Freight contracted by the Sender (CIF)
ByReceiver	1	Freight contracted by the Recipient (FOB)
ByThirdParties	2	Freight contracted by third parties
OwnBySender	3	Own transport by sender
OwnByBuyer	4	Own transport by recipient
Free	9	No transport occurrence. Default.

Validation: If Free, the transportGroup, transportVehicle, reboque and volume groups must not be filled.

11.6.2. IntermediationType — Import Intermediation Form (tpIntermedio)

JSON Value	SEFAZ Value	Description
None	0	Not defined
ByOwn	1	Import on own account
ImportOnBehalf	2	Import on account and order of third party
ByOrder	3	Import by order

11.6.3. InternationalTransportType — International Transport Mode (tpViaTransp)

Informed in the Import Declaration (DI).

JSON Value	SEFAZ Value	Description
None	0	Not defined
Maritime	1	Maritime
River	2	River
Lake	3	Lake
Airline	4	Air
Postal	5	Postal
Railway	6	Railway
Highway	7	Highway
Network	8	Pipeline / Transmission Network
Own	9	Own means
Ficta	10	Fictional inflow / outflow
Courier	11	Courier service
Handcarry	12	Hand-carry

11.7. Print and Environment Enums

11.7.1. PrintType — DANFE Print Format (tpImp)

JSON Value	SEFAZ Value	Description
None	0	No DANFE generation
NFeNormalPortrait	1	DANFE normal — Portrait
NFeNormalLandscape	2	DANFE normal — Landscape
NFeSimplified	3	Simplified DANFE
DANFE_NFC_E	4	DANFE NFC-e
DANFE_NFC_E_MSG_ELETRONICA	5	DANFE NFC-e in electronic message

11.7.2. EnvironmentType — Environment Type (tpAmb)

JSON Value	SEFAZ Value	Description
None	—	Not defined
Production	1	Production (fiscal validity)
Test	2	Homologation (no fiscal validity)

11.7.3. StateTaxProcessingAuthorizer

Identifies the SEFAZ authorizer that processed (or is processing) the document.

JSON Value	Description
Normal	Normal Authorizer (issuer's UF SEFAZ or alternative authorizer)
EPEC	Authorizer for Prior Issuance Event in Contingency

11.8. Status and Event Enums

11.8.1. InvoiceStatus — NF-e Status

JSON Value	Internal Numeric	Description
None	0	Initial state / not defined
Created	1	Created (received by API, not yet sent to SEFAZ)
Processing	2	In processing (submission in progress)
Issued	3	Issued and authorized by SEFAZ
IssuedContingency	4	Issued in contingency
Cancelled	5	Cancelled
Disabled	6	Invalidated (numbering)
IssueDenied	-2	Issuance denied by SEFAZ
Error	-1	Processing error

11.8.2. EconomicActivityType — Economic Activity Type

JSON Value	Description
Main	Main
Secondary	Secondary

11.9. Brazilian States Enum (StateCode)

List of Brazilian UF abbreviations + foreign indicator (EX). Applicable to fields like state (address), customsClearanceState, etc.

Abbreviation	Description
NA	Not Applicable
RO, AC, AM, RR, PA, AP, TO	North Region
MA, PI, CE, RN, PB, PE, AL, SE, BA	Northeast Region
MG, ES, RJ, SP	Southeast Region
PR, SC, RS	South Region
MS, MT, GO, DF	Center-West Region
EX	Foreign country

11.10. Legal Nature Enum (LegalNature)

Applicable to the issuer (issuer.legalNature).

JSON Value	Description
EmpresaPublica	Public Company
SociedadeEconomiaMista	Mixed Economy Society
SociedadeAnonimaAberta	Open Joint-Stock Company
SociedadeAnonimaFechada	Closed Joint-Stock Company
SociedadeEmpresariaLimitada	Limited Business Society
SociedadeEmpresariaEmNomeColetivo	Business Society in Collective Name
SociedadeEmpresariaEmComanditaSimples	Business Society in Simple Limited Partnership
SociedadeEmpresariaEmComanditaporAcoes	Business Society in Limited Partnership by Shares
SociedadeemContaParticipacao	Society in Participation Account
Empresario	Individual Entrepreneur
Cooperativa	Cooperative
ConsorcioSociedades	Consortium of Societies
GrupoSociedades	Group of Societies
EmpresaDomiciliadaExterior	Company Domiciled Abroad
ClubeFundoInvestimento	Investment Club/Fund
SociedadeSimplesPura	Pure Simple Society
SociedadeSimplesLimitada	Limited Simple Society
SociedadeSimplesEmNomeColetivo	Simple Society in Collective Name
SociedadeSimplesEmComanditaSimples	Simple Society in Simple Limited Partnership
EmpresaBinacional	Binational Company
ConsorcioEmpregadores	Consortium of Employers
ConsorcioSimples	Simple Consortium
EireliNaturezaEmpresaria	EIRELI of Business Nature
EireliNaturezaSimples	EIRELI of Simple Nature
ServicoNotarial	Notarial and Registration Service
FundacaoPrivada	Private Foundation
ServicoSocialAutonomo	Autonomous Social Service
CondominioEdilicio	Building Condominium
ComissaoConciliacaoPrevia	Prior Conciliation Commission
EntidadeMediacaoArbitragem	Mediation and Arbitration Entity
PartidoPolitico	Political Party
EntidadeSindical	Trade Union Entity
EstabelecimentoBrasilFundacaoAssociacaoEstrangeiras	Brazilian Establishment of Foreign Foundation or Association
FundacaoAssociacaoDomiciliadaExterior	Foundation or Association Domiciled Abroad
OrganizacaoReligiosa	Religious Organization
ComunidadeIndigena	Indigenous Community
FundoPrivado	Private Fund
AssociacaoPrivada	Private Association

---

12. Appendix I: Property-by-Property Mapping (JSON ↔ SEFAZ XML)

This section complements Appendix A (§3) going down to the level of each individual property. For each JSON field, we indicate the full path, the corresponding XML tag in the official layout (NT 2025.002), the type, and filling notes.

Convention: The JSON path uses dot notation (e.g., buyer.address.state). The XML tag uses the exact element name in the official schema. When a JSON field encapsulates multiple tags or auxiliary structures, the "XML Tag" lists the principal tag.

12.1. Invoice Identification (ide)

These fields live at the root level of the request JSON.

JSON Path	XML Tag	Type	Notes
serie	serie	int	Document series (0–999).
number	nNF	int	Sequential number.
issuedOn	dhEmi	datetime	Issue date and time. Optional: when omitted, defaults to operationOn or the processing date. Do not send for NFC-e.
operationOn	dhSaiEnt	datetime	Exit/entry date and time. Do not send for NFC-e.
operationNature	natOp	string	Operation description.
operationType	tpNF	enum	Outgoing=1, Incoming=0. See §11.1.1.
destination	idDest	enum	See §11.1.2.
printType	tpImp	enum	See §11.7.1.
purposeType	finNFe	enum	See §11.1.3.
debitType	tpNFDebito	enum	Only for purposeType = DebitInvoice (finNFe 6). See §11.1.4.
creditType	tpNFCredito	enum	Only for purposeType = CreditInvoice (finNFe 5). See §11.1.5.
consumerType	indFinal	enum	See §11.2.1.
presenceType	indPres	enum	See §11.2.2.
contingencyOn	dhCont	datetime	Entry into contingency.
contingencyJustification	xJust	string	Justification (min. 15 chars).

12.2. Government Purchases (gCompraGov)

This group is not accepted by the API: values sent in the request are ignored. See §6.5.

12.3. Buyer / Recipient (dest)

JSON Path	XML Tag	Type	Notes
buyer.name	xNome	string	Mandatory.
buyer.federalTaxNumber	CNPJ or CPF	int	Mandatory. Or idEstrangeiro for foreign.
buyer.email	email	string	Mandatory.
buyer.tradeName	xFant	string	Trade name.
buyer.taxRegime	CRT	enum	See §11.3.1.
buyer.stateTaxNumber	IE	string	State registration.
buyer.stateTaxNumberIndicator	indIEDest	enum	See §11.2.4.
buyer.type	(logical)	enum	Person type (NaturalPerson/LegalEntity).
buyer.address.state	UF	string	ISO 3166-2 abbreviation (2 chars).
buyer.address.city.code	cMun	string	IBGE code.
buyer.address.city.name	xMun	string	Municipality name.
buyer.address.district	xBairro	string	District.
buyer.address.additionalInformation	xCpl	string	Address complement.
buyer.address.street	xLgr	string	Street.
buyer.address.number	nro	string	"S/N" if no number.
buyer.address.postalCode	CEP	string	Postal code (digits only).
buyer.address.country	xPais	string	ISO 3166-1 alpha-3. Default BRA.
buyer.address.phone	fone	string	Phone (area code + number).

12.4. Delivery and Withdrawal Locations

JSON Path	XML Tag	Type	Notes
delivery.federalTaxNumber	CNPJ/CPF (in entrega)	int	Only if different from buyer.
delivery.address.*	entrega/...	object	Same structure as buyer.address.
withdrawal.federalTaxNumber	CNPJ/CPF (in retirada)	int	Only if different from issuer.
withdrawal.address.*	retirada/...	object	Same structure as buyer.address.

12.5. Item — Identification and Values

JSON Path	XML Tag	Type	Notes
items[].code	cProd	string	Mandatory.
items[].codeGTIN	cEAN	string	"SEM GTIN" if non-existent.
items[].description	xProd	string	Mandatory.
items[].ncm	NCM	string	2 or 8 digits.
items[].nve[]	NVE	string array	Customs and Statistical Value Nomenclature.
items[].extipi	EXTIPI	string	TIPI exception.
items[].cfop	CFOP	int	Mandatory if no taxDetermination.
items[].unit	uCom	string	Commercial unit.
items[].quantity	qCom	decimal	Commercial quantity.
items[].unitAmount	vUnCom	decimal	Commercial unit price.
items[].totalAmount	vProd	decimal	quantity * unitAmount.
items[].codeTaxGTIN	cEANTrib	string	Taxable unit GTIN; "SEM GTIN" if none.
items[].unitTax	uTrib	string	Taxable unit.
items[].quantityTax	qTrib	decimal	Taxable quantity.
items[].taxUnitAmount	vUnTrib	decimal	Taxable unit price.
items[].freightAmount	vFrete	decimal	Freight amount apportioned to the item.
items[].insuranceAmount	vSeg	decimal	Insurance amount apportioned to the item.
items[].discountAmount	vDesc	decimal	Item discount amount.
items[].othersAmount	vOutro	decimal	Other accessory expenses of the item.
items[].totalIndicator	indTot	bool	0 or 1. Default true.
items[].usedMovableGood	indBemMovelUsado	bool	Optional. Used movable good indicator (resale of used goods). The tag is emitted only when true; with false or omitted it is not written to the XML.
items[].cest	CEST	string	7 digits.
items[].itemAmount	vItem	decimal	⚠️ Not accepted by the API: value ignored and vItem is not generated in the XML (NT 2025.002 flags the requirement as future implementation, rule VB01-05).
items[].numberOrderBuy	xPed	string	Purchase order number.
items[].itemNumberOrderBuy	nItemPed	int	Item number in the purchase order.
items[].importControlSheetNumber	nFCI	string	Import Content Sheet.
items[].benefit	cBenef	string	Tax benefit code in the UF.
items[].additionalInformation	infAdProd	string	Product additional information.

12.6. Item — ICMS (tax.icms)

JSON Path	XML Tag	Type	Notes
items[].tax.icms.origin	orig	string	Goods origin (0–8): domestic, imported (direct or domestic market), etc.
items[].tax.icms.cst	CST	string	ICMS Tax Situation Code (normal regime).
items[].tax.icms.csosn	CSOSN	string	Operation Situation Code under Simples Nacional (replaces CST for CRT=1).
items[].tax.icms.baseTaxModality	modBC	string	ICMS calculation basis modality: 0=Value Added Margin (%); 1=List (value); 2=Max. Tabled Price (value); 3=Operation value.
items[].tax.icms.baseTax	vBC	decimal	ICMS calculation basis amount.
items[].tax.icms.rate	pICMS	decimal	ICMS rate (%).
items[].tax.icms.amount	vICMS	decimal	ICMS amount.
items[].tax.icms.baseTaxReduction	pRedBC	decimal	Calculation basis reduction percentage.
items[].tax.icms.baseTaxSTModality	modBCST	string	ICMS ST basis modality: 0=Tabled/max. suggested price; 1=Negative List; 2=Positive List; 3=Neutral List; 4=Value Added Margin (%); 5=List.
items[].tax.icms.baseTaxSTReduction	pRedBCST	decimal	ICMS ST basis reduction percentage.
items[].tax.icms.baseTaxST	vBCST	decimal	ICMS ST calculation basis amount.
items[].tax.icms.stRate	pICMSST	decimal	ICMS ST rate (%).
items[].tax.icms.stAmount	vICMSST	decimal	ICMS ST amount.
items[].tax.icms.stMarginAmount	pMVAST	decimal	ICMS ST value added margin percentage.
items[].tax.icms.stRetentionAmount	vICMSSTRet	decimal	ICMS ST previously withheld amount.
items[].tax.icms.baseSTRetentionAmount	vBCSTRet	decimal	ICMS ST previously withheld basis amount.
items[].tax.icms.snCreditRate	pCredSN	decimal	Applicable credit calculation rate (Simples Nacional).
items[].tax.icms.snCreditAmount	vCredICMSSN	decimal	ICMS credit amount available for use (Simples Nacional).
items[].tax.icms.fcpRate	pFCP	decimal	Poverty Combat Fund (FCP) percentage.
items[].tax.icms.fcpAmount	vFCP	decimal	FCP amount.
items[].tax.icms.fcpstRate	pFCPST	decimal	FCP percentage withheld by ST.
items[].tax.icms.fcpstAmount	vFCPST	decimal	FCP amount withheld by ST.
items[].tax.icms.fcpstRetRate	pFCPSTRet	decimal	FCP percentage previously withheld by ST.
items[].tax.icms.fcpstRetAmount	vFCPSTRet	decimal	FCP amount previously withheld by ST.
items[].tax.icms.baseTaxFCPSTAmount	vBCFCPST	decimal	FCP-ST calculation basis amount.
items[].tax.icms.exemptAmount	vICMSDeson	decimal	Exempted ICMS amount.
items[].tax.icms.exemptReason	motDesICMS	enum	ICMS exemption reason. See §11.3.3.
items[].tax.icms.deductionIndicator	indDeducao	enum	Indicator for deducting the exempted ICMS from the item amount. See §11.3.4.
items[].tax.icms.ufst	UFST	string	UF to which the ICMS ST is due.
items[].tax.icms.percentualDeferment	pDif	decimal	ICMS deferment percentage.
items[].tax.icms.baseDeferred	vICMSDif	decimal	Deferred ICMS amount.
items[].tax.icms.basisBenefitCode	cBenefRBC	string	UF tax benefit code applied to the item when there is a basis reduction.
items[].tax.icms.stFinalConsumerRate	pST	decimal	Rate borne by the final consumer (ST with withholding).
items[].tax.icms.effectiveBaseTaxReductionRate	pRedBCEfet	decimal	Effective basis reduction percentage.
items[].tax.icms.effectiveBaseTaxAmount	vBCEfet	decimal	Effective calculation basis amount.
items[].tax.icms.effectiveRate	pICMSEFET	decimal	Effective ICMS rate (%).
items[].tax.icms.effectiveAmount	vICMSEFET	decimal	Effective ICMS amount.

12.7. Item — IPI / II / PIS / COFINS

JSON Path	XML Tag	Type	Notes
items[].tax.ipi.cst	CST (in IPI)	string	IPI Tax Situation Code.
items[].tax.ipi.classificationCode	cEnq	string	IPI legal classification code.
items[].tax.ipi.classification	clEnq	string	IPI classification class (cigarettes and beverages).
items[].tax.ipi.producerCNPJ	CNPJProd	string	CNPJ of the goods producer, when different from the issuer.
items[].tax.ipi.stampCode	cSelo	string	IPI control stamp code.
items[].tax.ipi.stampQuantity	qSelo	decimal	IPI control stamp quantity.
items[].tax.ipi.base	vBC (in IPI)	decimal	IPI calculation basis (taxation by value).
items[].tax.ipi.rate	pIPI	decimal	IPI rate (%).
items[].tax.ipi.unitQuantity	qUnid	decimal	Total quantity in the standard unit (IPI taxation per unit).
items[].tax.ipi.unitAmount	vUnid	decimal	Value per taxable unit (IPI taxation per unit).
items[].tax.ipi.amount	vIPI	decimal	IPI amount.
items[].tax.ipiDevol.percentage	pDevol (in impostoDevol)	decimal	Percentage of the returned goods (greater than 0, up to 100). Return invoices only.
items[].tax.ipiDevol.amount	vIPIDevol (in impostoDevol/IPI)	decimal	Returned IPI amount of the item. Return invoices only.
items[].tax.ii.baseTax	vBC (in II)	decimal	Import Tax calculation basis.
items[].tax.ii.customsExpenditureAmount	vDespAdu	decimal	Customs expenditure amount.
items[].tax.ii.amount	vII	decimal	Import Tax amount.
items[].tax.ii.iofAmount	vIOF	decimal	IOF (Tax on Financial Operations) amount.
items[].tax.pis.cst	CST (in PIS)	string	PIS Tax Situation Code.
items[].tax.pis.baseTax	vBC (in PIS)	decimal	PIS calculation basis (taxation by percentage).
items[].tax.pis.rate	pPIS	decimal	PIS rate (%).
items[].tax.pis.amount	vPIS	decimal	PIS amount.
items[].tax.pis.baseTaxProductQuantity	qBCProd	decimal	Quantity sold (PIS taxation by specific rate/unit).
items[].tax.pis.productRate	vAliqProd	decimal	PIS rate as value per unit (R$).
items[].tax.cofins.cst	CST (in COFINS)	string	COFINS Tax Situation Code.
items[].tax.cofins.baseTax	vBC (in COFINS)	decimal	COFINS calculation basis (taxation by percentage).
items[].tax.cofins.rate	pCOFINS	decimal	COFINS rate (%).
items[].tax.cofins.amount	vCOFINS	decimal	COFINS amount.
items[].tax.cofins.baseTaxProductQuantity	qBCProd	decimal	Quantity sold (COFINS taxation by specific rate/unit).
items[].tax.cofins.productRate	vAliqProd	decimal	COFINS rate as value per unit (R$).

12.8. Item — ICMS Destination UF (ICMSUFDest)

Applicable to interstate operations with non-taxpayer final consumers (DIFAL).

JSON Path	XML Tag	Type	Notes
items[].tax.icmsDestination.vBCUFDest	vBCUFDest	decimal	ICMS calculation basis amount in the destination UF.
items[].tax.icmsDestination.pFCPUFDest	pFCPUFDest	decimal	FCP percentage due to the destination UF.
items[].tax.icmsDestination.pICMSUFDest	pICMSUFDest	decimal	Internal rate in the destination UF.
items[].tax.icmsDestination.pICMSInter	pICMSInter	decimal	Interstate rate applicable between origin and destination UF.
items[].tax.icmsDestination.pICMSInterPart	pICMSInterPart	decimal	Provisional sharing percentage of interstate ICMS (currently 100% to the destination UF).
items[].tax.icmsDestination.vFCPUFDest	vFCPUFDest	decimal	FCP amount due to the destination UF.
items[].tax.icmsDestination.vICMSUFDest	vICMSUFDest	decimal	ICMS sharing amount due to the destination UF.
items[].tax.icmsDestination.vICMSUFRemet	vICMSUFRemet	decimal	ICMS sharing amount due to the sender UF.
items[].tax.icmsDestination.vBCFCPUFDest	vBCFCPUFDest	decimal	FCP calculation basis amount in the destination UF.

12.9. Item — Selective Tax (IS)

This group is not accepted by the API: values sent in the request are ignored. See §4.1.

12.10. Item — IBS/CBS (IBSCBS)

Root and jurisdictions

JSON Path	XML Tag	Type	Notes
items[].tax.IBSCBS.situationCode	CST (in IBSCBS)	string	IBS/CBS Tax Situation Code (3 digits). See §10.
items[].tax.IBSCBS.classCode	cClassTrib	string	IBS/CBS tax classification code. See §10.
items[].tax.IBSCBS.donationIndicator	indDoacao	string	Indicator of donation to a government entity. See §4.6.1.
items[].tax.IBSCBS.basis	vBC (in IBSCBS)	decimal	IBS/CBS calculation basis.
items[].tax.IBSCBS.state.rate	pIBSUF	decimal	State IBS rate (%).
items[].tax.IBSCBS.state.amount	vIBSUF	decimal	State IBS amount.
items[].tax.IBSCBS.municipal.rate	pIBSMun	decimal	Municipal IBS rate (%).
items[].tax.IBSCBS.municipal.amount	vIBSMun	decimal	Municipal IBS amount.
items[].tax.IBSCBS.cbs.rate	pCBS	decimal	CBS rate (%).
items[].tax.IBSCBS.cbs.amount	vCBS	decimal	CBS amount.
items[].tax.IBSCBS.ibsTotalAmount	vIBSTot	decimal	Total IBS amount (state + municipal).

Per-jurisdiction subgroups (state/municipal/cbs)

JSON Path	XML Tag	Type	Notes
*.deferment.rate	pDif	decimal	Deferment percentage applied to the jurisdiction. See §4.4.1.
*.deferment.amount	vDif	decimal	Deferred tax amount.
*.reduction.rateReduction	pRedAliq	decimal	Rate reduction percentage. See §4.4.2.
*.reduction.effectiveRate	pAliqEfet	decimal	Effective rate after reduction.
*.returnedAmount.amount	vDevTrib	decimal	Tax amount returned to the taxpayer. See §4.4.3.

Special subgroups (root IBSCBS)

Each subgroup is an object with multiple fields; refer to the indicated reference section for the detail of each property.

JSON Path	XML Tag	Type	Notes
items[].tax.IBSCBS.regularTaxation.*	gTribRegular	object	Hypothetical regular taxation (informational). See §4.5.6.
items[].tax.IBSCBS.governmentPurchase.*	gTribCompraGov	object	Government purchase composition. Requires the invoice-level gCompraGov, not yet accepted by the API. See §4.5.5.
items[].tax.IBSCBS.monophase.standard.*	gMonofasicoPadrao	object	Standard monophasic taxation. See §4.5.1.
items[].tax.IBSCBS.monophase.withholding.*	gMonofasicoRetido	object	Monophasic with withholding. See §4.5.1.
items[].tax.IBSCBS.monophase.previouslyWithheld.*	gMonofasicoRetidoAnt	object	Monophasic previously withheld. See §4.5.1.
items[].tax.IBSCBS.monophase.deferment.*	gMonofasicoDif	object	Monophasic with deferment. See §4.5.1.
items[].tax.IBSCBS.creditTransfer.*	gTransfCred	object	Credit transfer. See §4.5.3.
items[].tax.IBSCBS.operationalPresumedCredit.*	gCredPresOper	object	Operational presumed credit. See §4.5.2.
items[].tax.IBSCBS.creditReversal.*	gEstornoCred	object	Credit reversal. See §4.5.4.
items[].tax.IBSCBS.zfmPresumedCredit.*	gCredPresIBSZFM	object	Manaus Free Trade Zone presumed credit. See §4.5.7.
items[].tax.IBSCBS.competenceAdjustment.*	gAjusteCompet	object	Competence adjustment (CST 811 items only). See §4.6.2.

12.11. Totals (total)

JSON Path	XML Tag	Type	Notes
totals.icms.baseTax	vBC	decimal	ICMS calculation basis (sum of items).
totals.icms.icmsAmount	vICMS	decimal	Total ICMS amount.
totals.icms.icmsExemptAmount	vICMSDeson	decimal	Total exempted ICMS amount.
totals.icms.stCalculationBasisAmount	vBCST	decimal	ICMS ST calculation basis.
totals.icms.stAmount	vST	decimal	Total ICMS ST amount.
totals.icms.productAmount	vProd	decimal	Total amount of products and services.
totals.icms.freightAmount	vFrete	decimal	Total freight amount.
totals.icms.insuranceAmount	vSeg	decimal	Total insurance amount.
totals.icms.discountAmount	vDesc	decimal	Total discount amount.
totals.icms.iiAmount	vII	decimal	Total Import Tax amount.
totals.icms.ipiAmount	vIPI	decimal	Total IPI amount.
totals.icms.pisAmount	vPIS	decimal	Total PIS amount.
totals.icms.cofinsAmount	vCOFINS	decimal	Total COFINS amount.
totals.icms.othersAmount	vOutro	decimal	Other accessory expenses.
totals.icms.invoiceAmount	vNF	decimal	Total NF-e amount.
totals.icms.fcpufDestinationAmount	vFCPUFDest	decimal	Total FCP amount due to the destination UF.
totals.icms.icmsufDestinationAmount	vICMSUFDest	decimal	Total ICMS sharing amount for the destination UF.
totals.icms.icmsufSenderAmount	vICMSUFRemet	decimal	Total ICMS sharing amount for the sender UF.
totals.icms.federalTaxesAmount	vTotTrib	decimal	Approximate total amount of taxes (federal, state, and municipal).
totals.icms.fcpAmount	vFCP	decimal	Total FCP amount.
totals.icms.fcpstAmount	vFCPST	decimal	Total FCP amount withheld by ST.
totals.icms.fcpstRetAmount	vFCPSTRet	decimal	Total FCP amount previously withheld by ST.
totals.icms.ipiDevolAmount	vIPIDevol	decimal	Total returned IPI amount. The platform calculates it as the sum of items[].tax.ipiDevol.amount. The value sent is only used on complementary invoices and on return invoices with totals.icms.iiAmount (where it must equal the sum of the items); otherwise, sending it without items carrying ipiDevol is rejected ([V-IPIDEV-04]). See Devolução de NF-e por item.
totals.issqn.baseRateISS	vBC (in ISSQNtot)	decimal	ISSQN calculation basis.
totals.issqn.totalISS	vISS	decimal	Total ISSQN amount.
totals.withheldTaxes.pisAmount	vRetPIS	decimal	PIS amount withheld by substitution.
totals.withheldTaxes.cofinsAmount	vRetCOFINS	decimal	COFINS amount withheld by substitution.
totals.withheldTaxes.csllAmount	vRetCSLL	decimal	Withheld CSLL amount.
totals.withheldTaxes.irrfBasis	vBCIRRF	decimal	IRRF calculation basis.
totals.withheldTaxes.irrfAmount	vIRRF	decimal	Withheld IRRF amount.
totals.withheldTaxes.socialSecurityBasis	vBCRetPrev	decimal	Social Security withholding calculation basis.
totals.withheldTaxes.socialSecurityAmount	vRetPrev	decimal	Social Security withholding amount.
totals.ibsCbs.basis	vBCIBSCBS	decimal	Total IBS/CBS calculation basis.
totals.ibsCbs.ibs.state.amount	vIBSUF (in totals)	decimal	Total state IBS amount.
totals.ibsCbs.ibs.municipal.amount	vIBSMun (in totals)	decimal	Total municipal IBS amount.
totals.ibsCbs.ibs.totalAmount	vIBS (in IBSCBSTot)	decimal	Total IBS amount (state + municipal).
totals.ibsCbs.cbs.amount	vCBS (in totals)	decimal	Total CBS amount.

12.12. Transport (transp)

JSON Path	XML Tag	Type	Notes
transport.freightModality	modFrete	enum	Freight modality. See §11.6.1.
transport.transportGroup.name	xNome	string	Carrier company name or name.
transport.transportGroup.federalTaxNumber	CNPJ/CPF	int	Carrier CNPJ or CPF.
transport.transportGroup.stateTaxNumber	IE	string	Carrier state tax registration.
transport.transportGroup.address.*	(subfields of transporta)	object	Carrier address (xEnder, xMun, UF).
transport.transportVehicle.plate	placa	string	Transport vehicle license plate.
transport.transportVehicle.state	UF	string	Vehicle registration UF.
transport.transportVehicle.rntc	RNTC	string	National Cargo Carrier Registry (ANTT).
transport.reboque.plate	placa (in reboque)	string	Trailer license plate.
transport.reboque.uf	UF (in reboque)	string	Trailer registration UF.
transport.reboque.rntc	RNTC (in reboque)	string	Trailer RNTC.
transport.reboque.wagon	vagao	string	Wagon identification (rail transport).
transport.reboque.ferry	balsa	string	Ferry identification.
transport.volume.volumeQuantity	qVol	int	Quantity of transported volumes.
transport.volume.species	esp	string	Species of the transported volumes.
transport.volume.brand	marca	string	Brand of the transported volumes.
transport.volume.volumeNumeration	nVol	string	Numbering of the transported volumes.
transport.volume.netWeight	pesoL	decimal	Net weight (kg).
transport.volume.grossWeight	pesoB	decimal	Gross weight (kg).
transport.sealNumber	nLacre	string	Seal numbers.
transport.transpRate.serviceAmount	vServ	decimal	Transport service amount (transport ICMS withholding).
transport.transpRate.bcRetentionAmount	vBCRet	decimal	Transport ICMS withholding calculation basis.
transport.transpRate.icmsRetentionRate	pICMSRet	decimal	Transport ICMS withholding rate.
transport.transpRate.icmsRetentionAmount	vICMSRet	decimal	Withheld transport ICMS amount.
transport.transpRate.cfop	CFOP (in retTransp)	int	Transport service CFOP.
transport.transpRate.cityGeneratorFactCode	cMunFG (in retTransp)	int	IBGE code of the city where the transport ICMS taxable event occurred.

12.13. Payment (pag)

JSON Path	XML Tag	Type	Notes
payment[].paymentDetail[].method	tPag	enum	Payment method. See §11.5.1.
payment[].paymentDetail[].methodDescription	xPag	string	Payment method description (required when tPag=99/others).
payment[].paymentDetail[].paymentType	indPag	enum	Payment form indicator (cash/installment). See §11.5.2.
payment[].paymentDetail[].amount	vPag	decimal	Payment amount.
payment[].paymentDetail[].paymentDate	dPag	datetime	Payment date.
payment[].paymentDetail[].federalTaxNumberPag	CNPJPag	string	CNPJ of the establishment receiving the payment.
payment[].paymentDetail[].statePag	UFPag	string	UF of the payment beneficiary.
payment[].paymentDetail[].card.federalTaxNumber	CNPJ (in card)	string	CNPJ of the credit/debit card acquirer.
payment[].paymentDetail[].card.flag	tBand	enum	Card flag. See §11.5.4.
payment[].paymentDetail[].card.authorization	cAut	string	Card operation authorization number.
payment[].paymentDetail[].card.integrationPaymentType	tpIntegra	enum	Payment integration type with the automation system. See §11.5.3.
payment[].payBack	vTroco	decimal	Change amount.

12.14. Billing (cobr)

JSON Path	XML Tag	Type	Notes
billing.bill.number	nFat	string	Invoice (fatura) number.
billing.bill.originalAmount	vOrig	decimal	Original invoice amount.
billing.bill.discountAmount	vDesc	decimal	Invoice discount amount.
billing.bill.netAmount	vLiq	decimal	Net invoice amount.
billing.duplicates[].number	nDup	string	Installment (duplicata) number.
billing.duplicates[].expirationOn	dVenc	datetime	Installment due date.
billing.duplicates[].amount	vDup	decimal	Installment amount.

12.15. Additional Information (infAdic)

JSON Path	XML Tag	Type	Notes
additionalInformation.fisco	infAdFisco	string	Additional information of interest to the tax authority.
additionalInformation.taxpayer	infCpl	string	Complementary information of interest to the taxpayer.
additionalInformation.xmlAuthorized[]	autXML/CNPJ/CPF	int array	CNPJ/CPF authorized to access the NF-e XML.
additionalInformation.taxDocumentsReference[].documentElectronicInvoice.accessKey	refNFe	string	Access key of the referenced NF-e.
additionalInformation.taxDocumentsReference[].documentInvoiceReference.federalTaxNumber	refNF/CNPJ	string	CNPJ of the issuer of the referenced NF (model 1/1A).
additionalInformation.taxDocumentsReference[].documentInvoiceReference.state	refNF/cUF	int	UF code of the referenced NF issuer.
additionalInformation.taxDocumentsReference[].documentInvoiceReference.yearMonth	refNF/AAMM	string	Year and month (AAMM) of issuance of the referenced NF.
additionalInformation.taxDocumentsReference[].documentInvoiceReference.model	refNF/mod	string	Model of the referenced fiscal document.
additionalInformation.taxDocumentsReference[].documentInvoiceReference.series	refNF/serie	string	Series of the referenced NF.
additionalInformation.taxDocumentsReference[].documentInvoiceReference.number	refNF/nNF	string	Number of the referenced NF.
additionalInformation.taxDocumentsReference[].taxCouponInformation.modelDocumentFiscal	refECF/mod	string	Model of the referenced Tax Coupon (ECF).
additionalInformation.taxDocumentsReference[].taxCouponInformation.orderECF	refECF/nECF	string	Sequential order number of the ECF.
additionalInformation.taxDocumentsReference[].taxCouponInformation.orderCountOperation	refECF/nCOO	int	Operation Order Counter number (COO).
additionalInformation.advancePayment[].accessKey	gPagAntecipado/refNFe	string	⚠️ Not accepted by the API: value ignored and the group is not generated in the XML.
additionalInformation.taxpayerComments[].field	obsCont/xCampo	string	Identification of the taxpayer free field.
additionalInformation.taxpayerComments[].text	obsCont/xTexto	string	Content of the taxpayer free field.
additionalInformation.referencedProcess[].identifierConcessory	nProc	string	Identifier of the process or granting act.
additionalInformation.referencedProcess[].identifierOrigin	indProc	int	Process origin (SEFAZ, Federal/State Justice, Secex/RFB, others).
additionalInformation.referencedProcess[].concessionActType	tpAto	int	Granting act type.

12.16. Purchase, Export, and Intermediate

JSON Path	XML Tag	Type	Notes
purchaseInformation.commitmentNote	xNEmp	string	Commitment note (public procurement).
purchaseInformation.purchaseOrder	xPed (in compra)	string	Purchase order number.
purchaseInformation.contractNumber	xCont	string	Contract number.
export.state	UFSaidaPais	enum	UF of embarkation or border crossing.
export.office	xLocExporta	string	Place of embarkation or dispatch of the export.
export.local	xLocDespacho	string	Description of the dispatch location.
transactionIntermediate.federalTaxNumber	CNPJ (in infIntermed)	int	CNPJ of the transaction intermediary (e.g., marketplace).
transactionIntermediate.identifier	idCadIntTran	string	Identifier of the intermediary in the marketplace portal.
issuer.stStateTaxNumber	IEST	string	State tax registration of the tax substitute in the destination UF.

12.17. Item — Special Subgroups (DI, Fuel, Vehicle)

JSON Path	XML Tag	Type	Notes
items[].importDeclarations[].code	nDI	string	Import Declaration number (DI/DSI/DA).
items[].importDeclarations[].registeredOn	dDI	datetime	DI registration date.
items[].importDeclarations[].customsClearanceName	xLocDesemb	string	Customs clearance location.
items[].importDeclarations[].customsClearanceState	UFDesemb	enum	UF where customs clearance took place.
items[].importDeclarations[].customsClearancedOn	dDesemb	datetime	Customs clearance date.
items[].importDeclarations[].afrmmAmount	vAFRMM	decimal	AFRMM amount (Merchant Marine Renewal Freight Surcharge).
items[].importDeclarations[].internationalTransport	tpViaTransp	enum	International transport mode. See §11.6.3.
items[].importDeclarations[].intermediation	tpIntermedio	enum	Import intermediation form. See §11.6.2.
items[].importDeclarations[].acquirerFederalTaxNumber	CNPJ/CPF	string	CNPJ/CPF of the acquirer or orderer.
items[].importDeclarations[].stateThird	UFTerceiro	string	UF of the acquirer or orderer.
items[].importDeclarations[].exporter	cExportador	string	Exporter code (used by the importer in its records).
items[].importDeclarations[].additions[].code	nAdicao	int	Sequential addition number.
items[].importDeclarations[].additions[].manufacturer	cFabricante	string	Foreign manufacturer code (importer record).
items[].importDeclarations[].additions[].amount	vDescDI	decimal	Addition discount amount.
items[].importDeclarations[].additions[].drawback	nDraw	int	Drawback granting act number.
items[].fuelDetail.codeANP	cProdANP	string	Product code per the ANP table.
items[].fuelDetail.descriptionANP	descANP	string	Product description per the ANP.
items[].fuelDetail.percentageNG	pMixGN	decimal	Percentage of natural gas in the GLP product (mixture).
items[].fuelDetail.percentageGLP	pGLP	decimal	Percentage of GLP derived from petroleum.
items[].fuelDetail.percentageNGn	pGNn	decimal	Percentage of domestic natural gas.
items[].fuelDetail.percentageGNi	pGNi	decimal	Percentage of imported natural gas.
items[].fuelDetail.startingAmount	vPart	decimal	Starting value (pGLP × sale value).
items[].fuelDetail.codif	CODIF	string	Authorization/registration code in CODIF.
items[].fuelDetail.amountTemp	qTemp	decimal	Quantity of fuel billed at ambient temperature.
items[].fuelDetail.stateBuyer	UFCons	string	Fuel consumption UF.
items[].fuelDetail.cide.bc	qBCProd	decimal	CIDE calculation basis (quantity sold).
items[].fuelDetail.cide.rate	vAliqProd	decimal	CIDE rate as value per unit (R$).
items[].fuelDetail.cide.cideAmount	vCIDE	decimal	CIDE amount.
items[].fuelDetail.pump.spoutNumber	nBico	int	Nozzle number used in the refueling.
items[].fuelDetail.pump.number	nBomba	int	Number of the pump the nozzle is connected to.
items[].fuelDetail.pump.tankNumber	nTanque	int	Number of the tank the nozzle is connected to.
items[].fuelDetail.pump.beginningAmount	vEncIni	decimal	Encerrante value at the start of the refueling.
items[].fuelDetail.pump.endAmount	vEncFin	decimal	Encerrante value at the end of the refueling.
items[].vehicleDetail.*	veicProd/* (fields J02–J26)	object	New vehicle data (chassis, color, power, etc.). See §6.22.

12.18. Response — Identifiers and Status

The fields below are filled by the server and returned in query endpoints. They should not be sent in the request.

JSON Path	XML Tag	Type	Notes
id	(internal)	string	Internal identifier of the resource in NFe.io.
status	cStat	enum	NF-e status. See §11.8.1.
authorization.receiptOn	dhRecbto	datetime	Date/time of processing by SEFAZ.
authorization.accessKey	chNFe	string	NF-e access key (44 digits).
authorization.message	xMsg	string	Complementary message returned by SEFAZ.
authorization.description	xMotivo	string	Description of the status reason (cStat).
contingencyDetails.authorizer	(internal)	enum	Authorizer used in contingency.
contingencyDetails.startedOn	(internal)	datetime	Date/time the contingency started.
contingencyDetails.reason	(internal)	string	Justification for entering contingency.
lastEvents.events[]	(internal)	array	List of linked events (cancellation, CC-e, etc.).

Final notes:

1. Paths with * indicate the subgroup has multiple fields with the same structure — refer to the specific subgroup documentation (referenced in §4.5 and §11).
2. XML tags in parentheses of the form (in X) indicate the tag has the same name in multiple groups; the suffix disambiguates the parent group.
3. For the complete relation between cClassTrib (codClassTrib) and IBS/CBS CST, refer to Appendix G (§10).