Documentos Fiscais Eletrônicos Guide

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.

These instructions apply to both the sandbox and live environments. Please note that the sandbox environment is simulated, and most responses are mocked. You’ll still need to register suppliers in the sandbox, but the company details, certificates or passwords don’t need to be valid or real.

All of the following steps must be carried out from the Invopop Console.

Connect the Documentos Fiscais Eletrônicos Brazil app

Enter the Configuration section, then tap Apps. Tap on the Connect button of the Documentos Fiscais Eletrônicos Brazil app.

Create the supplier registration workflow

Follow one of the methods below and ensure to Save and Publish the workflow:

Template
Code
Build from scratch

DF-e register supplier

This workflow will start the registration of a supplier to issue electronic tax documents.

Copy and paste into a new Empty Party workflow code view.

Example DF-e supplier registration workflow

{
    "name": "DF-e register supplier",
    "description": "Starts the registration of a DF-e supplier",
    "schema": "org/party",
    "steps": [
        {
            "id": "68e5abd0-b64b-11f0-8ddf-b9fd6fa99d97",
            "name": "Sign Envelope",
            "provider": "silo.close"
        },
        {
            "id": "6f0a6500-b64b-11f0-8ddf-b9fd6fa99d97",
            "name": "Register DF-e supplier (Brazil)",
            "provider": "nfe-br.register"
        },
        {
            "id": "71918510-b64b-11f0-8ddf-b9fd6fa99d97",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `processing`{.state .processing}",
            "config": {
                "state": "processing"
            }
        }
    ],
    "rescue": [
        {
            "id": "7d127750-b64b-11f0-8ddf-b9fd6fa99d97",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `error`{.state .error}",
            "config": {
                "state": "error"
            }
        }
    ]
}

Before starting, review the workflows guide to understand the general setup process.In Console, create a new workflow and choose Empty Party workflow as the base. Then name the workflow with a descriptive label such as “NFS-e register supplier workflow”.The new workflow will need to perform three steps:

Sign the Envelope
Register DF-e issuer (Brazil)
Set State - with configuration set to Processing.

Add any additional steps you may need, and save the new workflow.

Configure the supplier post-registration workflow

Follow one of the methods below and ensure to Save and Publish the workflow:

Template
Code
Build from scratch

DF-e process supplier post-registration

This workflow should contain any processing that needs to happen after a supplier completes the registration process.

Copy and paste into a new Empty Party workflow code view.

Example DF-e supplier post-registration workflow

{
    "name": "DF-e process supplier post-registration",
    "description": "Runs after a DF-e supplier has been registered",
    "schema": "org/party",
    "steps": [
        {
            "id": "ec727530-b648-11f0-8ddf-b9fd6fa99d97",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `registered`{.state .registered}",
            "config": {
                "state": "registered"
            }
        }
    ],
    "rescue": [
        {
            "id": "9a7b3d50-1358-11ef-af96-a18cfb3774fa",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `error`{.state .error}",
            "config": {
                "state": "error"
            }
        }
    ]
}

Before starting, review the workflows guide to understand the general setup process.In Console, create a new workflow and choose Empty Party workflow as the base. Then name the workflow with a descriptive label such as “DF-e process supplier post-registration”.This worfkow is composed by a single step:

Set State - To Registered.

This workflow will automatically be executed once a supplier completes the registration process. You can customize it to suit your needs (e.g., adding a webhook, or an email notification after a supplier has been registered.)

Now you need to go back to Configuration > Apps, tap the Configure button on the Documentos Fiscais Eletrônicos Brazil app, choose the “Post-registration workflow” we just created and Save the changes.

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:

Template
Code
Build from scratch

DF-e issue service invoice (NFS-e)

This workflow will issue a service invoice (NFS-e) in Brazil.

Copy and paste into a new Empty Invoice workflow code view.

Example DF-e issue service invoice (NFS-e) workflow

{
    "name": "DF-e issue service invoice (NFS-e)",
    "description": "Issue a NFS-e invoice in Brazil",
    "schema": "bill/invoice",
    "steps": [
        {
            "id": "d1c7bde0-b651-11f0-b6c3-efa5610a4723",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `processing`{.state .processing}",
            "config": {
                "state": "processing"
            }
        },
        {
            "id": "dbcb8600-b651-11f0-b6c3-efa5610a4723",
            "name": "Add Sequential Code",
            "provider": "sequence.enumerate",
            "summary": "Dynamic · NFS-e · 1",
            "config": {
                "name": "NFS-e",
                "padding": 1,
                "start": 1
            }
        },
        {
            "id": "e8eba950-b651-11f0-b6c3-efa5610a4723",
            "name": "Sign Envelope",
            "provider": "silo.close"
        },
        {
            "id": "ec64f190-b651-11f0-b6c3-efa5610a4723",
            "name": "Send NFS-e (Brazil)",
            "provider": "nfe-br.send"
        },
        {
            "id": "eecc7bb0-b651-11f0-b6c3-efa5610a4723",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `sent`{.state .sent}",
            "config": {
                "state": "sent"
            }
        }
    ],
    "rescue": [
        {
            "id": "f9195ac0-b651-11f0-b6c3-efa5610a4723",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `error`{.state .error}",
            "config": {
                "state": "error"
            }
        }
    ]
}

Before starting, review the workflows guide to understand the general setup process.In Console, create a new workflow and choose Empty Invoice workflow as the base. Then name the workflow with a descriptive label such as “Issue NFS-e invoice”.The new workflow will need to perform these steps:

Set State - to Processing.
Add Sequential Code - with dynamic sequences and a name like “NFS-e”.
Send NFS-e (Brazil).
Set State - to Sent.

Finally, in the Error Handling area, add the Set State action and select Error.Add any additional steps you may need, and save the new workflow.

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:

Template
Code
Build from scratch

DF-e issue product invoice (NF-e)

This workflow will issue a product invoice (NF-e) in Brazil.

Copy and paste into a new Empty Invoice workflow code view.

Example DF-e issue product invoice (NF-e) workflow

{
    "name": "DF-e issue product invoice (NF-e)",
    "description": "Issue a NF-e invoice in Brazil",
    "schema": "bill/invoice",
    "steps": [
        {
            "id": "9ba5d6c8-f64a-4140-aa49-0b529231264e",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `processing`{.state .processing}",
            "config": {
                "state": "processing"
            }
        },
        {
            "id": "14a8175e-5902-493b-b0d3-005f96da870a",
            "name": "Add Sequential Code",
            "provider": "sequence.enumerate",
            "summary": "Dynamic · NF-e · 1",
            "config": {
                "name": "NF-e",
                "padding": 1,
                "start": 1
            }
        },
        {
            "id": "810fbb98-6370-4104-8d49-9cdd6a4ca157",
            "name": "Sign Envelope",
            "provider": "silo.close"
        },
        {
            "id": "796486be-0dae-4b07-ae52-34f4793ebeee",
            "name": "Send NF-e (Brazil)",
            "provider": "nfe-br.send.nfe"
        },
        {
            "id": "8bfd4fba-8e99-42f6-953f-7a967b6c1f74",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `sent`{.state .sent}",
            "config": {
                "state": "sent"
            }
        }
    ],
    "rescue": [
        {
            "id": "157750d1-3284-4f40-add4-24b1cbcacc1d",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `error`{.state .error}",
            "config": {
                "state": "error"
            }
        }
    ]
}

Before starting, review the workflows guide to understand the general setup process.In Console, create a new workflow and choose Empty Invoice workflow as the base. Then name the workflow with a descriptive label such as “Issue NF-e invoice”.The new workflow will need to perform these steps:

Set State - to Processing.
Add Sequential Code - with dynamic sequences and a name like “NF-e”.
Send NF-e (Brazil).
Set State - to Sent.

Finally, in the Error Handling area, add the Set State action and select Error.Add any additional steps you may need, and save the new workflow.

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:

Template
Code
Build from scratch

DF-e issue consumer invoice (NFC-e)

This workflow will issue a customer invoice (NFC-e) in Brazil.

Copy and paste into a new Empty Invoice workflow code view.

Example DF-e issue consumer invoice (NFC-e) workflow

{
    "name": "DF-e issue consumer invoice (NFC-e)",
    "description": "Issue a NFC-e invoice in Brazil",
    "schema": "bill/invoice",
    "steps": [
        {
            "id": "93769100-b652-11f0-a7d9-bfad358c6464",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `processing`{.state .processing}",
            "config": {
                "state": "processing"
            }
        },
        {
            "id": "971c6780-b652-11f0-a7d9-bfad358c6464",
            "name": "Add Sequential Code",
            "provider": "sequence.enumerate",
            "summary": "Dynamic · NFC-e · 1",
            "config": {
                "name": "NFC-e",
                "padding": 1,
                "start": 1
            }
        },
        {
            "id": "9f965b50-b652-11f0-a7d9-bfad358c6464",
            "name": "Sign Envelope",
            "provider": "silo.close"
        },
        {
            "id": "8693f670-b653-11f0-a7d9-bfad358c6464",
            "name": "Send NFC-e (Brazil)",
            "provider": "nfe-br.send.nfce"
        },
        {
            "id": "a9dc0e70-b652-11f0-a7d9-bfad358c6464",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `sent`{.state .sent}",
            "config": {
                "state": "sent"
            }
        }
    ],
    "rescue": [
        {
            "id": "b0f7f8e0-b652-11f0-a7d9-bfad358c6464",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `error`{.state .error}",
            "config": {
                "state": "error"
            }
        }
    ]
}

Before starting, review the workflows guide to understand the general setup process.In Console, create a new workflow and choose Empty Invoice workflow as the base. Then name the workflow with a descriptive label such as “Issue NFC-e invoice”.The new workflow will need to perform these steps:

Set State - to Processing.
Add Sequential Code - with dynamic sequences and a name like “NFC-e”.
Send NFC-e (Brazil).
Set State - to Sent.

Finally, in the Error Handling area, add the Set State action and select Error.Add any additional steps you may need, and save the new workflow.

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:

Template
Code
Build from scratch

DF-e cancel service invoice (NFS-e)

This workflow will cancel a previously sent NFS-e invoice in Brazil.

Copy and paste into a new Empty Invoice workflow code view.

Example Cancel NFS-e invoice workflow

{
    "name": "Cancel NFS-e invoice",
    "description": "Cancel an NFS-e service invoice via PlugNotas",
    "schema": "bill/invoice",
    "steps": [
        {
            "id": "5e63dc30-535e-11f1-aba1-0fa2408cece2",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `processing`{.state .processing}",
            "config": {
                "state": "processing"
            }
        },
        {
            "id": "71238320-535e-11f1-aba1-0fa2408cece2",
            "name": "Cancel NFS-e",
            "provider": "nfe-br.cancel.nfse"
        },
        {
            "id": "65aa8020-535e-11f1-aba1-0fa2408cece2",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `void`{.state .void}",
            "config": {
                "state": "void"
            }
        }
    ],
    "rescue": [
        {
            "id": "6b3199c0-535e-11f1-aba1-0fa2408cece2",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `error`{.state .error}",
            "config": {
                "state": "error"
            }
        }
    ]
}

Before starting, review the workflows guide to understand the general setup process.In Console, create a new workflow and choose Empty Invoice workflow as the base. Then name the workflow with a descriptive label such as “Cancel NFS-e invoice”.The new workflow will need to perform these steps:

Set State - to Processing.
Cancel NFS-e.
Set State - to Void.

Finally, in the Error Handling area, add the Set State action and select Error.Add any additional steps you may need, and save the new workflow.

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:

Template
Code
Build from scratch

DF-e cancel product invoice (NF-e)

This workflow will cancel a previously sent NF-e invoice in Brazil.

Copy and paste into a new Empty Invoice workflow code view.

Example Cancel NF-e invoice workflow

{
    "name": "Cancel NF-e invoice",
    "description": "Cancel an NF-e product invoice via PlugNotas",
    "schema": "bill/invoice",
    "steps": [
        {
            "id": "66252078-732d-4c87-a0a5-859d1dc4ef53",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `processing`{.state .processing}",
            "config": {
                "state": "processing"
            }
        },
        {
            "id": "e7ef1042-3c51-48e6-b4d9-9cec74a09489",
            "name": "Cancel NF-e",
            "provider": "nfe-br.cancel.nfe"
        },
        {
            "id": "9c1f3a20-732d-4c87-a0a5-859d1dc4ef53",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `void`{.state .void}",
            "config": {
                "state": "void"
            }
        }
    ],
    "rescue": [
        {
            "id": "a4d82b10-732d-4c87-a0a5-859d1dc4ef53",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `error`{.state .error}",
            "config": {
                "state": "error"
            }
        }
    ]
}

Before starting, review the workflows guide to understand the general setup process.In Console, create a new workflow and choose Empty Invoice workflow as the base. Then name the workflow with a descriptive label such as “Cancel NF-e invoice”.The new workflow will need to perform these steps:

Set State - to Processing.
Cancel NF-e.
Set State - to Void.

Finally, in the Error Handling area, add the Set State action and select Error.Add any additional steps you may need, and save the new workflow.

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:

Template
Code
Build from scratch

DF-e cancel consumer invoice (NFC-e)

This workflow will cancel a previously sent NFC-e invoice in Brazil.

Copy and paste into a new Empty Invoice workflow code view.

Example Cancel NFC-e invoice workflow

{
    "name": "Cancel NFC-e invoice",
    "description": "Cancel an NFC-e consumer invoice via PlugNotas",
    "schema": "bill/invoice",
    "steps": [
        {
            "id": "5e63dc30-535e-11f1-aba1-0fa2408cece2",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `processing`{.state .processing}",
            "config": {
                "state": "processing"
            }
        },
        {
            "id": "71238320-535e-11f1-aba1-0fa2408cece2",
            "name": "Cancel NFC-e",
            "provider": "nfe-br.cancel.nfce"
        },
        {
            "id": "65aa8020-535e-11f1-aba1-0fa2408cece2",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `void`{.state .void}",
            "config": {
                "state": "void"
            }
        }
    ],
    "rescue": [
        {
            "id": "6b3199c0-535e-11f1-aba1-0fa2408cece2",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `error`{.state .error}",
            "config": {
                "state": "error"
            }
        }
    ]
}

Before starting, review the workflows guide to understand the general setup process.In Console, create a new workflow and choose Empty Invoice workflow as the base. Then name the workflow with a descriptive label such as “Cancel NFC-e invoice”.The new workflow will need to perform these steps:

Set State - to Processing.
Cancel NFC-e.
Set State - to Void.

Finally, in the Error Handling area, add the Set State action and select Error.Add any additional steps you may need, and save the new workflow.

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.

Brazil supplier example for sandbox

{
    "$schema": "https://gobl.org/draft-0/org/party",
    "name": "TechNova Soluções Digitais Ltda.",
    "tax_id": {
        "country": "BR",
        "code": "05229829000184"
    },
    "identities": [
        {
            "key": "br-nfse-municipal-reg",
            "code": "45678901234567"
        },
        {
            "key": "br-nfe-state-reg",
            "code": "66093885154234"
        }
    ],
    "addresses": [
        {
            "num": "101",
            "street": "Avenida Paulista",
            "locality": "Bela Vista",
            "region": "São Paulo",
            "state": "SP",
            "code": "01311-000",
            "country": "BR"
        }
    ],
    "emails": [
        {
            "addr": "contact@technova.test"
        }
    ],
    "ext": {
        "br-ibge-municipality": "3550308",
        "br-nfse-simples": "1"
    }
}

Tap Build, ensure there are no errors, and click Save. We should now see the document. Find and click the Select Workflow button. Select the Register Supplier workflow created during setup, and click Run workflow. The execution should be successful, and the silo entry will now be in the Processing state. Tap the Meta tab to see the registration link:

You can access the registration link via the API by fetching the silo entry and reading the meta row where the key is set to registration-link.

Tap the registration link. A new browser window will open with a form to upload the supplier’s credentials. Note that this form can be shared directly with the supplier, if necessary.

The details from this form are sent securely to Invopop’s local partner, PlugNotas, who will use them to authenticate the supplier in the corresponding tax authority. The supplier must ensure that the certificate and password are valid and accepted by the municipality or state where they operate. Once the form is submitted, the supplier will be registered, and the post-registration workflow will be executed, changing the supplier’s state to 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.

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.

Example B2B service invoice (NFS-e)

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.

{
  "$schema": "https://gobl.org/draft-0/bill/invoice",
  "$addons": [
    "br-nfse-v1"
  ],
  "series": "XXBR",
  "supplier": {
    "name": "TechNova Soluções Digitais Ltda.",
    "tax_id": {
      "country": "BR",
      "code": "05229829000184"
    },
    "identities": [
      {
        "key": "br-nfse-municipal-reg",
        "code": "45678901234567"
      }
    ],
    "addresses": [
      {
        "num": "101",
        "street": "Avenida Paulista",
        "locality": "Bela Vista",
        "region": "São Paulo",
        "state": "SP",
        "code": "01311-000",
        "country": "BR"
      }
    ],
    "emails": [
      {
        "addr": "contact@technova.test"
      }
    ],
    "ext": {
      "br-ibge-municipality": "3550308",
      "br-nfse-simples": "1"
    }
  },
  "customer": {
    "name": "Construforte Engenharia Ltda.",
    "tax_id": {
      "country": "BR",
      "code": "46602178000103"
    },
    "addresses": [
      {
        "num": "75",
        "street": "Avenida Sete de Setembro",
        "street_extra": "Bloco C",
        "locality": "Centro",
        "region": "Salvador",
        "state": "BA",
        "code": "40060-000",
        "country": "BR"
      }
    ]
  },
  "lines": [
    {
      "quantity": "15",
      "item": {
        "name": "Consultancy Services",
        "price": "100.00",
        "ext": {
          "br-nfse-cnae": "62.01-5-01",
          "br-nfse-service": "10.5"
        }
      },
      "taxes": [
        {
          "cat": "ISS",
          "percent": "15%"
        }
      ]
    }
  ]
}

Example B2B service invoice with RTC (NFS-e)

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:

we’ve set the br-nfse-operation extension, the br-nfse-tax-status extension and the br-nfse-tax-class extension at item level which will be used to determine the IBS and CBS taxes as part of the tax reform.

{
  "$schema": "https://gobl.org/draft-0/bill/invoice",
  "$addons": [
    "br-nfse-v1"
  ],
  "series": "XXBR",
  "supplier": {
    "name": "TechNova Soluções Digitais Ltda.",
    "tax_id": {
      "country": "BR",
      "code": "05229829000184"
    },
    "identities": [
      {
        "key": "br-nfse-municipal-reg",
        "code": "45678901234567"
      }
    ],
    "addresses": [
      {
        "num": "101",
        "street": "Avenida Paulista",
        "locality": "Bela Vista",
        "region": "São Paulo",
        "state": "SP",
        "code": "01311-000",
        "country": "BR"
      }
    ],
    "emails": [
      {
        "addr": "contact@technova.test"
      }
    ],
    "ext": {
      "br-ibge-municipality": "3550308",
      "br-nfse-simples": "1"
    }
  },
  "customer": {
    "name": "Construforte Engenharia Ltda.",
    "tax_id": {
      "country": "BR",
      "code": "46602178000103"
    },
    "addresses": [
      {
        "num": "75",
        "street": "Avenida Sete de Setembro",
        "street_extra": "Bloco C",
        "locality": "Centro",
        "region": "Salvador",
        "state": "BA",
        "code": "40060-000",
        "country": "BR"
      }
    ]
  },
  "lines": [
    {
      "quantity": "15",
      "item": {
        "name": "Consultancy Services",
        "price": "100.00",
        "ext": {
          "br-nfse-cnae": "62.01-5-01",
          "br-nfse-operation": "030101",
          "br-nfse-service": "10.5",
          "br-nfse-tax-class": "000001",
          "br-nfse-tax-status": "000"
        }
      },
      "taxes": [
        {
          "cat": "ISS",
          "percent": "15%"
        }
      ]
    }
  ]
}

Example B2B product invoice (NF-e)

In this example, we’re issuing a simple 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 with the br-ibge-municipality extension,
each line must include a br-nfe-cfop extension to classify the fiscal operation,
item identities are used to provide the NCM (Mercosur Common Nomenclature) product code,
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.

{
  "$schema": "https://gobl.org/draft-0/bill/invoice",
  "$addons": [
    "br-nfe-v4"
  ],
  "series": "1",
  "tax": {
    "ext": {
      "br-nfe-model": "55",
      "br-nfe-presence": "1"
    }
  },
  "supplier": {
    "name": "TechNova Soluções Digitais Ltda.",
    "tax_id": {
      "country": "BR",
      "code": "05229829000184"
    },
    "identities": [
      {
        "key": "br-nfe-state-reg",
        "code": "12345678901234"
      }
    ],
    "addresses": [
      {
        "num": "101",
        "street": "Avenida Paulista",
        "locality": "Bela Vista",
        "region": "São Paulo",
        "state": "SP",
        "code": "01311-000",
        "country": "BR"
      }
    ],
    "emails": [
      {
        "addr": "contact@technova.test"
      }
    ],
    "ext": {
      "br-ibge-municipality": "3550308"
    }
  },
  "customer": {
    "name": "Construforte Engenharia Ltda.",
    "tax_id": {
      "country": "BR",
      "code": "46602178000103"
    },
    "addresses": [
      {
        "num": "75",
        "street": "Avenida Sete de Setembro",
        "street_extra": "Bloco C",
        "locality": "Centro",
        "region": "Salvador",
        "state": "BA",
        "code": "40060-000",
        "country": "BR"
      }
    ],
    "ext": {
      "br-ibge-municipality": "2927408"
    }
  },
  "lines": [
    {
      "quantity": "10",
      "item": {
        "name": "Cabo USB-C 2 metros",
        "price": "28.90",
        "identities": [
          {
            "key": "ncm",
            "code": "85444290"
          }
        ]
      },
      "taxes": [
        {
          "cat": "ICMS",
          "percent": "12.0%"
        },
        {
          "cat": "PIS",
          "percent": "1.65%"
        },
        {
          "cat": "COFINS",
          "percent": "7.60%"
        }
      ],
      "ext": {
        "br-nfe-cfop": "6102"
      }
    }
  ],
  "payment": {
    "instructions": {
      "key": "credit-transfer"
    }
  },
  "notes": [
    {
      "key": "reason",
      "text": "Venda de Mercadorias"
    }
  ]
}

Example B2C consumer invoice (NFC-e)

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,
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.

{
  "$schema": "https://gobl.org/draft-0/bill/invoice",
  "$addons": [
    "br-nfe-v4"
  ],
  "$tags": [
    "simplified"
  ],
  "series": "123",
  "tax": {
    "ext": {
      "br-nfe-presence": "1"
    }
  },
  "supplier": {
    "name": "TechNova Soluções Digitais Ltda.",
    "tax_id": {
      "country": "BR",
      "code": "05229829000184"
    },
    "identities": [
      {
        "key": "br-nfe-state-reg",
        "code": "12345678901234"
      }
    ],
    "addresses": [
      {
        "num": "101",
        "street": "Avenida Paulista",
        "locality": "Bela Vista",
        "region": "São Paulo",
        "state": "SP",
        "code": "01311-000",
        "country": "BR"
      }
    ],
    "emails": [
      {
        "addr": "contact@technova.test"
      }
    ],
    "ext": {
      "br-ibge-municipality": "3550308",
      "br-nfse-simples": "1"
    }
  },
  "lines": [
    {
      "quantity": "2",
      "item": {
        "name": "Cabo USB-C 2 metros",
        "price": "28.90"
      },
      "taxes": [
        {
          "cat": "ICMS",
          "percent": "18.0%"
        },
        {
          "cat": "PIS",
          "percent": "1.65%"
        },
        {
          "cat": "COFINS",
          "percent": "7.60%"
        }
      ]
    }
  ],
  "payment": {
    "instructions": {
      "key": "card"
    }
  },
  "notes": [
    {
      "key": "reason",
      "text": "Venda de mercadoria"
    }
  ]
}

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.

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.

Job arguments take precedence over the step configuration. To pass them when creating a job via the API:

{
  "workflow_id": "...",
  "silo_entry_id": "...",
  "args": {
    "nfe-br-cancel-reason": "Cancelamento a pedido do Prestador",
    "nfe-br-cancel-code": "9"
  }
}

FAQ

What type of Documentos Fiscais does Invopop support?

Invopop supports NF-e, NFS-e and NFC-e documents. Transport documents (MDF-e and CF-e) are not currently supported.

Where can I find the mapping of GOBL fields to DF-e documents?

For further details on how GOBL prepares data for conversion, see:

More available in our Brazil FAQ section

🇧🇷 Invopop resources for Brazil


Compliance	Invoicing compliance in Brazil Compliance timeline
Apps	Documentos Fiscais Eletrônicos Brazil
Guides	DFE Brazil Guide
FAQ	Brazil FAQ
GOBL	Brazil Tax Regime Brazil NF-e Addon Brazil NFS-e Addon

Participate in our community

Ask and answer questions about invoicing in Brazil →

Documentation Index

​Introduction

​Prerequisites

​Setup

DF-e register supplier

DF-e process supplier post-registration

DF-e issue service invoice (NFS-e)

DF-e issue product invoice (NF-e)

DF-e issue consumer invoice (NFC-e)

DF-e cancel service invoice (NFS-e)

DF-e cancel product invoice (NF-e)

DF-e cancel consumer invoice (NFC-e)

​Running

​Register a Supplier

​Send Invoices

​Cancel an invoice

​Configuration

​FAQ

Participate in our community

Introduction

Prerequisites

Setup

Running

Register a Supplier

Send Invoices

Cancel an invoice

Configuration

FAQ