.. image:: https://odoo-community.org/readme-banner-image
:target: https://odoo-community.org/get-involved?utm_source=readme
:alt: Odoo Community Association
====================
NF-e abstract models
====================
..
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!! This file is generated by oca-gen-addon-readme !!
!! changes will be overwritten. !!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!! source digest: sha256:6e982bdff2a9286de055ca5430dfce1f1ace448eabc1095b605f660a40e23410
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
.. |badge1| image:: https://img.shields.io/badge/maturity-Mature-brightgreen.png
:target: https://odoo-community.org/page/development-status
:alt: Mature
.. |badge2| image:: https://img.shields.io/badge/license-LGPL--3-blue.png
:target: http://www.gnu.org/licenses/lgpl-3.0-standalone.html
:alt: License: LGPL-3
.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fl10n--brazil-lightgray.png?logo=github
:target: https://github.com/OCA/l10n-brazil/tree/16.0/l10n_br_nfe_spec
: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-16-0/l10n-brazil-16-0-l10n_br_nfe_spec
: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=16.0
:alt: Try me on Runboat
|badge1| |badge2| |badge3| |badge4| |badge5|
Este módulo é a fundação para a emissão da Nota Fiscal Eletrônica
(``NF-e`` modelo ``55`` e ``NFC-e`` modelo ``65``) no Odoo, fornecendo
uma estrutura de dados completa e fiel ao leiaute oficial 4.0 da SEFAZ.
É importante entender que este módulo atua como uma biblioteca de
modelos abstratos (mixins) e não realiza a emissão da NF-e por si só.
Sua finalidade é ser a base para um módulo de implementação, como o
``l10n_br_nfe``, que é responsável por mapear esses modelos nos
documentos fiscais do Odoo (``l10n_br_fiscal.document``) e comunicar-se
com os web services da SEFAZ. Esta arquitetura, que separa a estrutura
de dados da lógica de emissão, é a mesma utilizada com sucesso nos
outros documentos fiscais eletrônicos da localização brasileira.
Estrutura e Principais Conceitos da NF-e
----------------------------------------
O módulo ``l10n_br_nfe_spec`` mapeia com precisão a complexa estrutura
hierárquica da NF-e. Os conceitos mais importantes implementados são:
- Identificação (``ide``): O cabeçalho da nota, contendo informações
como modelo, série, número, datas, finalidade e tipo de operação.
- Emitente e Destinatário (``emit``, ``dest``): Modelos detalhados para
os dados cadastrais completos do emissor e do recebedor da mercadoria.
- Itens da Nota (``det``): O coração da NF-e, um grupo repetível para
cada produto ou serviço, contendo descrição, NCM, CFOP, quantidades e
valores.
- Impostos (``imposto``): Dentro de cada item, há uma estrutura complexa
para o detalhamento de todos os tributos incidentes (ICMS, IPI, PIS,
COFINS, etc.).
- Totais (``total``): Contém o grupo ICMSTot com a consolidação de todas
as bases de cálculo e valores de impostos da nota.
- Transporte (``transp``): Modelos para informar a modalidade do frete,
os dados da transportadora, do veículo e dos volumes transportados.
- Pagamento (``pag``): Estrutura para detalhar as formas de pagamento
(detPag), incluindo informações de cartões, PIX e boletos.
Geração de Código Automatizada
------------------------------
A principal característica deste módulo é que 100% dos seus modelos de
dados Odoo são gerados automaticamente a partir dos esquemas XSD
oficiais, publicados pelo Portal da NF-e. Essa geração pelo
``xsdata-odoo`` garante máxima fidelidade aos leiautes fiscais e
agilidade na atualização para novas versões.
Embora os esquemas XSD oficiais da NF-e sejam publicados e mantidos no
Portal da SEFAZ, a arquitetura deste projeto se apoia na biblioteca
``nfelib`` para a tarefa de serialização dos dados em XML. Para
facilitar o processo de desenvolvimento e garantir a consistência, a
própria ``nfelib`` armazena em seu repositório uma cópia atualizada
desses esquemas oficiais.
Portanto, a prática recomendada para (re)gerar os modelos deste módulo é
utilizar um clone local do repositório da ``nfelib`` como fonte para os
arquivos de esquema (.xsd), direcionando o comando do ``xsdata-odoo``
para o diretório correspondente.
Links:
- `GitHub - akretion/xsdata-odoo: Odoo abstract model generator from xsd
schemas using xsdata <https://github.com/akretion/xsdata-odoo>`__
- `GitHub - akretion/nfelib <https://github.com/akretion/nfelib>`__
O comando utilizado para gerar os modelos da versão 4.0 da NF-e foi:
.. code:: bash
git clone https://github.com/akretion/nfelib
cd nfelib
export XSDATA_SCHEMA=nfe
export XSDATA_VERSION=40
export XSDATA_SKIP="^ICMS.ICMS\d+|^ICMS.ICMSSN\d+"
export XSDATA_LANG="portuguese"
xsdata generate nfelib/nfe/schemas/v4_0 \
--package nfelib.nfe.odoo.v4_0 \
--output=odoo
mv nfelib/odoo/nfe/v4_0 <caminho_do_odoo>/l10n_br_nfe_spec/models/v4_0
Prefixo dos campos e versão
---------------------------
Com mais de 800 campos fiscais apenas na NF-e, com uma meia dúzia de
documentos fiscais complexos, com 3000 módulos OCA, existiria um risco
real de conflito com os nomes de campos vindo dos esquemas. Além disso,
temos várias versões da NFe, a 3.1, a 4.0 etc...
Nisso foi decidido que cada campo tem um prefixo composto do nome do
schema e de alguns dígitos da versão do esquema. No caso nfe40\_. A
escolha de 2 dígitos permite que uma atualização menor do esquema use os
mesmos campos (e dados no banco então) e que um simples update Odoo
(--update=...) consiga resolver a migração. Enquanto que para uma
mudança maior como de 3.1 para 4.0, seria assumido de usar novos campos
e novas tabelas (para os objetos não Odoo) e que a lib nfelib iria
trabalhar com os campos da versão maior do documento fiscal considerado.
O Tratamento Específico dos Impostos ICMS e ICMSSN
--------------------------------------------------
Um desafio particular na geração dos modelos da NF-e é a forma como o
ICMS é estruturado no XSD oficial. O esquema define um grupo de tags
para cada CST de ICMS (ex: ICMS00, ICMS10, ICMS40, etc.), muitos dos
quais contêm campos com nomes idênticos (como vBC, pICMS, vICMS).
Se todos esses grupos fossem gerados e injetados no mesmo modelo Odoo,
ocorreriam colisões de nomes de campos. Para resolver isso, o comando de
geração utiliza o parâmetro ``XSDATA_SKIP`` para ignorar explicitamente
essas classes de imposto individuais.
Essa abordagem é a ideal, pois a localização brasileira do Odoo, através
do módulo ``l10n_br_fiscal``, já possui um sistema robusto e genérico
para cálculo e representação de impostos. Portanto, o mapeamento dos
campos de impostos para o XML é uma tarefa que exige uma lógica mais
elaborada, sendo delegada ao módulo de implementação (``l10n_br_nfe``),
que é o local apropriado para tais regras de negócio.
**Table of contents**
.. contents::
:local:
Installation
============
Configuration
=============
Usage
=====
Known issues / Roadmap
======================
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_nfe_spec%0Aversion:%2016.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>`__:
- Raphaël Valyi <raphael.valyi@akretion.com.br>
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-rvalyi| image:: https://github.com/rvalyi.png?size=40px
:target: https://github.com/rvalyi
:alt: rvalyi
Current `maintainer <https://odoo-community.org/page/maintainer-role>`__:
|maintainer-rvalyi|
This module is part of the `OCA/l10n-brazil <https://github.com/OCA/l10n-brazil/tree/16.0/l10n_br_nfe_spec>`_ project on GitHub.
You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.
Raw data
{
"_id": null,
"home_page": "https://github.com/OCA/l10n-brazil",
"name": "odoo-addon-l10n-br-nfe-spec",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Akretion, Odoo Community Association (OCA)",
"author_email": "support@odoo-community.org",
"download_url": null,
"platform": null,
"description": ".. image:: https://odoo-community.org/readme-banner-image\n :target: https://odoo-community.org/get-involved?utm_source=readme\n :alt: Odoo Community Association\n\n====================\nNF-e abstract models\n====================\n\n.. \n !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\n !! This file is generated by oca-gen-addon-readme !!\n !! changes will be overwritten. !!\n !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\n !! source digest: sha256:6e982bdff2a9286de055ca5430dfce1f1ace448eabc1095b605f660a40e23410\n !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\n\n.. |badge1| image:: https://img.shields.io/badge/maturity-Mature-brightgreen.png\n :target: https://odoo-community.org/page/development-status\n :alt: Mature\n.. |badge2| image:: https://img.shields.io/badge/license-LGPL--3-blue.png\n :target: http://www.gnu.org/licenses/lgpl-3.0-standalone.html\n :alt: License: LGPL-3\n.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fl10n--brazil-lightgray.png?logo=github\n :target: https://github.com/OCA/l10n-brazil/tree/16.0/l10n_br_nfe_spec\n :alt: OCA/l10n-brazil\n.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png\n :target: https://translation.odoo-community.org/projects/l10n-brazil-16-0/l10n-brazil-16-0-l10n_br_nfe_spec\n :alt: Translate me on Weblate\n.. |badge5| image:: https://img.shields.io/badge/runboat-Try%20me-875A7B.png\n :target: https://runboat.odoo-community.org/builds?repo=OCA/l10n-brazil&target_branch=16.0\n :alt: Try me on Runboat\n\n|badge1| |badge2| |badge3| |badge4| |badge5|\n\nEste m\u00f3dulo \u00e9 a funda\u00e7\u00e3o para a emiss\u00e3o da Nota Fiscal Eletr\u00f4nica\n(``NF-e`` modelo ``55`` e ``NFC-e`` modelo ``65``) no Odoo, fornecendo\numa estrutura de dados completa e fiel ao leiaute oficial 4.0 da SEFAZ.\n\n\u00c9 importante entender que este m\u00f3dulo atua como uma biblioteca de\nmodelos abstratos (mixins) e n\u00e3o realiza a emiss\u00e3o da NF-e por si s\u00f3.\nSua finalidade \u00e9 ser a base para um m\u00f3dulo de implementa\u00e7\u00e3o, como o\n``l10n_br_nfe``, que \u00e9 respons\u00e1vel por mapear esses modelos nos\ndocumentos fiscais do Odoo (``l10n_br_fiscal.document``) e comunicar-se\ncom os web services da SEFAZ. Esta arquitetura, que separa a estrutura\nde dados da l\u00f3gica de emiss\u00e3o, \u00e9 a mesma utilizada com sucesso nos\noutros documentos fiscais eletr\u00f4nicos da localiza\u00e7\u00e3o brasileira.\n\nEstrutura e Principais Conceitos da NF-e\n----------------------------------------\n\nO m\u00f3dulo ``l10n_br_nfe_spec`` mapeia com precis\u00e3o a complexa estrutura\nhier\u00e1rquica da NF-e. Os conceitos mais importantes implementados s\u00e3o:\n\n- Identifica\u00e7\u00e3o (``ide``): O cabe\u00e7alho da nota, contendo informa\u00e7\u00f5es\n como modelo, s\u00e9rie, n\u00famero, datas, finalidade e tipo de opera\u00e7\u00e3o.\n- Emitente e Destinat\u00e1rio (``emit``, ``dest``): Modelos detalhados para\n os dados cadastrais completos do emissor e do recebedor da mercadoria.\n- Itens da Nota (``det``): O cora\u00e7\u00e3o da NF-e, um grupo repet\u00edvel para\n cada produto ou servi\u00e7o, contendo descri\u00e7\u00e3o, NCM, CFOP, quantidades e\n valores.\n- Impostos (``imposto``): Dentro de cada item, h\u00e1 uma estrutura complexa\n para o detalhamento de todos os tributos incidentes (ICMS, IPI, PIS,\n COFINS, etc.).\n- Totais (``total``): Cont\u00e9m o grupo ICMSTot com a consolida\u00e7\u00e3o de todas\n as bases de c\u00e1lculo e valores de impostos da nota.\n- Transporte (``transp``): Modelos para informar a modalidade do frete,\n os dados da transportadora, do ve\u00edculo e dos volumes transportados.\n- Pagamento (``pag``): Estrutura para detalhar as formas de pagamento\n (detPag), incluindo informa\u00e7\u00f5es de cart\u00f5es, PIX e boletos.\n\nGera\u00e7\u00e3o de C\u00f3digo Automatizada\n------------------------------\n\nA principal caracter\u00edstica deste m\u00f3dulo \u00e9 que 100% dos seus modelos de\ndados Odoo s\u00e3o gerados automaticamente a partir dos esquemas XSD\noficiais, publicados pelo Portal da NF-e. Essa gera\u00e7\u00e3o pelo\n``xsdata-odoo`` garante m\u00e1xima fidelidade aos leiautes fiscais e\nagilidade na atualiza\u00e7\u00e3o para novas vers\u00f5es.\n\nEmbora os esquemas XSD oficiais da NF-e sejam publicados e mantidos no\nPortal da SEFAZ, a arquitetura deste projeto se apoia na biblioteca\n``nfelib`` para a tarefa de serializa\u00e7\u00e3o dos dados em XML. Para\nfacilitar o processo de desenvolvimento e garantir a consist\u00eancia, a\npr\u00f3pria ``nfelib`` armazena em seu reposit\u00f3rio uma c\u00f3pia atualizada\ndesses esquemas oficiais.\n\nPortanto, a pr\u00e1tica recomendada para (re)gerar os modelos deste m\u00f3dulo \u00e9\nutilizar um clone local do reposit\u00f3rio da ``nfelib`` como fonte para os\narquivos de esquema (.xsd), direcionando o comando do ``xsdata-odoo``\npara o diret\u00f3rio correspondente.\n\nLinks:\n\n- `GitHub - akretion/xsdata-odoo: Odoo abstract model generator from xsd\n schemas using xsdata <https://github.com/akretion/xsdata-odoo>`__\n- `GitHub - akretion/nfelib <https://github.com/akretion/nfelib>`__\n\nO comando utilizado para gerar os modelos da vers\u00e3o 4.0 da NF-e foi:\n\n.. code:: bash\n\n git clone https://github.com/akretion/nfelib\n cd nfelib\n export XSDATA_SCHEMA=nfe\n export XSDATA_VERSION=40\n export XSDATA_SKIP=\"^ICMS.ICMS\\d+|^ICMS.ICMSSN\\d+\"\n export XSDATA_LANG=\"portuguese\"\n\n xsdata generate nfelib/nfe/schemas/v4_0 \\\n --package nfelib.nfe.odoo.v4_0 \\\n --output=odoo\n\n mv nfelib/odoo/nfe/v4_0 <caminho_do_odoo>/l10n_br_nfe_spec/models/v4_0\n\nPrefixo dos campos e vers\u00e3o\n---------------------------\n\nCom mais de 800 campos fiscais apenas na NF-e, com uma meia d\u00fazia de\ndocumentos fiscais complexos, com 3000 m\u00f3dulos OCA, existiria um risco\nreal de conflito com os nomes de campos vindo dos esquemas. Al\u00e9m disso,\ntemos v\u00e1rias vers\u00f5es da NFe, a 3.1, a 4.0 etc...\n\nNisso foi decidido que cada campo tem um prefixo composto do nome do\nschema e de alguns d\u00edgitos da vers\u00e3o do esquema. No caso nfe40\\_. A\nescolha de 2 d\u00edgitos permite que uma atualiza\u00e7\u00e3o menor do esquema use os\nmesmos campos (e dados no banco ent\u00e3o) e que um simples update Odoo\n(--update=...) consiga resolver a migra\u00e7\u00e3o. Enquanto que para uma\nmudan\u00e7a maior como de 3.1 para 4.0, seria assumido de usar novos campos\ne novas tabelas (para os objetos n\u00e3o Odoo) e que a lib nfelib iria\ntrabalhar com os campos da vers\u00e3o maior do documento fiscal considerado.\n\nO Tratamento Espec\u00edfico dos Impostos ICMS e ICMSSN\n--------------------------------------------------\n\nUm desafio particular na gera\u00e7\u00e3o dos modelos da NF-e \u00e9 a forma como o\nICMS \u00e9 estruturado no XSD oficial. O esquema define um grupo de tags\npara cada CST de ICMS (ex: ICMS00, ICMS10, ICMS40, etc.), muitos dos\nquais cont\u00eam campos com nomes id\u00eanticos (como vBC, pICMS, vICMS).\n\nSe todos esses grupos fossem gerados e injetados no mesmo modelo Odoo,\nocorreriam colis\u00f5es de nomes de campos. Para resolver isso, o comando de\ngera\u00e7\u00e3o utiliza o par\u00e2metro ``XSDATA_SKIP`` para ignorar explicitamente\nessas classes de imposto individuais.\n\nEssa abordagem \u00e9 a ideal, pois a localiza\u00e7\u00e3o brasileira do Odoo, atrav\u00e9s\ndo m\u00f3dulo ``l10n_br_fiscal``, j\u00e1 possui um sistema robusto e gen\u00e9rico\npara c\u00e1lculo e representa\u00e7\u00e3o de impostos. Portanto, o mapeamento dos\ncampos de impostos para o XML \u00e9 uma tarefa que exige uma l\u00f3gica mais\nelaborada, sendo delegada ao m\u00f3dulo de implementa\u00e7\u00e3o (``l10n_br_nfe``),\nque \u00e9 o local apropriado para tais regras de neg\u00f3cio.\n\n**Table of contents**\n\n.. contents::\n :local:\n\nInstallation\n============\n\n\n\nConfiguration\n=============\n\n\n\nUsage\n=====\n\n\n\nKnown issues / Roadmap\n======================\n\n\n\nBug Tracker\n===========\n\nBugs are tracked on `GitHub Issues <https://github.com/OCA/l10n-brazil/issues>`_.\nIn case of trouble, please check there if your issue has already been reported.\nIf you spotted it first, help us to smash it by providing a detailed and welcomed\n`feedback <https://github.com/OCA/l10n-brazil/issues/new?body=module:%20l10n_br_nfe_spec%0Aversion:%2016.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.\n\nDo not contact contributors directly about support or help with technical issues.\n\nCredits\n=======\n\nAuthors\n-------\n\n* Akretion\n\nContributors\n------------\n\n- `Akretion <https://akretion.com/pt-BR>`__:\n\n - Rapha\u00ebl Valyi <raphael.valyi@akretion.com.br>\n\nMaintainers\n-----------\n\nThis module is maintained by the OCA.\n\n.. image:: https://odoo-community.org/logo.png\n :alt: Odoo Community Association\n :target: https://odoo-community.org\n\nOCA, or the Odoo Community Association, is a nonprofit organization whose\nmission is to support the collaborative development of Odoo features and\npromote its widespread use.\n\n.. |maintainer-rvalyi| image:: https://github.com/rvalyi.png?size=40px\n :target: https://github.com/rvalyi\n :alt: rvalyi\n\nCurrent `maintainer <https://odoo-community.org/page/maintainer-role>`__:\n\n|maintainer-rvalyi| \n\nThis module is part of the `OCA/l10n-brazil <https://github.com/OCA/l10n-brazil/tree/16.0/l10n_br_nfe_spec>`_ project on GitHub.\n\nYou are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.\n",
"bugtrack_url": null,
"license": "LGPL-3",
"summary": "NF-e abstract models generated by xsdata-odoo from the official xsd",
"version": "16.0.3.0.0",
"project_urls": {
"Homepage": "https://github.com/OCA/l10n-brazil"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "02e0e792347316beaa362ef6ea98951b38f016d249fae9fb3713e715d585dd95",
"md5": "4592bdb887d5fc4c98c6e401a8c566b6",
"sha256": "fa3e82f44fc4c0646a1be6d595eb15da9ee1d5b39278801b65288523204b468c"
},
"downloads": -1,
"filename": "odoo_addon_l10n_br_nfe_spec-16.0.3.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4592bdb887d5fc4c98c6e401a8c566b6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 135614,
"upload_time": "2025-07-16T06:09:24",
"upload_time_iso_8601": "2025-07-16T06:09:24.652869Z",
"url": "https://files.pythonhosted.org/packages/02/e0/e792347316beaa362ef6ea98951b38f016d249fae9fb3713e715d585dd95/odoo_addon_l10n_br_nfe_spec-16.0.3.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-16 06:09:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "OCA",
"github_project": "l10n-brazil",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "brazilcep",
"specs": []
},
{
"name": "brazilfiscalreport",
"specs": []
},
{
"name": "email-validator",
"specs": []
},
{
"name": "erpbrasil.assinatura",
"specs": [
[
">=",
"1.7.0"
]
]
},
{
"name": "erpbrasil.base",
"specs": [
[
">=",
"2.3.0"
]
]
},
{
"name": "erpbrasil.edoc",
"specs": [
[
">=",
"2.5.2"
]
]
},
{
"name": "erpbrasil.transmissao",
"specs": [
[
">=",
"1.1.0"
]
]
},
{
"name": "nfelib",
"specs": [
[
"<=",
"2.0.7"
]
]
},
{
"name": "num2words",
"specs": []
},
{
"name": "phonenumbers",
"specs": []
},
{
"name": "pyyaml",
"specs": []
},
{
"name": "unidecode",
"specs": []
},
{
"name": "workalendar",
"specs": []
}
],
"lcname": "odoo-addon-l10n-br-nfe-spec"
}
JSON
