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

# Brazil FAQ

> Frequently asked questions about invoicing compliance in Brazil

### Compliance questions

**Brazil**

<AccordionGroup>
  <Accordion title="Issuing B2C invoices is mandatory in Brazil?">
    Yes, all transaction are mandatory in Brazil.
  </Accordion>

  <Accordion title="Who can issue invoices in Brazil?">
    Any entity with a CNPJ (legal entity) or CPF (individual) registered in Brazil. State and municipal registrations (Inscrição Estadual / Municipal) are also required depending on whether the supplier issues NF-e (state) or NFS-e (municipal) documents.
  </Accordion>
</AccordionGroup>

**NF-e**

<AccordionGroup>
  <Accordion title="What are the NF-e mandate timelines in Brazil?">
    NF-e (model 55) for goods has been mandatory since 2008 — phased in by sector and turnover. NFC-e (model 65, retail B2C) replaced the paper Cupom Fiscal in most states between 2014 and 2020. Both are now required for any commercial circulation of goods.
  </Accordion>

  <Accordion title="Are there special supplier obligations under NF-e?">
    The supplier needs an active state Inscrição Estadual, a CNAE that authorizes goods circulation, and an A1 certificate matching the issuing CNPJ. Some states (SP, RJ, MG) require additional credenciamento before NF-e issuance.
  </Accordion>
</AccordionGroup>

**NFS-e**

<AccordionGroup>
  <Accordion title="How does ISS tax work in Brazil?">
    ISS (Imposto Sobre Serviços) is not treated as a standard transactional tax calculated on top of a net amount. Instead, it is an **informative tax embedded in the final price**—the invoice only reports what portion of the total corresponds to ISS.

    In GOBL, ISS is flagged as an "informative" tax category. This means:

    * ISS must be added to the GOBL invoice like any other tax, with the proper percentage.
    * The tax amount is not added to the price; it represents the portion of the total that corresponds to ISS.
    * The NFS-e document displays ISS as informational data, reflecting what was already embedded in the final price.
    * **Do not use `prices_include` with ISS**—since ISS is informative, it should not be treated as a price-inclusive tax.
  </Accordion>

  <Accordion title="Should I change my integration for the 2026 NFS-e federal tax format regulation?">
    It is not necessary, any fields pertaining to the previous municipal tax implementation will be ignored and the invoice will already have all the data to be compliant. However, it is always recommended to remove ignored fields to avoid confusion and keep your documents clean.
  </Accordion>

  <Accordion title="What are the issuer requirements under NFS-e?">
    NFS-e is municipal, so the supplier needs an Inscrição Municipal in every município where they invoice services. Special tax regimes (Simples Nacional, MEI, ISS estimado) impose additional fields and rates.
  </Accordion>
</AccordionGroup>

### Invoicing questions

**Brazil**

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

  <Accordion title="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](https://docs.gobl.org/regimes/br).
    * The [NFS-e Addon GOBL Reference](https://docs.gobl.org/addons/br-nfse-v1).
    * The [NF-e Addon GOBL Reference](https://docs.gobl.org/addons/br-nfe-v4).
  </Accordion>
</AccordionGroup>

**NF-e**

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

    ```json theme={"system"}
    "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"
        }
      ]
    }
    ```
  </Accordion>

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

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

    ```json theme={"system"}
    "stamps": [
      { "provider": "sefaz-key", "value": "35240114200166000187550010000000071123456789" },
      { "provider": "sefaz-auth", "value": "135240000123456" }
    ]
    ```
  </Accordion>

  <Accordion title="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 <br /> ⬜ 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        | ✅         | ❌          |

    ```json theme={"system"}
    "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 <br /> ⬜ 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"`.
  </Accordion>
</AccordionGroup>

**NFS-e**

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

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

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

### Registering supplier questions

**Brazil**

<AccordionGroup>
  <Accordion title="How do I onboard a new supplier in Brazil?">
    Upload the supplier's A1 digital certificate (PFX or P12) plus password through the registration workflow. Invopop validates it against the relevant SEFAZ or municipal endpoint and activates the supplier for issuing.
  </Accordion>

  <Accordion title="How are supplier credentials stored in Invopop for Brazil?">
    A1 certificates (X.509 + private key, exported as PKCS#12) and their passwords are stored encrypted. Invopop uses them to sign documents and authenticate to the relevant SEFAZ or municipal endpoint on the supplier's behalf.
  </Accordion>
</AccordionGroup>

**NF-e**

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

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

**NFS-e**

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

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

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