sped-extractor
Esse package extrai as tabelas dos pdf das especificações do SPED usando o package python camelot e cria arquivos CSV com as informações dos registros e campos de cada módulo, levemente formatados para ser utilizados por outros programas.
Os módulos da SPED tratados por esse package são :
- MODULE_registers.csv : a lista detalhada dos registros do módulo
MODULE
. - MODULE_accurate_fields.csv : a lista das linhas dos campos de cada registro como eles aparecem no pdf das especificações (para conferir e melhorar o resultado da extração).
- MODULE_fields.csv : a lista dos mesmos campos porém com atributos "interpretados", utilizáveis mais facilmente por outros programas.
sped-extractor
for instalado, os campos, registros e blocos de cada módulo são facilmente accessiveis como dicionários python :
>>> from spedextractor import get_fields, get_registers, get_blocks
>>> get_fields("ecd")
[{'register': '0000', 'index': 2, 'code': 'LECD', 'desc': 'Texto fixo contendo “LECD”.', 'length': '004', 'type': 'char', 'required': True, [...]}, [...] ]
Índice
Arquivos extraidos
Instalação
$ pip install sped-extractor
Utilização
Uma vez a distribuição sped-extractor
instalada, o package spedextractor
está disponível com as 3 funções get_fields
, get_registers
e get_blocks
que permitem acessar aos campos, registros e blocos do módulo desejado :
>>> from spedextractor import get_fields, get_registers, get_blocks
>>> ecd_fields_2020 = get_fields("ecd")
323 fields catched in ECD
>>> ecd_fields_2019 = get_fields("ecd", 2019)
282 fields catched in ECD
>>> efd_pis_cofins_registers_2020 = get_registers("efd_pis_cofins")
203 registers catched in EFD_PIS_COFINS
É só indicar o nome do módulo ("ecd"
, "ecf"
, "efd_icms_ipi"
ou "efd_pis_cofins"
) e o ano da versão do pdf do módulo. Se não indicar nada, o ano mais recente presente na pasta specs/ é usado.
Extração dos campos e registros
O package é composto de todos os scripts necessários à construção desses 4 tipos de arquivos CSV e JSON. Para usá-los e extrair as informações de novos pdfs do SPED, primeiro é necessário baixar o repositório github do projeto
$ git clone https://github.com/akretion/sped-extractor/
. ├── spedextractor ├── specs ├── 2019 | [...] └── 2020 ├── camelot_patch │ ├── ecd_camelot_patch.csv | [...] ├── download_info.csv ├── ecd │ ├── ecd_accurate_fields.csv │ ├── ecd_fields.csv │ └── ecd_registers.csv ├── ecf | [...] ├── efd_icms_ipi | [...] ├── efd_pis_cofins | [...] └── pdf ├── ecd.pdf ├── ecf.pdf ├── efd_icms_ipi.pdf └── efd_pis_cofins.pdf
Para extrair as informações de uma nova versão de pdf, você precisa apenas criar uma nova pasta cujo nome seja o ano de publicação dessa nova versão (por exemplo 2021/
) e contendo um arquivo download_info.csv
com os URLs dos pdf para serem baixados e usados, seguindo o modelo dos arquivos atuais :
module | version | date_init | url |
ecd | 8 | 2019-01-01 | http://sped.rfb.gov.br/arquivo/download/4210 |
ecf | 6 | 2019-01-01 | http://sped.rfb.gov.br/arquivo/download/4272 |
efd_icms_ipi | 3.0.3 | 2019-01-01 | http://sped.rfb.gov.br/arquivo/download/4202 |
efd_pis_cofins | 1.33 | 2019-01-01 | http://sped.rfb.gov.br/arquivo/download/4263 |
⚠️ É importante diferenciar o ano de publicação de um manual (número da pasta contendo os pdf e os arquivos extraidos) da data de início de validade do manual (odate_init
indicado no arquivodownload_info.csv
).Por exemplo, o package python-sped chama de ecd_2017.json o leiaute do manual para ser usado a partir do 01/01/2017 enquanto nós achamos que faz mais sentido colocar esse mesmo manual na pasta
specs/2018/
porque ele foi divulgado em 2018.
Uma vez que essa pasta e esse arquivo forem criados, você pode lançar o script principal do package (posicionando-se na raiz do projeto sped-extractor/):
PATH/TO/sped-extractor$ python -m spedextractor
Se a pasta com o arquivo download_info.csv
for realmente vazia, ele vai realizar automaticamente as 3 etapas para a construção dos arquivos CSV :
📥 Baixar os pdf graça aos URLs informados (módulodownload.py
)⛏️ Extrair todas as tabelas desses pdfs com camelot e colocar os CSV brutos extraidos na subpasta MODULE/raw_camelot_csv/ (móduloextract_tables.py
)🏗️ Construir os arquivos CSV interpretando essas tabelas brutas (módulobuild_csv.py
)
⚠️ É bom verificar se o packagesped-extractor
não for instalado no seu ambiente de trabalho compip uninstall sped-extractor
antes de lançar o script de extração afim de evitar modificar o seu package instalado na sua pasta lib/python3.7/site-packages/ em vez de modificar esse package baixado de github.
Se o número da nova pasta for anterior ao ano mais recente da pasta specs/, é necessário indicar ao script em que pasta ele tem que trabalhar com a opção --year
, por exemplo
$ python -m spedextractor --year=2018
Obviamente os scripts download.py
e extract_tables.py
são utilizáveis individualmente se precisar apenas baixar ou extrair as tabelas de todos os módulos SPED:
$ python -m spedextractor.download $ python -m spedextractor.extract_tables
Configuração
Patches
Apesar de camelot ser o melhor package python para extrair tabelas de pdf, ele não é 100% perfeito. No entanto, é possível substituir linhas de campos extraidas incorretamente por linhas certas registradas manualmente.
Para isso basta escrever a linha correta no arquivo specs/YEAR/camelot_patch/MODULE_camelot_patch.csv para ela ser applicada no lugar certo no CSV MODULE_accurate_fields.csv.
🔎 Ospedextractor
aplica as linhas corretivas por padrão. Para não aplicar essas correções, usar a opção--no-patch
.
Cabeçalhos de Módulos
Os arquivos CSV "fiéis" de cada módulo SPED usam um cabeçalho (comum a todos os campos do módulo) escrito em duro nas constantes constants.py
.
Para definir "manualmente" esses cabeçalhos, é possível usar o script get_table_headers.py
que exibe no terminal todos os diferentes cabeçalhos extraídos por camelot :
PATH/TO/sped-extractor$ python -m spedextractor.get_table_headers ECD's headers : ['Nº', 'Campo', 'Descrição', 'Tipo', 'Tamanho', 'Decimal'] ['Nº', 'Campo', 'Descrição', 'Tipo', 'Tamanho', 'Decimal', 'Valores Válidos', 'Obrigatório', 'Regras de Validação do Campo'] ['Nº', 'Campo', 'Descrição', '', 'Tipo Tamanho', 'Decimal', 'Valores Válidos', 'Obrigatório', 'Regras de Validação do Campo'] ['Nº', 'Campo', 'Descrição', 'Tipo', 'Tamanho', 'Decimal', 'Valores Válidos', 'Obrigatório', 'Regras de Validação de Campo'] [...]
Comparar sped-extractor com python-sped
python-sped é uma biblioteca python com a lista dos campos de cada módulo da SPED, porém escrita "manualmente" e desatualizada (ECD e ECF seguindo os pdf das especificações de 2017, EFD/ICMS-IPI e EFD/PIS-COFINS seguindo os pdf das especificações de 2015).
Apesar disso, pode ser interessante comparar essas listas de campos com as listas extraidas pelo sped-extractor. Para isso é só lançar o script compare_pythonsped.py
$ python -m spedextractor.compare_pythonsped
Um exemplo de comparação com python-sped pode ser encontrado aqui.
🔎 Para detalhar as listas dos campos faltando em cada modelo, adicionar a opção--detail
.
Roadmap
- Adicionar colonas de mapping com ERP externos nos arquivos CSV.
- Melhorar o arquivo JSON "tipo python-sped" (valor dos itens "regras" e "campos_chave" dos registros)
Créditos
Autores
- Akretion
Contributores
- Raphaël Valyi <raphael.valyi@akretion.com.br>
- Clément Mombereau <clement.mombereau@akretion.com.br>
Administradores
Esse package está administrado por Akretion.