Classificações fiscais
Primeramente, este módulo traz uma variedade de cadastros fiscais para produtos, parceiros ou empresas. Na hora de emitir documentos fiscais como NF-e, NFS-e etc... até empresas do regime simplificado ou MEI precisam de vários desses cadastros. E empresas do regime normal precisam deles para calcular os impostos ou emitir documentos fiscais.
Produtos:
- tipo fiscal
- NCM (com ligações com os impostos)
- genêro fiscal
- CEST
- NBM
- NBS
- tipo de serviço
- unidades fiscais
Parceiros:
- CNAE
- perfil fiscal
Conceito de documento fiscal
O Odoo nativo não tem o conceito de documento fiscal. O conceito mais parecido seria o account.move e até a versão 10.0 a localização estendia o invoice para suportar as NF-e e NFS-e apenas. Naquela época não era razoável você cogitar fazer o SPED no Odoo, o próprio core do Odoo não tinha maturidade para isso então era válido a abordagem empírica de ir suportando mais casos de NFe dentro do invoice Odoo apenas.
Porém, na v12, amadurecemos o framework XML/SOAP de forma que se torna razoável suportar vários documentos fiscais (NF-e, NFS-e, MDF-e, CT-e, EFD-Reinf, e-Social, GNRE, BP-e...) com a qualidade OCA dentro do Odoo. Também, apesar de complexo, o core do Odoo finalmente tem suporte suficiente para as operações de uma empresa que faria o SPED.
Nisso se torna interessante ter o conceito de documento fiscal l10n_br_fiscal.document independente do invoice Odoo para suportar todos os documentos fiscais mesmo, de forma modular. Um outro motivo para ter o conceito de documento fiscal fora do módulo account é que quando você analisa o código deste módulo l10n_br_fiscal, quase nada dele poderia ser feito pelo módulo account do Odoo. Então ter esse módulo l10n_br_fiscal que não depende do módulo account também é uma forma de modularizar a localização para facilitar a manutenção dela, especialmente quando se trata de migrar e que o módulo pode ter mudado bastante como foi o caso entre a v8.0 e a v9.0 ou a v12.0 e v13.0 por exemplo. Facilita também a governança do projeto possibilitando que pessoas sejam responsáveis por diferentes partes. O módulo l10n_br_fiscal foi principalmente extraído do módulo l10n_br_l10n_br_account_product das v7.0 as v.10.0.
Esse módulo l10n_br_fiscal é agnóstico de qualquer tecnologia XML ou SOAP. Ele contém apenas o que há de comum entre os documentos fiscais mas esses últimos são implementados em outros módulos. Para um determinado documento fiscal como a Nf-e, você tem então por exemplo:
- nfelib: um pacote de data bindings puro Python (que não depende do Odoo). Em geral usamos um gerador de código para gerar esses bindings a partir dos esquemas XSD da fazenda.
- l10n_br_nfe_spec: um modulo de mixins Odoo geridos também a partir dos XSD. Esses mixins são apenas as estruturas de dados das especificações antes de ser injectados em objetos Odoo existantes (como res.partner ou l10n_br_fiscal.document) ou até tornados concretos caso não exite objetos na Odoo ou na OCA para eles já.
- l10n_br_nfe: um módulo Odoo que trata de injectar esses mappings fiscais nos objetos Odoo e que implementa a lógica como os wizards para a transmissão.
A transmissão é realizada usando uma lib de transmissão como erpbrasil.doc (baseada em Python Zeep). Importante: no caso da NFS-e, a ausência de padrão nacional hoje e a simplicidade do modelo (comparado com a NFe) faz que foi decidido de não usar um módulo de mixins fiscais Odoo geridos, o mapping é com a lib de binding é feito manualmente, família de NFS-e por família.
Alem disso a maioria do codigo do l10n_br_fiscal.document e das linhas dele l10n_br_fiscal.document.line é na verdade feito dentro de mixins 10n_br_fiscal.document.mixin e 10n_br_fiscal.document.line.mixin respectivamente. Esses mixins podem assim ser injectados em outros objetos Odoo que precedem os documentos fiscais e podem armazenar então o mesmo tipo de informação: sale.order, purchase.order, stock.picking... Isso é bem visível nos módulos que estendem esse módulo:
Porem o caso do invoice Odoo no modulo l10n_br_account é diferente ainda. Pois já se tem a tabela independente do documento fiscal cuja grande maioria das dezenas e até centenas de campos fiscais (no caso de muitos tipos de documentos fiscais) não são redundante com os do invoice Odoo. Se a gente injetasse esses mixins dentro do invoice, aí sim essas centenas de campos seriam duplicados entre o invoice e o documento fiscal. Por isso, o sistema que foi adotado no modulo l10n_br_account é que um invoice Odoo passa a ter um _inherits = "l10n_br_fiscal.document" de forma que se pilota o documento fiscal através do invoice, oferecendo o mesmo tipo de integração como antes. O mesmo tipo de mecanismo acontece com a linha do documento fiscal.
Sendo assim, já pelos _inherits, o invoice Odoo e as linhas dele já vão puxar todos campos fiscais como se eles fossem das suas respectivas tabelas sem duplicar eles no banco. Se alem disso a gente injetasse os mixins 10n_br_fiscal.document.mixin e 10n_br_fiscal.document.line.mixin no invoice e invoice.line, esses campos fiscais apareceriam também nas tabelas account_move e account_move_line de forma redundantes com os campos puxados pelos _inherits. Para não ter esse problema, os métodos fiscais comuns (sem os campos) foram ainda extraidos nos mixins: 10n_br_fiscal.document.mixin.methods e 10n_br_fiscal.document.line.mixin.methods que são injectados nos objetos account_move e account_move_line respectivamente dentro do modulo l10n_br_account.
Impostos brasileiros
O módulo l10n_br_fiscal lida com os principais impostos brasileiros como:
- ICMS do Simples Nacional
- ICMS do Regime normal
- IPI
- PIS
- COFINS
- ISSQN
- IRPJ
- II
- CSLL
- INSS
O módulo l10n_br_fiscal também lida com:
- ST
- retenções
É notório que o cálculo dos impostos no Brasil é muito especial e muito trabalhoso. Geralmente é o motivo pelo qual os ERPs internacionais não tem grande fatia de mercado brasileiro.
Até a versão 10.0, tentamos usar e estender o objeto Odoo account.tax. A Akretion até criou o projeto OCA/account-fiscal-rule para determinar as alíquotas de cada imposto de accordo com os parâmetros da operação fiscal. Porém, a gente acabava usando quase nada do account.fiscal.position nativo na parte fiscal e pelo contrário, isso nos obrigava a ter um registro account.tax para cada aliquota e nos obrigava a manter centenas de taxas e dezenas de milhares de regras para selecionar a "posição fiscal" Odoo que aplicaria as taxas corretas. E você ainda tinha que gerir essas dezenas de milhares de regras para uma determinada empresa do regime normal. Conclusão: era inviável nos projetos menores de tentar se encaixa na lógica do Odoo para calcular os impostos brasileiros.
Nisso criamos neste módulo os modelos de taxas que representam exatamente o funcionamentos dos impostos brasileiros. Além dos cálculos, esses modelos também nos servem a carregar as tabelas dos impostos. E mais adiante, no módulo l10n_br_account, ligamos os objetos nativos account.tax as alíquotas dos impostos brasileiros.
Claro esses modelos dos impostos atendem as empresas do regime normal, mas é bom lembrar que até empresas do regime simplificado precisam desses modelos para realizar as operações com ST (Substituição Tributária)...
Operações fiscais
>
No Odoo nativo, o conceito mais parecido com a operação fiscal e o account.fiscal.position. E ate a versão 10.0, era o que a gente usava. Porém, a posição fiscal do Odoo não resolve muito os nossos problemas pois:
- no Brasil se tem uma operação fiscal por linha de documento fiscal
- a posição fiscal do Odoo desconhece a lógica da parametrização fiscal brasileira
- já que puxamos o cadastro dos impostos no módulo l10n_br_fiscal fora do módulo account (sem depender dele), não temos ainda o objeto account.fiscal.position neste módulo.
Com tudo, optamos por criar um objeto l10n_br_fiscal.operation que faz exactamente o que precisamos para o Brasil. Mais adiante, no módulo l10n_br_account é realizado a integração entre a posição fiscal do Odoo e essa operação fiscal.
auto_awesome What this module does
AI-generated from the code · Odoo 19.0Provides the Brazilian fiscal master data and tax engine: fiscal classifications for products and partners, tax rules, fiscal operations and a generic fiscal document with lines, states and returns.
This module adds the Brazilian fiscal foundation used by later modules that issue NF-e, NFS-e and other fiscal documents. It does not replace invoices; it adds its own fiscal document screen with lines, a document type, a serie and a number, and two statuses: the electronic document status and the fiscal status.
Users can maintain fiscal master data: - Product classifications such as NCM, NBS, NBM, CEST, fiscal genre, service type and fiscal units. - Partner data such as CNAE and fiscal profile. - Tax tables: CST, CFOP, tax groups, tax definitions, ICMS relief and regulation, PIS/COFINS bases and credits, IPI seals and guidelines. - Fiscal operations and their lines, which drive which taxes apply.
Automatic behaviours shown in the code: - CFOP destination and import flag are computed from the first digit of the code, and CFOP codes must be unique. - CEST records automatically link the NCMs typed in their NCM field. - Fiscal comments can be built from templates and merged into the fiscal and customer additional data of a document. - A document number cannot be reused for the same company, issuer, type and serie; documents that are open, authorised, cancelled, denied or invalidated cannot be deleted. - A return document can be created from an existing one using the return fiscal operation configured on the operation and its lines. - NCM and NBS records can fetch estimated tax percentages from an external tax service, manually or by a scheduled job, when the company has the service configured.
Archiving and unarchiving fiscal master data is restricted to fiscal managers.
Depends on
Required by other modules
Menus it adds
Models and fields (30)
- uom.uom · extends an existing modelcode, description
- res.company · extends an existing modelripi (RIPI), ibpt_api (Use IBPT API), ibpt_token, tax_ipi_id (Default IPI), is_industry, tax_csll_id (Default CSLL), tax_icms_id (Default ICMS), tax_inss_id (Default INSS), tax_irpj_id (Default IRPJ), cnae_main_id (Main CNAE), piscofins_id (PIS/COFINS), tax_issqn_id (Default ISSQN), accountant_id (Accountant), coefficient_r, industry_type, tax_framework, tax_pis_wh_id (Default PIS RET), annual_revenue, delivery_costs, payroll_amount (Last Period Payroll Amount), tax_csll_wh_id (Default CSLL RET), tax_inss_wh_id (Default INSS RET), tax_irpj_wh_id (Default IRPJ RET), legal_nature_id (Legal Nature), tax_issqn_wh_id (Default ISSQN RET), document_type_id (Default Document Type), ibpt_update_days (IBPT Token Updates), processador_edoc (Processador documentos eletrônicos), tax_cofins_wh_id (Default COFINS RET), accounting_office
- res.partner · extends an existing modelvat, city_id, state_id, ind_final (Final Consumption Operation), is_company, rntrc_code (RNTRC Code), ind_ie_dest (Contribuinte do ICMS), cnae_main_id (Main CNAE), tax_framework, l10n_br_ie_code, l10n_br_im_code, legal_nature_id (Legal Nature), is_public_entity (Public Entity), fiscal_profile_id (Fiscal Partner Profile), cnae_secondary_ids (Secondary CNAEs), nif_motive_absence (NIF motive absence), public_entity_type (Tipo de Entidade Governamental)
- product.product · new model
- product.template · new modelnbm_id (NBM), nbs_id (NBS), ncm_id (NCM), uoe_id (Export UoM), uot_id (Tax UoM), cest_id (CEST), uoe_factor (Export UoM Factor), uot_factor (Tax UoM Factor), fiscal_type, icms_origin (ICMS Origin), fiscal_genre_id (Fiscal Product Genre), service_type_id (Service Type LC 166), fiscal_genre_code (Fiscal Product Genre Code), tax_icms_or_issqn (ICMS or ISSQN Tax), ipi_control_seal_id (IPI Control Seal), city_taxation_code_ids (City Taxation Code), ipi_guideline_class_id (IPI Guideline Class), operation_indicator_id, national_taxation_code_id (National Taxation Code)
- res.country.state · extends an existing modeltax_definition_ids (Tax Definitions)
- l10n_br_fiscal.cst · new modelcode, cst_type (Type), tax_domain (Tax Domain), tax_group_id (Fiscal Tax Group)
- l10n_br_fiscal.nbm · new modelcode, ncms (NCM), ncm_ids (NCMs), code_unmasked, product_tmpl_ids, tax_definition_ids (Tax Definition)
- l10n_br_fiscal.nbs · new modelcode, code_unmasked, product_tmpl_ids, tax_estimate_ids
- l10n_br_fiscal.ncm · new modelcode, uoe_id (Export UoM), uot_id (Tax UoM), nbm_ids (NBMs), cest_ids (CESTs), exception, tax_ii_id (Tax II), tax_ipi_id (Tax IPI), code_unmasked, piscofins_ids (PIS/COFINS), product_tmpl_ids, tax_estimate_ids, tax_definition_ids (Tax Definition)
- l10n_br_fiscal.tax · new modelname, uot_id (Tax UoM), sequence, cst_in_id (CST In), tax_scope, cst_out_id (CST Out), tax_domain (Tax Domain), currency_id (Currency), icmsst_value (PFC Value), tax_group_id (Fiscal Tax Group), value_amount (Value), tax_base_type, cst_tax_domain (CST Tax Domain), icms_base_type, percent_amount (Percent), compute_sequence, icmsst_base_type (ICMS ST Base Type), percent_reduction, icmsst_mva_percent (MVA Percent), percent_debit_credit (Percent Debit/Credit), withholding_min_value (Minimum Withholding Value)
- l10n_br_fiscal.cest · new modelcode, item, ncms (NCM), ncm_ids (NCMs), segment, code_unmasked, product_tmpl_ids, tax_definition_ids (Tax Definition)
- l10n_br_fiscal.cfop · new modelcode, ind_cte (Used in CTe), ind_nfe (Used in NFe), ind_comb (Fuel?), ind_anula (Revocation?), ind_devol (Return?), ind_remes (Shipment?), ind_retor (Regress?), is_icmsst (ICMS ST?), is_import (Is Import?), type_move, ind_transp (Transport?), small_name, stock_move (Stock Moves?), assent_move (Assent Move?), destination, type_in_out (Type), account_move (Account Move?), finance_move (Finance Moves?), ind_comunica (Communication?), cfop_return_id (Return CFOP), cfop_inverse_id (Inverse CFOP), tax_definition_ids (Tax Definition)
- l10n_br_fiscal.cnae · new modelcode, version, child_ids (Children CNAEs), parent_id (Parent CNAE), internal_type
- res.config.settings · extends an existing modelibpt_api (Use IBPT API), ibpt_token (IBPT Token), delivery_costs, document_type_id (Default Document Type), ibpt_update_days (IBPT Update), module_l10n_br_cte (CT-e), module_l10n_br_nfe (NF-e/NFC-e), module_l10n_br_mdfe (MDF-e), module_l10n_br_nfse (NFS-e)
- l10n_br_fiscal.comment · new modelname, object, comment, date_end (Final Date), sequence, object_id (Reference), date_begin (Initial Date), comment_type, test_comment
- l10n_br_fiscal.document · new modelname, state (State), user_id (User), company_id (Company), partner_id (Partner), state_edoc (Situação e-doc), currency_id (Currency), date_in_out (Date IN/OUT), edoc_purpose (Finalidade), state_fiscal (Situação Fiscal), document_date, document_type (Document Type Code), fiscal_line_ids (Document Lines), partner_cnpj_cpf (CNPJ), processador_edoc, imported_document (Imported), partner_legal_name (Legal Name), public_entity_type (Tipo de Entidade Governamental), document_electronic (Electronic?), fiscal_operation_id (Fiscal Operation), partner_shipping_id (Shipping Address), document_related_ids (Fiscal Document Related), fiscal_operation_type, edoc_refund_debit_type (Tipo de Nota de Débito), fiscal_additional_data, edoc_refund_credit_type (Tipo de Nota de Crédito), partner_l10n_br_ie_code (State Tax Number), customer_additional_data, company_l10n_br_ie_code_st (Company ST State Tax Number)
- l10n_br_fiscal.operation · new modelcode, name, color (Color Index), state, line_ids (Operation Line), company_id (Company), comment_ids (Comment), fiscal_type, edoc_purpose (Finalidade), kanban_dashboard, document_type_ids (Operation Document Types), default_price_unit (Default Price Unit?), fiscal_operation_type (Type), return_fiscal_operation_id (Return Operation), inverse_fiscal_operation_id (Inverse Operation)
- l10n_br_fiscal.tax.group · new modelname, cst_ids (CSTs), tax_ids (Taxes), sequence, tax_scope, partner_id (WH Partner), tax_domain, wh_due_day (Due Day), tax_include (Tax Included in Price), tax_withholding, compute_sequence, base_without_icms (Remove ICMS value from Base), base_with_additional_values (Add the value of freight, insurance and others to the Base)
- l10n_br_fiscal.icms.relief · new model
- l10n_br_fiscal.legal.nature · new modelcode
- l10n_br_fiscal.service.type · new modelchild_ids (Service Type Child), parent_id (Parent Service Type), internal_type, product_tmpl_ids, withholding_at_place (Tax Retention at place of provision), withholding_possible (Subject to withholding tax)
- l10n_br_fiscal.tax.estimate · new modelkey, nbs_id (NBS), ncm_id (NCM), origin (Source), version, state_id (State), company_id (Company), create_date, state_taxes (Impostos Estaduais Nacional), municipal_taxes (Impostos Municipais Nacional), federal_taxes_import (Impostos Federais Importado), federal_taxes_national (Impostos Federais Nacional)
- l10n_br_fiscal.data.abstract · new modelcode, name, active, date_end (End Date), date_start (Start Date), code_unmasked (Unmasked Code)
- l10n_br_fiscal.document.line · new modelname, uom_id (UOM), quantity, company_id (Company), partner_id, price_unit, document_id (Document), edoc_purpose, tax_framework, delivery_costs, additional_data, force_compute_delivery_costs_by_total
- l10n_br_fiscal.document.type · new modelcode, name, type (Document Type), sufix, prefix, electronic (Is Electronic?), document_serie_ids (Document Series)
- l10n_br_fiscal.product.genre · new modelproduct_tmpl_ids
- l10n_br_fiscal.product.mixin · new model
- l10n_br_fiscal.document.mixin · new modelissuer, ind_pres (Buyer Presence), ind_final (Final Consumption Operation), company_id (Company), partner_id, comment_ids (Comments), currency_id (Currency), document_key (Key), total_weight, amount_ii_base (II Base), delivery_costs, document_serie (Serie Number), operation_name, amount_cbs_base (CBS Base), amount_ibs_base (IBS Base), amount_ii_value (II Value), amount_ipi_base (IPI Base), amount_pis_base (PIS Base), document_number (Fiscal Document Number), key_check_digit (Document Key Check Digit), key_random_code (Document Key Random Code), amount_cbs_value (CBS Value), amount_csll_base (CSLL Base), amount_ibs_value (IBS Value), amount_icms_base (ICMS Base), amount_inss_base (INSS Base), amount_ipi_value (IPI Value), amount_irpj_base (IRPJ Base), amount_pis_value (PIS Value), document_type_id (Fiscal Document Type)
- l10n_br_fiscal.document.serie · new modelcode, name, active, company_id (Company), fiscal_type (Type), document_type_id (Fiscal Document), internal_sequence_id (Sequence), invalidate_number_id (Invalidate Number Range), sequence_number_next
Text generated by AI (DeepSeek) from reading the Odoo 19.0 code on GitHub; it may contain mistakes, so check the code before deciding. The module is very large and only part of the code was read. View the code on GitHub
Availability by version
Reviewed: 2026-11-03Confirmation status: 8 confirmed, 1 with no information of 9 versions.
Sources · Odoo 19.0
Confirmed on 2026-11-03 in branch 19.0 of OCA/l10n-brazil.
terminal Installation and usage
OCA documentation · Odoo 19.0Installation
Source · Odoo 19.0Para instalar o módulo l10n_br_fiscal, você precisa de instalar primeiro os pacotes Python
- erpbrasil.base
- erpbrasil.assinatura
Configuration
Source · Odoo 19.0Para uma boa configuração fiscal, você tem que revisar bem:
- em Configurações: as operaçoes fiscais que você vai usar, as linhas de operação fiscal e as definições das taxas nessas linhas.
- a configuração fiscal da sua empresa (aba fiscal)
- a configuração fiscal dos clientes e fornecedores (aba fiscal) e dos produtos (aba fiscal).
Usage
Source · Odoo 19.0Você pode criar documentos fiscais direitamente pelo menu fiscal, mas a princípio você vai pilotar a criação de documentos fiscais a partir dos invoices Odoo, usando módulos adicionais como l10n_br_account, l10n_br_sale, l10n_br_purchase...
Installation instructions, the distribution package, dependencies and configuration steps are not shown because they have not yet been verified in the module documentation for any version.
Data imported from GitHub: this sheet reflects the latest catalog review, not a live lookup. Always check the module documentation and staging before installing in production.