Skip to main content

Introduction

Before a supplier can issue electronic fiscal documents in Brazil — service invoices (NFS-e), product invoices (NF-e), or consumer invoices (NFC-e) — they must be registered with Invopop’s local partner, PlugNotas, who authenticates the supplier with the corresponding tax authority. In this guide you’ll learn how to register a supplier using the Documentos Fiscais Eletrônicos Brazil app, and how to unregister them when they should no longer issue documents from your workspace. Once a supplier is registered, continue with the companion guide: Brazil: Issuing invoices.

Prerequisites

To register a supplier 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.
  • 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.
  • For NFS-e, knowing which system the supplier must issue through: the municipality’s own system or the national Emissor Nacional. See Choose the NFS-e system below.

Setup

There are three key processes to prepare:
  • connect the Documentos Fiscais Eletrônicos Brazil app,
  • create the supplier registration workflow, and,
  • configure the supplier post-registration 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

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.
DF-e Brazil App
2

Create the supplier registration workflow

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

DF-e register supplier

Add to my workspace →
3

Configure the supplier post-registration workflow

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

DF-e process supplier post-registration

Add to my workspace →
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.

Register a supplier

All operations described in this section 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. 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
The br-nfse- identities and extensions configure service invoices (NFS-e), while the br-nfe- ones configure product and consumer invoices (NF-e/NFC-e) — omit the family the supplier won’t issue.See the br-nfse-v1 and br-nfe-v4 addons for the possible values.
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.
Supplier registration form showing the company CNPJ, the Sistema selector with the Sistema da prefeitura and Emissor Nacional options, and the certificate upload
The form shows the supplier’s CNPJ, a Sistema selector for NFS-e (see Choose the NFS-e system below), and the certificate upload. When a certificate is already registered, the upload can be left blank to keep it. In live workspaces, the form also includes an environment selector (“Ambiente da prefeitura”) with two options:
  • Homologação (homologation): the tax authority’s test environment. Documents are processed end to end but have no fiscal validity. Note that not all municipalities offer a homologation environment for NFS-e.
  • Produção (production): the real environment. Documents issued here are legally valid.
The selected environment applies to every document type the supplier issues (NFS-e, NF-e, and NFC-e) and remains in effect until the supplier is registered again. See Switch between environments below. In sandbox workspaces, the selector is not shown: the sandbox always operates in simulation mode, and responses are mocked regardless of any environment.

Choose the NFS-e system

The Sistema section of the form shown above decides where the supplier’s service invoices (NFS-e) are sent:
  • Sistema da prefeitura (municipal system): NFS-e are issued through the municipality’s own system, with the municipality’s service codes and rules.
  • Emissor Nacional (national emitter): NFS-e are issued through the national NFS-e system run by the Receita Federal, using the national standard layout and the national service list.
The selection only affects NFS-e. Product and consumer invoices (NF-e and NFC-e) always go through the state’s SEFAZ and are not affected. Which option applies is defined by Brazilian regulation rather than by preference, so check the supplier’s situation before registering: When in doubt, confirm with the municipality’s tax office or the supplier’s accountant. The Portal Nacional da NFS-e publishes the list of municipalities that have joined the national system and whether each one uses the Emissor Nacional.
Suppliers registered before this option was available are on the municipal system. Some of them now fall under the Emissor Nacional (for example, ME and EPP in the Simples Nacional since 1 November 2026, or suppliers whose municipality has since migrated) and must be switched, or their NFS-e will be rejected. Switching does not require uploading the certificate again: see Re-register a supplier below.
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. For the Emissor Nacional, an A1 certificate (.pfx or .p12) is required to issue through the API. 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 invoices on behalf of the supplier. Head over to the DF-e issuing invoices guide to continue.

Re-register a supplier

Running the registration process again over an already registered supplier lets you change their configuration without starting from scratch. You can change the NFS-e system in any workspace and, in live workspaces, the environment. To re-register a supplier:
  1. Run the Register Supplier workflow over the supplier’s silo entry to obtain a new registration link.
  2. Open the registration link. The form shows the supplier’s current NFS-e system pre-selected and, in live workspaces, their current environment.
  3. Select the new system or environment.
  4. Leave the certificate field blank to keep the current certificate (or upload a new one), and submit the form.
Once the form is submitted, the supplier is reconfigured with the new settings and the post-registration workflow runs again.

Switch between environments

In live workspaces, a supplier is registered in either homologation or production — never both at the same time. A common scenario is registering a supplier in homologation first to test the integration end to end, and then re-registering them in production to start issuing real documents.

Switch between NFS-e systems

Re-register the supplier and select the other option in the Sistema section whenever the system that applies to them changes. Typical cases:
  • the supplier was registered before the system could be chosen (they are on the municipal system) and now falls under the Emissor Nacional,
  • the supplier joins the Simples Nacional regime, which puts them on the Emissor Nacional,
  • the supplier leaves the Simples Nacional regime in a municipality that kept its own system, which puts them back on the municipal system, or
  • the supplier’s municipality migrates its taxpayers to the Emissor Nacional.
Check the table in Choose the NFS-e system to confirm which system applies before switching: a change of tax regime only requires a switch if the applicable system actually changes. The certificate does not need to be uploaded again. From the next NFS-e onwards, invoices are sent to the selected system, so make sure the service codes used on the supplier’s invoices are the ones expected by that system: municipal codes for the municipal system, and the national service list for the Emissor Nacional.
The environment selected in the most recent registration applies to all documents issued for that supplier from that point on, across every document type (NFS-e, NF-e, and NFC-e). After switching to homologation, no legally valid documents can be issued for the supplier until you register them back in production. Always verify which environment a supplier is in before issuing.
Sandbox workspaces are not affected: they always operate in simulation mode, and responses are mocked. To test against the tax authority’s real homologation environment, register the supplier in a live workspace with the homologation environment selected.

Unregister a supplier

Unregistering a supplier revokes their invoice issuing privileges from your workspace. You might need to unregister an entity because the supplier is no longer your client or because of a change in their Tax ID. To do so, use the following workflow template:

DF-e unregister supplier

Add to my workspace →

FAQ

Upload the supplier’s A1 digital certificate (PFX or P12) plus password through the registration workflow. Invopop validates it against the relevant SEFAZ or municipal endpoint and activates the supplier for issuing.
A1 certificates (X.509 + private key, exported as PKCS#12) and their passwords are stored encrypted. Invopop uses them to sign documents and authenticate to the relevant SEFAZ or municipal endpoint on the supplier’s behalf.
More available in our Brazil FAQ section

Participate in our community

Ask and answer questions about invoicing in Brazil →