Metadata-Version: 2.1
Name: odoo-addon-l10n_br_fiscal_edi
Version: 19.0.1.0.0.2
Requires-Dist: odoo-addon-l10n_br_fiscal==19.0.*
Requires-Dist: odoo==19.0.*
Requires-Dist: transitions
Summary: Common EDI fiscal features
Home-page: https://github.com/OCA/l10n-brazil
License: AGPL-3
Author: Akretion, KMEE, Odoo Community Association (OCA)
Author-email: support@odoo-community.org
Classifier: Programming Language :: Python
Classifier: Framework :: Odoo
Classifier: Framework :: Odoo :: 19.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

==========================
Common EDI fiscal features
==========================

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

.. |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/19.0/l10n_br_fiscal_edi
    :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-19-0/l10n-brazil-19-0-l10n_br_fiscal_edi
    :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=19.0
    :alt: Try me on Runboat

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

Este módulo fornece a infraestrutura base para o Intercâmbio Eletrônico
de Dados (EDI) de documentos fiscais brasileiros no Odoo.

Ele implementa uma Máquina de Estados Finitos (FSM - Finite State
Machine) para gerenciar o ciclo de vida dos documentos fiscais
eletrônicos (NF-e, NFC-e, NFS-e, CT-e, MDF-e etc.), garantindo
integridade, consistência e rastreabilidade das transições de estado.

Principais Características
--------------------------

- **Máquina de Estados (FSM):** controle rigoroso das transições de
  estado (por exemplo, de ``draft`` para ``open``, depois para
  ``sending`` e finalmente para ``authorized``, ``rejected`` ou
  ``denied``), com bloqueio de movimentos inválidos.
- **Configuração extensível por documento:** a FSM base é definida no
  método ``get_state_machine_config()`` e pode ser sobrescrita por
  módulos específicos de documento fiscal para ajustar estados,
  transições e callbacks.
- **Gerenciamento de Eventos:** arquitetura para suportar eventos
  fiscais vinculados ao documento, como Cancelamento, Carta de Correção
  Eletrônica (CC-e) e Inutilização de Numeração.
- **Abstração de Protocolo:** separa a lógica de negócios da lógica de
  comunicação. Módulos específicos (como ``l10n_br_nfe`` ou
  ``l10n_br_nfse``) herdam deste módulo para implementar a integração
  com webservices (SEFAZ/Prefeituras), enquanto o ``l10n_br_fiscal_edi``
  orquestra o fluxo.
- **Interface Padronizada:** oferece uma experiência consistente com
  botões e ações uniformes, independentemente do modelo de documento
  fiscal.

Workflow de Estados
-------------------

O diagrama abaixo ilustra os estados e transições padrão definidos no
módulo base (a configuração pode ser estendida/sobrescrita por módulos
filhos):

|FSM state diagram|

.. |FSM state diagram| image:: https://raw.githubusercontent.com/OCA/l10n-brazil/19.0/l10n_br_fiscal_edi/static/description/fsm_graph.png

**Table of contents**

.. contents::
   :local:

Usage
=====

O fluxo operacional para emissão e gerenciamento de documentos fiscais
(eletrônicos e não eletrônicos) segue as etapas abaixo.

1. Validação (``draft`` -> ``open``)

--------------

- O documento inicia no estado **Rascunho** (``draft``).
- Ao clicar no botão **Confirmar**, o sistema executa validações de
  integridade, define data, comentário, numeração/sequência (quando
  aplicável) e demais preparações do documento.
- O estado muda para **Em Aberto** (``open``), indicando que o documento
  está apto para o próximo passo.

2. Transmissão (``open`` -> ``sending`` -> resultado)

--------------

- No estado **Em Aberto**, o botão **Enviar** fica disponível.

- Ao enviar, o documento vai para o estado transitório **Enviando**
  (``sending``), e a camada de integração executa a comunicação com o
  fisco.

- Possíveis resultados padrão:

  - **Autorizado** (``authorized``): autorização concluída com protocolo
    e XML de retorno.
  - **Rejeitado** (``rejected``): erros de validação retornados pelo
    fisco. O usuário corrige o documento e pode enviar novamente.
  - **Denegado** (``denied``): irregularidade fiscal. Em geral,
    representa um estado final para aquela numeração.

- Observação: para documentos não eletrônicos (ou sem processador), o
  fluxo de envio pode finalizar diretamente em **Autorizado** conforme a
  implementação.

3. Cancelamento (``*`` -> ``cancel``)

--------------

- O estado **Cancelado** (``cancel``) pode ser atingido a partir de
  múltiplos estados no fluxo base (``authorized``, ``open``,
  ``rejected``, ``draft``, ``sending``).
- Para documentos autorizados eletrônicos emitidos pela empresa, a ação
  de cancelar abre assistente próprio para coleta/processamento da
  justificativa.
- Para documentos ainda não autorizados, o cancelamento pode ocorrer
  diretamente no fluxo local.

4. Retorno para Rascunho (``*`` -> ``draft``)

--------------

- O fluxo base permite retornar para **Rascunho** (``draft``) a partir
  de ``open``, ``sending``, ``rejected``, ``cancel``, ``denied`` e
  também de ``draft`` (idempotente).
- Essa ação limpa informações transitórias de erro/relatório para
  permitir nova preparação do documento.

5. Eventos e correções

--------------

- **Carta de Correção (CC-e):** para documentos autorizados que suportam
  o evento.
- **Inutilização de Numeração:** para faixas de numeração não
  utilizadas, conforme regras fiscais aplicáveis.

6. Extensão do workflow por módulo fiscal

--------------

A FSM deste módulo é projetada para extensão. Módulos de tipos fiscais
específicos podem sobrescrever ``get_state_machine_config()`` e
callbacks relacionados para:

- incluir estados adicionais;
- alterar transições válidas;
- personalizar regras de pré/pós-transição;
- adaptar o fluxo ao comportamento dos webservices de cada documento.

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_fiscal_edi%0Aversion:%2019.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
* KMEE

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

- `Akretion <https://www.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>

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
.. |maintainer-mileo| image:: https://github.com/mileo.png?size=40px
    :target: https://github.com/mileo
    :alt: mileo

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

|maintainer-renatonlima| |maintainer-rvalyi| |maintainer-mileo| 

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

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