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

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:

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 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"
            }
        }
    ]
}

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 envelope
Register supplier in 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 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"
            }
        }
    ]
}

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 workflow is composed of 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.

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"
    }
}

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

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:

Template
Code
Build from scratch

DF-e unregister supplier

This workflow will revoke invoice issuing privileges for a supplier in Brazil.

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"
            }
        }
    ]
}

In Console create a new workflow and select Empty Party workflow in the template selector, then add the following steps:

Unregister supplier in Brazil - Removes the supplier’s registration so it can no longer issue electronic fiscal documents from this workspace.
Set state - Select void to label the supplier accordingly.

In the Error Handling section, add the Set state action and select 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

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

​Unregister a supplier

DF-e unregister supplier

​FAQ

Participate in our community

Introduction

Prerequisites

Setup

Register a supplier

Unregister a supplier

FAQ