Brazil has a variety of electronic tax documents that must be issued in different cases for various tax purposes. These include service invoices (NFS-e), product invoices (NF-e), and consumer invoices (NFC-e). Each document type is subject to variations from state to state and municipality to municipality, with each jurisdiction applying its own rules, formats, and APIs for issuing fiscal documents.Invopop’s Documentos Fiscais Eletrônicos app provides a unified way to issue fiscal documents across all Brazilian states and 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 electronic fiscal documents in their name.
(only for services) 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 (for NFS-e) or the state (for NF-e and NFC-e) to send electronic fiscal documents in the name of the supplier.
connect the Documentos Fiscais Eletrônicos Brazil app,
create the supplier registration workflow,
configure the supplier post-registration workflow,
prepare the invoicing workflows.
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.
2
Create the supplier registration workflow
Follow one of the methods below and ensure to Save and Publish the workflow:
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 the Envelope
Register DF-e issuer (Brazil)
Set State - with configuration set to Processing.
Add any additional steps you may need, and save the new workflow.
3
Configure the supplier post-registration workflow
Follow one of the methods below and ensure to Save and Publish the workflow:
Example DF-e supplier post-registration workflow with states
Copy
Ask AI
{ "name": "DF-e process supplier post-registration", "description": "Runs after a DF-e supplier has been 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 worfkow is composed by 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.
4
Prepare NFS-e Workflow
You can skip this step if you’re not interested in issuing NFS-e documents.
Follow one of the methods below and ensure to Save and Publish the workflow:
Before starting, review the workflows guide to understand the general setup process.In Console, create a new workflow and choose Empty Invoice workflow as the base. Then name the workflow with a descriptive label such as “Issue NFS-e invoice”.The new workflow will need to perform these steps:
Set State - to Processing.
Add Sequential Code - with dynamic sequences and a name like “NFS-e”.
Send NFS-e (Brazil).
Set State - to Sent.
Finally, in the Error Handling area, add the Set State action and select Error.Add any additional steps you may need, and save the new workflow.
5
Prepare NFC-e Workflow
You can skip this step if you’re not interested in issuing NFC-e documents.
Follow one of the methods below and ensure to Save and Publish the workflow:
Before starting, review the workflows guide to understand the general setup process.In Console, create a new workflow and choose Empty Invoice workflow as the base. Then name the workflow with a descriptive label such as “Issue NFC-e invoice”.The new workflow will need to perform these steps:
Set State - to Processing.
Add Sequential Code - with dynamic sequences and a name like “NFC-e”.
Send NFC-e (Brazil).
Set State - to Sent.
Finally, in the Error Handling area, add the Set State action and select Error.Add any additional steps you may need, and save the new workflow.
In this section, we’ll provide details on how to first persist and register a supplier, followed by issuing 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.All operations described in the following sections 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.
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 service invoices on behalf of the supplier.
The following examples are of example 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” or the “Issue NFC-e” workflow created during setup over them.
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 tax authority and the actual PDF generated will be attached to the silo entry.
ISS (Imposto Sobre Serviços) is not treated as a standard transactional tax calculated on top of a net amount. Instead, it is an informative tax embedded in the final price—the invoice only reports what portion of the total corresponds to ISS.In GOBL, ISS is flagged as an “informative” tax category. This means:
ISS must be added to the GOBL invoice like any other tax, with the proper percentage.
The tax amount is not added to the price; it represents the portion of the total that corresponds to ISS.
The NFS-e document displays ISS as informational data, reflecting what was already embedded in the final price.
Do not use prices_include with ISS—since ISS is informative, it should not be treated as a price-inclusive tax.
How do I configure Chargebee or Stripe imports for Brazilian invoices with ISS?
Billing platforms like Chargebee and Stripe are not aware of ISS particularities and tend to wrongly treat ISS as a typical tax included in the price. This causes invalid-prices-include errors during import because that pricing model is not compatible with how ISS works for NFS-e.The correct setup is:
Do not configure ISS as a tax in your billing platform (Chargebee, Stripe, etc.).
Prices in your billing platform should already be the final public prices with ISS embedded.
Add a Modify Silo Entry step to your import workflow that injects the ISS tax with the desired percentage into the GOBL invoice.
This workflow approach ensures ISS is properly added to the GOBL invoice as an informative tax category before submission to the Brazilian tax authority, while avoiding the pricing conflicts that occur when billing platforms try to handle ISS as a standard tax.
