Metadata-Version: 2.1
Name: odoo-addon-l10n_br_nfse_spec
Version: 16.0.1.1.0.4
Requires-Python: >=3.10
Requires-Dist: odoo>=16.0a,<16.1dev
Summary: NFS-e abstract models generated by xsdata-odoo from the official xsd
Home-page: https://github.com/OCA/l10n-brazil
License: LGPL-3
Author: Akretion, Odoo Community Association (OCA)
Author-email: support@odoo-community.org
Classifier: Programming Language :: Python
Classifier: Framework :: Odoo
Classifier: Framework :: Odoo :: 16.0
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Development Status :: 3 - Alpha
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

=====================
NFS-e abstract models
=====================

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

.. |badge1| image:: https://img.shields.io/badge/maturity-Alpha-red.png
    :target: https://odoo-community.org/page/development-status
    :alt: Alpha
.. |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_nfse_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_nfse_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 de Serviços
Eletrônica de padrão nacional (``NFS-e``, Sistema Nacional NFS-e) no
Odoo, fornecendo uma estrutura de dados completa e fiel ao leiaute
oficial 1.00.

É importante entender que este módulo atua como uma biblioteca de
modelos abstratos (mixins) e não realiza a emissão da NFS-e por si só.
Sua finalidade é ser a base para um módulo de implementação, como o
``l10n_br_nfse_nacional``, que é responsável por mapear esses modelos
nos documentos fiscais do Odoo (``l10n_br_fiscal.document``) e
comunicar-se com o ambiente nacional (Sefin Nacional / ADN). 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.

No padrão nacional, o contribuinte gera e assina uma ``DPS`` (Declaração
de Prestação de Serviços) e o ambiente nacional retorna a ``NFS-e``
autorizada, que encapsula a DPS.

Estrutura e Principais Conceitos da NFS-e
-----------------------------------------

O módulo ``l10n_br_nfse_spec`` mapeia a estrutura hierárquica da DPS e
da NFS-e. Os conceitos mais importantes implementados são:

- Identificação da DPS (``infDPS``): O cabeçalho da declaração, com
  município emitente, série, número, datas e ambiente.
- Prestador e Tomador (``prest``, ``toma``): Modelos para os dados
  cadastrais do prestador e do tomador do serviço, incluindo endereço
  nacional (``endNac``) ou exterior (``endExt``) e o regime de
  tributação (``regTrib``).
- Serviço (``serv``): O detalhamento do serviço prestado, com o local da
  prestação (``locPrest``) e a sua codificação (``cServ``): código de
  tributação nacional, código de tributação municipal e código NBS.
- Valores (``valores``): O valor do serviço (``vServPrest``), os
  descontos (``vDescCondIncond``) e a tributação — municipal/ISSQN
  (``tribMun``), federal e PIS/COFINS (``tribNac``) e o total de
  tributos (``tribTotal``).
- Eventos: As estruturas para os eventos da NFS-e (como o cancelamento),
  igualmente geradas a partir dos esquemas oficiais.

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 Sistema Nacional NFS-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 NFS-e sejam publicados e mantidos
pela Receita Federal, 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 1.00 da NFS-e foi:

.. code:: bash

   git clone https://github.com/akretion/nfelib
   cd nfelib
   export XSDATA_SCHEMA=nfse
   export XSDATA_VERSION=10
   export XSDATA_LANG="portuguese"

   xsdata generate nfelib/nfse/schemas/v1_0 \
     --package nfelib.nfse.odoo.v1_0 \
     --output=odoo

   mv nfelib/odoo/nfse/v1_0 <caminho_do_odoo>/l10n_br_nfse_spec/models/v1_0

Prefixo dos campos e versão
---------------------------

Com centenas de campos fiscais, 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, podemos ter várias
versões da NFS-e.

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 ``nfse10_``. 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 de versão, 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.

.. IMPORTANT::
   This is an alpha version, the data model and design can change at any time without warning.
   Only for development or testing purpose, do not use in production.
   `More details on development status <https://odoo-community.org/page/development-status>`_

**Table of contents**

.. contents::
   :local:

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_nfse_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_nfse_spec>`_ project on GitHub.

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