DF-e supplier registration guide

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.

-	Sandbox	Live
Supplier	Registration required, but details don’t need to be real	Real company details required
Certificates	Not required to be valid	Must be valid and real
Environment	Always simulation mode — responses are mocked	Homologation or production, chosen during registration

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.

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.

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:

DF-e register supplier

Add to my workspace →

Workflow
Code

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

Example NFC/NFS-e register supplier workflow

{
    "name": "NFC/NFS-e register supplier",
    "description": "Register a supplier to issue NFC/NFS-e in Brazil",
    "schema": "org/party",
    "steps": [
        {
            "id": "68e5abd0-b64b-11f0-8ddf-b9fd6fa99d97",
            "name": "Sign envelope",
            "provider": "silo.close"
        },
        {
            "id": "6f0a6500-b64b-11f0-8ddf-b9fd6fa99d97",
            "name": "Register supplier in 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"
            }
        }
    ]
}

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 →

Workflow
Code

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

Example Brazil supplier post-registration workflow

{
    "name": "Brazil supplier post-registration",
    "description": "Mark a supplier as 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"
            }
        }
    ]
}

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

{
    "$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",
        "br-nfse-fiscal-incentive": "2",
        "br-nfse-special-regime": "6",
        "br-nfe-regime": "1",
        "br-nfe-fiscal-incentive": "2",
        "br-nfe-special-regime": "6"
    }
}

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:

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.

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. 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 invoices on behalf of the supplier. Head over to the DF-e issuing invoices guide to continue.

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 moving them to production to start issuing real documents. To switch a supplier from one environment to the other, run the registration process again:

Run the Register Supplier workflow over the supplier’s silo entry to obtain a new registration link.
Open the registration link and select the new environment.
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 in the selected environment. To check which environment a supplier is currently in, obtain a registration link the same way (step 1) and open it: the form shows the supplier’s current environment pre-selected.

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 →

Workflow
Code

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

Example NFC/NFS-e unregister supplier workflow

{
    "name": "NFC/NFS-e unregister supplier",
    "description": "Unregister a supplier from issuing NFC/NFS-e in Brazil",
    "schema": "org/party",
    "steps": [
        {
            "id": "1b9bfd47-701c-4834-b219-dc58da8cf51b",
            "name": "Unregister supplier in Brazil",
            "provider": "nfe-br.unregister"
        },
        {
            "id": "710ca93c-7f2e-4999-9209-ae358d5dbad0",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `void`{.state .void}",
            "config": {
                "state": "void"
            }
        }
    ],
    "rescue": [
        {
            "id": "2c1f292c-7bd5-4588-971f-8adeb12ade7a",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `error`{.state .error}",
            "config": {
                "state": "error"
            }
        }
    ]
}

FAQ

How do I onboard a new supplier in Brazil?

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.

How are supplier credentials stored in Invopop for Brazil?

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

🇧🇷 Invopop resources for Brazil


Compliance	Invoicing compliance in Brazil Compliance timeline
Apps	Documentos Fiscais Eletrônicos Brazil
Guides	Supplier registration Issuing invoices
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 →

Networks

Countries

Set-up

GOBL

Apps

API

Features

DF-e supplier registration guide

Introduction

Prerequisites

Setup

DF-e register supplier

DF-e process supplier post-registration

Register a supplier

Switch between environments

Unregister a supplier

DF-e unregister supplier

FAQ

Participate in our community

​Introduction

​Prerequisites

​Setup

DF-e register supplier

DF-e process supplier post-registration

​Register a supplier

​Switch between environments

​Unregister a supplier

DF-e unregister supplier

​FAQ

Participate in our community

Introduction

Prerequisites

Setup

Register a supplier

Switch between environments

Unregister a supplier

FAQ