Skip to main content

​
Introduction

The NFS-e (Nota Fiscal de Serviços Eletrônica) is the electronic document that Brazilian service providers must issue to report service transactions to municipalities for ISS tax collection. Each municipality has its own rules, format, and API for issuing service invoices. Invopop’s Notas Fiscais Eletrônicas app provides a unified way to issue NFS-e documents across 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 service invoices in their name.

​
Prerequisites

To issue service invoices in Brazil, you will need:
  • Supplier details, including:
    • name,
    • CNPJ (Cadastro Nacional da Pessoa Jurídica),
    • address,
    • municipality code (IGBE),
    • municipal registration number,
    • 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.
  • Details of the service provided, including quantity, price, applicable ISS rate, and 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 to send service invoices in the name of every supplier.

​
Setup

There are four key processes to prepare:
  • create supplier post-registration workflow,
  • connect the Notas Fiscais Eletrônicas Brazil app,
  • configure a supplier registration workflow, and,
  • prepare an invoicing workflow.
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.
1

Create supplier post-registration workflow

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

Connect the Notas Fiscais Eletrônicas Brazil App

Enter the Configuration section, then tap Apps. Tap on the Connect button of the Notas Fiscais Eletrônicas Brazil app.
NFe Brazil App
Tap the Configure button on the app, and choose the “Post-registration workflow” we created in the previous step, or leave it empty.Tap the Save button.
3

Configure the supplier registration workflow

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

Prepare Invoice Workflow

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

​
Running

In this section, we’ll provide details on how to first persist and register a supplier, followed by issuing service 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.

​
Register a Supplier

Suppliers can be registered manually via the Invopop Console, or programmatically via the API. The process is essentially the same, so we’ll demonstrate the manual method for this guide. Find the Contacts 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 demonstration purposes only). This will only work in the sandbox environment; in production, you’ll need the details of an actual company:
Brazil supplier example for sandbox
{
    "$schema": "https://gobl.org/draft-0/org/party",
    "uuid": "01932ee8-8285-7bcd-a9b2-fb2230db3382",
    "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": "01310-000",
            "country": "BR"
        }
    ],
    "emails": [
        {
            "addr": "contact@technova.test"
        }
    ],
    "ext": {
        "br-nfse-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:
Supplier 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.
Issuer Registration Form
The details from this form are sent securely to Invopop’s local partner, PlugNotas, who will use them to authenticate in the corresponding municipality API. The supplier must ensure that the certificate and password are valid and accepted by the municipality where they are registered. 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 a Services Invoice

The following examples are of partial 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 “Issue NFS-e” workflow created during setup.
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 municipality and the actual PDF generated will be attached to the silo entry.
GOBL Invoices sent as NFS-e require the following properties to perform the correct normalization and validation steps. Invopop will try to assign these automatically, but we recommend defining them explicitly before uploading:

​
B2B Service Invoice

In this example, we’re issuing a simple service invoice from a Brazilian supplier to another Brazilian customer. Please note:
  • 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.
NFS-e Service Invoice
{
  "$schema": "https://gobl.org/draft-0/bill/invoice",
  "$regime": "BR",
  "$addons": ["br-nfse-v1"],
  "uuid": "0193305c-a7be-730d-b552-2093f0df2df7",
  "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": "01310-000",
            "country": "BR"
        }
    ],
    "ext": {
        "br-nfse-municipality": "3550308",
        "br-nfse-fiscal-incentive": "1",
        "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": [
    {
      "i": 1,
      "quantity": "15",
      "item": {
        "name": "Consultancy Services",
        "price": "100.00",
        "ext": {
          "br-nfse-service": "10.5",
          "br-nfse-cnae": "62.01-5-01"
        }
      },
      "taxes": [
        {
          "cat": "ISS",
          "percent": "15%",
          "ext": {
            "br-nfse-iss-liability": "1"
          }
        }
      ]
    }
  ]
}

​
FAQ

Please contact the [Invopop support team] (email:support@invopop.com) if you have any questions that are not listed here.
At the moment, only NFS-e is supported. We are working on adding support for NF-e (for products) and NFC-e (for final consumers).
For further details on how GOBL prepares data for conversion, see the Brazil Tax Regime.
⌘I