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 first to register a supplier and then issue electronic fiscal documents in their name.| - | Sandbox | Live |
|---|---|---|
| Supplier | Registration required, but details don’t need to be real | Real company details required |
| Responses | Simulated/mocked | Real from DFe system |
| Certificates | Not required to be valid | Must be valid and real |
| PDF & XML | Always the same mock-up files attached to silo entry | Actual XML sent to tax authority and actual generated PDF attached |
Prerequisites
To issue electronic fiscal documents in Brazil, you will need:- Supplier details, including:
- name,
- CNPJ (Cadastro Nacional da Pessoa Jurídica),
- address,
- municipality code (IBGE),
- municipal registration number (for NFS-e),
- state registration number (for NF-e and NFC-e),
- whether the supplier opts into the Simples Nacional tax regime,
- whether the supplier benefits from a fiscal incentive, and,
- optionally, any special tax regime (MEI, estimated, coop…) the supplier is subject to.
- 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
- A certificate and password accepted by the municipality (for NFS-e) or the state (for NF-e and NFC-e) to send electronic fiscal documents in the name of the supplier.
Setup
There are four key processes to prepare:- connect the Documentos Fiscais Eletrônicos Brazil app,
- create the supplier registration workflow,
- configure the supplier post-registration workflow,
- prepare the invoicing workflows.
Connect the Documentos Fiscais Eletrônicos Brazil app

Create the supplier registration workflow
- Template
- Code
- Build from scratch
DF-e register supplier
Configure the supplier post-registration workflow
- Template
- Code
- Build from scratch
DF-e process supplier post-registration
Prepare NFS-e Workflow
- Template
- Code
- Build from scratch
DF-e issue service invoice (NFS-e)
Prepare NF-e Workflow
- Template
- Code
- Build from scratch
DF-e issue product invoice (NF-e)
Prepare NFC-e Workflow
- Template
- Code
- Build from scratch
DF-e issue consumer invoice (NFC-e)
Prepare NFS-e Cancel Workflow
- Template
- Code
- Build from scratch
DF-e cancel service invoice (NFS-e)
Prepare NF-e Cancel Workflow
- Template
- Code
- Build from scratch
DF-e cancel product invoice (NF-e)
Prepare NFC-e Cancel Workflow
- Template
- Code
- Build from scratch
DF-e cancel consumer invoice (NFC-e)
Running
In this section, we’ll provide details on how to first persist and register a supplier, followed by issuing invoices on their behalf. 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.Register a Supplier
Find the Parties section of the sidebar and click Suppliers. Tap the + New Supplier button to be presented with a new editor. Copy and paste the example provided below (for testing purposes only, in production you’ll need the details of an actual company). The example includes all the fields required to register a supplier for both NF-e/NFC-e and NFS-e issuance.Processing state. Tap the Meta tab to see the registration link:

meta row where
the key is set to registration-link.
Registered.
From this point on, you can send service invoices on behalf of the supplier.
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.Example B2B service invoice (NFS-e)
Example B2B service invoice (NFS-e)
- we’ve added the
br-nfse-v1addon; 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.
Example B2B service invoice with RTC (NFS-e)
Example B2B service invoice with RTC (NFS-e)
- we’ve set the
br-nfse-operationextension, thebr-nfse-tax-statusextension and thebr-nfse-tax-classextension at item level which will be used to determine the IBS and CBS taxes as part of the tax reform.
Example B2B product invoice (NF-e)
Example B2B product invoice (NF-e)
- we’ve added the
br-nfe-v4addon without thesimplifiedtag; this sets thebr-nfe-modelextension to55(NF-e), - the customer is required for NF-e and must include a full address; Brazilian customers must declare the
br-ibge-municipalityextension and a valid state, while foreign customers can be identified by a country-qualifiedidentity(e.g. a passport) instead of atax_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-cfopextension to classify the fiscal operation, - item identities carry the NCM product classification code (
cProdin the NF-e XML) and the GTIN barcode (cEAN), item.refmaps to the supplier’s internal product code, anditem.unitis converted to a UNECE unit code,- line
discountsreduce the taxable base (vDesc); linechargeswith keydeliverymap to freight (vFrete) and keyinsuranceto insurance value (vSeg), line.orderprovides the line reference within the purchase order (nItemPed),- a line
notesentry with keygoodsmaps to per-item additional information (infAdProd), ordering.codesets the purchase order number (nPedincompra) andordering.contracts[0].codesets the contract number (nCont),delivery.receiversets 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 thebr-nfe-payment-meansextension to be set automatically to18(transferência bancária), - a
generalnote 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.
Example B2B product invoice for a Simples Nacional issuer (NF-e)
Example B2B product invoice for a Simples Nacional issuer (NF-e)
- the supplier declares its regime with the
br-nfe-regimeextension set to1(Simples Nacional); use2for Simples Nacional, Excess or4for MEI — omitting it defaults to3(normal regime), - each ICMS line carries the
br-nfe-icms-csosnextension (here101, taxed with credit permission) instead of thebr-nfe-icms-cstcode that normal-regime issuers use, - 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-cstandbr-nfe-cofins-cstextensions set to49(other operations) at a0%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.
Example NF-e for a full goods return
Example NF-e for a full goods return
- the document
typeiscredit-note; it keeps thebr-nfe-v4addon and is still issued as an NF-e, sobr-nfe-modelis derived as55, - a
precedingentry references the original NF-e and carries its SEFAZ access key (chave de acesso) as a stamp — you can copy it from thesefaz-keyentry in thestampsarray of the original invoice’s envelopehead, where it was added once the tax authority authorized the document, - because this is a full return, the
br-nfe-purposeextension is set to4(Goods Return) and thebr-nfe-operation-typeextension to0(Inbound / Entrada), since the returned goods re-enter the supplier; standard invoices set these automatically to1(normal) and1(outbound), but corrective documents must set both explicitly, - no
br-nfe-credit-note-typeextension is used: that field only applies to post-reform IBS/CBS credit notes (those setbr-nfe-purposeto5), - the line
br-nfe-cfopis a return code —2202(Devolução de venda de mercadoria adquirida ou recebida de terceiros) — mirroring the original6102sale but recorded as an inbound inter-state operation (CFOP starting with2), - the payment sets the
br-nfe-payment-meansextension to90(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.
Example B2C consumer invoice (NFC-e)
Example B2C consumer invoice (NFC-e)
- we’ve added the
br-nfe-v4addon with thesimplifiedtag; this sets thebr-nfe-modelextension to65(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, - the payment instructions key is set to
card, which causes thebr-nfe-payment-meansextension to be set automatically to03(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.
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 toVoid.
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.| Parameter | Job argument | Applies to | Notes |
|---|---|---|---|
| Cancellation reason | nfe-br-cancel-reason | NFS-e, NF-e, and NFC-e | Free-text reason for the cancellation. For NF-e and NFC-e, must be at least 15 characters if provided. Defaults to the system default when omitted. |
| Cancellation code | nfe-br-cancel-code | NFS-e only | Municipality-specific cancellation code, for example 9 for “Outros” in the National NFS-e system. Defaults to the system default when omitted. |
FAQ
What type of Documentos Fiscais does Invopop support?
What type of Documentos Fiscais does Invopop support?
Where can I find the mapping of GOBL fields to DF-e documents?
Where can I find the mapping of GOBL fields to DF-e documents?
🇧🇷 Invopop resources for Brazil
🇧🇷 Invopop resources for Brazil