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 :
📚 Para cada módulo estão gerados 4 arquivos :
- 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.
📇 Uma vez 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
$ pip install sped-extractorUma 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.
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/
🗄️ A pasta spedextractor/specs/ reúne os pdf baixados, os CSV e JSON extraídos, os patches possíveis para essas extrações além das infos para baixar os pdf, tudo agrupado pelo ano de publicação das versões dos pdf dos manuais da SPED, enquanto os outros arquivos da pasta spedextractor/ são os scripts de extração dos dados :
.
├── 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_initindicado 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ódulo
download.py) - ⛏️ Extrair todas as tabelas desses pdfs com camelot e colocar os CSV brutos extraidos na subpasta MODULE/raw_camelot_csv/ (módulo
extract_tables.py) - 🏗️ Construir os arquivos CSV interpretando essas tabelas brutas (módulo
build_csv.py)
⚠️ É bom verificar se o packagesped-extractornão for instalado no seu ambiente de trabalho compip uninstall sped-extractorantes 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
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.
🔎 Ospedextractoraplica as linhas corretivas por padrão. Para não aplicar essas correções, usar a opção--no-patch.
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'] [...]
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.
- 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)
- Akretion
- Raphaël Valyi <[email protected]>
- Clément Mombereau <[email protected]>
Esse package está administrado por Akretion.