Skip to content

Update BR docs to extended simples nacional #511

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cavalle merged 2 commits into from
Jul 29, 2026
Merged

Update BR docs to extended simples nacional #511

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cc809f5
Update BR docs to extended simples nacional
cavalle Jul 29, 2026
8dcf42f
Correct grammar
cavalle Jul 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions guides/br-dfe-supplier.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,12 @@ Find the **Parties** section of the sidebar and click **Suppliers**. Tap the **+

<Supplier />

<Info>
The `br-nfse-` identities and extensions configure service invoices (NFS-e), while the `br-nfe-` ones configure product and consumer invoices (NF-e/NFC-e) — omit the family the supplier won't issue.

See the [`br-nfse-v1`](https://docs.gobl.org/addons/br-nfse-v1) and [`br-nfe-v4`](https://docs.gobl.org/addons/br-nfe-v4) addons for the possible values.
</Info>

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**.
Expand Down
27 changes: 26 additions & 1 deletion snippets/invoices/br/accordion.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ import ServiceInvoiceRTCMin from '/snippets/invoices/br/dfe-service-invoice-rtc.
import ServiceInvoiceRTC from '/snippets/invoices/br/dfe-service-invoice-rtc.mdx';
import ConsumerInvoiceMin from '/snippets/invoices/br/dfe-consumer-invoice.min.mdx';
import ConsumerInvoice from '/snippets/invoices/br/dfe-consumer-invoice.mdx';
import ConsumerInvoiceSimplesMin from '/snippets/invoices/br/dfe-consumer-invoice-simples.min.mdx';
import ConsumerInvoiceSimples from '/snippets/invoices/br/dfe-consumer-invoice-simples.mdx';
import ProductInvoiceMin from '/snippets/invoices/br/dfe-product-invoice.min.mdx';
import ProductInvoice from '/snippets/invoices/br/dfe-product-invoice.mdx';
import ProductInvoiceSimplesMin from '/snippets/invoices/br/dfe-product-invoice-simples.min.mdx';
Expand Down Expand Up @@ -79,8 +81,10 @@ import CreditNote from '/snippets/invoices/br/dfe-credit-note.mdx';

Notice the differences from the previous example:

- the supplier declares its regime with the [`br-nfe-regime`](https://docs.gobl.org/addons/br-nfe-v4#tax-regime-code) extension set to `1` (_Simples Nacional_); use `2` for _Simples Nacional, Excess_ or `4` for _MEI_ — omitting it defaults to `3` (normal regime),
- the supplier declares its regime with the [`br-nfe-regime`](https://docs.gobl.org/addons/br-nfe-v4#tax-regime-code) extension set to `1` (_Simples Nacional_); `4` (_MEI_) behaves the same, while `2` (_Simples Nacional, Excess_) uses CST codes like the normal regime (`3`, the default),
- each ICMS line carries the [`br-nfe-icms-csosn`](https://docs.gobl.org/addons/br-nfe-v4#icms-simples-nacional-status-code-csosn) extension (here `101`, taxed with credit permission) instead of the `br-nfe-icms-cst` code that normal-regime issuers use,
- with CSOSN `101` the ICMS `percent` is not a charged tax: it represents the _Simples Nacional_ credit rate (`pCredSN` in the NF-e XML) and the resulting amount becomes the credit value the buyer may take (`vCredICMSSN`),
- CSOSN `101` transfers a tax credit and is only accepted when the customer is an ICMS taxpayer, so the customer includes a `br-nfe-state-reg` identity with its state registration number,
- 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`](https://docs.gobl.org/addons/br-nfe-v4#pis-tax-status-code-cst) and [`br-nfe-cofins-cst`](https://docs.gobl.org/addons/br-nfe-v4#cofins-tax-status-code-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.
Expand Down Expand Up @@ -121,6 +125,7 @@ import CreditNote from '/snippets/invoices/br/dfe-credit-note.mdx';
- we've added the [`br-nfe-v4`](https://docs.gobl.org/addons/br-nfe-v4) addon with the `simplified` tag; this sets the [`br-nfe-model`](https://docs.gobl.org/addons/br-nfe-v4#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,
- each line must include a [`br-nfe-cfop`](https://docs.gobl.org/addons/br-nfe-v4#cfop-fiscal-operations-and-services-code) extension to classify the fiscal operation, just as on an NF-e,
- the payment instructions key is set to `card`, which causes the [`br-nfe-payment-means`](https://docs.gobl.org/addons/br-nfe-v4#payment-method) 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,
Expand All @@ -132,4 +137,24 @@ import CreditNote from '/snippets/invoices/br/dfe-credit-note.mdx';
</CodeGroup>
</Accordion>

<Accordion title="Example B2C consumer invoice for a Simples Nacional issuer (NFC-e)">

In this example, we're issuing a consumer invoice (NFC-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`](https://docs.gobl.org/addons/br-nfe-v4#tax-regime-code) extension set to `1` (_Simples Nacional_),
- ICMS carries the [`br-nfe-icms-csosn`](https://docs.gobl.org/addons/br-nfe-v4#icms-simples-nacional-status-code-csosn) extension set to `102` (taxed without credit permission) with a `0%` percent,
- PIS and COFINS use the [`br-nfe-pis-cst`](https://docs.gobl.org/addons/br-nfe-v4#pis-tax-status-code-cst) and [`br-nfe-cofins-cst`](https://docs.gobl.org/addons/br-nfe-v4#cofins-tax-status-code-cst) extensions set to `49` (other operations) at a `0%` rate,
- the line carries a [`br-nfe-cfop`](https://docs.gobl.org/addons/br-nfe-v4#cfop-fiscal-operations-and-services-code) extension set to `5102`,
- all of these fields must be set explicitly (i.e., you have them in the minimal example), since the automatic defaults are the normal-regime ones: an ICMS line that omits the CSOSN fails validation, while an omitted PIS or COFINS CST silently falls back to `01`,
- 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.

<CodeGroup>
<ConsumerInvoiceSimplesMin />
<ConsumerInvoiceSimples />
</CodeGroup>
</Accordion>

</AccordionGroup>
169 changes: 169 additions & 0 deletions snippets/invoices/br/dfe-consumer-invoice-simples.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,169 @@
```json Built version
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
"$regime": "BR",
"$addons": [
"br-nfe-v4"
],
"$tags": [
"simplified"
],
"type": "standard",
"series": "123",
"issue_date": "2026-07-28",
"currency": "BRL",
"tax": {
"ext": {
"br-nfe-model": "65",
"br-nfe-operation-type": "1",
"br-nfe-presence": "1",
"br-nfe-purpose": "1"
}
},
"supplier": {
"name": "Drogaria Vida Saudável Ltda.",
"tax_id": {
"country": "BR",
"code": "55263640000186"
},
"identities": [
{
"key": "br-nfe-state-reg",
"code": "35503304557308"
}
],
"addresses": [
{
"num": "200",
"street": "Rua Primeiro de Março",
"street_extra": "Torre A",
"locality": "Centro",
"region": "Rio de Janeiro",
"state": "RJ",
"code": "20010-000",
"country": "BR"
}
],
"emails": [
{
"addr": "saudemais@example.com"
}
],
"ext": {
"br-ibge-municipality": "3304557",
"br-nfe-regime": "1"
}
},
"lines": [
{
"i": 1,
"quantity": "2",
"item": {
"name": "Caixa de Máscaras Cirúrgicas",
"price": "10.00"
},
"sum": "20.00",
"taxes": [
{
"cat": "ICMS",
"percent": "0%",
"ext": {
"br-nfe-icms-csosn": "102",
"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": "20.00",
"ext": {
"br-nfe-cfop": "5102"
}
}
],
"payment": {
"instructions": {
"key": "card",
"ext": {
"br-nfe-payment-means": "03"
}
}
},
"totals": {
"sum": "20.00",
"total": "20.00",
"taxes": {
"categories": [
{
"code": "ICMS",
"informative": true,
"rates": [
{
"ext": {
"br-nfe-icms-csosn": "102",
"br-nfe-icms-origin": "0"
},
"base": "20.00",
"percent": "0%",
"amount": "0.00"
}
],
"amount": "0.00"
},
{
"code": "PIS",
"informative": true,
"rates": [
{
"ext": {
"br-nfe-pis-cst": "49"
},
"base": "20.00",
"percent": "0%",
"amount": "0.00"
}
],
"amount": "0.00"
},
{
"code": "COFINS",
"informative": true,
"rates": [
{
"ext": {
"br-nfe-cofins-cst": "49"
},
"base": "20.00",
"percent": "0%",
"amount": "0.00"
}
],
"amount": "0.00"
}
],
"sum": "0.00"
},
"tax": "0.00",
"total_with_tax": "20.00",
"payable": "20.00"
},
"notes": [
{
"key": "reason",
"text": "Venda de mercadoria"
}
]
}
```
98 changes: 98 additions & 0 deletions snippets/invoices/br/dfe-consumer-invoice-simples.min.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
```json B2C Consumer Invoice — Simples Nacional (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": "Drogaria Vida Saudável Ltda.",
"tax_id": {
"country": "BR",
"code": "55263640000186"
},
"identities": [
{
"key": "br-nfe-state-reg",
"code": "35503304557308"
}
],
"addresses": [
{
"num": "200",
"street": "Rua Primeiro de Março",
"street_extra": "Torre A",
"locality": "Centro",
"region": "Rio de Janeiro",
"state": "RJ",
"code": "20010-000",
"country": "BR"
}
],
"emails": [
{
"addr": "saudemais@example.com"
}
],
"ext": {
"br-ibge-municipality": "3304557",
"br-nfe-regime": "1"
}
},
"lines": [
{
"quantity": "2",
"item": {
"name": "Caixa de Máscaras Cirúrgicas",
"price": "10.00"
},
"taxes": [
{
"cat": "ICMS",
"percent": "0%",
"ext": {
"br-nfe-icms-csosn": "102",
"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"
}
}
],
"ext": {
"br-nfe-cfop": "5102"
}
}
],
"payment": {
"instructions": {
"key": "card"
}
},
"notes": [
{
"key": "reason",
"text": "Venda de mercadoria"
}
]
}
```
7 changes: 5 additions & 2 deletions snippets/invoices/br/dfe-consumer-invoice.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
],
"type": "standard",
"series": "123",
"issue_date": "2026-07-08",
"issue_date": "2026-07-28",
"currency": "BRL",
"tax": {
"ext": {
Expand Down Expand Up @@ -87,7 +87,10 @@
}
}
],
"total": "57.80"
"total": "57.80",
"ext": {
"br-nfe-cfop": "5102"
}
}
],
"payment": {
Expand Down
5 changes: 4 additions & 1 deletion snippets/invoices/br/dfe-consumer-invoice.min.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,10 @@
"cat": "COFINS",
"percent": "7.60%"
}
]
],
"ext": {
"br-nfe-cfop": "5102"
}
}
],
"payment": {
Expand Down
8 changes: 7 additions & 1 deletion snippets/invoices/br/dfe-product-invoice-simples.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
],
"type": "standard",
"series": "1",
"issue_date": "2026-07-08",
"issue_date": "2026-07-28",
"currency": "BRL",
"tax": {
"ext": {
Expand Down Expand Up @@ -56,6 +56,12 @@
"country": "BR",
"code": "33944792000101"
},
"identities": [
{
"key": "br-nfe-state-reg",
"code": "112233445566"
}
],
"addresses": [
{
"num": "742",
Expand Down
Loading