Brazil¶
See also
Helpful resources for the Brazilian localization, including onboarding materials and videos:
Modules¶
The following modules are installed automatically with the Brazilian localization:
Name |
Technical name |
Description |
|---|---|---|
Brazilian - Accounting |
|
Default fiscal localization package, which represents having the Generic Brazilian chart of accounts and Taxes, together with document types and identification types. |
Brazil - Accounting Reports |
|
Accounting reports for Brazil. |
Brazil Pix QR codes |
|
Implements Pix QR codes for Brazil. |
Brazil - Sale Subscription |
|
Subscriptions modifications for Brazil. |
Brazil - Sale |
|
Sales modifications for Brazil. |
Brazil - Website Sale |
|
Allows tax calculation and EDI for eCommerce. |
Additionally, the following modules must be manually installed:
Name |
Technical name |
Description |
|---|---|---|
Avatax Brazil & Avatax Brazil for Services & Test SOs for the Brazilian Avatax |
|
Goods and services tax computation through Avalara. |
Avatax Brazil eCommerce Fiscal Reform |
|
eCommerce modifications for the 2026 tax reform. |
Avatax Brazil Fiscal Reform |
|
Avatax modifications for the 2026 tax reform. |
Avatax Brazil Sale Fiscal Reform |
|
Sales Avatax modifications for the 2026 tax reform |
Avatax Brazil Sale for Services |
|
Sales modifications for Brazil for services |
Brazilian Accounting EDI & Brazilian Accounting EDI for services |
|
Provides electronic invoicing for goods and services for Brazil through AvaTax. |
Brazilian Accounting EDI For Sale |
|
Adds fields to sales orders that will be carried over to the invoice. |
Note
In some cases, such as when upgrading to a version with additional modules, it is possible that modules may not be installed automatically. Any missing modules can be manually installed.
Localization overview¶
The Brazilian localization package ensures compliance with Brazilian fiscal and accounting regulations. It includes tools for managing taxes, fiscal positions, reporting, and a predefined chart of accounts tailored to Brazil’s standards.
The Brazilian localization package provides the following key features to ensure compliance with local fiscal and accounting regulations:
Chart of accounts: a predefined structure tailored to Brazilian accounting standards
Taxes: pre-configured tax rates, including standard VAT, zero-rated, and exempt options.
Chart of accounts¶
In the chart of accounts, the accounts are mapped automatically to their corresponding taxes, and the default account payable and account receivable fields.
Note
The Brazil chart of accounts is based on the SPED CoA, which provides a baseline of the necessary accounts.
Taxes¶
Taxes are automatically created and configured when installing the Brazilian localization. Avalara uses some to compute taxes on sales orders or invoices.
Taxes used for services must be manually added and configured, as the rate may differ depending on the city where the service is offered.
Important
NFS-e can’t be issued for service taxes created manually. To electronically send an NFS-e, compute taxes using Avalara.
Warning
Do not delete taxes, as they are used for the AvaTax tax computation. If deleted, Odoo creates them again when used in an SO or invoice, computing taxes with AvaTax. However, the account used to register the tax must be reconfigured in the tax’s Definition tab, under the Distribution for invoices and Distribution for refunds sections.
Company and contacts¶
To use all the features of this fiscal localization, the following fields are required on the company record:
Name
Address: add City, State, Zip Code, Country
In the Street field, enter the street name, number, and any additional address information.
In the Street 2 field, enter the neighborhood.
Identification Number: CNPJ or CPF
Tax ID: associated with the identification type
IE: State registration
IM: Municipal registration
SUFRAMA code: Superintendence of the Manaus Free Trade Zone - add if applicable
Phone
Email
Tip
Select the Company option for a contact with a tax ID (CNPJ), or the Individual option for a contact with a CPF.
To update your company’s complete record, open the Contacts app and access the relevant record.
Configure the Fiscal Information within the Sales & Purchase tab:
Add the Fiscal Position for AvaTax Brazil.
Tax Regime: Federal tax regime.
ICMS Taxpayer Type: Select ICMS regime, Exempt status, or Non-Taxpayer.
Main Activity Sector
The following fields are specific to the 2026 tax reform:
Tax Regime: For the simplified tax regime (Simples Nacional), set up the additional fields:
CBS/IBS Normal: Enable the option for Regime Normal (Regime Regular) regime or disable for Hybrid Simples Nacional (Regime Hibrido) regime. For the Hybrid Simples Nacional (Regime Hibrido) tax regime, configure the following additional fields:
CBS Presumed Credit (%): Specify the percentage of presumed CBS credit available for entities under the Hybrid Simples Nacional tax regime.
IBS Presumed Credit (%): Specify the percentage of presumed IBS credit available for entities under the Hybrid Simples Nacional tax regime.
ISS Simplified Rate: Indicate the specific municipal service tax rate applicable to the simplified tax regime.
Entity Type: Select the legal classification.
CBS/IBS Taxpayer: Enable the option if the entity is subject to CBS or IBS. Disable it for exempt entities or those operating under special non-taxable regimes.
Configure the following extra Fiscal Information to issue NFS-e:
Add the Fiscal Position for AvaTax Brazil.
COFINS Details: Select the option that matches the correct COFINS tax status.
PIS Details: Select the option that matches the correct PIS tax status.
CSLL Taxable: Enable the option if the company is subject to CSLL.
Tip
If it is a simplified regime, the ICMS rate must be configured. To do so, go to , scroll down to the Taxes section, and set the Sales Tax and Purchase Tax fields in the Default Taxes section.
The same configuration applies to the relevant contact form when using the AvaTax integration.
AvaTax integration¶
Note
Make sure to install the AvaTax Brazil (
l10n_br_avatax) module.Odoo is a certified partner of Avalara Brazil.
The Avalara AvaTax integration uses In-App-Purchases (IAPs) to compute taxes and handle electronic documents (e.g., NF-e, NFS-e). Each action consumes credits from the IAP credit balance. On creation, new databases receive 500 free credits.
To compute the goods and services tax and process electronic invoices, the following configurations are needed:
Configuration¶
Credentials¶
Connect AvaTax in the AvaTax Brazil section, add the administrator’s email address for the AvaTax portal in the AvaTax Portal Email field, then click Create account.
Warning
When testing or creating a production AvaTax Portal Email integration in a sandbox or production database, use a real email address, as it is needed to connect to Avalara and set up the certificates, whether to test or use it on production.
There are two different Brazilian Avalara Portals:
One for testing: https://portal.sandbox.avalarabrasil.com.br/
One for production: https://portal.avalarabrasil.com.br/
When the account is created from Odoo, select the right environment. Moreover, the email used to open the account cannot be used to open another account. Save the API ID and API Key when the account is created from Odoo.
After the account is created from Odoo, go to the Avalara Portal to set up the password:
Access the Avalara portal.
Click Meu primeiro acesso.
Add the email address used in Odoo to create the Avalara/AvaTax account, and click Solicitar Senha.
An email will then be received with a token and a link to create a password. Click this link and copy-paste the token to set the desired password.
Tip
If you use AvaTax in Odoo for tax computation only, setting a password or accessing the Avalara portal is unnecessary. However, to use the electronic invoice service, access to AvaTax is needed, and the certificate must be uploaded.
Note
API credentials can be transferred. This option should be used only when an account has already been created in another Odoo instance and must be reused.
2026 tax reform¶
To enable the sending of the new attributes of the 2026 tax reform, go to , scroll to the Taxes section, and enable Enable Brazilian fiscal reform under AvaTax Brazil.
Tip
If inconsistencies occur when submitting invoices under the 2026 tax reform rules, disable the Enable Brazilian fiscal reform option to revert invoice transmission to the previous communication model.
A1 certificate upload¶
To issue electronic invoices, a certificate must be uploaded to the AvaTax portal.
The certificate will be synchronized with Odoo as long as the external identifier number in the AvaTax portal matches, without special characters, with the CNPJ number, and the identification number (CNPJ) in Odoo matches the CNPJ in AvaTax.
Important
Some cities require the certificate to be linked within the City Portal system before issuing NFS-e from Odoo.
If an error message from the city that says Your certificate is not linked to the user is received, this process needs to be done in the city portal.
Fiscal positions¶
To set up the Automatic Tax Mapping (Avalara Brazil) fiscal position, enable the Detect Automatically and Use AvaTax Brazil API options.
See also
Products¶
Accurate fiscal classification of goods and services is essential for tax calculation and electronic invoice issuance in compliance with the Brazilian regulations and the 2026 tax reform.
Note
Brazil must be specified as the Country field of the company to display the required Brazilian fields.
Make sure the following fields are completed on the General Information tab of the products form:
Legal Unit of Measure: Select the conversion factor between the commercial unit and the taxable unit for taxes applied by quantity (ad rem).
IS taxable: Enable this option if the product is subject to Selective Tax (Imposto Seletivo or IS).
Special Customs Regime (optional): Select the applicable special customs regime if the transaction involving capital goods falls under such a regime.
L10N Br Transaction Usage (optional): Define the tax classification indicating how the good or service is used in the transaction, as this can affect tax calculation and invoice issuance.
If the selected Product Type is Service, select the NBS Code (Nomenclatura Brasileira de Serviços) necessary for tax classification.
To use the AvaTax integration on sales orders and invoices, enter the following information on the product form, based on how the product will be used:
E-invoices for goods (NF-e)¶
Important
The Avalara integration works on a credit-based system, where each interaction with Avalara consumes one credit. Below are the main credit-consuming operations:
Sales application
Tax calculation on quotations and sales orders.
Accounting application
Tax calculation on invoices.
Electronic invoice submission (NF-e or NFS-e).
Occasional operations: (each step is billed separately)
Note
If taxes are calculated in the Sales app, and the invoice is later issued in the Accounting app, the calculation happens twice, consuming two credits.
Example
CEST Code: tax classification code identifying goods and products subject to tax substitution under ICMS regulations, and helps determine the applicable tax treatment and procedures for specific items. The product’s applicability to this requirement can be verified on the Código CEST website.
Mercosul NCM Code: Mercosur Common Nomenclature Product Code
Source of Origin: origin of the product, which can be foreign or domestic, among other possible options, depending on the specific use case
SPED Fiscal Product Type: fiscal product type according to the SPED list table
Purpose of Use: intended purpose of use for this product
Note
Odoo automatically creates three products to be used for transportation costs associated with sales. These are named Freight, Insurance, and Other Costs and are already configured. If more need to be created, duplicate and use the same configuration:
Product Type: Service
Transportation Cost Type: Insurance, Freight, or Other Costs
E-invoices for services (NFS-e)¶
Important
The Avalara integration works on a credit-based system, where each interaction with Avalara consumes one credit. Below are the main credit-consuming operations:
Sales application
Tax calculation on quotations and sales orders.
Accounting application
Tax calculation on invoices.
Electronic invoice submission (NF-e or NFS-e).
Invoice status check (1 credit is consumed each time the invoice status is checked).
Occasional operations: (each step is billed separately)
Note
If taxes are calculated in the Sales app and the invoice is later issued in the Accounting app, the calculation happens twice, consuming two credits.
Example
Mercosul NCM Code: Mercosur Common Nomenclature Product Code
Purpose of Use: intended purpose of use for this product
Service Code Origin: City Service Code where the provider is registered
Labor Assignment: checkbox to select if the service involves labor
Transport Cost Type: type of transport costs to select
Service Codes: City Service Code where the service will be provided; if no code is added, the Service Code Origin will be used.
Tax computation¶
See also
Tax calculations on quotations and sales orders¶
Trigger an API call to calculate taxes on a quotation or sales order automatically with AvaTax in any of the following ways:
- Quotation confirmation
Confirm a quotation into a sales order.
- Manual trigger
Click Compute Taxes Using AvaTax.
- Preview
Click Preview.
- Email a quotation/sales order
Send a quotation or sales order to a customer via email.
- Online quotation access
When a customer accesses the quotation online (via the portal view), the API call is triggered.
Tax calculations on invoices¶
Trigger an API call to calculate taxes on a customer invoice automatically with AvaTax in any of the following ways:
- Manual trigger
Click Compute Taxes Using AvaTax.
- Preview
Click Preview.
- Online invoice access
When a customer accesses the invoice online (via the portal view), the API call is triggered.
Note
The Fiscal Position must be set to Automatic Tax Mapping (Avalara Brazil) for any
of these actions to compute taxes automatically.
Accounting¶
Electronic documents¶
Configuration¶
A series number is linked to a sequence number range for electronic invoices. To configure the series number on a sales journal, follow these steps:
Go to and open the sales journal.
Enable Use Documents? to display the Series field.
Set the series number in the Series field.
Tip
If more than one series is needed, a new sales journal must be created, and a new series number must be assigned for each series. When creating the new sales journal, ensure the Dedicated Credit Note Sequence field in the Accounting Information section is disabled, as invoice, credit note, and debit note sequences are shared per series number, i.e., per journal.
When issuing electronic and non-electronic invoices, the document type is automatically selected based on the Type selected upon invoice creation.
Customer invoices¶
To process an electronic invoice for goods (NF-e) or services (NFS-e), the invoice must be confirmed and taxes must be computed by Avalara. The following fields must be filled out:
Customer, with all customer information
Payment Method: Brazil: Specify the expected payment method.
Document Type: Select (55) Electronic Invoice (NF-e) or (SE) Electronic Service Invoice (NFS-e).
In the Other Info tab:
Fiscal Position set as Automatic Tax Mapping (Avalara Brazil).
Some optional fields depend on the nature of the transaction. These fields in the Other Info tab are not required, so in most cases, leaving them blank will not result in errors from the government when the invoice is submitted:
Freight Model defines the freight contracting and transport model for the shipment.
Transporter Brazil determines who is doing the transportation.
Then, click Send. In the pop-up window, click Process e-invoice and any other options, such as Download or Email. Finally, click Send to process the invoice with the government.
Note
All fields available on the invoice used to issue an electronic invoice are also available on the sales order, if needed. When creating the first invoice, the Document Number field is displayed and allocated as the first number to be used sequentially for subsequent invoices.
Credit notes¶
If a sales return needs to be registered, a credit note can be created in Odoo and sent to the government for validation.
Note
Credit notes are only available for electronic invoices for goods (NF-e).
Debit notes¶
If additional information needs to be included or values that were not accurately provided in the original invoice need to be corrected, a debit note can be issued.
Note
Debit notes are only available for electronic invoices for goods (NF-e).
Only the products included in the original invoice can be included in the debit note. While changes can be made to the product’s unit price or quantity, products cannot be added to the debit note. The purpose of this document is only to declare the amount to be added to the original invoice for the same or fewer products.
Invoice cancellation¶
It is possible to cancel an electronic invoice that the government validated.
Note
Check whether the electronic invoice is still within the cancellation deadline, which may vary according to each state’s legislation.
E-invoices for goods (NF-e)¶
To cancel an e-invoice for goods (NF-e) in Odoo, click Request Cancel and add a cancellation Reason on the pop-up that appears. To send this cancellation reason to the customer via email, enable the E-mail checkbox.
Note
This is an electronic cancellation, which means that Odoo will send a request to the government to cancel the NF-e. It will then consume one IAP credit, as an API call occurs.
E-invoices for services (NFS-e)¶
To cancel an e-invoice for services (NFS-e) in Odoo, click Request Cancel. There is no electronic cancellation process in this case, as not every city has this service available. The user needs to cancel this NFS-e on the city portal manually. Once that step is completed, they can request the cancellation in Odoo, which will cancel the invoice.
Correction letter¶
A correction letter can be created and linked to an electronic invoice for goods (NF-e) that the government validated.
To do so in Odoo, click Correction Letter and add a correction Reason to the pop-up. To send the correction reason to a customer via email, enable the E-mail checkbox.
Note
Correction letters are only available for electronic invoices for goods (NF-e).
Invoice number range invalidation¶
A range of sequences that are assigned to sales journals can be invalidated by the government if they are not currently used and will not be used in the future. To do so, go to , open the journal, click the (gear) icon, and select Invalidate Number Range (BR). On the Invalidate Number Range (BR) wizard, add the Initial Number and End Number of the range that should be cancelled, and enter an invalidation Reason.
Note
Invoice number range invalidation is only available for electronic invoices for goods (NF-e).
The journal’s chatter records the log of the cancelled numbers, along with the XML file.
Vendor bills¶
When receiving an invoice from a supplier, encode the bill in Odoo by adding all the commercial information and the same Brazilian-specific information recorded on the customer invoices.
These Brazilian-specific fields are:
Payment Method: Brazil: Specify the expected payment method.
Document Type: used by the vendor
Document Number: the invoice number from the supplier
Freight Model (NF-e specific): Define the freight contracting and transport model for the shipment.
Transporter Brazil (NF-e specific): who is doing the transportation.