Skip to main content

​
Introduction

Brazil has a variety of electronic tax documents that must be issued in different cases for various tax purposes. These include service invoices (NFS-e), product invoices (NF-e), and consumer invoices (NFC-e). Each document type is subject to variations from state to state and municipality to municipality, with each jurisdiction applying its own rules, formats, and APIs for issuing fiscal documents. Invopop’s Documentos Fiscais Eletrônicos app provides a unified way to issue fiscal documents across all Brazilian states and over 2000 municipalities using GOBL. You can find the full list of supported municipalities here. This guide will walk you through the steps required to issue electronic fiscal documents in a supplier’s name, and to cancel them if needed.

​
Prerequisites

To issue electronic fiscal documents in Brazil, you will need:
  • A registered supplier: follow the DF-e supplier registration guide to connect the Documentos Fiscais Eletrônicos Brazil app and register the supplier’s certificate before issuing.
  • Customer details (except for NFC-e where the customer is optional).
  • Details of the goods or services provided:
    • quantity,
    • price,
    • applicable tax rates (ISS, ICMS, PIS, COFINS, etc.), and,
    • (only for services) service code (Código Item Lista Serviço) as defined by the municipality.
  • To have chosen an invoice series

​
Setup

Prepare the invoicing workflows for the document types you want to issue and cancel.
These instructions apply to both the sandbox and live environments. Please note that the sandbox environment is simulated, and most responses are mocked. The Documentos Fiscais Eletrônicos Brazil app must already be connected and configured — this is covered in the supplier registration guide.
All of the following steps must be carried out from the Invopop Console.
1

Prepare NFS-e workflow

You can skip this step if you’re not interested in issuing NFS-e documents.
Follow one of the methods below and ensure to Save and Publish the workflow:

DF-e issue service invoice (NFS-e)

Add to my workspace →
2

Prepare NF-e Workflow

You can skip this step if you’re not interested in issuing NF-e documents.
Follow one of the methods below and ensure to Save and Publish the workflow:

DF-e issue product invoice (NF-e)

Add to my workspace →
3

Prepare NFC-e Workflow

You can skip this step if you’re not interested in issuing NFC-e documents.
Follow one of the methods below and ensure to Save and Publish the workflow:

DF-e issue consumer invoice (NFC-e)

Add to my workspace →
4

Prepare NFS-e Cancel Workflow

You can skip this step if you’re not interested in cancelling NFS-e documents.
Follow one of the methods below and ensure to Save and Publish the workflow:

DF-e cancel service invoice (NFS-e)

Add to my workspace →
5

Prepare NF-e Cancel Workflow

You can skip this step if you’re not interested in cancelling NF-e documents.
Follow one of the methods below and ensure to Save and Publish the workflow:

DF-e cancel product invoice (NF-e)

Add to my workspace →
6

Prepare NFC-e Cancel Workflow

You can skip this step if you’re not interested in cancelling NFC-e documents.
Follow one of the methods below and ensure to Save and Publish the workflow:

DF-e cancel consumer invoice (NFC-e)

Add to my workspace →

​
Running

In this section, we’ll provide details on how to issue invoices on behalf of a registered supplier, and how to cancel them. As usual, the recommended approach for running jobs is to perform two steps; first upload the document to the silo, second create a job. All operations described in the following sections can be performed manually via the Invopop Console, or programmatically via the API. The process is essentially the same in both cases, so we’ll demonstrate the manual method for this guide.

​
Send invoices

The following examples are of example GOBL documents you can copy and paste directly into the Invopop Console or store via the API as silo entries. Then, you must run the appropriate issue workflow created during setup — “DF-e issue service invoice (NFS-e)”, “DF-e issue product invoice (NF-e)”, or “DF-e issue consumer invoice (NFC-e)” — over them.
In the sandbox environment, you’ll notice that executing the workflow will always result in the same PDF and XML being attached to the silo entry. These are mock-up files returned by the sandbox environment for testing purposes.In production, the actual XML file sent to the tax authority and the actual PDF generated will be attached to the silo entry.
In this example, we’re issuing a simple service invoice (NFS-e) from a Brazilian supplier to another Brazilian business customer.Notice:
  • we’ve added the br-nfse-v1 addon; this ensures the document will be validated using the NFS-e rules built into the GOBL library,
  • extensions (ext) and identities have been used in multiple locations for fields whose values cannot be determined any other way,
  • ISS percentage is provided explicitly as it varies depending on the municipality and type of service,
  • there are no totals or calculations; all these will be made automatically when uploading, and,
  • make sure to process it with the “DF-e issue service invoice (NFS-e)” workflow created during setup.
In this example, we’re issuing a simple service invoice (NFS-e) with the currently supported RTC (Tax Reform) fields.Notice the differences from the previous example:
In this example, we’re issuing an extended product invoice (NF-e) from a Brazilian supplier to another Brazilian business customer.Notice:
  • we’ve added the br-nfe-v4 addon without the simplified tag; this sets the br-nfe-model extension to 55 (NF-e),
  • the customer is required for NF-e and must include a full address; Brazilian customers must declare the br-ibge-municipality extension and a valid state, while foreign customers can be identified by a country-qualified identity (e.g. a passport) instead of a tax_id,
  • supplier and customer addresses must include a country; it is auto-filled from the party’s tax ID (or first identity that declares a country) when omitted,
  • each line must include a br-nfe-cfop extension to classify the fiscal operation,
  • item identities carry the NCM product classification code (cProd in the NF-e XML) and the GTIN barcode (cEAN),
  • item.ref maps to the supplier’s internal product code, and item.unit is converted to a UNECE unit code,
  • line discounts reduce the taxable base (vDesc); line charges with key delivery map to freight (vFrete) and key insurance to insurance value (vSeg),
  • line.order provides the line reference within the purchase order (nItemPed),
  • a line notes entry with key goods maps to per-item additional information (infAdProd),
  • ordering.code sets the purchase order number (nPed in compra) and ordering.contracts[0].code sets the contract number (nCont),
  • delivery.receiver sets a separate delivery address (entrega) when goods ship to a different location than the buyer’s fiscal address,
  • the payment instructions key is set to credit-transfer, which causes the br-nfe-payment-means extension to be set automatically to 18 (transferência bancária),
  • a general note maps to complementary information (infCpl) in the NF-e XML,
  • tax percentages are provided explicitly as they vary depending on the state and type of goods,
  • there are no totals or calculations; all these will be made automatically when uploading, and,
  • make sure to process it with the “DF-e issue product invoice (NF-e)” workflow created during setup.
In this example, we’re issuing a product invoice (NF-e) from a supplier enrolled in the Simples Nacional tax regime.Notice the differences from the previous example:
  • the supplier declares its regime with the br-nfe-regime extension set to 1 (Simples Nacional); 4 (MEI) behaves the same, while 2 (Simples Nacional, Excess) uses CST codes like the normal regime (3, the default),
  • each ICMS line carries the br-nfe-icms-csosn extension (here 101, taxed with credit permission) instead of the br-nfe-icms-cst code that normal-regime issuers use,
  • with CSOSN 101 the ICMS percent is not a charged tax: it represents the Simples Nacional credit rate (pCredSN in the NF-e XML) and the resulting amount becomes the credit value the buyer may take (vCredICMSSN),
  • CSOSN 101 transfers a tax credit and is only accepted when the customer is an ICMS taxpayer, so the customer includes a br-nfe-state-reg identity with its state registration number,
  • PIS and COFINS are still required on every line but are not levied per item under Simples Nacional, so they use the br-nfe-pis-cst and br-nfe-cofins-cst extensions set to 49 (other operations) at a 0% rate,
  • there are no totals or calculations; all these will be made automatically when uploading, and,
  • make sure to process it with the “DF-e issue product invoice (NF-e)” workflow created during setup.
In this example, we’re issuing a NF-e that fully returns the goods of a previously issued B2B product invoice — a devolução total under the pre-reform (pre-RTC) rules.Notice the differences from a standard product invoice:
  • the document type is credit-note; it keeps the br-nfe-v4 addon and is still issued as an NF-e, so br-nfe-model is derived as 55,
  • a preceding entry references the original NF-e and carries its SEFAZ access key (chave de acesso) as a stamp — you can copy it from the sefaz-key entry in the stamps array of the original invoice’s envelope head, where it was added once the tax authority authorized the document,
  • because this is a full return, the br-nfe-purpose extension is set to 4 (Goods Return) and the br-nfe-operation-type extension to 0 (Inbound / Entrada), since the returned goods re-enter the supplier; standard invoices set these automatically to 1 (normal) and 1 (outbound), but corrective documents must set both explicitly,
  • no br-nfe-credit-note-type extension is used: that field only applies to post-reform IBS/CBS credit notes (those set br-nfe-purpose to 5),
  • the line br-nfe-cfop is a return code — 2202 (Devolução de venda de mercadoria adquirida ou recebida de terceiros) — mirroring the original 6102 sale but recorded as an inbound inter-state operation (CFOP starting with 2),
  • the payment sets the br-nfe-payment-means extension to 90 (No payment), as a return does not involve a new payment,
  • there are no totals or calculations; all these will be made automatically when uploading, and,
  • make sure to process it with the “DF-e issue product invoice (NF-e)” workflow created during setup.
In this example, we’re issuing a simple consumer invoice (NFC-e) from a Brazilian supplier.Notice:
  • we’ve added the br-nfe-v4 addon with the simplified tag; this sets the br-nfe-model extension to 65 (NFC-e),
  • the customer is optional and in this example we’ve omitted it,
  • extensions (ext) and identities have been used in multiple locations for fields whose values cannot be determined any other way,
  • each line must include a br-nfe-cfop extension to classify the fiscal operation, just as on an NF-e,
  • the payment instructions key is set to card, which causes the br-nfe-payment-means extension to be set automatically to 03 (cartão de crédito),
  • tax percentages are provided explicitly as they vary depending on the state and type of goods,
  • there are no totals or calculations; all these will be made automatically when uploading, and,
  • make sure to process it with the “DF-e issue consumer invoice (NFC-e)” workflow created during setup.
In this example, we’re issuing a consumer invoice (NFC-e) from a supplier enrolled in the Simples Nacional tax regime.Notice the differences from the previous example:
  • the supplier declares its regime with the br-nfe-regime extension set to 1 (Simples Nacional),
  • ICMS carries the br-nfe-icms-csosn extension set to 102 (taxed without credit permission) with a 0% percent,
  • PIS and COFINS use the br-nfe-pis-cst and br-nfe-cofins-cst extensions set to 49 (other operations) at a 0% rate,
  • the line carries a br-nfe-cfop extension set to 5102,
  • all of these fields must be set explicitly (i.e., you have them in the minimal example), since the automatic defaults are the normal-regime ones: an ICMS line that omits the CSOSN fails validation, while an omitted PIS or COFINS CST silently falls back to 01,
  • there are no totals or calculations; all these will be made automatically when uploading, and,
  • make sure to process it with the “DF-e issue consumer invoice (NFC-e)” workflow created during setup.

​
Cancel an invoice

If you need to cancel a document that has already been sent to the tax authority, you can use the cancel workflows created during setup. Run the appropriate cancel workflow — NFS-e, NF-e, or NFC-e — over the silo entry you want to cancel. On success, the entry will be set to Void.
NFS-e cancellations are subject to the rules of each municipality. Some require a specific cancellation code. NFC-e cancellations must be requested within the cancellation window set by the originating state.

​
Configuration

Both cancel actions accept optional parameters that control the cancellation request. They can be set as a default on the workflow step (via the step’s configuration page in the Console) or overridden per job by passing them as arguments when creating the job via the API. Job arguments take precedence over the step configuration. To pass them when creating a job via the API:

​
FAQ

Invopop supports NF-e, NFS-e and NFC-e documents. Transport documents (MDF-e and CT-e) are not currently supported.
For further details on how GOBL prepares data for conversion, see:
More available in our Brazil FAQ section

Participate in our community

Ask and answer questions about invoicing in Brazil →