Documentos fiscais electrônicos Brazil

Send NFC-e & NFS-e documents to the tax authorities in Brazil via Plugnotas.

Description

Documentos Fiscais Eletrônicos Brazil

View implementation 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 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 and NFC-e Support: Issue B2B and B2C invoices for service and consumer transactions.

Make sure to check out our Documentos Fiscais Eletrônicos Guide for instructions on how to issue invoices, register suppliers, and set 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 CF-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.

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.

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
ext.br-ibge-municipality	✅	7-digit IBGE municipality code

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

Field	Required	Notes
tax_id.country	✅	"BR"
tax_id.code	✅	CNPJ or CPF
addresses	✅
ext.br-ibge-municipality	✅	Required when addresses are present

Line items

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

Optional item extensions: item.ext.br-nfe-cfop, 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 (Brazil)

Send NFC-e (Brazil)

Register DF-e supplier (Brazil)

Register suppliers to issue electronic fiscal documents on their behalf.

Workflows

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

DF-e issue service invoice (NFS-e)

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

Example DF-e issue service invoice (NFS-e) workflow

{
    "name": "DF-e issue service invoice (NFS-e)",
    "description": "Issue a NFS-e invoice in Brazil",
    "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 (Brazil)",
            "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 consumer invoice (NFC-e)

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

Example DF-e issue consumer invoice (NFC-e) workflow

{
    "name": "DF-e issue consumer invoice (NFC-e)",
    "description": "Issue a NFC-e invoice in Brazil",
    "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 (Brazil)",
            "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 →

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 “Issue 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%"
        }
      ]
    }
  ]
}

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

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-v1 addon; this ensures the document will be validated using the NF-e/NFC-e rules built into the GOBL library,
• 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,
• 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 “Issue 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"
    }
  ]
}

Supplier documents:

DF-e Brazil Supplier

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

---

🇧🇷 Invopop resources for Brazil

Compliance	Invoicing compliance in Brazil Compliance timeline
Apps	Documentos Fiscais Eletrônicos Brazil
Guides	DFE Brazil Guide
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 →