Bitconn Fiscal

Accounting/Localizations · v19.0.4.0.0 · OPL-1

Módulo fiscal unificado para emissão de documentos fiscais eletrônicos brasileiros.

Dependências

base, account, mail, product, purchase

Documentação

Módulo Odoo 19 unificado para emissão de documentos fiscais eletrônicos brasileiros: NF-e (modelo 55), NFC-e (modelo 65), NFS-e (multi-provedor), MDF-e e CT-e (modelo 57).

Índice

Visão Geral
Arquitetura de Diretórios
Instalação
Configuração
Prioridade de Configuração Fiscal
Operação
CT-e — Conhecimento de Transporte Eletrônico
Cálculo de Impostos (NF-e / NFC-e)
ICMS no CT-e
Documentação Técnica
Erros Comuns e Solução
Referências

Visão Geral

O módulo bitconn_fiscal é um módulo único que cobre toda a emissão de documentos fiscais eletrônicos brasileiros:

Documento	Modelo	Transporte	Descrição
NF-e	55	SOAP 1.2 (SEFAZ)	Nota Fiscal Eletrônica — leiaute XML 4.00, MOC 7.0
NFC-e	65	SOAP 1.2 (SEFAZ)	Nota Fiscal de Consumidor — QR Code, CSC, DANFE reduzido
NFS-e	—	REST / SOAP	Nota Fiscal de Serviço — Padrão Nacional (SEFIN) e ABRASF
MDF-e	58	SOAP 1.2 (SEFAZ)	Manifesto de Documentos Fiscais Eletrônicos
CT-e	57	SOAP 1.2 (SEFAZ)	Conhecimento de Transporte Eletrônico — leiaute 4.00, modal rodoviário

Funcionalidades

Certificado digital A1 (PKCS#12 / PFX) — validação, leitura e mTLS
Assinatura XML manual (sem dependência do signxml) — RSA-SHA1 (NF-e/NFC-e/MDF-e) e RSA-SHA256 (NFS-e)
Comunicação SOAP/REST com SEFAZ/SEFIN usando certificado mTLS
Emissão via fatura (account.move) ou como nota avulsa (bitconn_fiscal.document)
Suporte a múltiplos documentos fiscais por fatura (split)
Cancelamento via evento SEFAZ / API
Inutilização de faixa de numeração (NF-e/NFC-e)
Carta de Correção Eletrônica (CC-e) — NF-e e CT-e
Impressão de DANFE (NF-e, NFC-e, NFS-e, MDF-e) e DACTE (CT-e)
Importação de XML de CT-e recebidos (com opção de lançamento contábil)
Classificação fiscal configurável (NCM, CFOP, ICMS, PIS, COFINS, IPI)
Tabela de municípios IBGE
Arquitetura multi-provedor NFS-e (Padrão Nacional, ABRASF)
MDF-e com encerramento, vale pedágio e seguro
URLs SEFAZ cobrindo todos os autorizadores: AM, BA, GO, MG, MS, MT, PE, PR, RS, SP, SVRS

Arquitetura de Diretórios

bitconn_fiscal/
├── __manifest__.py
├── requirements.txt
├── README.md
│
├── lib/                                   # Bibliotecas (sem dependência do Odoo)
│   ├── certificate.py                     # Utilitários de certificado PKCS#12 (unificado)
│   ├── xml_signer.py                      # Assinador XML-DSIG unificado (SHA-1/SHA-256)
│   ├── uf_codes.py                        # Mapeamento UF ↔ código IBGE
│   ├── nfe_xml_parser.py                  # Parser XML NF-e (chave, protocolo, etc.)
│   │
│   ├── nfe/                               # NF-e / NFC-e (SEFAZ)
│   │   ├── xml_builder.py                 # Gerador XML <NFe> (leiaute 4.00)
│   │   ├── xml_signer.py                  # Wrapper RSA-SHA1
│   │   ├── sefaz_client.py                # Cliente SOAP 1.2
│   │   ├── sefaz_urls.py                  # URLs por UF/autorizador/ambiente
│   │   ├── http_client.py                 # Transporte HTTP com mTLS
│   │   ├── soap.py                        # Envelope SOAP 1.2
│   │   ├── event_builder.py               # Builder de eventos (cancelamento, CC-e)
│   │   └── schemas/                       # XSD NF-e 4.00
│   │
│   ├── nfse/                              # NFS-e (multi-provedor)
│   │   ├── xml_builder.py                 # Gerador DPS (Padrão Nacional)
│   │   ├── xml_signer.py                  # Wrapper RSA-SHA256
│   │   ├── xml_validator.py               # Validador XSD
│   │   ├── sefin_client.py                # Cliente REST SEFIN (gzip + base64)
│   │   ├── http_client.py                 # Transporte HTTP NFS-e
│   │   ├── schemas/                       # XSD NFS-e (DPS v1.01)
│   │   └── providers/                     # Provedores NFS-e
│   │       ├── base.py                    # Classe base NfseProvider
│   │       ├── registry.py                # Registro de provedores
│   │       ├── nacional.py                # Padrão Nacional (SEFIN/ADN)
│   │       ├── abrasf.py                  # ABRASF genérico
│   │       ├── abrasf_rps_builder.py      # Builder RPS ABRASF
│   │       ├── abrasf_soap_client.py      # Cliente SOAP ABRASF
│   │       └── abrasf_xml_signer.py       # Assinador ABRASF
│   │
│   └── mdfe/                              # MDF-e
│       ├── xml_builder.py                 # Gerador XML <MDFe>
│       ├── xml_validator.py               # Validador XSD
│       ├── client.py                      # Cliente SEFAZ MDF-e
│       ├── event_builder.py               # Builder de eventos MDF-e
│       └── schemas/                       # XSD MDF-e
│
│   └── cte/                               # CT-e (modelo 57)
│       ├── xml_builder.py                 # Gerador XML <CTe> (leiaute 4.00)
│       ├── xml_validator.py               # Validador XSD (cte_v4.00.xsd)
│       ├── client.py                      # Cliente SEFAZ CT-e (SVRS, SP, MG, MT)
│       ├── sefaz_urls.py                  # URLs por UF/autorizador/ambiente CT-e
│       ├── event_builder.py               # Builder de eventos (cancelamento, CC-e)
│       └── schemas/                       # 44 XSDs CT-e 4.00 (SEFAZ oficial)
│
├── models/
│   ├── res_company.py                     # Campos fiscais do emitente
│   ├── res_partner.py                     # Campos fiscais do destinatário
│   ├── product_template.py               # Campos fiscais do produto
│   ├── account_move.py                    # Campos e ações na fatura
│   ├── account_move_line.py               # CFOP/natureza por linha
│   ├── fiscal_document.py                 # Modelo de documento fiscal (NF-e/NFC-e)
│   ├── fiscal_document_line.py            # Linhas do documento fiscal
│   ├── fiscal_document_duplicata.py       # Duplicatas
│   ├── fiscal_document_pagamento.py       # Formas de pagamento
│   ├── mdfe.py                            # Modelo MDF-e
│   ├── mdfe_documento.py                  # Documentos vinculados ao MDF-e
│   ├── mdfe_municipio.py                  # Municípios de percurso
│   ├── mdfe_vale_pedagio.py               # Vale pedágio
│   ├── cte.py                             # Modelo CT-e (bitconn_fiscal.cte)
│   ├── cte_componente.py                  # Componentes de valor da prestação
│   ├── cte_documento.py                   # Documentos transportados
│   ├── municipio.py                       # Tabela de municípios IBGE
│   ├── cfop.py                            # Tabela CFOP
│   ├── ncm.py                             # Tabela NCM
│   └── natureza_operacao.py               # Tabela de naturezas de operação
│
├── wizards/
│   ├── emit_wizard.py                     # Wizard de emissão NF-e/NFC-e
│   ├── cancel_wizard.py                   # Wizard de cancelamento NF-e/NFC-e
│   ├── cce_wizard.py                      # Wizard de CC-e
│   ├── inutilizar_wizard.py               # Wizard de inutilização
│   ├── cancel_mdfe_wizard.py              # Wizard de cancelamento MDF-e
│   ├── encerrar_mdfe_wizard.py            # Wizard de encerramento MDF-e
│   ├── cancel_cte_wizard.py               # Wizard de cancelamento CT-e
│   ├── cce_cte_wizard.py                  # Wizard de CC-e CT-e
│   └── import_xml_cte_wizard.py           # Wizard de importação de XML CT-e recebido
│
├── report/
│   ├── report_danfe_nfe.py                # Gerador DANFE NF-e
│   ├── report_danfe_nfce.py               # Gerador DANFE NFC-e
│   ├── report_danfse.py                   # Gerador DANFSE
│   ├── report_damdfe.py                   # Gerador DAMDFE
│   ├── report_cce.py                      # Gerador CC-e
│   ├── report_dacte.py                    # Gerador DACTE (CT-e)
│   ├── danfe_nfe_template.xml             # Template QWeb DANFE NF-e
│   ├── danfe_nfce_template.xml            # Template QWeb DANFE NFC-e
│   ├── danfe_nfce_a4_template.xml         # Template DANFE NFC-e formato A4
│   ├── danfse_template.xml                # Template DANFSE
│   ├── damdfe_template.xml                # Template DAMDFE
│   ├── cce_template.xml                   # Template CC-e
│   └── dacte_template.xml                 # Template DACTE (CT-e)
│
├── views/
│   ├── res_company_views.xml
│   ├── res_partner_views.xml
│   ├── product_template_views.xml
│   ├── account_move_views.xml
│   ├── fiscal_document_views.xml
│   ├── mdfe_views.xml
│   ├── cte_views.xml
│   ├── cfop_views.xml
│   ├── ncm_views.xml
│   ├── natureza_operacao_views.xml
│   └── menu_views.xml
│
├── data/                                  # Dados iniciais (CSV)
│   ├── bitconn_fiscal.cfop.csv
│   ├── bitconn_fiscal.ncm.csv
│   ├── bitconn_fiscal.municipio.csv
│   └── bitconn_fiscal.natureza_operacao.csv
│
└── security/
    └── ir.model.access.csv

Instalação

Dependências do Sistema (Debian/Ubuntu)

sudo apt update
sudo apt install -y build-essential pkg-config python3-dev \
    libxml2-dev libxslt1-dev libssl-dev libffi-dev ca-certificates

Dependências Python

Pacote	Versão mínima	Uso
`requests`	2.28	Comunicação HTTP com SEFAZ e prefeituras
`lxml`	4.9	Construção, parsing e canonicalização de XML
`cryptography`	41.0	Assinatura XML e leitura de certificados A1 (PKCS#12)
`qrcode`	7.0	QR Code no DANFE NFC-e e DANFSE

pip install -r bitconn_fiscal/requirements.txt

Instalação no Odoo

Adicione o diretório pai ao addons_path do odoo.conf:

addons_path = /path/to/odoo/addons,/path/to/bitconn_addons

Ative o modo desenvolvedor no Odoo.
Vá em Apps → Atualizar lista de módulos.
Pesquise e instale Bitconn Fiscal.

Configuração

No formulário da empresa, as configurações ficam distribuídas em abas:

Aba	Conteúdo
Fiscal	Emitente, endereço, certificado A1, CFOP/natureza, impostos padrão
NF-e	Série/numeração, modelo padrão, ações (inutilizar, status SEFAZ)
NFC-e	Série/numeração, CSC, URLs QR Code/consulta
NFS-e	Padrão, provedor, ambiente, tributação ISS, regime
MDF-e	Série/numeração, modal, tipo emitente

Certificado Digital

Campo	Descrição
Certificado A1 (.pfx)	Arquivo PKCS#12 (certificado digital A1)
Chave Privada	Chave privada extraída ou o mesmo PFX
Senha do certificado	Senha do arquivo PFX

Parceiro (Destinatário)

Caminho: Contatos → Parceiro → aba Fiscal

Campo	Descrição
CNPJ / CPF	Documento do destinatário
Tipo de Documento	CPF ou CNPJ
Indicador IE Dest.	1 (contribuinte), 2 (isento), 9 (não contribuinte)
Município	Seleção por tabela IBGE

Produto

Caminho: Estoque → Produtos → Produto → aba Fiscal

Grupo	Campos
Classificação	NCM, CEST, CFOP, Origem, Tipo Fiscal
ICMS	CST ICMS / CSOSN, Alíquota (%), Redução BC (%)
ICMS ST	Alíquota ST (%), MVA (%), Redução BC ST (%)
FCP	Alíquota FCP (%), Alíquota FCP ST (%)
PIS	CST PIS, Alíquota (%)
COFINS	CST COFINS, Alíquota (%)
IPI	CST IPI, Alíquota (%)
CBS / IBS / IS	CST CBS, Alíquota CBS; CST IBS, Alíquota IBS; Alíquota IS
DIFAL	Alíq. Interna Destino (%), Alíq. Interestadual (%), FCP UF Destino (%)

Prioridade de Configuração Fiscal

Na emissão do XML, cada campo fiscal segue uma hierarquia de resolução. O sistema percorre os níveis da esquerda para a direita e usa o primeiro valor não-vazio encontrado.

Campos do item (`<det>/<prod>` e `<imposto>`)

Campo XML	1º — Linha do documento	2º — Documento/Fatura	3º — Empresa (padrão)	Fallback
CFOP	`line.cfop_id`	`doc.cfop_id`	`company.fiscal_cfop_default_dentro/fora_id`	`5102` / `6102`
NCM	`line.ncm_id`	—	`company.fiscal_ncm_default_id`	`00000000`
CEST	`line.cest`	—	—	omitido
Origem	`line.origem`	—	—	`0` (Nacional)
CST/CSOSN ICMS	`line.icms_cst`	—	`company.fiscal_icms_csosn_default` / `fiscal_icms_cst_default`	`102` (SN) / `00` (RN)
Alíquota ICMS	`line.icms_aliquota`	—	`company.fiscal_aliquota_icms`	`0`
Redução BC ICMS	`line.icms_reducao_bc`	—	—	`0`
CST PIS	`line.pis_cst`	—	`company.fiscal_pis_cst_default`	`01`
Alíquota PIS	`line.pis_aliquota`	—	`company.fiscal_pis_aliquota`	`0`
CST COFINS	`line.cofins_cst`	—	`company.fiscal_cofins_cst_default`	`01`
Alíquota COFINS	`line.cofins_aliquota`	—	`company.fiscal_cofins_aliquota`	`0`
CST IPI	`line.ipi_cst`	—	`company.fiscal_ipi_cst_default`	`53` (NT)
Alíquota IPI	`line.ipi_aliquota`	—	`company.fiscal_ipi_aliquota`	`0`
MVA / alíquota ST	`line.icms_st_mva` / `icms_st_aliquota`	—	—	`0`

Regra geral para o item: Linha do documento → Empresa. O produto não interfere diretamente no XML — ele é a fonte de origem ao criar a linha (via _onchange_product_id ou _emit_fiscal_document). Uma vez que a linha está criada, o XML usa apenas os valores da linha.

Campos do cabeçalho (`<ide>` e `<emit>`)

Campo XML	Origem
Natureza da operação	`doc.natureza_operacao_id` → `company.fiscal_natureza_operacao_dentro/fora_id` → `"VENDA DE MERCADORIA"`
Série	`company.nfe_serie` / `company.nfce_serie`
dhSaiEnt	`doc.dh_sai_ent` → `dh_emi` (data de emissão)
finNFe	`doc.fin_nfe` (default `1` – Normal)
indPres	`doc.ind_pres` → `1` (NFC-e) ou `0` (NF-e)
indFinal	Derivado de `partner.fiscal_ind_ie_dest` (`9` = consumidor final = `1`)
tpNF	`doc.tipo_operacao` (default `1` – Saída)
CRT	`company.fiscal_crt`

Dados do destinatário (`<dest>`)

Campo XML	1º — Campos fiscais do parceiro	2º — Campos nativos Odoo
CNPJ/CPF	`partner.fiscal_cnpj_cpf`	`partner.vat`
xNome	`partner.fiscal_razao_social`	`partner.name`
xLgr	`partner.fiscal_logradouro`	`partner.street`
nro	`partner.fiscal_numero_endereco`	`"S/N"`
xCpl	`partner.fiscal_complemento`	`partner.street2`
xBairro	`partner.fiscal_bairro`	—
cMun	`partner.fiscal_cod_municipio`	—
xMun	`partner.fiscal_nome_municipio`	`partner.city`
UF	`partner.fiscal_uf`	`partner.state_id.code`
CEP	`partner.fiscal_cep`	`partner.zip`
fone	`partner.fiscal_fone`	`partner.phone`
email	`partner.fiscal_email`	`partner.email`
indIEDest	`partner.fiscal_ind_ie_dest`	`9`
IE	`partner.fiscal_inscricao_estadual`	—
IM	`partner.fiscal_inscricao_municipal`	—
ISUF	`partner.fiscal_inscricao_suframa`	—

Os campos fiscal_* do parceiro têm prioridade total. Os campos nativos do Odoo (street, city, vat, etc.) são usados apenas como fallback. Para emitir corretamente, preencha a aba Fiscal do cadastro do parceiro.

Como os dados do produto chegam à linha

Quando uma NF-e é criada a partir de uma fatura (_emit_fiscal_document), o módulo copia para cada linha do documento fiscal:

Dados do produto: NCM, CEST, CFOP, origem, tipo fiscal
ICMS: CST/CSOSN, alíquota, redução BC, MVA/ST (do product.template)
PIS / COFINS / IPI: CST e alíquota (do product.template)
CBS / IBS / IS: CST e alíquota (do product.template, se configurado)
DIFAL: alíquota interna, interestadual e FCP (do product.template, se configurado)

Após a criação da linha, os valores podem ser editados manualmente no documento fiscal antes da emissão. O botão “Recalcular Impostos” executa _fill_line_tax_values e recalcula base e valor usando os dados atuais da linha + padrões da empresa.

Base de cálculo (vBC) — regra geral

vBC = (qty × preço_unitário) × (1 - desconto%) + frete + seguro + outras_despesas

Esta é a regra modBC=3 (valor da operação), utilizada para ICMS, PIS, COFINS, IPI, CBS, IBS e IS.

Operação

Emitir NF-e / NFC-e

Crie e valide uma fatura de cliente no Odoo.
Na fatura, clique no botão “Emitir NF-e” ou “Emitir NFC-e”.
O módulo cria o documento fiscal, calcula os impostos e gera o XML.
O XML é assinado com o certificado A1 e enviado à SEFAZ via SOAP 1.2 com mTLS.
A aba fiscal da fatura mostra: número, chave de acesso, protocolo e status.

Campos adicionais do documento fiscal

Campo	Descrição
Finalidade da NF-e	`1` Normal · `2` Complementar · `3` Ajuste · `4` Devolução
Data/Hora Saída / Entrada	`dhSaiEnt` — se não informado, usa a data de emissão
Indicador de Presença	`0` Não se aplica · `1` Presencial · `2` Internet · `3` Teleatendimento · `4` Entrega em domicílio · `5` Fora do estabelecimento · `9` Outros

Campos adicionais da linha do documento

Campo	Descrição
Informações do produto (`inf_ad_prod`)	Texto livre por item — gerado como `<infAdProd>` no XML
Alíq. Interna DIFAL (%)	Alíquota interna do estado destino — preencha para DIFAL
Alíq. Interestadual DIFAL (%)	Alíquota interestadual da operação
FCP UF Destino (%)	Alíquota FCP do estado destino
Alíquota II (%)	Imposto de Importação — preencha para operações de importação
IPI Devolução (R$)	Valor IPI devolvido — use com finNFe=4 (Devolução)

Emitir NFS-e

Configure os campos da empresa na aba NFS-e (padrão, provedor, certificado).
Crie e valide uma fatura de serviço.
No menu de ações da fatura, use “Emit NFS-e”.
O módulo seleciona o provedor configurado e executa build → sign → send.

Emitir MDF-e

Configure série e numeração na aba MDF-e da empresa.
Acesse o menu Fiscal → MDF-e e crie um novo manifesto.
Preencha os dados de carregamento, descarregamento e veículo.
Clique em Emitir — o módulo gera o XML, assina e envia à SEFAZ.

Cancelar Documento Fiscal

Na fatura/MDF-e com documento autorizado:

Clique no botão “Cancelar” correspondente.
Preencha a justificativa no wizard.
Confirme — o módulo envia o evento de cancelamento.

Inutilizar Numeração (NF-e)

Na aba NF-e da empresa:

Clique em “Inutilizar Faixa de Numeração”.
Informe número inicial, final, série e justificativa.
Confirme — o módulo envia à SEFAZ.

Encerrar MDF-e

No MDF-e autorizado, clique em “Encerrar” e informe o município e UF de encerramento.

CT-e — Conhecimento de Transporte Eletrônico

O CT-e (modelo 57, leiaute 4.00) é o documento fiscal para prestações de serviço de transporte.

Acessar

Menu: Fiscal → Documentos Fiscais → CT-e

Emitir CT-e

Crie um CT-e pelo botão “Novo” no menu CT-e.
Preencha os campos obrigatórios:

Grupo	Campos obrigatórios
Identificação	Tipo de CT-e, Modal, Tipo de Serviço, CFOP, Natureza da Operação
Participantes	Remetente, Destinatario, Mun. Início, Mun. Fim, Tomador
Valores	Componentes de prestação, Produto Predominante
Impostos	CST ICMS, Base de Cálculo, Alíquota, Valor
Modal	RNTRC (rodoviário), placa e dados do veículo

Clique em “Emitir”.

Fluxo interno de emissão

Emitir CT-e
    │
    ├─ Validações (certificado, RNTRC, dados mínimos)
    ├─ _get_next_numero()          ← numeração automática da empresa
    ├─ build_cte_xml()             ← gera XML <CTe> leiaute 4.00
    ├─ sign_xml(sign_tag="infCte") ← assina RSA-SHA1
    ├─ validate_cte_xml()          ← valida contra cte_v4.00.xsd (SEFAZ)
    ├─ CteClient.autorizar()       ← SOAP 1.2 + mTLS
    └─ Parse resposta (cStat 100 = autorizado → salva cte_xml + cte_protocolo)

Autorizadores por UF

Autorizador	UFs atendidas
SP	São Paulo
MG	Minas Gerais
MT	Mato Grosso
SVRS	Todos os demais estados

Cancelar CT-e

No CT-e autorizado, clique em “Cancelar”.
Informe a justificativa (mínimo 15 caracteres).
Confirme — o módulo envia o evento de cancelamento (tpEvento 110111).

Prazo: 24 horas após a autorização. Após esse prazo a SEFAZ rejeita o cancelamento.

Carta de Correção Eletrônica (CC-e CT-e)

No CT-e autorizado, clique em “Carta de Correção”.
Informe o texto da correção (mínimo 15 caracteres).
O sistema incrementa automaticamente o número sequencial do evento (tpEvento 110110).

A CC-e não substitui o CT-e — corrige apenas dados que não influenciem o valor do frete.

Download do XML

No CT-e autorizado, clique em “Download XML” para baixar o arquivo CTe-{chave}.xml.

Consultar SEFAZ

Clique em “Consultar” para verificar a situação atual do CT-e na SEFAZ (consSitCTe).

Importar XML de CT-e Recebido

Menu: Fiscal → Documentos Fiscais → Importar XML CT-e

Permite registrar no sistema CT-e emitidos por terceiros (transportadoras), com duas opções:

Opção	Resultado
Criar registro fiscal	Cria um `bitconn_fiscal.cte` com os dados do XML (padrão ativado)
Criar lançamento contábil	Cria uma `account.move` de despesa com o frete

Passos

Acesse o menu e suba o arquivo .xml do CT-e.
Clique em “Analisar XML” — o wizard exibe os dados parsed: chave, número, emitente, valores.
Configure as opções e, se for lançar contábil, escolha a conta de frete e o parceiro.
Clique em “Importar”.

Imprimir DACTE

No CT-e autorizado, acesse o menu Imprimir → DACTE. O documento contém:

Cabeçalho com dados do emitente e identificação
Origem e destino da prestação
Tomador, remetente e destinatário
Valores da prestação por componente e ICMS
Informações da carga e documentos transportados
Modal rodoviário (placa, RNTRC, motorista)
Código de barras + chave de acesso + protocolo de autorização

ICMS no CT-e

O CT-e possui apenas ICMS — não há PIS, COFINS, IPI. O imposto incide sobre o valor total da prestação de serviço de transporte (vTPrest), e existe um único bloco ICMS por CT-e (não por item).

Campos ICMS do CT-e

Campo	Tag XML	Descrição
CST ICMS	`cst`	Código de Situação Tributária
Base de Cálculo	`vBC`	Valor sobre o qual a alíquota incide
Alíquota ICMS (%)	`pICMS`	Percentual do imposto
Valor ICMS	`vICMS`	`BC × alíquota%`
% Redução BC	`pRedBC`	Reduz a base — apenas CST 20

CST ICMS — Qual usar?

CST	Situação	Campos obrigatórios	Nota
00	Tributação integral	BC = vTPrest, Alíquota, Valor	Mais comum em regime normal
20	Base reduzida	% Redução BC, BC reduzida, Alíquota, Valor	BC = vTPrest × (1 - %RedBC/100)
40	Isento	— (deixe tudo zero)	Isenção fiscal
41	Não tributado	— (deixe tudo zero)	Fora do campo de incidência
51	Diferimento	Alíquota e Valor Diferido	Usado em acordos estaduais
60	ST retida anteriormente	BC retida, Valor retido, Alíquota retida	Retribuição anterior de ST
90	Outros	BC, Alíquota, Valor	Situações mistas

Simples Nacional (CRT 1 ou 2): os campos de BC/Alíquota/Valor são ignorados. O módulo gera automaticamente <ICMSSN><indSN>1</indSN></ICMSSN> independente do que for preenchido.

Exemplos de cálculo

CST 00 — Tributação Normal:

vTPrest    = R$ 1.000,00
BC         = R$ 1.000,00  (igual ao vTPrest)
Alíquota   = 12%
Valor ICMS = R$ 120,00

CST 20 — Base Reduzida 33,33%:

vTPrest      = R$ 1.000,00
% Redução BC = 33,33%
BC           = R$ 1.000,00 × (1 - 0,3333) = R$ 666,70
Alíquota     = 12%
Valor ICMS   = R$ 80,00

Atenção: o cálculo é manual — o módulo não recalcula automaticamente quando o valor da prestação muda. Preencha BC e Valor corretos antes de clicar em Emitir.

Tag XML gerada por CST

CST	Tag XML no `<ICMS>`
00	`<ICMS00>` com `cst`, `vBC`, `pICMS`, `vICMS`
20	`<ICMS20>` com `cst`, `pRedBC`, `vBC`, `pICMS`, `vICMS`
40, 41, 51	`<ICMS45>` com `cst` (e `pICMS`/`vICMSDif` para CST 51)
60	`<ICMS60>` com `cst`, `vBCSTRet`, `vICMSSTRet`, `pICMSSTRet`
90	`<ICMS90>` com `cst`, `pRedBC`, `vBC`, `pICMS`, `vICMS`
SN	`<ICMSSN>` com `indSN=1` (Simples Nacional)

Cálculo de Impostos (NF-e / NFC-e)

Base de cálculo

vBC_item = (qty × preço_unitário) - desconto_R$ + frete + seguro + outras_despesas

Esta base (modBC=3) é utilizada para todos os tributos calculados por alíquota.

ICMS — Simples Nacional (CRT 1 ou 2)

CSOSN	Tag XML	Gera ICMS?	Observação
101	ICMSSN101	Sim (crédito SN)	pCredSN / vCredICMSSN
102, 103, 300, 400	ICMSSN102	Não	—
201, 202, 203	ICMSSN202	Não (ST)	vBCST / vICMSST
500	ICMSSN500	Não	—
900	ICMSSN900	Sim	modBC=3, vBC, pICMS, vICMS + ST zerado

ICMS — Regime Normal (CRT 3)

CST	Tag XML	Base reduzida?	ST?
00	ICMS00	Não	Não
10	ICMS10	Não	Sim
20	ICMS20	Sim (pRedBC)	Não
40, 41, 50	ICMS40	Não	Não
51	ICMS51	Diferimento	Não
60	ICMS60	Não	Substituído
90	ICMS90	Não	Não

DIFAL — Diferencial de Alíquota (interestadual + consumidor final)

Aplicado automaticamente quando:

NF-e (modelo 55)
Operação interestadual (UF emitente ≠ UF destinatário)
indFinal = 1 (consumidor final — derivado de indIEDest = 9)
Campos difal_aliquota_interna e difal_aliquota_interestadual preenchidos na linha

Tag XML gerada: <ICMSUFDest> por item. Acumuladores no totalizador: vFCPUFDest, vICMSUFDest, vICMSUFRemet.

vICMSUFDest = vBC × aliq_interna% - vBC × aliq_interestadual%
vFCPUFDest  = vBC × fcp_aliquota%

PIS

CST	Tag XML	Calcula?
01, 02	PISAliq	Sim
04 a 09	PISNT	Não
49, 99 e outros	PISOutr	Sim

COFINS

CST	Tag XML	Calcula?
01, 02	COFINSAliq	Sim
04 a 09	COFINSNT	Não
49, 99 e outros	COFINSOutr	Sim

IPI

Apenas em NF-e (modelo 55). NFC-e não inclui IPI.
CSTs tributados (00, 49, 50, 99) → IPITrib. Demais → IPINT.
Para NF-e de devolução (finNFe=4): preencha o campo IPI Devolução na linha — o valor vai para vIPIDevol no totalizador.

II — Imposto de Importação

Preencha Alíquota II (%) na linha do documento fiscal.
O módulo calcula ii_valor = vBC × aliq_ii% e acumula em vII no totalizador.

CBS / IBS / IS — Reforma Tributária

Calculados e armazenados no banco de dados (campos cbs_valor, ibs_valor, is_valor).
Totais visíveis na aba Totais Reforma Tributária do documento.
Não emitidos no XML NF-e 4.00 — o schema 4.00 (MOC 7.0) não prevê essas tags. Serão incluídos quando a SEFAZ publicar o leiaute 5.00.

Fluxo do cálculo

Emitir ou Recalcular Impostos
    │
    ├─ _fill_line_tax_values()          ← calcula e persiste base + valor por linha
    │     ├─ vBC = qty×preço - desc + frete + seguro + outras
    │     ├─ ICMS (SN/CSOSN ou RN/CST)
    │     ├─ ICMS ST (CST 10, 70 / CSOSN 201-203)
    │     ├─ FCP (se fcp_aliquota > 0)
    │     ├─ DIFAL (interestadual + consumidor final, CRT 3)
    │     ├─ PIS / COFINS
    │     ├─ IPI (modelo 55)
    │     ├─ II (se ii_aliquota > 0)
    │     ├─ CBS / IBS / IS (armazenado, não emitido no XML)
    │     └─ Totais do documento recalculados (computed fields)
    │
    └─ build_nfe_xml()                  ← lê valores da linha e gera o XML
          ├─ <ide> finNFe, dhSaiEnt, indPres, indFinal
          ├─ <emit> dados da empresa
          ├─ <dest> dados do parceiro
          ├─ <det> por linha: prod, ICMS, ICMSUFDest, IPI, PIS, COFINS, infAdProd
          ├─ <total> ICMSTot com todos os acumuladores
          ├─ <transp> transportadora, veículo, volumes
          ├─ <cobr> duplicatas
          ├─ <pag> formas de pagamento
          └─ <infAdic> informações complementares e do fisco

Documentação Técnica

Bibliotecas — `lib/`

As bibliotecas não dependem do Odoo e podem ser usadas standalone.

Módulos compartilhados (`lib/`)

Arquivo	Descrição
`certificate.py`	Utilitários de certificado PKCS#12 — `decode_odoo_binary`, `load_pkcs12`, `CertificateInfo`, `validate_certificate`, `pfx_to_pem_files`
`xml_signer.py`	Assinador XML-DSIG unificado — parametrizado por algoritmo hash (SHA-1 / SHA-256), C14N 1.0
`uf_codes.py`	Mapeamento sigla UF ↔ código IBGE
`nfe_xml_parser.py`	Parsing de XML NF-e — extrai chave, protocolo, formato

NF-e / NFC-e (`lib/nfe/`)

Arquivo	Descrição
`xml_builder.py`	Gerador XML `<NFe>` (leiaute 4.00) a partir de `account.move`
`xml_signer.py`	Wrapper — delega para `xml_signer` com RSA-SHA1
`sefaz_client.py`	Cliente SOAP — `autorizar`, `consultar_recibo`, `consultar_nfe`, `status_servico`, `enviar_evento`, `inutilizar`
`sefaz_urls.py`	URLs por UF/autorizador/ambiente
`http_client.py`	Transporte HTTP com mTLS + `SefazError`, `SefazRejeicao`
`soap.py`	Envelope SOAP 1.2
`event_builder.py`	Builder de eventos XML (cancelamento, CC-e)

NFS-e (`lib/nfse/`)

Arquivo	Descrição
`xml_builder.py`	Gerador DPS (Padrão Nacional, XSD v1.01)
`xml_signer.py`	Wrapper — delega para `xml_signer` com RSA-SHA256
`xml_validator.py`	Validador XSD
`sefin_client.py`	Cliente REST SEFIN (payloads gzip + base64 em JSON)
`http_client.py`	Transporte HTTP NFS-e

Provedores NFS-e (`lib/nfse/providers/`)

Arquivo	Descrição
`base.py`	Classe base `NfseProvider`
`registry.py`	Registro de provedores
`nacional.py`	Padrão Nacional (SEFIN/ADN)
`abrasf.py`	ABRASF genérico
`abrasf_rps_builder.py`	Builder RPS ABRASF
`abrasf_soap_client.py`	Cliente SOAP ABRASF
`abrasf_xml_signer.py`	Assinador ABRASF

MDF-e (`lib/mdfe/`)

Arquivo	Descrição
`xml_builder.py`	Gerador XML `<MDFe>`
`xml_validator.py`	Validador XSD
`client.py`	Cliente SEFAZ MDF-e
`event_builder.py`	Builder de eventos MDF-e

CT-e (`lib/cte/`)

Arquivo	Descrição
`xml_builder.py`	Gerador XML `<CTe>` (leiaute 4.00) com suporte a todos os CSTs e modal rodoviário
`xml_validator.py`	Validador XSD contra `cte_v4.00.xsd` e `eventoCTe_v4.00.xsd`
`client.py`	Cliente SEFAZ CT-e — `autorizar`, `consultar`, `status_servico`, `enviar_evento`, `inutilizar`
`sefaz_urls.py`	URLs por UF/autorizador (SVRS, SP, MG, MT) e ambiente
`event_builder.py`	Builder de eventos: cancelamento (110111) e CC-e (110110)
`schemas/`	44 XSDs oficiais SEFAZ — PL_CTe_400_NT2025.001 RTC_1.14

Modelos Odoo

Modelo	Arquivo	Descrição
`res.company`	`res_company.py`	Campos fiscais do emitente, certificado, NF-e, NFC-e, NFS-e, MDF-e
`res.partner`	`res_partner.py`	Campos fiscais do destinatário
`product.template`	`product_template.py`	Classificação fiscal do produto
`account.move`	`account_move.py`	Campos e ações fiscais na fatura
`account.move.line`	`account_move_line.py`	CFOP/natureza por linha
`bitconn_fiscal.document`	`fiscal_document.py`	Documento fiscal (NF-e/NFC-e) — chave, XML, protocolo
`bitconn_fiscal.document.line`	`fiscal_document_line.py`	Linhas do documento fiscal
`bitconn_fiscal.document.duplicata`	`fiscal_document_duplicata.py`	Duplicatas
`bitconn_fiscal.document.pagamento`	`fiscal_document_pagamento.py`	Formas de pagamento
`bitconn_fiscal.mdfe`	`mdfe.py`	MDF-e — manifesto de documentos fiscais
`bitconn_fiscal.mdfe.documento`	`mdfe_documento.py`	Documentos vinculados ao MDF-e
`bitconn_fiscal.mdfe.municipio`	`mdfe_municipio.py`	Municípios de percurso
`bitconn_fiscal.mdfe.vale.pedagio`	`mdfe_vale_pedagio.py`	Vale pedágio
`bitconn_fiscal.cte`	`cte.py`	CT-e — chave, XML, protocolo, states, emissão, cancelamento, CC-e
`bitconn_fiscal.cte.componente`	`cte_componente.py`	Componentes de valor da prestação (vComp)
`bitconn_fiscal.cte.documento`	`cte_documento.py`	Documentos transportados (NF-e, NF, outros)
`bitconn_fiscal.municipio`	`municipio.py`	Tabela de municípios IBGE
`bitconn_fiscal.cfop`	`cfop.py`	Tabela CFOP
`bitconn_fiscal.ncm`	`ncm.py`	Tabela NCM
`bitconn_fiscal.natureza_operacao`	`natureza_operacao.py`	Tabela de naturezas de operação

Web Services Suportados

SEFAZ (NF-e / NFC-e / MDF-e)

Serviço	Descrição
NfeAutorizacao	Envio de NF-e/NFC-e para autorização
NfeRetAutorizacao	Consulta recibo de lote assíncrono
NfeConsultaProtocolo	Consulta pela chave de acesso
NfeStatusServico	Disponibilidade da SEFAZ
RecepcaoEvento	Cancelamento, CC-e
NfeInutilizacao	Inutilização de faixa de numeração
MDFeRecepcao	Envio de MDF-e
MDFeConsulta	Consulta MDF-e
MDFeRecepcaoEvento	Cancelamento / encerramento MDF-e

SEFAZ (CT-e)

Serviço	Descrição
CTeRecepcaoSinc	Envio síncrono de CT-e para autorização
CTeConsulta	Consulta pela chave de acesso (`consSitCTe`)
CTeStatusServico	Disponibilidade da SEFAZ CT-e
CTeRecepcaoEvento	Cancelamento (110111) e CC-e (110110)
CTeInutilizacao	Inutilização de faixa de numeração

SEFIN / ABRASF (NFS-e)

API	Transporte	Descrição
SEFIN (Padrão Nacional)	REST (gzip + base64)	Envio de DPS, consulta, cancelamento
ABRASF	SOAP	Envio de RPS, consulta, cancelamento (por prefeitura)

Fluxo de Emissão NF-e / NFC-e

Emitir NF-e/NFC-e
    │
    ├─ Validações (certificado, UF, destinatário, CSC para NFC-e)
    ├─ Numeração automática (serie + numero)
    ├─ _auto_fill_natureza_cfop() → natureza e CFOP padrão se vazios
    ├─ _fill_line_tax_values() → calcula ICMS/PIS/COFINS/IPI/DIFAL/II por linha
    ├─ build_nfe_xml() → gera XML conforme leiaute 4.00
    ├─ sign_xml() → assina RSA-SHA1
    ├─ SefazClient.autorizar() → SOAP 1.2 + mTLS
    └─ Parse resposta (cStat 100/150 = autorizado → salva xml_autorizado + protocolo)

Fluxo de Emissão NFS-e

Emitir NFS-e
    │
    ├─ Resolver provedor (nacional / abrasf)
    ├─ Validações (certificado, URL)
    ├─ xml_builder.py → gera DPS ou RPS
    ├─ xml_signer.py → assina (RSA-SHA256)
    └─ Enviar (REST ou SOAP conforme provedor)

Erros Comuns e Solução

NF-e / NFC-e

Situação	Solução
Certificado digital não configurado	Configure o PFX na aba Fiscal da empresa
UF não configurada	Preencha o endereço fiscal na aba Fiscal
CSC não configurado (NFC-e)	Preencha CSC ID e Token na aba NFC-e
Certificado expirado	Renove o certificado A1 junto à AC

NFS-e

Situação	Solução
E0037 (Município não Emissor Nacional)	Altere para `ABRASF` e configure WSDL/variante
E0310 (cTribNac inválido)	Corrija `nfse_codigo_tributacao` para o código de 6 dígitos correto
URL do provedor vazia	Configure a URL na aba NFS-e da empresa

Notas de Desenvolvimento

Prefixos de campos: fiscal_* (emitente/produto), nfe_* (NF-e), nfce_* (NFC-e), nfse_* (NFS-e), mdfe_* (MDF-e).
Herança por extensão: estende res.company, res.partner, product.template e account.move via _inherit.
Bibliotecas independentes: todo o código em lib/ não depende do Odoo e pode ser testado standalone.
Assinatura XML: implementação manual SHA-1/SHA-256 + C14N 1.0 unificada em lib/xml_signer.py, com wrappers thin em nfe/xml_signer.py e nfse/xml_signer.py.
Certificado: utilitários centralizados em lib/certificate.py, consumidos por todos os subdiretórios.
Provedores NFS-e: para adicionar provedores, crie uma subclasse de NfseProvider em lib/nfse/providers/.

Referências

MOC 7.0 — Manual de Orientação do Contribuinte
Portal Nacional NF-e
Tabela IBGE de Municípios
Tabela NCM
SEFIN Padrão Nacional (DPS) — documentação oficial
ABRASF — especificações RPS e elementos XML

Autor: Diego F. Rodrigues <[email protected]> Licença: OPL-1 (Odoo Proprietary License v1.0) Preço: $400 USD