Visão Geral — Arquitetura SPED¶

Mecanismo Central de Geração¶

Todas as obrigações SPED seguem o mesmo padrão arquitetural:

def gerar_sped(self):
    _arq = ArquivoDigital()          # 1. Cria arquivo digital
    self.enviar_registro_XXXX(_arq)  # 2. Gera registros
    _arq.getstring()                 # 3. Serializa como TXT
    base64.b64encode(...)            # 4. Salva como campo Binary

ArquivoDigital¶

Obrigação	Import	Módulo
EFD ICMS/IPI	`sped.efd.icms_ipi.arquivos`	`ArquivoDigital`
EFD Contribuições	`sped.efd.pis_cofins.arquivos`	`ArquivoDigital`
ECD	`sped.ecd.arquivos`	`ArquivoDigital`
ECF	`sped.ecf.arquivos`	`ArquivoDigital`
DCTF	`sped.dctf.arquivos`	`ArquivoDigital`
DIME/SC	Arquivo texto plano (sem lib)	Geração direta

Controle de Registros: `_registro_em_uso()`¶

Todo registro verificável segue este padrão:

def enviar_registro_XXXX(self, _arq):
    if not self._registro_em_uso('XXXX'):
        return  # registro não habilitado → não gera
    # ... lógica de geração

Obrigação	Campo de configuração	Tabela
EFD ICMS/IPI	`company.l10n_br_sped_fiscal_registros`	`l10n_br_ciel_it_account.sped.registro`
EFD Contribuições	`company.l10n_br_sped_contribuicao_registros`	`l10n_br_ciel_it_account.sped.registro`

📍 Onde configurar: Definições → Empresa → aba Localização BR → seção "Registros SPED Fiscal" ou "Registros SPED Contribuições"

Ordem de Geração (EFD ICMS/IPI)¶

A ordem de geração NÃO é numérica. Blocos de dados (B/C/D) são gerados primeiro para acumular listas de participantes, produtos e CFOPs usados depois no Bloco 0:

flowchart LR
    B["B001/B990"] --> C["C001/C100-C500/C990"]
    C --> D["D001/D100-D500/D990"]
    D --> E["E001/E100-E520/E990"]
    E --> G["G001/G990"]
    G --> H["H001/H005/H990"]
    H --> K["K001-K230/K990"]
    K --> B1["1001-1900/1990"]
    B1 --> B0["0000-0600/0990"]
    B0 --> B9["9001/9900/9990"]

    C -.->|"acumula partner_ids"| B0
    C -.->|"acumula product_ids"| B0
    C -.->|"acumula cfop_ids"| B0
    C -.->|"acumula e110_debitos/creditos"| E

Variáveis Globais Acumuladas¶

Variável	Populada em	Usada em
`partner_ids_list`	C100, C140, C500, D100, D500	0150 (Participantes)
`product_ids_list`	C100, C500, D500	0190, 0200, H005, K200/K230
`cfop_ids_list`	C100, C500, D100, D500	0400 (CFOP)
`qtd_cod_inf`	C100 (informações adicionais)	0450
`e110_vl_tot_debitos`	C190, C590, D190, D590	E110
`e110_vl_tot_creditos`	C190, C590, D190, D590	E110

Models Auxiliares¶

SPED Fiscal — `AccountSpedFiscal`¶

Fields de Apuração E110 (ICMS):

Campo	Tipo	Descrição	Preenchido por
`e110_vl_tot_debitos`	Float	Soma débitos ICMS	C190/C590/D190/D590 (auto)
`e110_vl_aj_debitos`	Float	Ajustes débito por documento	C197 (auto)
`e110_vl_tot_aj_debitos`	Float	Ajustes débito apuração	E111 (manual)
`e110_vl_estornos_cred`	Float	Estornos de créditos	Manual
`e110_vl_tot_creditos`	Float	Soma créditos ICMS	C190/C590/D190/D590 (auto)
`e110_vl_aj_creditos`	Float	Ajustes crédito por documento	C197 (auto)
`e110_vl_tot_aj_creditos`	Float	Ajustes crédito apuração	E111 (manual)
`e110_vl_estornos_deb`	Float	Estornos de débitos	Manual
`e110_vl_sld_credor_ant`	Float	Saldo credor anterior	🧮 `computed` → busca mês anterior
`e110_vl_sld_apurado`	Float	Saldo devedor	🧮 `computed`
`e110_vl_tot_ded`	Float	Deduções	Manual
`e110_vl_icms_recolher`	Float	ICMS a recolher	🧮 `computed`
`e110_vl_sld_credor_transportar`	Float	Saldo credor a transportar	🧮 `computed`
`e110_deb_esp`	Float	Valores extra-apuração	Manual

Fórmulas E110:

Débitos = vl_tot_debitos + vl_aj_debitos + vl_tot_aj_debitos + vl_estornos_cred
Créditos = vl_tot_creditos + vl_aj_creditos + vl_tot_aj_creditos + vl_estornos_deb + vl_sld_credor_ant

Se Débitos > Créditos:
    vl_sld_apurado = Débitos - Créditos
    vl_icms_recolher = max(vl_sld_apurado - vl_tot_ded, 0)
    vl_sld_credor_transportar = 0
Senão:
    vl_sld_apurado = 0
    vl_icms_recolher = 0
    vl_sld_credor_transportar = abs(Débitos - Créditos)

Fields de Apuração E520 (IPI):

Campo	Tipo	Descrição	Preenchido por
`e520_vl_sd_ant_ipi`	Float	Saldo credor IPI anterior	🧮 `computed` → mês anterior
`e520_vl_deb_ipi`	Float	Débitos IPI	C190 (auto)
`e520_vl_cred_ipi`	Float	Créditos IPI	C190 (auto)
`e520_vl_od_ipi`	Float	Outros débitos	Manual
`e520_vl_oc_ipi`	Float	Outros créditos	Manual
`e520_vl_sc_ipi`	Float	Saldo credor	🧮 `computed`
`e520_vl_sd_ipi`	Float	Saldo devedor	🧮 `computed`

Fórmulas E520:

Resultado = (vl_deb_ipi + vl_od_ipi) - (vl_sd_ant_ipi + vl_cred_ipi + vl_oc_ipi)
Se Resultado > 0 → vl_sd_ipi = Resultado, vl_sc_ipi = 0
Se Resultado < 0 → vl_sc_ipi = abs(Resultado), vl_sd_ipi = 0

ICMS-ST por UF — `AccountSpedFiscalUfICMSST`¶

Model l10n_br_ciel_it_account.sped.fiscal.uf.icmsst — Uma linha por UF com débitos/créditos de ICMS-ST:

Campo	Tipo	Preenchimento
`e210_vl_sld_cred_ant_st`	Float	🧮 Busca mês anterior, mesma UF
`e210_vl_retencao_st`	Float	Acumulado por C190 (auto)
`e210_vl_devol_st` / `e210_vl_ressarc_st`	Float	Manual
`e210_vl_out_cred_st` / `e210_vl_aj_creditos_st`	Float	Manual
`e210_vl_out_deb_st` / `e210_vl_aj_debitos_st`	Float	Manual
`e210_vl_sld_dev_ant_st`	Float	🧮 Computed
`e210_vl_deducoes_st`	Float	Manual
`e210_vl_icms_recol_st`	Float	🧮 `max(sld_dev - deducoes, 0)`
`e210_vl_sld_cred_st_transportar`	Float	🧮 `abs(saldo)` se negativo
`e210_deb_esp_st`	Float	Manual

DIFAL/FCP por UF — `AccountSpedFiscalUfDIFALFCP`¶

Model l10n_br_ciel_it_account.sped.fiscal.uf.difal.fcp — Duas apurações por UF (DIFAL + FCP), cada uma com:

Campos DIFAL	Campos FCP
`e310_vl_sld_cred_ant_difal`	`e310_vl_sld_cred_ant_fcp`
`e310_vl_tot_debitos_difal`	`e310_vl_tot_deb_fcp`
`e310_vl_out_deb_difal`	`e310_vl_out_deb_fcp`
`e310_vl_tot_creditos_difal`	`e310_vl_tot_cred_fcp`
`e310_vl_out_cred_difal`	`e310_vl_out_cred_fcp`
`e310_vl_sld_dev_ant_difal` (🧮)	`e310_vl_sld_dev_ant_fcp` (🧮)
`e310_vl_deducoes_difal`	`e310_vl_deducoes_fcp`
`e310_vl_recol_difal` (🧮)	`e310_vl_recol_fcp` (🧮)
`e310_vl_sld_cred_transportar_difal` (🧮)	`e310_vl_sld_cred_transportar_fcp` (🧮)
`e310_deb_esp_difal`	`e310_deb_esp_fcp`

Ajustes de Apuração — `AccountSpedFiscalE111`¶

Campo	Tipo
`cod_aj_apur`	Char — Código do ajuste
`descr_compl_aj`	Char — Descrição
`vl_aj_apur`	Float — Valor

Ajustes 1921 — `AccountSpedFiscal1921`¶

Mesma estrutura do E111, para ajustes da outra apuração (Bloco 1):

Campo	Tipo
`cod_aj_apur`	Char
`descr_compl_aj`	Char
`vl_aj_apur`	Float

Campos C197 (Ajustes ICMS por Documento)¶

Campo	Tipo	Descrição
`c197_gerar_apuracao_ajustes_icms`	Boolean	Ativar geração de ajustes
`c197_vl_tot_transf_creditos`	Float	Total transferências de créditos
`c197_vl_tot_transf_debitos`	Float	Total transferências de débitos
`c197_move_ids`	Many2many → `account.move`	Faturas com ajustes C197
`x1900_indicador_apuracao`	Selection	Tipo da outra apuração (3-8)
`x1900_vl_sld_credor_transp`	Float	Saldo credor da outra apuração
`x1900_vl_sld_credor_ant`	Float	🧮 Saldo credor anterior (mês-1)

Pré-requisitos Comuns¶

Pré-requisito	Obrigação	Validação
CNPJ da empresa	Todas	—
UF / Município / IE	Todas	—
Contador (`l10n_br_contador_partner_id`)	Todas exceto DIME	`RedirectWarning`
Registros habilitados	EFD / Contribuições	`_registro_em_uso()`
Faturas postadas no período	Todas	Filtro de busca
Chave NF-e com 44 dígitos	EFD / Contribuições	`RedirectWarning`
Lançamentos contábeis	ECD	`account.move` postados
SPED Fiscal do período	DIME/SC	`UserError`

Fluxo de Dados entre Obrigações¶

flowchart TD
    INV["Faturas (account.move)"]
    OP["Operação Fiscal"]
    MF["Motor Fiscal"]
    SPED_F["EFD ICMS/IPI"]
    SPED_C["EFD Contribuições"]
    ECD["ECD"]
    DCTF["DCTF"]
    DIME["DIME/SC"]
    ECF["ECF"]

    OP -->|"CST, CFOP, alíquotas"| MF
    MF -->|"Cálculo automático"| INV
    INV -->|"ICMS, IPI"| SPED_F
    INV -->|"PIS, COFINS"| SPED_C
    INV -->|"IRPJ, PIS, COFINS, IPI"| DCTF
    INV -->|"Lançamentos contábeis"| ECD
    SPED_F -->|"c197_move_ids, ajustes, saldos"| DIME
    ECD -->|"Saldos contábeis"| ECF

SQL Constraints¶

Obrigação	Constraint	Erro
EFD ICMS/IPI	`UNIQUE(company_id, date_ini, date_fim)`	"O período já foi processado!"
EFD Contribuições	`UNIQUE(company_id, date_ini, date_fim)`	"O período já foi processado!"

GRUPO_DE_CONTA (Referência Contábil)¶

Usado no registro 0500 (Plano de Contas):

`account.account_type`	Código
`asset`	`01`
`expense`	`02`
`liability`	`02`
`equity`	`03`
`income`	`04`
`off_balance`	`09`