Framework genérico para monitoramento de documentos fiscais eletrônicos recebidos via os web services de Distribuição de DF-e da SEFAZ (Ambiente Nacional).
Este módulo é agnóstico ao tipo de documento fiscal: ele implementa toda a lógica comum de distribuição DF-e — paginação de NSUs, agendamento inteligente baseado na resposta da SEFAZ (138, 137, 656), desduplicação, notificações, logs SOAP e o painel (banner) — parametrizado por tipo de documento (fiscal_type).
Os módulos específicos implementam apenas o que é particular de cada documento fiscal:
- l10n_br_nfe_dfe — DF-e de NF-e (NFeDistribuicaoDFe, NT 2014.002)
- l10n_br_cte_dfe — DF-e de CT-e (CTeDistribuicaoDFe) — futuro
Funcionalidades genéricas:
- Motor de distribuição em res.company, parametrizado por fiscal_type (campos {fiscal_type}_last_nsu, {fiscal_type}_max_nsu, {fiscal_type}_dfe_last_query, etc. definidos pelos módulos específicos)
- Modelos genéricos: l10n_br_fiscal_dfe.dfe (payload XML por NSU) e l10n_br_fiscal_dfe.document (documento agrupado por chave de acesso)
- Consulta manual — assistente de busca específica por chave de acesso (com validação do dígito verificador) ou por NSU
- Painel (banner) genérico — componente Owl DfeBanner, alimentado por res.company.dfe_get_banner_data(fiscal_type), exibido nas listas dos módulos específicos via a js_class dfe_document_list
- Notificações no Inbox — notifica usuários sobre novos documentos de terceiros (preferência por usuário)
- Matching automático de parceiro pelo CNPJ da chave de acesso
- Log de distribuição com request/response SOAP para depuração
- Suporte multi-empresa com record rules
- Canal queue_job root.dfe para as consultas automáticas
auto_awesome What this module does
AI-generated from the code · Odoo 18.0Monitors incoming Brazilian electronic fiscal documents (DF-e) received from SEFAZ, storing them in an inbox where users can view, download XMLs, match partners and import them. It adds a banner on the document list with query status and buttons to search all or specific documents.
This module provides the shared engine to fetch electronic fiscal documents (DF-e) from the SEFAZ distribution web service. It is document-type agnostic and works for NF-e and CT-e.
Users get a new menu area with three lists: Third-party Documents (the inbox of received documents), DF-e Records (each raw payload received, with NSU, type, event and pretty XML), and Distribution Logs (SOAP request/response and messages).
On the document list a banner shows the last query, next scheduled query, last status, NSU progress, whether the NSU is synced, today's third-party count, pending imports and an inactivity warning. From it users can trigger a full search or open a wizard to search a specific document by access key or NSU.
Business rules: documents are deduplicated by NSU or access key; the next query is scheduled automatically based on the SEFAZ status code (success, no documents, rate limited, error); a cooldown blocks manual searches too soon; the company CNPJ is compared with the access key to flag own documents; the partner is matched by CNPJ; and opted-in users receive inbox notifications for new third-party documents. A scheduled job runs the distribution automatically for companies with auto-fetch enabled. Users can download a single XML or a zip of complete XMLs, and import or generate PDFs through the document-type specific modules.
Depends on
Required by other modules
Menus it adds
Models and fields (6)
- res.users · extends an existing modeldfe_notification (DF-e Notification)
- res.company · extends an existing model
- l10n_br_fiscal_dfe.dfe · new modelnsu (NSU), access_key, company_id (Company), xml_pretty (XML Pretty), fiscal_type, schema_type, attachment_id, event_type_dfe (Event Type), operation_type, dfe_document_id (DF-e Document), document_type_dfe (DF-e Type), event_type_dfe_label (Event)
- dfe.specific.search.wizard · new modelnsu (NSU), access_key, company_id (Company), fiscal_type, search_type
- l10n_br_fiscal_dfe.document · new modelvat (CNPJ/CPF), serie, dfe_ids (DF-e records), emitter, access_key, company_id, partner_id (Partner), currency_id, fiscal_type, color_status, document_state (State Code), document_amount (Document Total Value), document_number, is_own_document (Own Document), fiscal_document_id (Fiscal Document), document_state_label (State), document_emission_date (Emission Date)
- l10n_br_fiscal_dfe.distribution_log · new modelmessage, log_type, company_id, fiscal_type, request_xml (SOAP Request), response_xml (SOAP Response)
Text generated by AI (DeepSeek) from reading the Odoo 18.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-03Confirmation status: 5 confirmed, 4 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 18.0Installation
Source · Odoo 18.0Dependências Python
erpbrasil.base— validação de chave de acesso (dígito verificador)
Os módulos específicos declaram suas próprias dependências (ex.: l10n_br_nfe_dfe requer nfelib e brazilfiscalreport).
queue_job como server wide module
O queue_job precisa ser carregado na inicialização do Odoo. Adicione na configuração do servidor:
[options]
server_wide_modules = web,queue_jobOu via variável de ambiente:
SERVER_WIDE_MODULES=web,queue_jobEm produção, o Odoo deve rodar com workers > 0 para que o jobrunner inicie como processo dedicado.
Com --workers=0 (modo threaded / desenvolvimento), o queue_job funciona normalmente — ele cria uma thread extra no mesmo processo.
Configuration
Source · Odoo 18.0Canal queue_job
O módulo registra os jobs de distribuição DF-e no canal root.dfe. É obrigatório configurar este canal com capacidade máxima de 1 job simultâneo, caso contrário consultas concorrentes à SEFAZ podem causar erro 656 (consumo indevido) e bloqueio temporário do CNPJ.
No arquivo de configuração do Odoo:
[queue_job]
channels = root:2,root.dfe:1Ou via variável de ambiente:
ODOO_QUEUE_JOB_CHANNELS=root:2,root.dfe:1Configuração da empresa
A configuração por empresa (ambiente, busca automática, NSU, etc.) é feita nos módulos específicos de cada documento fiscal (ex.: aba NF-e DF-e do módulo l10n_br_nfe_dfe).
Notificações
Cada usuário pode ativar a preferência DF-e Notification em Preferências para receber notificações no Inbox quando novos documentos de terceiros forem encontrados.
Usage
Source · Odoo 18.0Este módulo é uma base técnica. O uso funcional acontece nos módulos específicos de cada documento fiscal:
- NF-e: instale
l10n_br_nfe_dfee acesse Faturamento > Consultas DF-e > NF-e de Terceiros.
O menu Faturamento > Consultas DF-e também dá acesso às visões genéricas (todos os documentos, registros DF-e brutos e logs de distribuição) para depuração.
Installation instructions, the distribution package, dependencies and configuration steps are not shown because they have not yet been verified in the module documentation for any version.
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.