Metadata-Version: 2.1
Name: odoo-addon-l10n_br_account
Version: 17.0.1.0.0.26
Requires-Python: >=3.10
Requires-Dist: odoo-addon-l10n_br_coa>=17.0dev,<17.1dev
Requires-Dist: odoo-addon-l10n_br_fiscal>=17.0dev,<17.1dev
Requires-Dist: odoo>=17.0a,<17.1dev
Summary: Invoicing and accounting entries for Brazil
Home-page: https://github.com/OCA/l10n-brazil
License: AGPL-3
Author: Akretion, Odoo Community Association (OCA)
Author-email: support@odoo-community.org
Classifier: Programming Language :: Python
Classifier: Framework :: Odoo
Classifier: Framework :: Odoo :: 17.0
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Development Status :: 4 - Beta
Description-Content-Type: text/x-rst

.. image:: https://odoo-community.org/readme-banner-image
   :target: https://odoo-community.org/get-involved?utm_source=readme
   :alt: Odoo Community Association

===========================================
Invoicing and accounting entries for Brazil
===========================================

.. 
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! This file is generated by oca-gen-addon-readme !!
   !! changes will be overwritten.                   !!
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! source digest: sha256:3fef6f9166c101b8d77d7eba32c9fc28a8c08220cd105d58b4698b3f25973690
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
    :target: https://odoo-community.org/page/development-status
    :alt: Beta
.. |badge2| image:: https://img.shields.io/badge/license-AGPL--3-blue.png
    :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
    :alt: License: AGPL-3
.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fl10n--brazil-lightgray.png?logo=github
    :target: https://github.com/OCA/l10n-brazil/tree/17.0/l10n_br_account
    :alt: OCA/l10n-brazil
.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png
    :target: https://translation.odoo-community.org/projects/l10n-brazil-17-0/l10n-brazil-17-0-l10n_br_account
    :alt: Translate me on Weblate
.. |badge5| image:: https://img.shields.io/badge/runboat-Try%20me-875A7B.png
    :target: https://runboat.odoo-community.org/builds?repo=OCA/l10n-brazil&target_branch=17.0
    :alt: Try me on Runboat

|badge1| |badge2| |badge3| |badge4| |badge5|

Visão Geral
===========

O módulo ``l10n_br_account`` integra o motor fiscal brasileiro
(``l10n_br_fiscal``) ao framework contábil nativo do Odoo (módulo
``account``). Ele integra a complexa lógica da tributação e dos
documentos fiscais do Brasil com as faturas e lançamentos contábeis
conforme as normas de contabilidade brasileiras.

O módulo atende desde a automação na emissão de notas para empresas do
Simples Nacional até os cenários contábeis mais exigentes do regime
normal (Lucro Real/Presumido).

Arquitetura e Integração: Decorator Pattern (``_inherits``)
===========================================================

A arquitetura do módulo se baseia no mecanismo de herança por composição
``_inherits`` do Odoo para criar uma composição dinâmica entre os
modelos fiscais e contábeis:

- **account.move** herda de **l10n_br_fiscal.document**
- **account.move.line** herda de **l10n_br_fiscal.document.line**

Esta abordagem, análoga ao *Decorator Pattern*, oferece as seguintes
vantagens:

1. **Gerenciamento Unificado**: Permite controlar o Documento Fiscal
   diretamente pela interface da Fatura do Odoo. Campos fiscais (CFOP,
   NCM, valores de impostos) são acessados e computados de forma
   transparente, como se fossem nativos do ``account.move.line``.

2. **Baixíssima Redundância de Dados**: A herança por composição evita a
   duplicação de centenas de campos fiscais nas tabelas contábeis. A
   "fonte da verdade" fiscal é sempre o registro em
   ``l10n_br_fiscal.document``, garantindo um banco de dados normalizado
   e consistente.

3. **Modularidade e Manutenção**: A lógica fiscal complexa permanece
   encapsulada no ``l10n_br_fiscal``. Para assegurar a reatividade dos
   campos computados na interface da fatura, o módulo utiliza um *mixin*
   especializado (``l10n_br_account.decorator.mixin``) que gerencia a
   herança de métodos e campos dinâmicos.

Principais Funcionalidades e Casos de Uso
=========================================

Uso Simplificado: Cálculo dos impostos e criação dos Documentos Fiscais
=======================================================================

O módulo ``l10n_br_account`` é a peça chave para automatizar a emissão
de documentos fiscais a partir de qualquer fluxo de negócio que gere uma
fatura no Odoo, como:

- Ordens de Venda (``sale.order``)
- Ordens de Compra (``purchase.order``)
- Movimentações de Estoque (``stock.picking``)
- Contratos (``contract.contract``), entre outros.

A **Operação Fiscal** pré-configurada orquestra o preenchimento
automático de todos os dados necessários, permitindo a geração de NF-e,
NFS-e e outros documentos com mínima intervenção.

Uso Avançado: Lançamentos contábeis corretos para as empresas do Regime Normal
==============================================================================

Para empresas no Lucro Real ou Presumido, o ``l10n_br_account`` habilita
uma gestão contábil e fiscal precisa e aderente à legislação.

- **Lançamentos Contábeis de Impostos**: Conecta os impostos fiscais
  (``l10n_br_fiscal.tax``) aos contábeis (``account.tax``), garantindo
  que a validação de uma fatura gere os lançamentos corretos para ICMS,
  IPI, PIS, COFINS, etc., em suas respectivas contas (custo,
  recuperável, despesa).

- **Operações Sem Impacto Financeiro**: Suporta operações como "Remessa
  para Industrialização", permitindo a emissão do documento fiscal
  obrigatório e o lançamento correto dos impostos, mas sem gerar contas
  a pagar ou a receber, mantendo a integridade fiscal e contábil.

- **Composição de Valores Financeiros**: Gerencia a correta composição
  do valor financeiro das faturas. Por exemplo, assegura que o valor do
  IPI, quando não recuperável, seja somado ao contas a pagar do
  fornecedor.

- **Importação de Documentos (XML)**: Facilita a importação de
  documentos de fornecedores, criando simultaneamente o
  ``l10n_br_fiscal.document`` com os dados fiscais e a fatura de
  fornecedor (``account.move``) pronta para validação e pagamento.

Escopo e Delimitação do Módulo
==============================

O nome ``l10n_br_account`` deriva do módulo ``account``, que ele
estende. É importante notar que o módulo ``account`` do Odoo, em sua
essência, é focado em faturamento, embora contenha os conceitos
fundamentais de planos de contas e lançamentos contábeis.

Para uma contabilidade completa de uma empresa no regime normal, mesmo
utilizando o Odoo Enterprise, é necessária a instalação de dezenas de
módulos adicionais da OCA, provenientes de diversos repositórios da OCA.
O ``l10n_br_account``, apesar do nome, **não substitui** este
ecossistema. Ele se concentra na ponte fiscal-contábil. Funções como
conciliação avançada (através de módulos como ``account_reconcile``),
gestão de ordens de pagamento, integração bancária (CNAB) e importação
de extratos são tratadas por dezenas de outros módulos específicos da
OCA...

Por outro lado, é importante ressaltar que os autores deste módulo
possuem clientes do regime normal com uma contabilidade
significativamente mais completa do que a oferecida nativamente pelo
Odoo Enterprise, baseando-se exclusivamente em módulos de código aberto
da OCA. Alcançar tal nível de sofisticação, no entanto, exige anos de
experiência em implementação e uma escolha estratégica da versão do
Odoo. É importante evitar versões muito recentes, para as quais o
ecossistema de módulos da OCA ainda não atingiu a maturidade e
estabilidade necessárias após o processo de migração (uma versão nova do
Odoo mal tem 500 módulos da OCA migrados depois de 6 meses, mas tem
quase 2000 depois de um ano e quase 3000 depois de 3 anos).

Vale a pena mencionar que lançamentos de Custo da Mercadoria Vendida
(CMV) e outros lançamentos de contabilidade de estoque IFRS/IAS2, são
tipicamente realizados através da combinação do módulo nativo
``stock_account``, do ``l10n_br_stock_account`` (deste mesmo repo) e da
ativação do modo "anglo-saxon" no seu plano de contas.

Detalhes sobre o modelo de dados
================================

Cardinalidade: Documentos Fiscais e Lançamentos Contábeis
=========================================================

A arquitetura suporta cenários onde um único lançamento financeiro
(``account.move``) agrupa múltiplos documentos fiscais, como uma fatura
única para pagar vários Conhecimentos de Transporte (CT-e). Esta
flexibilidade é garantida por três campos-chave:

- **account.move.fiscal_document_id**: O campo ``Many2one`` que
  implementa o ``_inherits``. Representa o documento fiscal "principal"
  ou em edição na interface da fatura.

- **account.move.line.fiscal_document_line_id**: O pilar da arquitetura.
  Permite que **cada linha** da fatura aponte para uma linha de um
  documento fiscal distinto. É isso que possibilita agregar múltiplos
  documentos em um único ``account.move``.

- **account.move.fiscal_document_ids**: Campo ``One2many`` computado que
  agrega todos os documentos fiscais vinculados às linhas da fatura,
  oferecendo uma visão completa e consolidada quando o lançamento tem
  mais de um documento fiscal.

A flexibilidade do design é bidirecional. O sistema também gerencia
nativamente cenários onde **um lançamento contábil (``account.move``)
não possui nenhum documento fiscal associado**. Isso é fundamental para
operações puramente contábeis ou não fiscais, como:

- Lançamentos de folha de pagamento.
- Operações financeiras ou contábeis em empresas de um grupo
  multinacional que não operam no Brasil.

Além disso, mesmo dentro de uma fatura fiscalizada, a associação é
granular. Apenas as linhas de produto (``invoice_line_ids`` com
``display_type='product'``) são vinculadas a uma
``l10n_br_fiscal.document.line``. Linhas de impostos, de contas a
pagar/receber, ou linhas de anotação/seção permanecem como lançamentos
puramente contábeis, sem linha de documento fiscal específica.

Observação sobre a Normalização do Modelo de Dados
==================================================

Idealmente, o modelo de dados teria redundância zero. Contudo, para
simplificar a injeção de mixins fiscais — em especial o
``l10n_br_fiscal.document.line.mixin`` — e alavancar a lógica nativa do
Odoo, foi uma decisão de design manter a nomenclatura de um pequeno e
controlado conjunto de campos, como ``partner_id``, ``company_id``,
``user_id``, ``currency_id``, ``product_id``, ``quantity``,
``price_unit`` e ``name``.

Como consequência, existe uma redundância mínima e gerenciada.
Considerando os milhares de campos necessários para a diversidade de
documentos fiscais brasileiros, apenas cerca de quatro campos do
``account.move`` e quatro do ``account.move.line`` são efetivamente
duplicados. Para garantir a integridade, estes campos (apelidados de
*shadow fields*) são cuidadosamente sincronizados em tempo real,
inclusive durante a edição de novos registros em memória (fase
``NewId``), assegurando total consistência entre a fatura e o documento
fiscal.

A Separação Estratégica dos Mixins Fiscais
==========================================

No caso do ``account.move``, o objetivo era obter os campos do
``l10n_br_fiscal.document`` sem duplicá-los (o que o ``_inherits`` faz
perfeitamente), mas também precisávamos de seus métodos (como
``_compute_fiscal_tax_ids`` ou ``_compute_tax_fields``). Se usássemos
``_inherit`` no mixin principal (``l10n_br_fiscal.document.mixin``),
teríamos os métodos, mas os campos seriam duplicados, quebrando o
princípio de normalização.

Por outro lado, modelos como ``sale.order`` e ``purchase.order`` não são
uma representação de um documento fiscal, mas sim precursores dele.
Portanto, eles podem usar uma herança simples (``_inherit``) diretamente
no mixin principal (``l10n_br_fiscal.document.mixin``), pois precisam
tanto dos campos quanto dos métodos para preparar os dados que serão
posteriormente utilizados na geração do documento fiscal.

Modelo UML Simplificado
=======================

|UML account.move|

|UML account.move.line|

Aviso Importante: Pré-requisitos e Complexidade
===============================================

Para utilizar o ``l10n_br_account`` de forma eficaz, é necessário ter
domínio aprofundado de dois ecossistemas complexos: o módulo ``account``
nativo do Odoo e o motor ``l10n_br_fiscal`` deste repositório.

O ``account`` é o maior e mais intrincado módulo do Odoo, constituindo
por si só um ERP financeiro completo, e não apenas um simples software
de emissão de notas para microempresas. Por sua vez, o
``l10n_br_fiscal`` é o maior módulo entre os mais de 3000 disponíveis na
OCA. Este módulo, ``l10n_br_account``, está também entre os três mais
complexos da localização brasileira e exige um uso avançado do ORM do
Odoo para gerenciar a dualidade documento fiscal/lançamento contábil.

A implementação bem-sucedida de um ERP estrangeiro no Brasil é uma
tarefa que demanda profissionais altamente qualificados, com anos de
experiência em programação backend (Python) e implantação de verdadeiros
sistemas ERP. Uma implementação não se resume a baixar e instalar módulo
(apenas 1% do trabalho); envolve análise de processos, configuração,
migração de dados e customizações, migração de modulos OCA a partir de
outras versões... Subestimar essa complexidade invariavelmente leva a
projetos problemáticos e custos elevados no longo prazo.

Este aviso serve para alinhar expectativas e reforçar que o sucesso de
uma implantação Odoo no Brasil depende de expertise técnica e funcional
aprofundada. Infelizmente, este mercado atrai aventureiros que
subestimam essa complexidade ou que vendem projetos acreditando ser
possível terceirizar a execução sem grande compromisso com a entrega,
explorando a falta de informação do cliente. Este cenário caracteriza um
"market for lemons", onde a assimetria de informação torna difícil
distinguir entre fornecedores qualificados e despreparados, impedindo o
desenvolvimento de um mercado de implementação maduro.

Agravando a situação, onde se esperaria uma garantia criteriosa de
qualidade, o ecossistema corporativo "oficial" investe pesadamente em
propaganda para mascarar essa realidade, promovendo uma visão onde a
consultoria de implementação é tratada como uma commodity. Esse modelo,
focado em comissões pela venda de licenças (muitas vezes desnecessárias
ao utilizar o ecossistema da OCA), alimenta um mercado paralelo notório
de "parceiros fantoches/bucha de canhão" que compram certificações
oficiais de empresas estrangeiras para simular uma competência que não
possuem. Cuidado com profissionais que ostentam certificações compradas
para transferir a responsabilidade da implementação sem o devido suporte
ou conhecimento real. Não se deixe enganar por narrativas que
simplificam a complexidade do projeto para priorizar a venda de
licenças!

Conclusão
=========

O ``l10n_br_account`` possui um design robusto que unifica as complexas
lógicas fiscal e contábil do Brasil dentro do Odoo. Sua arquitetura,
projetada por especialistas para especialistas, oferece uma plataforma
flexível e confiável, capaz de sustentar operações de alta complexidade
e garantir a conformidade fiscal e contábil das empresas que utilizam a
localização brasileira da OCA.

.. |UML account.move| image:: https://raw.githubusercontent.com/OCA/l10n-brazil/17.0/l10n_br_account/static/img/account_move.png
.. |UML account.move.line| image:: https://raw.githubusercontent.com/OCA/l10n-brazil/17.0/l10n_br_account/static/img/account_move_line.png

**Table of contents**

.. contents::
   :local:

Installation
============

Este modulo depende dos módulos:

- l10n_br_coa (que depende do módulo account)
- l10n_br_fiscal

Configuration
=============

Antes de seguir este guia, é fundamental que você:

1. **Tenha configurado sua empresa** com o país "Brasil". A maioria dos
   campos fiscais só aparecerá neste contexto.
2. Tenha configurado o regime fiscal da sua empresa.
3. Tenha configurado um Plano de Contas, idealmente deriavdo do plano
   base do módulo l10n_br_coa.
4. **Esteja familiarizado com o processo de faturamento padrão do Odoo**
   através do módulo ``account``.
5. **Compreenda os conceitos básicos do módulo ``l10n_br_fiscal``**,
   especialmente o que são Operações Fiscais
   (``l10n_br_fiscal.operation``) e como o sistema seleciona e calcula
   os impostos com base nelas.

Usage
=====

Passo a Passo: Criando uma Fatura Fiscal
----------------------------------------

O processo se inicia a partir da fatura padrão do Odoo, agora "decorada"
com os campos fiscais necessários.

1. **Navegue até Faturamento** Acesse o menu
   ``Faturamento > Clientes > Faturas``.

2. **Crie uma Nova Fatura** Clique no botão ``Criar``.

3. **Selecione o Cliente** No campo ``Cliente``, selecione um parceiro
   configurado para o Brasil. O cadastro do cliente contenha as
   informações fiscais corretas (CNPJ/CPF, perfil fiscal, endereço,
   etc.). Nos dados de demonstração, a **AMD do Brasil** é um excelente
   exemplo.

4. **Preencha os Dados Fiscais do Cabeçalho** Com a instalação do
   módulo, novos campos fiscais aparecerão no cabeçalho da fatura.

   - **Tipo de Documento**: Selecione o modelo do documento fiscal. Para
     uma NF-e, por exemplo, escolha **``55 - Nota Fiscal Eletrônica``**.
   - **Operação Fiscal**: Este é um campo chave. Ele define a natureza
     da transação. Selecione uma operação compatível, como
     **``Venda de Mercadoria``**.

5. **Adicione as Linhas da Fatura** Na aba ``Linhas da Fatura``, clique
   em ``Adicionar uma linha``.

   - Selecione um produto. Usando os dados de demonstração, você pode
     escolher o produto **``[E-COM08] Storage Box``**.
   - Observe que, ao selecionar o produto, os campos fiscais da linha,
     como ``Operação Fiscal da Linha`` e ``Impostos``, são preenchidos
     automaticamente com base nas regras da Operação Fiscal principal.
     Os impostos são calculados e exibidos em tempo real.

Visualizando e Editando os Detalhes Fiscais da Linha
----------------------------------------------------

A grade de linhas da fatura oferece uma visão simplificada. Para acessar
todos os detalhes fiscais de uma linha ou para editar manualmente algum
campo (como um NCM ou CST específico para aquela operação), você pode
usar o modo de edição em pop-up.

- Clique no ícone de **"abrir registro externo" (um quadrado com uma
  seta)**, localizado à esquerda da linha do produto na grade editável.
- Uma janela pop-up se abrirá, exibindo o formulário completo da linha.
  Nele, você encontrará a aba **``Impostos``**, que contém o
  detalhamento completo dos cálculos para cada tributo (ICMS, IPI, PIS,
  COFINS, etc.).

Verificando os Lançamentos Contábeis
------------------------------------

Após preencher a fatura, você pode (e deve) inspecionar os lançamentos
contábeis que serão gerados.

1. Acesse a aba **``Lançamentos Contábeis``**.
2. Nesta aba, você verá todas as contas que serão movimentadas,
   incluindo as linhas específicas para cada imposto (débito de impostos
   a recuperar, crédito de impostos a recolher, etc.), refletindo o
   resultado dos cálculos do motor fiscal.

..

   **Nota Importante**: Para usuários da versão Community do Odoo, a aba
   ``Lançamentos Contábeis`` pode estar oculta por padrão. A instalação
   do módulo **``account_usability``** (disponível no repositório
   ``OCA/account-financial-tools``) é fortemente recomendada para
   torná-la visível e facilitar a análise contábil.

Após a conferência, você pode ``Confirmar`` a fatura para gerar os
lançamentos contábeis e prosseguir com a transmissão do documento
fiscal, caso seja um documento eletrônico.

Acessando a Visão Fiscal Detalhada
----------------------------------

No canto superior direito do formulário da fatura, você encontrará um
*smart button* chamado **Detalhe Fiscal**.

Clicar neste botão permite navegar diretamente para a tela do
``l10n_br_fiscal.document``, que oferece uma visão completa e focada nos
aspectos puramente fiscais. Nesta tela, é possível consultar detalhes
aprofundados, gerenciar o ciclo de vida do documento (cancelamento,
carta de correção) e, para documentos eletrônicos, acompanhar todo o
histórico de comunicação e o status de transmissão junto à SEFAZ.

Known issues / Roadmap
======================



Changelog
=========



Bug Tracker
===========

Bugs are tracked on `GitHub Issues <https://github.com/OCA/l10n-brazil/issues>`_.
In case of trouble, please check there if your issue has already been reported.
If you spotted it first, help us to smash it by providing a detailed and welcomed
`feedback <https://github.com/OCA/l10n-brazil/issues/new?body=module:%20l10n_br_account%0Aversion:%2017.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.

Do not contact contributors directly about support or help with technical issues.

Credits
=======

Authors
-------

* Akretion

Contributors
------------

- `Akretion <https://akretion.com/pt-BR>`__:

  - Renato Lima <renato.lima@akretion.com.br>
  - Raphaël Valyi <raphael.valyi@akretion.com.br>

- `KMEE <https://www.kmee.com.br>`__:

  - Luis Felipe Mileo <mileo@kmee.com.br>

- `Escodoo <https://www.escodoo.com.br>`__:

  - Marcel Savegnago <marcel.savegnago@escodoo.com.br>

- `Engenere <https://engenere.one>`__:

  - Antônio S. Pereira Neto <neto@engenere.one>
  - Felipe Motter Pereira <felipe@engenere.one>

Maintainers
-----------

This module is maintained by the OCA.

.. image:: https://odoo-community.org/logo.png
   :alt: Odoo Community Association
   :target: https://odoo-community.org

OCA, or the Odoo Community Association, is a nonprofit organization whose
mission is to support the collaborative development of Odoo features and
promote its widespread use.

.. |maintainer-renatonlima| image:: https://github.com/renatonlima.png?size=40px
    :target: https://github.com/renatonlima
    :alt: renatonlima
.. |maintainer-rvalyi| image:: https://github.com/rvalyi.png?size=40px
    :target: https://github.com/rvalyi
    :alt: rvalyi

Current `maintainers <https://odoo-community.org/page/maintainer-role>`__:

|maintainer-renatonlima| |maintainer-rvalyi| 

This module is part of the `OCA/l10n-brazil <https://github.com/OCA/l10n-brazil/tree/17.0/l10n_br_account>`_ project on GitHub.

You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.
