OdooWiki OCA HUB

Common EDI fiscal features

l10n_br_fiscal_edi folder_open OCA/l10n-brazil open_in_new
Localisation License: AGPL-3

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):

auto_awesome What this module does

AI-generated from the code · Odoo 19.0

Adds a controlled lifecycle for Brazilian electronic fiscal documents (NF-e, NFC-e, CT-e, MDF-e, NFS-e), with buttons to confirm, send, cancel, correct and invalidate numbers, plus a log of fiscal events and their XML files.

This module gives Brazilian electronic fiscal documents a strict, step-by-step status flow so they cannot jump to an invalid state. A document moves from draft to confirmed, then sending, then authorized, rejected or denied, and can be cancelled or invalidated. Each change is checked, and an invalid move is blocked with an error message.

On the fiscal document screen users get buttons to confirm, send, return to draft, cancel, create a correction letter and invalidate a number. Cancelling an authorized document opens a cancellation wizard; corrections and number invalidation open their own wizards. A "Check status" action asks the tax authority about selected documents in small batches and shows a notification summarising what changed, what stayed the same and what failed.

Every exchange with the tax authority is stored as a fiscal event, with its type (authorization, cancellation, correction letter, consultation, etc.), response message, protocol number and date, and the request and response XML files. Events can be printed as a report. The document also keeps links to its authorization, cancellation and invalidation events and their XML files, and users can open the XML or the PDF report in a new tab.

Business rules: the issuer is mandatory for electronic documents; a document access key must be valid and unique per company and issuer; correction justifications need at least 15 characters; a document already recorded as cancelled for SPED cannot go back to draft; and a document whose XML failed schema validation cannot be transmitted.

New menus "Fiscal Event" and "Invalidate Number" appear under the fiscal documents menu. The fiscal operation dashboard counts confirmed-but-not-sent, sending and rejected documents as still to confirm, and denied ones as cancelled.

Depends on

l10n_br_fiscal

Required by other modules

l10n_br_ctel10n_br_fiscal_closingl10n_br_fiscal_notificationl10n_br_fiscal_queuel10n_br_fiscal_subsequent_documentl10n_br_mdfel10n_br_nfel10n_br_nfse

Menus it adds

Invalidate NumberFiscal Event
Models and fields (8)
  • l10n_br_fiscal.event · new modeltype (Service), state (Status), origin (Source Document), message, response (Response Message), sequence, file_path, company_id (Company), partner_id (Partner), write_date, create_date, document_id (Fiscal Document), environment, status_code, display_name (name), justification, protocol_date, document_number, file_request_id (XML), protocol_number, document_type_id (Fiscal Document Type), file_response_id (XML Response), document_serie_id, lot_receipt_number, invalidate_number_id (Invalidate Number)
  • l10n_br_fiscal.document · extends an existing modelissuer, event_ids (Events), state_edoc, cancel_date (Cancel Protocol Date), status_code, status_name, send_file_id (Send Document File XML), cancel_reason, cancel_file_id (Cancel File XML), file_report_id (Document Report), cancel_event_id (Cancel Event), invalidate_date (Invalidate Protocol Date), is_edoc_printed (Is Printed?), document_version (Version), correction_reason, xml_error_message (XML validation errors), authorization_date (Authorization Protocol Date), invalidate_file_id (Invalidate File XML), status_description, invalidate_event_id (Invalidate Event), correction_event_ids (Correction Events), original_xml_file_id (Original XML File), authorization_file_id (Authorization File XML), authorization_event_id (Authorization Event), authorization_protocol (Authorization Protocol Number), cancel_protocol_number (Cancel Protocol Protocol), invalidate_protocol_number (Invalidate Protocol Number)
  • l10n_br_fiscal.document.related · extends an existing model
  • l10n_br_fiscal.base.wizard.mixin · extends an existing modelevent_id (Fiscal Event)
  • l10n_br_fiscal.invalidate.number · extends an existing modelevent_ids (Events), send_file_id (Send Document File XML), authorization_date (Authorization Date), authorization_file_id (Authorization File XML), authorization_event_id (Authorization Event), authorization_protocol (Authorization Protocol)
  • l10n_br_fiscal.document.cancel.wizard · new model
  • l10n_br_fiscal.invalidate.number.wizard · new model
  • l10n_br_fiscal.document.correction.wizard · new model

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-03
Confirmed (verified in repository and branch) Estimated (unverified) No information

Confirmation status: 6 confirmed, 3 with no information of 9 versions.

Sources · Odoo 17.0

Confirmed on 2026-11-03 in branch 17.0 of OCA/l10n-brazil.

terminal Installation and usage

OCA documentation · Odoo 19.0

Usage

Source · Odoo 19.0

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

  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.

No verified information in OCA: Installation, Configuration.

info

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.