Documentos fiscais eletrônicos Brazil

Send NF-e, NFC-e & NFS-e documents to the tax authorities in Brazil via PlugNotas.

Description

Register suppliers

Supplier registration guide ›

Issue invoices

Issuing guide ›

Developer	Invopop
Category	Government
Scope	B2B, B2C
Country	Brazil

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.

Invopop has partnered with PlugNotas to issue electronic fiscal documents in Brazil. The integration handles the complexity of different state and municipal requirements, allowing you to issue documents through a single unified interface.

Key features

• Workflow automation: This app provides automated workflows for issuing NFS-e, NF-e, and NFC-e documents through the Brazilian tax authorities.
• Multi-jurisdiction support: Unified interface for issuing documents across all Brazilian states and over 2000 municipalities, each with their own rules and formats.
• Supplier registration: Secure supplier onboarding process with certificate-based authentication for issuing documents on behalf of suppliers.
• Legally compliant documents: Documents are generated with all mandatory fields and tax calculations as required by Brazilian fiscal legislation.
• PlugNotas integration: Direct integration with PlugNotas, an authorized technology provider for Brazilian electronic fiscal documents.
• NFS-e, NF-e, and NFC-e support: Issue invoices for service, B2B product, and consumer transactions.

Make sure to check out our Supplier registration guide for onboarding suppliers, and the Issuing invoices guide for issuing documents and setting up your workflows.

FAQ

Invoicing questions

What type of Documentos Fiscais does Invopop support?

Invopop supports NF-e, NFS-e and NFC-e documents. Transport documents (MDF-e and CT-e) are not currently supported.

Where can I find the mapping of GOBL fields to DF-e documents?

For further details on how GOBL prepares data for conversion, see:

• The Brazil Regime GOBL Reference.
• The NFS-e Addon GOBL Reference.
• The NF-e Addon GOBL Reference.

Can I issue an NF-e to a foreign customer?

Yes. A foreign customer that does not have a Brazilian CNPJ or CPF can be identified by providing a country-qualified identity (e.g. a passport number) on the customer party. The identity.country must be an ISO country code other than BR.

When a foreign customer is used:

• the tax_id block can be omitted,
• the customer address country is required and must not be BR (it is auto-filled from the identity country if missing),
• the state field and the br-ibge-municipality extension are not required, as they only apply to Brazilian parties.

Example customer block for a foreign buyer:

"customer": {
  "name": "Acme International Inc.",
  "identities": [
    {
      "key": "passport",
      "country": "US",
      "code": "US-FOREIGN-123"
    }
  ],
  "addresses": [
    {
      "num": "500",
      "street": "Market Street",
      "locality": "San Francisco",
      "code": "94105",
      "country": "US"
    }
  ]
}

What's the workflow for issuing NF-e invoices?

Build a GOBL invoice with the br-nfe-v4 addon, send it through the Issue NF-e workflow. Invopop signs with the supplier’s A1 cert, transmits to the issuer’s state SEFAZ, receives the protocolo de autorização, and exposes the authorized XML and DANFE PDF.

How do I retrieve the NF-e access key and authorization protocol?

After a successful issuance, SEFAZ returns two identifiers that Invopop stores as envelope stamps on the silo entry under data.head.stamps:

• sefaz-key — the 44-digit NF-e access key (chave de acesso) that uniquely identifies the document.
• sefaz-auth — the authorization protocol number (número do protocolo) confirming SEFAZ acceptance.

Use them to reconcile your records, build the DANFE QR code, or query SEFAZ directly.

"stamps": [
  { "provider": "sefaz-key", "value": "35240114200166000187550010000000071123456789" },
  { "provider": "sefaz-auth", "value": "135240000123456" }
]

What are the required and optional fields for NF-e invoices in Brazil?

NF-e (br-nfe-v4) covers electronic invoices for the circulation of goods in Brazil. It maps to two fiscal models:

• Model 55 — NF-e: B2B or business-to-government transactions
• Model 65 — NFC-e: B2C consumer transactions (simplified)

Notation

• ✅ Required — validation will fail if missing
• ⬜ Optional — can be omitted
• 🔧 Auto-normalized — set automatically if not provided

Invoice Header

Field	Required	Notes
$schema	auto	https://gobl.org/draft-0/bill/invoice
$addons	✅	["br-nfe-v4"]
$tags	⬜	Use ["simplified"] for NFC-e (model 65)
uuid	⬜	Auto-generated if absent
type	⬜	Defaults to standard
series	✅	Pattern: ^(?:0|[1-9]{1}[0-9]{0,2})$
code	⬜	Required to sign the document.
issue_date	✅	ISO date, e.g. "2024-11-15"
currency	✅	Must be "BRL"
tax	✅	See Tax Extensions
notes	✅	At least one note with key: "reason" required
lines	✅	At least one line item
charges	⬜	Document-level charges
discounts	⬜	Document-level discounts
supplier	✅	See Supplier
customer	✅ model 55 ⬜ model 65	See Customer
payment	✅ if not fully paid	See Payment
ordering	⬜
delivery	⬜

Tax Extensions

Extension	Required	Values
tax.ext.br-nfe-model	✅	"55" (NF-e, B2B) or "65" (NFC-e, B2C)
tax.ext.br-nfe-presence	✅	See table below. Restricted by model.
tax.ext.br-nfe-regime	⬜	"1"=Simples Nacional, "2"=Simples Nacional Excess, "3"=Normal
tax.ext.br-nfe-fiscal-incentive	⬜	"1"=Has incentive, "2"=No incentive

br-nfe-presence allowed values:

Code	Description	NF-e (55)	NFC-e (65)
0	N/A	✅	❌
1	In-person	✅	✅
2	Internet	✅	❌
3	Tele-service	✅	❌
4	Home delivery	❌	✅
5	Off-site	✅	❌
9	Others	✅	❌

"tax": {
  "ext": {
    "br-nfe-model": "55",
    "br-nfe-presence": "1"
  }
}

Notes

At least one note with key: "reason" is required. It maps to the NF-e natOp field (nature of the operation).

Supplier

Field	Required	Notes
name	✅
tax_id.country	✅	"BR"
tax_id.code	✅	CNPJ (14 digits) or CPF (11 digits), Mod11 validated
identities[].key: "br-nfe-state-reg"	✅	State Registration (Inscrição Estadual)
addresses	✅	At least one
addresses[].country	✅ 🔧	ISO country code. Auto-filled from tax_id.country if missing.
ext.br-ibge-municipality	✅	7-digit IBGE municipality code

Customer (Model 55 — required, Model 65 — optional)

Brazilian customers must provide a Brazilian tax_id. Foreign customers can issue an NF-e by providing a country-qualified identity (e.g. a passport number) instead of a tax_id.

Field	Required	Notes
tax_id.country	✅ for BR customers	"BR"
tax_id.code	✅ when tax_id is present	CNPJ or CPF
identities[] with non-BR country	✅ for foreign customers without a tax_id	E.g. { "key": "passport", "country": "US", "code": "US-FOREIGN-123" }
addresses	✅
addresses[].country	✅ 🔧	ISO country code. Auto-filled from the tax_id country or the first identity that declares a country.
addresses[].state	✅ for BR customers	Must be a valid Brazilian state acronym (e.g. SP). Not required for foreign customers.
ext.br-ibge-municipality	✅ for BR customers	7-digit IBGE code. Not required for foreign customers.

Line items

Required tax categories per line: ICMS, PIS, COFINS. IPI is optional.

Extension	Required	Notes
line.ext.br-nfe-cfop	✅ model 55 ⬜ model 65	CFOP (Código Fiscal de Operações e Prestações) code identifying the fiscal nature of the operation, e.g. "5102" for in-state resale. Required on every line of an NF-e (model 55).

Optional item identities: item.identities[].key: "ncm" | "gtin" | "gtin+taxable".

Payment

Required when the invoice is not fully paid. Must include payment.instructions.key. Payment-means mapping is auto-set unless key: "other".

What's the workflow for issuing NFS-e invoices?

Build a GOBL invoice with the br-nfse-v1 addon and send it through the Issue NFS-e workflow. Until the federal NFS-e (DPS) takes over in 2026, Invopop routes per-municipality — the workflow handles the underlying API differences transparently.

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:

1. Do not configure ISS as a tax in your billing platform (Chargebee, Stripe, etc.).
2. Prices in your billing platform should already be the final public prices with ISS embedded.
3. 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.

What are the required and optional fields for NFS-e invoices in Brazil?

NFS-e (br-nfse-v1) covers electronic service invoices (Notas Fiscais de Serviços Eletrônicas) in Brazil. Service invoices are regulated at the municipal level, so several fields carry municipality-specific codes. The addon implements the ABRASF national standard (v2.04).

Invoice Header

Field	Required	Notes
$addons	✅	["br-nfse-v1"]
series	✅	Any non-empty string
code	⬜	Required to sign the document
issue_date	✅	ISO date
currency	✅	Must be "BRL"
lines	✅	At least one line item
charges	❌	Not supported by NFS-e
discounts	❌	Not supported by NFS-e
supplier	✅	See Supplier

Supplier

Field	Required	Notes
name	✅
tax_id.country	✅	"BR"
tax_id.code	✅	CNPJ or CPF
identities[].key: "br-nfse-municipal-reg"	✅	Municipal Registration
addresses	✅
ext.br-ibge-municipality	✅	7-digit IBGE municipality code
ext.br-nfse-simples	✅	"1" opt-in, "2" opt-out
ext.br-nfse-fiscal-incentive	✅	"1" has incentive, "2" does not (default)
ext.br-nfse-special-regime	⬜	Special regime values

Customer

Optional. When provided, ext.br-ibge-municipality is required if addresses are present.

Line items

Required item extension: item.ext.br-nfse-service (municipality service code).

Optional item extensions: item.ext.br-nfse-cnae, plus the all-or-none trio item.ext.br-nfse-{operation,tax-status,tax-class}.

Required tax category per line: ISS. ISS extension taxes[ISS].ext.br-nfse-iss-liability defaults to "1" (Liable).

Registering supplier questions

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.

How do I register a supplier with NF-e?

Upload the A1 certificate plus its password through the Register Supplier workflow, providing the supplier’s CNPJ and Inscrição Estadual. Invopop validates the certificate against SEFAZ and activates the supplier for the corresponding UF.

What certificates does NF-e require to authenticate a supplier?

An ICP-Brasil A1 certificate issued to the supplier’s CNPJ (or CPF for individuals). Format: PKCS#12 (.pfx/.p12) containing the X.509 cert and matching private key. Validity is typically 1 year.

How do I register a supplier with NFS-e?

Upload the supplier’s A1 certificate plus the Inscrição Municipal for the relevant city. The federal DPS (2026) consolidates registration; until then, separate enrollment per municipality may be required for high-volume issuance.

What certificates does NFS-e require to authenticate a supplier?

Most municipalities accept the same ICP-Brasil A1 certificate used for NF-e. A few require A3 (smartcard/USB token) — Invopop currently supports A1 only.

More answers in our Brazil FAQ section

Actions

The following workflow actions will be available once you install and enable this app:

Send NFS-e to Prefeitura

Send NF-e to SEFAZ

Send NFC-e to SEFAZ

Register supplier in Brazil

Register suppliers to issue electronic fiscal documents on their behalf.

Unregister supplier in Brazil

Remove a supplier’s registration so it can no longer issue electronic fiscal documents from this workspace.

Cancel NFS-e with Prefeitura

Cancel a previously sent NFS-e invoice via PlugNotas. The cancellation reason and code can be set on the workflow step configuration or overridden per job using the nfe-br-cancel-reason and nfe-br-cancel-code arguments.

Cancel NF-e with SEFAZ

Cancel a previously sent NF-e invoice via PlugNotas. The cancellation reason can be set on the workflow step or overridden per job using the nfe-br-cancel-reason argument.

Cancel NFC-e with SEFAZ

Cancel a previously sent NFC-e invoice via PlugNotas. The cancellation reason can be set on the workflow step or overridden per job using the nfe-br-cancel-reason argument.

Workflows

The following workflows are available to make your integration easier. Use them as templates to build upon.

Issuing document workflows:

DF-e issue service invoice (NFS-e)

This workflow automates NFS-e service invoice processing and tax compliance in Brazil.

Example SEFAZ issue NFS-e invoice workflow

{
    "name": "SEFAZ issue NFS-e invoice",
    "description": "Issue an NFS-e service invoice via PlugNotas",
    "schema": "bill/invoice",
    "steps": [
        {
            "id": "d1c7bde0-b651-11f0-b6c3-efa5610a4723",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `processing`{.state .processing}",
            "config": {
                "state": "processing"
            }
        },
        {
            "id": "dbcb8600-b651-11f0-b6c3-efa5610a4723",
            "name": "Add sequential code",
            "provider": "sequence.enumerate",
            "summary": "Dynamic · NFS-e · 1",
            "config": {
                "name": "NFS-e",
                "padding": 1,
                "start": 1
            }
        },
        {
            "id": "e8eba950-b651-11f0-b6c3-efa5610a4723",
            "name": "Sign envelope",
            "provider": "silo.close"
        },
        {
            "id": "ec64f190-b651-11f0-b6c3-efa5610a4723",
            "name": "Send NFS-e to Prefeitura",
            "provider": "nfe-br.send"
        },
        {
            "id": "eecc7bb0-b651-11f0-b6c3-efa5610a4723",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `sent`{.state .sent}",
            "config": {
                "state": "sent"
            }
        }
    ],
    "rescue": [
        {
            "id": "f9195ac0-b651-11f0-b6c3-efa5610a4723",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `error`{.state .error}",
            "config": {
                "state": "error"
            }
        }
    ]
}

Add to my workspace →

DF-e issue product invoice (NF-e)

This workflow automates NF-e product invoice processing and tax compliance in Brazil.

Example issue NF-e invoice workflow

{
    "name": "Issue NF-e invoice",
    "description": "Issue an NF-e product invoice via PlugNotas",
    "schema": "bill/invoice",
    "steps": [
        {
            "id": "ddfb8e79-8260-4ecd-bf59-115e837cd135",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `processing`{.state .processing}",
            "config": {
                "state": "processing"
            }
        },
        {
            "id": "169c4b15-83ae-4242-b0c9-4e4915d15361",
            "name": "Add sequential code",
            "provider": "sequence.enumerate",
            "summary": "Dynamic · NF-e · 1",
            "config": {
                "name": "NF-e",
                "padding": 1,
                "start": 1
            }
        },
        {
            "id": "283dae9e-ea44-46c0-8f63-5af48ec5f388",
            "name": "Sign envelope",
            "provider": "silo.close"
        },
        {
            "id": "12bd4677-dc3c-4043-85ca-54f8d034803d",
            "name": "Send NF-e to SEFAZ",
            "provider": "nfe-br.send.nfe"
        },
        {
            "id": "999ad559-1040-4e69-98c9-93e62c8833d4",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `sent`{.state .sent}",
            "config": {
                "state": "sent"
            }
        }
    ],
    "rescue": [
        {
            "id": "5c38f3d4-1338-4990-a248-0822c5081124",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `error`{.state .error}",
            "config": {
                "state": "error"
            }
        }
    ]
}

Add to my workspace →

DF-e issue consumer invoice (NFC-e)

This workflow automates NFC-e consumer invoice processing and tax compliance in Brazil.

Example issue NFC-e invoice workflow

{
    "name": "Issue NFC-e invoice",
    "description": "Issue an NFC-e consumer invoice via PlugNotas",
    "schema": "bill/invoice",
    "steps": [
        {
            "id": "93769100-b652-11f0-a7d9-bfad358c6464",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `processing`{.state .processing}",
            "config": {
                "state": "processing"
            }
        },
        {
            "id": "971c6780-b652-11f0-a7d9-bfad358c6464",
            "name": "Add sequential code",
            "provider": "sequence.enumerate",
            "summary": "Dynamic · NFC-e · 1",
            "config": {
                "name": "NFC-e",
                "padding": 1,
                "start": 1
            }
        },
        {
            "id": "9f965b50-b652-11f0-a7d9-bfad358c6464",
            "name": "Sign envelope",
            "provider": "silo.close"
        },
        {
            "id": "8693f670-b653-11f0-a7d9-bfad358c6464",
            "name": "Send NFC-e to SEFAZ",
            "provider": "nfe-br.send.nfce"
        },
        {
            "id": "a9dc0e70-b652-11f0-a7d9-bfad358c6464",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `sent`{.state .sent}",
            "config": {
                "state": "sent"
            }
        }
    ],
    "rescue": [
        {
            "id": "b0f7f8e0-b652-11f0-a7d9-bfad358c6464",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `error`{.state .error}",
            "config": {
                "state": "error"
            }
        }
    ]
}

Add to my workspace →

Cancelling document workflows:

DF-e cancel service invoice (NFS-e)

This workflow cancels a previously sent NFS-e invoice in Brazil.

Example Cancel NFS-e invoice workflow

{
    "name": "Cancel NFS-e invoice",
    "description": "Cancel an NFS-e service invoice via PlugNotas",
    "schema": "bill/invoice",
    "steps": [
        {
            "id": "5e63dc30-535e-11f1-aba1-0fa2408cece2",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `processing`{.state .processing}",
            "config": {
                "state": "processing"
            }
        },
        {
            "id": "71238320-535e-11f1-aba1-0fa2408cece2",
            "name": "Cancel NFS-e with Prefeitura",
            "provider": "nfe-br.cancel.nfse"
        },
        {
            "id": "65aa8020-535e-11f1-aba1-0fa2408cece2",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `void`{.state .void}",
            "config": {
                "state": "void"
            }
        }
    ],
    "rescue": [
        {
            "id": "6b3199c0-535e-11f1-aba1-0fa2408cece2",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `error`{.state .error}",
            "config": {
                "state": "error"
            }
        }
    ]
}

Add to my workspace →

DF-e cancel product invoice (NF-e)

This workflow cancels a previously sent NF-e invoice in Brazil.

Example Cancel NF-e invoice workflow

{
    "name": "Cancel NF-e invoice",
    "description": "Cancel an NF-e product invoice via PlugNotas",
    "schema": "bill/invoice",
    "steps": [
        {
            "id": "7b40e24a-0c51-4462-b3e9-d2d20d424a0d",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `processing`{.state .processing}",
            "config": {
                "state": "processing"
            }
        },
        {
            "id": "834e52d6-d50a-4340-9ca6-f07557aa94d5",
            "name": "Cancel NF-e with SEFAZ",
            "provider": "nfe-br.cancel.nfe"
        },
        {
            "id": "ddfb8e79-8260-4ecd-bf60-115e837cd135",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `void`{.state .void}",
            "config": {
                "state": "void"
            }
        }
    ],
    "rescue": [
        {
            "id": "169c4b15-83ae-4243-b0c9-4e4915d15361",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `error`{.state .error}",
            "config": {
                "state": "error"
            }
        }
    ]
}

Add to my workspace →

DF-e cancel consumer invoice (NFC-e)

This workflow cancels a previously sent NFC-e invoice in Brazil.

Example Cancel NFC-e invoice workflow

{
    "name": "Cancel NFC-e invoice",
    "description": "Cancel an NFC-e consumer invoice via PlugNotas",
    "schema": "bill/invoice",
    "steps": [
        {
            "id": "5e63dc30-535e-11f1-aba1-0fa2408cece2",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `processing`{.state .processing}",
            "config": {
                "state": "processing"
            }
        },
        {
            "id": "71238320-535e-11f1-aba1-0fa2408cece2",
            "name": "Cancel NFC-e with SEFAZ",
            "provider": "nfe-br.cancel.nfce"
        },
        {
            "id": "65aa8020-535e-11f1-aba1-0fa2408cece2",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `void`{.state .void}",
            "config": {
                "state": "void"
            }
        }
    ],
    "rescue": [
        {
            "id": "6b3199c0-535e-11f1-aba1-0fa2408cece2",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `error`{.state .error}",
            "config": {
                "state": "error"
            }
        }
    ]
}

Add to my workspace →

Supplier workflows:

DF-e supplier post-registration

This workflow marks a supplier as registered after successful onboarding.

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

Add to my workspace →

DF-e register supplier

This workflow registers a supplier so it can issue electronic fiscal documents from this workspace.

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

Add to my workspace →

DF-e unregister supplier

This workflow removes a supplier’s registration so it can no longer issue electronic fiscal documents from this workspace.

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

Add to my workspace →

Documents

Invoice documents:

Example B2B service invoice (NFS-e)

In this example, we’re issuing a simple service invoice (NFS-e) from a Brazilian supplier to another Brazilian business customer.

Notice:

• we’ve added the br-nfse-v1 addon; this ensures the document will be validated using the NFS-e rules built into the GOBL library,
• extensions (ext) and identities have been used in multiple locations for fields whose values cannot be determined any other way,
• ISS percentage is provided explicitly as it varies depending on the municipality and type of service,
• there are no totals or calculations; all these will be made automatically when uploading, and,
• make sure to process it with the “DF-e issue service invoice (NFS-e)” workflow created during setup.

B2B Service Invoice (NFS-e)

{
  "$schema": "https://gobl.org/draft-0/bill/invoice",
  "$addons": [
    "br-nfse-v1"
  ],
  "series": "XXBR",
  "supplier": {
    "name": "TechNova Soluções Digitais Ltda.",
    "tax_id": {
      "country": "BR",
      "code": "05229829000184"
    },
    "identities": [
      {
        "key": "br-nfse-municipal-reg",
        "code": "45678901234567"
      }
    ],
    "addresses": [
      {
        "num": "101",
        "street": "Avenida Paulista",
        "locality": "Bela Vista",
        "region": "São Paulo",
        "state": "SP",
        "code": "01311-000",
        "country": "BR"
      }
    ],
    "emails": [
      {
        "addr": "[e-mail]"
      }
    ],
    "ext": {
      "br-ibge-municipality": "3550308",
      "br-nfse-simples": "1"
    }
  },
  "customer": {
    "name": "Construforte Engenharia Ltda.",
    "tax_id": {
      "country": "BR",
      "code": "46602178000103"
    },
    "addresses": [
      {
        "num": "75",
        "street": "Avenida Sete de Setembro",
        "street_extra": "Bloco C",
        "locality": "Centro",
        "region": "Salvador",
        "state": "BA",
        "code": "40060-000",
        "country": "BR"
      }
    ]
  },
  "lines": [
    {
      "quantity": "15",
      "item": {
        "name": "Consultancy Services",
        "price": "100.00",
        "ext": {
          "br-nfse-cnae": "62.01-5-01",
          "br-nfse-service": "10.5"
        }
      },
      "taxes": [
        {
          "cat": "ISS",
          "percent": "15%"
        }
      ]
    }
  ]
}

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	"$regime": "BR",
	"$addons": [
		"br-nfse-v1"
	],
	"type": "standard",
	"series": "XXBR",
	"issue_date": "2026-07-08",
	"currency": "BRL",
	"supplier": {
		"name": "TechNova Soluções Digitais Ltda.",
		"tax_id": {
			"country": "BR",
			"code": "05229829000184"
		},
		"identities": [
			{
				"key": "br-nfse-municipal-reg",
				"code": "45678901234567"
			}
		],
		"addresses": [
			{
				"num": "101",
				"street": "Avenida Paulista",
				"locality": "Bela Vista",
				"region": "São Paulo",
				"state": "SP",
				"code": "01311-000",
				"country": "BR"
			}
		],
		"emails": [
			{
				"addr": "[e-mail]"
			}
		],
		"ext": {
			"br-ibge-municipality": "3550308",
			"br-nfse-fiscal-incentive": "2",
			"br-nfse-simples": "1"
		}
	},
	"customer": {
		"name": "Construforte Engenharia Ltda.",
		"tax_id": {
			"country": "BR",
			"code": "46602178000103"
		},
		"addresses": [
			{
				"num": "75",
				"street": "Avenida Sete de Setembro",
				"street_extra": "Bloco C",
				"locality": "Centro",
				"region": "Salvador",
				"state": "BA",
				"code": "40060-000",
				"country": "BR"
			}
		]
	},
	"lines": [
		{
			"i": 1,
			"quantity": "15",
			"item": {
				"name": "Consultancy Services",
				"price": "100.00",
				"ext": {
					"br-nfse-cnae": "62.01-5-01",
					"br-nfse-service": "10.5"
				}
			},
			"sum": "1500.00",
			"taxes": [
				{
					"cat": "ISS",
					"percent": "15%",
					"ext": {
						"br-nfse-iss-liability": "1"
					}
				}
			],
			"total": "1500.00"
		}
	],
	"totals": {
		"sum": "1500.00",
		"total": "1500.00",
		"taxes": {
			"categories": [
				{
					"code": "ISS",
					"informative": true,
					"rates": [
						{
							"ext": {
								"br-nfse-iss-liability": "1"
							},
							"base": "1500.00",
							"percent": "15%",
							"amount": "225.00"
						}
					],
					"amount": "225.00"
				}
			],
			"sum": "0.00"
		},
		"tax": "0.00",
		"total_with_tax": "1500.00",
		"payable": "1500.00"
	}
}

Example B2B service invoice with RTC (NFS-e)

In this example, we’re issuing a simple service invoice (NFS-e) with the currently supported RTC (Tax Reform) fields.

Notice the differences from the previous example:

• we’ve set the br-nfse-operation extension, the br-nfse-tax-status extension and the br-nfse-tax-class extension at item level which will be used to determine the IBS and CBS taxes as part of the tax reform.

B2B Service Invoice (NFS-e) RTC

{
  "$schema": "https://gobl.org/draft-0/bill/invoice",
  "$addons": [
    "br-nfse-v1"
  ],
  "series": "XXBR",
  "supplier": {
    "name": "TechNova Soluções Digitais Ltda.",
    "tax_id": {
      "country": "BR",
      "code": "05229829000184"
    },
    "identities": [
      {
        "key": "br-nfse-municipal-reg",
        "code": "45678901234567"
      }
    ],
    "addresses": [
      {
        "num": "101",
        "street": "Avenida Paulista",
        "locality": "Bela Vista",
        "region": "São Paulo",
        "state": "SP",
        "code": "01311-000",
        "country": "BR"
      }
    ],
    "emails": [
      {
        "addr": "[e-mail]"
      }
    ],
    "ext": {
      "br-ibge-municipality": "3550308",
      "br-nfse-simples": "1"
    }
  },
  "customer": {
    "name": "Construforte Engenharia Ltda.",
    "tax_id": {
      "country": "BR",
      "code": "46602178000103"
    },
    "addresses": [
      {
        "num": "75",
        "street": "Avenida Sete de Setembro",
        "street_extra": "Bloco C",
        "locality": "Centro",
        "region": "Salvador",
        "state": "BA",
        "code": "40060-000",
        "country": "BR"
      }
    ]
  },
  "lines": [
    {
      "quantity": "15",
      "item": {
        "name": "Consultancy Services",
        "price": "100.00",
        "ext": {
          "br-nfse-cnae": "62.01-5-01",
          "br-nfse-operation": "030101",
          "br-nfse-service": "10.5",
          "br-nfse-tax-class": "000001",
          "br-nfse-tax-status": "000"
        }
      },
      "taxes": [
        {
          "cat": "ISS",
          "percent": "15%"
        }
      ]
    }
  ]
}

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	"$regime": "BR",
	"$addons": [
		"br-nfse-v1"
	],
	"type": "standard",
	"series": "XXBR",
	"issue_date": "2026-07-08",
	"currency": "BRL",
	"supplier": {
		"name": "TechNova Soluções Digitais Ltda.",
		"tax_id": {
			"country": "BR",
			"code": "05229829000184"
		},
		"identities": [
			{
				"key": "br-nfse-municipal-reg",
				"code": "45678901234567"
			}
		],
		"addresses": [
			{
				"num": "101",
				"street": "Avenida Paulista",
				"locality": "Bela Vista",
				"region": "São Paulo",
				"state": "SP",
				"code": "01311-000",
				"country": "BR"
			}
		],
		"emails": [
			{
				"addr": "[e-mail]"
			}
		],
		"ext": {
			"br-ibge-municipality": "3550308",
			"br-nfse-fiscal-incentive": "2",
			"br-nfse-simples": "1"
		}
	},
	"customer": {
		"name": "Construforte Engenharia Ltda.",
		"tax_id": {
			"country": "BR",
			"code": "46602178000103"
		},
		"addresses": [
			{
				"num": "75",
				"street": "Avenida Sete de Setembro",
				"street_extra": "Bloco C",
				"locality": "Centro",
				"region": "Salvador",
				"state": "BA",
				"code": "40060-000",
				"country": "BR"
			}
		]
	},
	"lines": [
		{
			"i": 1,
			"quantity": "15",
			"item": {
				"name": "Consultancy Services",
				"price": "100.00",
				"ext": {
					"br-nfse-cnae": "62.01-5-01",
					"br-nfse-operation": "030101",
					"br-nfse-service": "10.5",
					"br-nfse-tax-class": "000001",
					"br-nfse-tax-status": "000"
				}
			},
			"sum": "1500.00",
			"taxes": [
				{
					"cat": "ISS",
					"percent": "15%",
					"ext": {
						"br-nfse-iss-liability": "1"
					}
				}
			],
			"total": "1500.00"
		}
	],
	"totals": {
		"sum": "1500.00",
		"total": "1500.00",
		"taxes": {
			"categories": [
				{
					"code": "ISS",
					"informative": true,
					"rates": [
						{
							"ext": {
								"br-nfse-iss-liability": "1"
							},
							"base": "1500.00",
							"percent": "15%",
							"amount": "225.00"
						}
					],
					"amount": "225.00"
				}
			],
			"sum": "0.00"
		},
		"tax": "0.00",
		"total_with_tax": "1500.00",
		"payable": "1500.00"
	}
}

Example B2B product invoice (NF-e)

In this example, we’re issuing an extended product invoice (NF-e) from a Brazilian supplier to another Brazilian business customer.

Notice:

• we’ve added the br-nfe-v4 addon without the simplified tag; this sets the br-nfe-model extension to 55 (NF-e),
• the customer is required for NF-e and must include a full address; Brazilian customers must declare the br-ibge-municipality extension and a valid state, while foreign customers can be identified by a country-qualified identity (e.g. a passport) instead of a tax_id,
• supplier and customer addresses must include a country; it is auto-filled from the party’s tax ID (or first identity that declares a country) when omitted,
• each line must include a br-nfe-cfop extension to classify the fiscal operation,
• item identities carry the NCM product classification code (cProd in the NF-e XML) and the GTIN barcode (cEAN),
• item.ref maps to the supplier’s internal product code, and item.unit is converted to a UNECE unit code,
• line discounts reduce the taxable base (vDesc); line charges with key delivery map to freight (vFrete) and key insurance to insurance value (vSeg),
• line.order provides the line reference within the purchase order (nItemPed),
• a line notes entry with key goods maps to per-item additional information (infAdProd),
• ordering.code sets the purchase order number (nPed in compra) and ordering.contracts[0].code sets the contract number (nCont),
• delivery.receiver sets a separate delivery address (entrega) when goods ship to a different location than the buyer’s fiscal address,
• the payment instructions key is set to credit-transfer, which causes the br-nfe-payment-means extension to be set automatically to 18 (transferência bancária),
• a general note maps to complementary information (infCpl) in the NF-e XML,
• tax percentages are provided explicitly as they vary depending on the state and type of goods,
• there are no totals or calculations; all these will be made automatically when uploading, and,
• make sure to process it with the “DF-e issue product invoice (NF-e)” workflow created during setup.

B2B Product Invoice (NF-e)

{
  "$schema": "https://gobl.org/draft-0/bill/invoice",
  "$addons": [
    "br-nfe-v4"
  ],
  "series": "1",
  "issue_date": "2026-05-22",
  "tax": {
    "ext": {
      "br-nfe-model": "55",
      "br-nfe-presence": "2"
    }
  },
  "supplier": {
    "name": "TechNova Soluções Digitais Ltda.",
    "tax_id": {
      "country": "BR",
      "code": "05229829000184"
    },
    "identities": [
      {
        "key": "br-nfe-state-reg",
        "code": "12345678901234"
      }
    ],
    "addresses": [
      {
        "num": "101",
        "street": "Avenida Paulista",
        "locality": "Bela Vista",
        "region": "São Paulo",
        "state": "SP",
        "code": "01311-000",
        "country": "BR"
      }
    ],
    "emails": [
      {
        "addr": "[e-mail]"
      }
    ],
    "ext": {
      "br-ibge-municipality": "3550308"
    }
  },
  "customer": {
    "name": "Construforte Engenharia Ltda.",
    "tax_id": {
      "country": "BR",
      "code": "46602178000103"
    },
    "addresses": [
      {
        "num": "75",
        "street": "Avenida Sete de Setembro",
        "street_extra": "Bloco C",
        "locality": "Centro",
        "region": "Salvador",
        "state": "BA",
        "code": "40060-000",
        "country": "BR"
      }
    ],
    "ext": {
      "br-ibge-municipality": "2927408"
    }
  },
  "ordering": {
    "code": "PED-2026-0547",
    "contracts": [
      {
        "code": "CON-2026-015"
      }
    ]
  },
  "delivery": {
    "receiver": {
      "name": "Construforte Engenharia Ltda.",
      "tax_id": {
        "country": "BR",
        "code": "46602178000103"
      },
      "addresses": [
        {
          "num": "1200",
          "street": "Avenida ACM",
          "locality": "Caminho das Árvores",
          "region": "Salvador",
          "state": "BA",
          "code": "41820-014",
          "country": "BR"
        }
      ],
      "ext": {
        "br-ibge-municipality": "2927408"
      }
    }
  },
  "lines": [
    {
      "quantity": "10",
      "order": "1",
      "item": {
        "ref": "USB-C-2M",
        "name": "Cabo USB-C 2 metros",
        "unit": "piece",
        "price": "28.90",
        "identities": [
          {
            "key": "ncm",
            "code": "85444290"
          },
          {
            "key": "gtin",
            "code": "7891234567890"
          }
        ]
      },
      "discounts": [
        {
          "percent": "5%",
          "reason": "Desconto comercial"
        }
      ],
      "charges": [
        {
          "key": "delivery",
          "amount": "15.00"
        },
        {
          "key": "insurance",
          "amount": "5.00"
        }
      ],
      "notes": [
        {
          "key": "goods",
          "text": "Cabo homologado para carregamento rápido."
        }
      ],
      "taxes": [
        {
          "cat": "ICMS",
          "percent": "12.0%"
        },
        {
          "cat": "PIS",
          "percent": "1.65%"
        },
        {
          "cat": "COFINS",
          "percent": "7.60%"
        }
      ],
      "ext": {
        "br-nfe-cfop": "6102"
      }
    }
  ],
  "payment": {
    "instructions": {
      "key": "credit-transfer"
    }
  },
  "notes": [
    {
      "key": "reason",
      "text": "Venda de Mercadorias"
    },
    {
      "key": "general",
      "text": "Pedido nº 2026/0547."
    }
  ]
}

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	"$regime": "BR",
	"$addons": [
		"br-nfe-v4"
	],
	"type": "standard",
	"series": "1",
	"issue_date": "2026-05-22",
	"currency": "BRL",
	"tax": {
		"ext": {
			"br-nfe-model": "55",
			"br-nfe-operation-type": "1",
			"br-nfe-presence": "2",
			"br-nfe-purpose": "1"
		}
	},
	"supplier": {
		"name": "TechNova Soluções Digitais Ltda.",
		"tax_id": {
			"country": "BR",
			"code": "05229829000184"
		},
		"identities": [
			{
				"key": "br-nfe-state-reg",
				"code": "12345678901234"
			}
		],
		"addresses": [
			{
				"num": "101",
				"street": "Avenida Paulista",
				"locality": "Bela Vista",
				"region": "São Paulo",
				"state": "SP",
				"code": "01311-000",
				"country": "BR"
			}
		],
		"emails": [
			{
				"addr": "[e-mail]"
			}
		],
		"ext": {
			"br-ibge-municipality": "3550308",
			"br-nfe-regime": "3"
		}
	},
	"customer": {
		"name": "Construforte Engenharia Ltda.",
		"tax_id": {
			"country": "BR",
			"code": "46602178000103"
		},
		"addresses": [
			{
				"num": "75",
				"street": "Avenida Sete de Setembro",
				"street_extra": "Bloco C",
				"locality": "Centro",
				"region": "Salvador",
				"state": "BA",
				"code": "40060-000",
				"country": "BR"
			}
		],
		"ext": {
			"br-ibge-municipality": "2927408"
		}
	},
	"lines": [
		{
			"i": 1,
			"quantity": "10",
			"order": "1",
			"item": {
				"ref": "USB-C-2M",
				"name": "Cabo USB-C 2 metros",
				"identities": [
					{
						"key": "ncm",
						"code": "85444290"
					},
					{
						"key": "gtin",
						"code": "7891234567890"
					}
				],
				"price": "28.90",
				"unit": "piece"
			},
			"sum": "289.00",
			"discounts": [
				{
					"reason": "Desconto comercial",
					"percent": "5%",
					"amount": "14.45"
				}
			],
			"charges": [
				{
					"key": "delivery",
					"amount": "15.00"
				},
				{
					"key": "insurance",
					"amount": "5.00"
				}
			],
			"taxes": [
				{
					"cat": "ICMS",
					"percent": "12.0%",
					"ext": {
						"br-nfe-icms-cst": "00",
						"br-nfe-icms-origin": "0"
					}
				},
				{
					"cat": "PIS",
					"percent": "1.65%",
					"ext": {
						"br-nfe-pis-cst": "01"
					}
				},
				{
					"cat": "COFINS",
					"percent": "7.60%",
					"ext": {
						"br-nfe-cofins-cst": "01"
					}
				}
			],
			"total": "294.55",
			"notes": [
				{
					"key": "goods",
					"text": "Cabo homologado para carregamento rápido."
				}
			],
			"ext": {
				"br-nfe-cfop": "6102"
			}
		}
	],
	"ordering": {
		"code": "PED-2026-0547",
		"contracts": [
			{
				"code": "CON-2026-015"
			}
		]
	},
	"payment": {
		"instructions": {
			"key": "credit-transfer",
			"ext": {
				"br-nfe-payment-means": "18"
			}
		}
	},
	"delivery": {
		"receiver": {
			"name": "Construforte Engenharia Ltda.",
			"tax_id": {
				"country": "BR",
				"code": "46602178000103"
			},
			"addresses": [
				{
					"num": "1200",
					"street": "Avenida ACM",
					"locality": "Caminho das Árvores",
					"region": "Salvador",
					"state": "BA",
					"code": "41820-014",
					"country": "BR"
				}
			],
			"ext": {
				"br-ibge-municipality": "2927408"
			}
		}
	},
	"totals": {
		"sum": "294.55",
		"total": "294.55",
		"taxes": {
			"categories": [
				{
					"code": "ICMS",
					"informative": true,
					"rates": [
						{
							"ext": {
								"br-nfe-icms-cst": "00",
								"br-nfe-icms-origin": "0"
							},
							"base": "294.55",
							"percent": "12.0%",
							"amount": "35.35"
						}
					],
					"amount": "35.35"
				},
				{
					"code": "PIS",
					"informative": true,
					"rates": [
						{
							"ext": {
								"br-nfe-pis-cst": "01"
							},
							"base": "294.55",
							"percent": "1.65%",
							"amount": "4.86"
						}
					],
					"amount": "4.86"
				},
				{
					"code": "COFINS",
					"informative": true,
					"rates": [
						{
							"ext": {
								"br-nfe-cofins-cst": "01"
							},
							"base": "294.55",
							"percent": "7.60%",
							"amount": "22.39"
						}
					],
					"amount": "22.39"
				}
			],
			"sum": "0.00"
		},
		"tax": "0.00",
		"total_with_tax": "294.55",
		"payable": "294.55"
	},
	"notes": [
		{
			"key": "reason",
			"text": "Venda de Mercadorias"
		},
		{
			"key": "general",
			"text": "Pedido nº 2026/0547."
		}
	]
}

Example B2B product invoice for a Simples Nacional issuer (NF-e)

In this example, we’re issuing a product invoice (NF-e) from a supplier enrolled in the Simples Nacional tax regime.

Notice the differences from the previous example:

• the supplier declares its regime with the br-nfe-regime extension set to 1 (Simples Nacional); use 2 for Simples Nacional, Excess or 4 for MEI — omitting it defaults to 3 (normal regime),
• each ICMS line carries the br-nfe-icms-csosn extension (here 101, taxed with credit permission) instead of the br-nfe-icms-cst code that normal-regime issuers use,
• PIS and COFINS are still required on every line but are not levied per item under Simples Nacional, so they use the br-nfe-pis-cst and br-nfe-cofins-cst extensions set to 49 (other operations) at a 0% rate,
• there are no totals or calculations; all these will be made automatically when uploading, and,
• make sure to process it with the “DF-e issue product invoice (NF-e)” workflow created during setup.

B2B Product Invoice — Simples Nacional (NF-e)

{
  "$schema": "https://gobl.org/draft-0/bill/invoice",
  "$addons": [
    "br-nfe-v4"
  ],
  "series": "1",
  "tax": {
    "ext": {
      "br-nfe-presence": "1"
    }
  },
  "supplier": {
    "name": "Marcenaria Arte & Design ME",
    "tax_id": {
      "country": "BR",
      "code": "21586733000120"
    },
    "identities": [
      {
        "key": "br-nfe-state-reg",
        "code": "0623458900"
      }
    ],
    "addresses": [
      {
        "num": "85",
        "street": "Rua dos Artesãos",
        "locality": "Savassi",
        "region": "Minas Gerais",
        "state": "MG",
        "code": "30140-071",
        "country": "BR"
      }
    ],
    "emails": [
      {
        "addr": "[e-mail]"
      }
    ],
    "ext": {
      "br-ibge-municipality": "3106200",
      "br-nfe-regime": "1"
    }
  },
  "customer": {
    "name": "Comércio de Móveis Paulista Ltda.",
    "tax_id": {
      "country": "BR",
      "code": "33944792000101"
    },
    "addresses": [
      {
        "num": "742",
        "street": "Avenida Paulista",
        "locality": "Bela Vista",
        "region": "São Paulo",
        "state": "SP",
        "code": "01310-100",
        "country": "BR"
      }
    ],
    "ext": {
      "br-ibge-municipality": "3550308"
    }
  },
  "lines": [
    {
      "quantity": "5",
      "item": {
        "name": "Mesa de Jantar em Madeira Maciça",
        "price": "900.00",
        "identities": [
          {
            "key": "ncm",
            "code": "94036000"
          }
        ]
      },
      "taxes": [
        {
          "cat": "ICMS",
          "percent": "2.56%",
          "ext": {
            "br-nfe-icms-csosn": "101"
          }
        },
        {
          "cat": "PIS",
          "percent": "0%",
          "ext": {
            "br-nfe-pis-cst": "49"
          }
        },
        {
          "cat": "COFINS",
          "percent": "0%",
          "ext": {
            "br-nfe-cofins-cst": "49"
          }
        }
      ],
      "ext": {
        "br-nfe-cfop": "6102"
      }
    }
  ],
  "payment": {
    "instructions": {
      "key": "credit-transfer"
    }
  },
  "notes": [
    {
      "key": "reason",
      "text": "Venda de mercadoria"
    }
  ]
}

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	"$regime": "BR",
	"$addons": [
		"br-nfe-v4"
	],
	"type": "standard",
	"series": "1",
	"issue_date": "2026-07-08",
	"currency": "BRL",
	"tax": {
		"ext": {
			"br-nfe-model": "55",
			"br-nfe-operation-type": "1",
			"br-nfe-presence": "1",
			"br-nfe-purpose": "1"
		}
	},
	"supplier": {
		"name": "Marcenaria Arte \u0026 Design ME",
		"tax_id": {
			"country": "BR",
			"code": "21586733000120"
		},
		"identities": [
			{
				"key": "br-nfe-state-reg",
				"code": "0623458900"
			}
		],
		"addresses": [
			{
				"num": "85",
				"street": "Rua dos Artesãos",
				"locality": "Savassi",
				"region": "Minas Gerais",
				"state": "MG",
				"code": "30140-071",
				"country": "BR"
			}
		],
		"emails": [
			{
				"addr": "[e-mail]"
			}
		],
		"ext": {
			"br-ibge-municipality": "3106200",
			"br-nfe-regime": "1"
		}
	},
	"customer": {
		"name": "Comércio de Móveis Paulista Ltda.",
		"tax_id": {
			"country": "BR",
			"code": "33944792000101"
		},
		"addresses": [
			{
				"num": "742",
				"street": "Avenida Paulista",
				"locality": "Bela Vista",
				"region": "São Paulo",
				"state": "SP",
				"code": "01310-100",
				"country": "BR"
			}
		],
		"ext": {
			"br-ibge-municipality": "3550308"
		}
	},
	"lines": [
		{
			"i": 1,
			"quantity": "5",
			"item": {
				"name": "Mesa de Jantar em Madeira Maciça",
				"identities": [
					{
						"key": "ncm",
						"code": "94036000"
					}
				],
				"price": "900.00"
			},
			"sum": "4500.00",
			"taxes": [
				{
					"cat": "ICMS",
					"percent": "2.56%",
					"ext": {
						"br-nfe-icms-csosn": "101",
						"br-nfe-icms-origin": "0"
					}
				},
				{
					"cat": "PIS",
					"percent": "0%",
					"ext": {
						"br-nfe-pis-cst": "49"
					}
				},
				{
					"cat": "COFINS",
					"percent": "0%",
					"ext": {
						"br-nfe-cofins-cst": "49"
					}
				}
			],
			"total": "4500.00",
			"ext": {
				"br-nfe-cfop": "6102"
			}
		}
	],
	"payment": {
		"instructions": {
			"key": "credit-transfer",
			"ext": {
				"br-nfe-payment-means": "18"
			}
		}
	},
	"totals": {
		"sum": "4500.00",
		"total": "4500.00",
		"taxes": {
			"categories": [
				{
					"code": "ICMS",
					"informative": true,
					"rates": [
						{
							"ext": {
								"br-nfe-icms-csosn": "101",
								"br-nfe-icms-origin": "0"
							},
							"base": "4500.00",
							"percent": "2.56%",
							"amount": "115.20"
						}
					],
					"amount": "115.20"
				},
				{
					"code": "PIS",
					"informative": true,
					"rates": [
						{
							"ext": {
								"br-nfe-pis-cst": "49"
							},
							"base": "4500.00",
							"percent": "0%",
							"amount": "0.00"
						}
					],
					"amount": "0.00"
				},
				{
					"code": "COFINS",
					"informative": true,
					"rates": [
						{
							"ext": {
								"br-nfe-cofins-cst": "49"
							},
							"base": "4500.00",
							"percent": "0%",
							"amount": "0.00"
						}
					],
					"amount": "0.00"
				}
			],
			"sum": "0.00"
		},
		"tax": "0.00",
		"total_with_tax": "4500.00",
		"payable": "4500.00"
	},
	"notes": [
		{
			"key": "reason",
			"text": "Venda de mercadoria"
		}
	]
}

Example NF-e for a full goods return

In this example, we’re issuing a NF-e that fully returns the goods of a previously issued B2B product invoice — a devolução total under the pre-reform (pre-RTC) rules.

Notice the differences from a standard product invoice:

• the document type is credit-note; it keeps the br-nfe-v4 addon and is still issued as an NF-e, so br-nfe-model is derived as 55,
• a preceding entry references the original NF-e and carries its SEFAZ access key (chave de acesso) as a stamp — you can copy it from the sefaz-key entry in the stamps array of the original invoice’s envelope head, where it was added once the tax authority authorized the document,
• because this is a full return, the br-nfe-purpose extension is set to 4 (Goods Return) and the br-nfe-operation-type extension to 0 (Inbound / Entrada), since the returned goods re-enter the supplier; standard invoices set these automatically to 1 (normal) and 1 (outbound), but corrective documents must set both explicitly,
• no br-nfe-credit-note-type extension is used: that field only applies to post-reform IBS/CBS credit notes (those set br-nfe-purpose to 5),
• the line br-nfe-cfop is a return code — 2202 (Devolução de venda de mercadoria adquirida ou recebida de terceiros) — mirroring the original 6102 sale but recorded as an inbound inter-state operation (CFOP starting with 2),
• the payment sets the br-nfe-payment-means extension to 90 (No payment), as a return does not involve a new payment,
• there are no totals or calculations; all these will be made automatically when uploading, and,
• make sure to process it with the “DF-e issue product invoice (NF-e)” workflow created during setup.

Credit Note — Full Return (NF-e)

{
  "$schema": "https://gobl.org/draft-0/bill/invoice",
  "$addons": [
    "br-nfe-v4"
  ],
  "type": "credit-note",
  "series": "1",
  "issue_date": "2024-11-20",
  "tax": {
    "ext": {
      "br-nfe-presence": "1",
      "br-nfe-purpose": "4",
      "br-nfe-operation-type": "0"
    }
  },
  "preceding": [
    {
      "type": "standard",
      "series": "1",
      "code": "1",
      "issue_date": "2024-11-15",
      "stamps": [
        {
          "prv": "sefaz-key",
          "val": "35241105229829000184550010000000011000000019"
        }
      ]
    }
  ],
  "supplier": {
    "name": "TechNova Soluções Digitais Ltda.",
    "tax_id": {
      "country": "BR",
      "code": "05229829000184"
    },
    "identities": [
      {
        "key": "br-nfe-state-reg",
        "code": "12345678901234"
      }
    ],
    "addresses": [
      {
        "num": "101",
        "street": "Avenida Paulista",
        "locality": "Bela Vista",
        "region": "São Paulo",
        "state": "SP",
        "code": "01311-000",
        "country": "BR"
      }
    ],
    "emails": [
      {
        "addr": "[e-mail]"
      }
    ],
    "ext": {
      "br-ibge-municipality": "3550308"
    }
  },
  "customer": {
    "name": "Construforte Engenharia Ltda.",
    "tax_id": {
      "country": "BR",
      "code": "46602178000103"
    },
    "addresses": [
      {
        "num": "75",
        "street": "Avenida Sete de Setembro",
        "street_extra": "Bloco C",
        "locality": "Centro",
        "region": "Salvador",
        "state": "BA",
        "code": "40060-000",
        "country": "BR"
      }
    ],
    "ext": {
      "br-ibge-municipality": "2927408"
    }
  },
  "lines": [
    {
      "quantity": "10",
      "item": {
        "name": "Cabo USB-C 2 metros",
        "price": "28.90",
        "identities": [
          {
            "key": "ncm",
            "code": "85444290"
          }
        ]
      },
      "taxes": [
        {
          "cat": "ICMS",
          "percent": "12.0%"
        },
        {
          "cat": "PIS",
          "percent": "1.65%"
        },
        {
          "cat": "COFINS",
          "percent": "7.60%"
        }
      ],
      "ext": {
        "br-nfe-cfop": "2202"
      }
    }
  ],
  "payment": {
    "instructions": {
      "key": "other",
      "ext": {
        "br-nfe-payment-means": "90"
      }
    }
  },
  "notes": [
    {
      "key": "reason",
      "text": "Devolução total de mercadoria"
    }
  ]
}

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	"$regime": "BR",
	"$addons": [
		"br-nfe-v4"
	],
	"type": "credit-note",
	"series": "1",
	"issue_date": "2024-11-20",
	"currency": "BRL",
	"preceding": [
		{
			"type": "standard",
			"issue_date": "2024-11-15",
			"series": "1",
			"code": "1",
			"stamps": [
				{
					"prv": "sefaz-key",
					"val": "35241105229829000184550010000000011000000019"
				}
			]
		}
	],
	"tax": {
		"ext": {
			"br-nfe-model": "55",
			"br-nfe-operation-type": "0",
			"br-nfe-presence": "1",
			"br-nfe-purpose": "4"
		}
	},
	"supplier": {
		"name": "TechNova Soluções Digitais Ltda.",
		"tax_id": {
			"country": "BR",
			"code": "05229829000184"
		},
		"identities": [
			{
				"key": "br-nfe-state-reg",
				"code": "12345678901234"
			}
		],
		"addresses": [
			{
				"num": "101",
				"street": "Avenida Paulista",
				"locality": "Bela Vista",
				"region": "São Paulo",
				"state": "SP",
				"code": "01311-000",
				"country": "BR"
			}
		],
		"emails": [
			{
				"addr": "[e-mail]"
			}
		],
		"ext": {
			"br-ibge-municipality": "3550308",
			"br-nfe-regime": "3"
		}
	},
	"customer": {
		"name": "Construforte Engenharia Ltda.",
		"tax_id": {
			"country": "BR",
			"code": "46602178000103"
		},
		"addresses": [
			{
				"num": "75",
				"street": "Avenida Sete de Setembro",
				"street_extra": "Bloco C",
				"locality": "Centro",
				"region": "Salvador",
				"state": "BA",
				"code": "40060-000",
				"country": "BR"
			}
		],
		"ext": {
			"br-ibge-municipality": "2927408"
		}
	},
	"lines": [
		{
			"i": 1,
			"quantity": "10",
			"item": {
				"name": "Cabo USB-C 2 metros",
				"identities": [
					{
						"key": "ncm",
						"code": "85444290"
					}
				],
				"price": "28.90"
			},
			"sum": "289.00",
			"taxes": [
				{
					"cat": "ICMS",
					"percent": "12.0%",
					"ext": {
						"br-nfe-icms-cst": "00",
						"br-nfe-icms-origin": "0"
					}
				},
				{
					"cat": "PIS",
					"percent": "1.65%",
					"ext": {
						"br-nfe-pis-cst": "01"
					}
				},
				{
					"cat": "COFINS",
					"percent": "7.60%",
					"ext": {
						"br-nfe-cofins-cst": "01"
					}
				}
			],
			"total": "289.00",
			"ext": {
				"br-nfe-cfop": "2202"
			}
		}
	],
	"payment": {
		"instructions": {
			"key": "other",
			"ext": {
				"br-nfe-payment-means": "90"
			}
		}
	},
	"totals": {
		"sum": "289.00",
		"total": "289.00",
		"taxes": {
			"categories": [
				{
					"code": "ICMS",
					"informative": true,
					"rates": [
						{
							"ext": {
								"br-nfe-icms-cst": "00",
								"br-nfe-icms-origin": "0"
							},
							"base": "289.00",
							"percent": "12.0%",
							"amount": "34.68"
						}
					],
					"amount": "34.68"
				},
				{
					"code": "PIS",
					"informative": true,
					"rates": [
						{
							"ext": {
								"br-nfe-pis-cst": "01"
							},
							"base": "289.00",
							"percent": "1.65%",
							"amount": "4.77"
						}
					],
					"amount": "4.77"
				},
				{
					"code": "COFINS",
					"informative": true,
					"rates": [
						{
							"ext": {
								"br-nfe-cofins-cst": "01"
							},
							"base": "289.00",
							"percent": "7.60%",
							"amount": "21.96"
						}
					],
					"amount": "21.96"
				}
			],
			"sum": "0.00"
		},
		"tax": "0.00",
		"total_with_tax": "289.00",
		"payable": "289.00"
	},
	"notes": [
		{
			"key": "reason",
			"text": "Devolução total de mercadoria"
		}
	]
}

Example B2C consumer invoice (NFC-e)

In this example, we’re issuing a simple consumer invoice (NFC-e) from a Brazilian supplier.

Notice:

• we’ve added the br-nfe-v4 addon with the simplified tag; this sets the br-nfe-model extension to 65 (NFC-e),
• the customer is optional and in this example we’ve omitted it,
• extensions (ext) and identities have been used in multiple locations for fields whose values cannot be determined any other way,
• the payment instructions key is set to card, which causes the br-nfe-payment-means extension to be set automatically to 03 (cartão de crédito),
• tax percentages are provided explicitly as they vary depending on the state and type of goods,
• there are no totals or calculations; all these will be made automatically when uploading, and,
• make sure to process it with the “DF-e issue consumer invoice (NFC-e)” workflow created during setup.

B2C Consumer Invoice (NFC-e)

{
  "$schema": "https://gobl.org/draft-0/bill/invoice",
  "$addons": [
    "br-nfe-v4"
  ],
  "$tags": [
    "simplified"
  ],
  "series": "123",
  "tax": {
    "ext": {
      "br-nfe-presence": "1"
    }
  },
  "supplier": {
    "name": "TechNova Soluções Digitais Ltda.",
    "tax_id": {
      "country": "BR",
      "code": "05229829000184"
    },
    "identities": [
      {
        "key": "br-nfe-state-reg",
        "code": "12345678901234"
      }
    ],
    "addresses": [
      {
        "num": "101",
        "street": "Avenida Paulista",
        "locality": "Bela Vista",
        "region": "São Paulo",
        "state": "SP",
        "code": "01311-000",
        "country": "BR"
      }
    ],
    "emails": [
      {
        "addr": "[e-mail]"
      }
    ],
    "ext": {
      "br-ibge-municipality": "3550308",
      "br-nfse-simples": "1"
    }
  },
  "lines": [
    {
      "quantity": "2",
      "item": {
        "name": "Cabo USB-C 2 metros",
        "price": "28.90"
      },
      "taxes": [
        {
          "cat": "ICMS",
          "percent": "18.0%"
        },
        {
          "cat": "PIS",
          "percent": "1.65%"
        },
        {
          "cat": "COFINS",
          "percent": "7.60%"
        }
      ]
    }
  ],
  "payment": {
    "instructions": {
      "key": "card"
    }
  },
  "notes": [
    {
      "key": "reason",
      "text": "Venda de mercadoria"
    }
  ]
}

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	"$regime": "BR",
	"$addons": [
		"br-nfe-v4"
	],
	"$tags": [
		"simplified"
	],
	"type": "standard",
	"series": "123",
	"issue_date": "2026-07-08",
	"currency": "BRL",
	"tax": {
		"ext": {
			"br-nfe-model": "65",
			"br-nfe-operation-type": "1",
			"br-nfe-presence": "1",
			"br-nfe-purpose": "1"
		}
	},
	"supplier": {
		"name": "TechNova Soluções Digitais Ltda.",
		"tax_id": {
			"country": "BR",
			"code": "05229829000184"
		},
		"identities": [
			{
				"key": "br-nfe-state-reg",
				"code": "12345678901234"
			}
		],
		"addresses": [
			{
				"num": "101",
				"street": "Avenida Paulista",
				"locality": "Bela Vista",
				"region": "São Paulo",
				"state": "SP",
				"code": "01311-000",
				"country": "BR"
			}
		],
		"emails": [
			{
				"addr": "[e-mail]"
			}
		],
		"ext": {
			"br-ibge-municipality": "3550308",
			"br-nfe-regime": "3",
			"br-nfse-simples": "1"
		}
	},
	"lines": [
		{
			"i": 1,
			"quantity": "2",
			"item": {
				"name": "Cabo USB-C 2 metros",
				"price": "28.90"
			},
			"sum": "57.80",
			"taxes": [
				{
					"cat": "ICMS",
					"percent": "18.0%",
					"ext": {
						"br-nfe-icms-cst": "00",
						"br-nfe-icms-origin": "0"
					}
				},
				{
					"cat": "PIS",
					"percent": "1.65%",
					"ext": {
						"br-nfe-pis-cst": "01"
					}
				},
				{
					"cat": "COFINS",
					"percent": "7.60%",
					"ext": {
						"br-nfe-cofins-cst": "01"
					}
				}
			],
			"total": "57.80"
		}
	],
	"payment": {
		"instructions": {
			"key": "card",
			"ext": {
				"br-nfe-payment-means": "03"
			}
		}
	},
	"totals": {
		"sum": "57.80",
		"total": "57.80",
		"taxes": {
			"categories": [
				{
					"code": "ICMS",
					"informative": true,
					"rates": [
						{
							"ext": {
								"br-nfe-icms-cst": "00",
								"br-nfe-icms-origin": "0"
							},
							"base": "57.80",
							"percent": "18.0%",
							"amount": "10.40"
						}
					],
					"amount": "10.40"
				},
				{
					"code": "PIS",
					"informative": true,
					"rates": [
						{
							"ext": {
								"br-nfe-pis-cst": "01"
							},
							"base": "57.80",
							"percent": "1.65%",
							"amount": "0.95"
						}
					],
					"amount": "0.95"
				},
				{
					"code": "COFINS",
					"informative": true,
					"rates": [
						{
							"ext": {
								"br-nfe-cofins-cst": "01"
							},
							"base": "57.80",
							"percent": "7.60%",
							"amount": "4.39"
						}
					],
					"amount": "4.39"
				}
			],
			"sum": "0.00"
		},
		"tax": "0.00",
		"total_with_tax": "57.80",
		"payable": "57.80"
	},
	"notes": [
		{
			"key": "reason",
			"text": "Venda de mercadoria"
		}
	]
}

Party documents:

DF-e Brazil supplier

A CNPJ with the municipal and state registrations, IBGE municipality code, and Simples Nacional flag used by the DF-e flows.

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": "[e-mail]"
        }
    ],
    "ext": {
        "br-ibge-municipality": "3550308",
        "br-nfse-simples": "1"
    }
}

DF-e Brazil customer

A business customer with CNPJ, full address including state, and IBGE municipality code.

Brazil customer example

{
    "$schema": "https://gobl.org/draft-0/org/party",
    "name": "Comércio Aurora Ltda.",
    "tax_id": {
        "country": "BR",
        "code": "12345678000195"
    },
    "addresses": [
        {
            "num": "250",
            "street": "Rua das Laranjeiras",
            "locality": "Laranjeiras",
            "region": "Rio de Janeiro",
            "state": "RJ",
            "code": "22240-006",
            "country": "BR"
        }
    ],
    "emails": [
        {
            "addr": "[e-mail]"
        }
    ],
    "ext": {
        "br-ibge-municipality": "3304557"
    }
}

---

🇧🇷 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 Documentos Fiscais Eletrônicos Brazil App →