> ## Documentation Index
> Fetch the complete documentation index at: https://docs.invopop.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DF-e supplier registration guide

> Register suppliers to issue Documentos Fiscais Eletrônicos in Brazil.

## 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](/apps/documentos-fiscais-electronicos-brazil), 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](/guides/br-dfe).

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

<Info>
  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.
</Info>

All of the following steps must be carried out from the [Invopop Console](https://console.invopop.com).

<Steps>
  <Step title="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.

    <Frame>
      <img src="https://mintcdn.com/invopop/fWniCD0icTwRKXxR/assets/guides/br-dfe-app.png?fit=max&auto=format&n=fWniCD0icTwRKXxR&q=85&s=e3461a076becb8dfb7885b5b3764da90" alt="DF-e Brazil App" width="400" noZoom data-path="assets/guides/br-dfe-app.png" />
    </Frame>
  </Step>

  <Step title="Create the supplier registration workflow">
    Follow one of the methods below and ensure to **Save** and **Publish** the workflow:

    <Tabs>
      <Tab title="Template">
        <Card iconType="duotone" title="DF-e register supplier" icon="code-branch" href="https://console.invopop.com/redirect/workflows/new?template=br-dfe-register-supplier" cta="Add to my workspace">
          This workflow will start the registration of a supplier to issue electronic tax documents.
        </Card>
      </Tab>

      <Tab title="Code">
        Copy and paste into a new [Empty Party workflow](https://console.invopop.com/redirect/workflows/new?template=empty-party) code view.

        ```json Example NFC/NFS-e register supplier workflow theme={"system"}
        {
            "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"
                    }
                }
            ]
        }
        ```
      </Tab>

      <Tab title="Build from scratch">
        Before starting, review the [workflows guide](/guides/workflows) to understand the general setup process.

        In [Console](https://console.invopop.com), create a new workflow and choose [Empty Party workflow](https://console.invopop.com/redirect/workflows/new?template=empty-party) 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.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure the supplier post-registration workflow">
    Follow one of the methods below and ensure to **Save** and **Publish** the workflow:

    <Tabs>
      <Tab title="Template">
        <Card iconType="duotone" title="DF-e process supplier post-registration" icon="code-branch" href="https://console.invopop.com/redirect/workflows/new?template=br-dfe-postregistration" cta="Add to my workspace">
          This workflow should contain any processing that needs to happen after a supplier completes the registration process.
        </Card>
      </Tab>

      <Tab title="Code">
        Copy and paste into a new [Empty Party workflow](https://console.invopop.com/redirect/workflows/new?template=empty-party) code view.

        ```json Example Brazil supplier post-registration workflow theme={"system"}
        {
            "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"
                    }
                }
            ]
        }
        ```
      </Tab>

      <Tab title="Build from scratch">
        Before starting, review the [workflows guide](/guides/workflows) to understand the general setup process.

        In [Console](https://console.invopop.com), create a new workflow and choose [Empty Party workflow](https://console.invopop.com/redirect/workflows/new?template=empty-party) 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:

        1. **Set state** - To `Registered`.
      </Tab>
    </Tabs>

    <Info>
      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.)
    </Info>

    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.
  </Step>
</Steps>

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

```json Brazil supplier example for sandbox expandable theme={"system"}
{
    "$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:

<Frame>
  <img src="https://mintcdn.com/invopop/fWniCD0icTwRKXxR/assets/guides/br-dfe-reg-link.png?fit=max&auto=format&n=fWniCD0icTwRKXxR&q=85&s=24ab34244e7c5864e36fe4d4ea689e91" width="420" alt="Supplier Registration Link" noZoom data-path="assets/guides/br-dfe-reg-link.png" />
</Frame>

<Info>
  You can access the registration link via the API by [fetching the silo
  entry](/api-ref/silo/entries/fetch-an-entry) and reading the `meta` row where
  the `key` is set to `registration-link`.
</Info>

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.

<Frame>
  <img src="https://mintcdn.com/invopop/fWniCD0icTwRKXxR/assets/guides/br-dfe-reg-cer.png?fit=max&auto=format&n=fWniCD0icTwRKXxR&q=85&s=dfcb3977203da764c55e846076e36255" width="500" alt="Supplier Registration Form" data-path="assets/guides/br-dfe-reg-cer.png" />
</Frame>

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](/guides/br-dfe) 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:

<Tabs>
  <Tab title="Template">
    <Card title="DF-e unregister supplier" icon="code-branch" iconType="duotone" href="https://console.invopop.com/redirect/workflows/new?template=br-dfe-unregister-supplier" cta="Add to my workspace">
      This workflow will revoke invoice issuing privileges for a supplier in Brazil.
    </Card>
  </Tab>

  <Tab title="Code">
    Copy and paste into a new [Empty Party workflow](https://console.invopop.com/redirect/workflows/new?template=empty-party) code view.

    ```json Example NFC/NFS-e unregister supplier workflow theme={"system"}
    {
        "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"
                }
            }
        ]
    }
    ```
  </Tab>

  <Tab title="Build from scratch">
    In [Console](https://console.invopop.com) create a new workflow and select [Empty Party workflow](https://console.invopop.com/redirect/workflows/new?template=empty-party) in the template selector, then add the following steps:

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

    In the Error Handling section, add the **Set state** action and select `Error`.
  </Tab>
</Tabs>

## FAQ

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

More available in our [Brazil FAQ](/faq/brazil) section

***

<AccordionGroup>
  <Accordion title="🇧🇷 Invopop resources for Brazil">
    |            |                                                                                                                                                                                                                                                                                                                                                                            |
    | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Compliance | <Icon icon="https://assets.invopop.com/flags/br.svg" /> [Invoicing compliance in Brazil](/compliance/brazil)<br /> <Icon icon="timeline" /> [Compliance timeline](/timelines/brazil)                                                                                                                                                                                       |
    | Apps       | <Icon icon="https://assets.invopop.com/apps/notas-fiscais-eletronicas-brazil/icon.svg" /> [Documentos Fiscais Eletrônicos Brazil](/apps/documentos-fiscais-electronicos-brazil)                                                                                                                                                                                            |
    | Guides     | <Icon icon="book" /> [Supplier registration](/guides/br-dfe-supplier)<br /> <Icon icon="book" /> [Issuing invoices](/guides/br-dfe)                                                                                                                                                                                                                                        |
    | FAQ        | <Icon icon="square-question" /> [Brazil FAQ](/faq/brazil)                                                                                                                                                                                                                                                                                                                  |
    | GOBL       | <Icon icon="https://assets.invopop.com/icons/gobl.svg" />  [Brazil Tax Regime](https://docs.gobl.org/regimes/br)<br /> <Icon icon="https://assets.invopop.com/icons/gobl.svg" /> [Brazil NF-e Addon](https://docs.gobl.org/addons/br-nfe-v4)<br /> <Icon icon="https://assets.invopop.com/icons/gobl.svg" /> [Brazil NFS-e Addon](https://docs.gobl.org/addons/br-nfse-v1) |
  </Accordion>
</AccordionGroup>

<Card title="Participate in our community" icon="forumbee" href="https://community.invopop.com" arrow="true" horizontal>
  Ask and answer questions about invoicing in Brazil →
</Card>