{"id":22307869,"url":"https://github.com/akretion/sped-extractor","last_synced_at":"2025-10-09T14:41:44.438Z","repository":{"id":41284542,"uuid":"160772199","full_name":"akretion/sped-extractor","owner":"akretion","description":"SPED (Sistema Público de Escrituração Digital) no Odoo ERP (ECD, ECF, EFD ICMS IPI, EFD PIS COFINS)","archived":false,"fork":false,"pushed_at":"2025-07-04T13:22:34.000Z","size":107982,"stargazers_count":30,"open_issues_count":5,"forks_count":17,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-08-16T11:58:59.476Z","etag":null,"topics":["brasil","erp","odoo","sped"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/akretion.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-12-07T04:48:42.000Z","updated_at":"2025-06-09T14:44:45.000Z","dependencies_parsed_at":"2025-04-10T01:18:51.436Z","dependency_job_id":null,"html_url":"https://github.com/akretion/sped-extractor","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/akretion/sped-extractor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akretion%2Fsped-extractor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akretion%2Fsped-extractor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akretion%2Fsped-extractor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akretion%2Fsped-extractor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/akretion","download_url":"https://codeload.github.com/akretion/sped-extractor/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akretion%2Fsped-extractor/sbom","scorecard":{"id":176625,"data":{"date":"2025-08-11","repo":{"name":"github.com/akretion/sped-extractor","commit":"8fe0a54a767bf3cfefa39b41d79adeed63229e32"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.1,"checks":[{"name":"Code-Review","score":0,"reason":"Found 0/6 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":10,"reason":"30 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/publish.yml:1","Warn: no topLevel permission defined: .github/workflows/tests.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"License","score":0,"reason":"license file not detected","details":["Warn: project does not have a license file"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish.yml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/akretion/sped-extractor/publish.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish.yml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/akretion/sped-extractor/publish.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/publish.yml:38: update your workflow using https://app.stepsecurity.io/secureworkflow/akretion/sped-extractor/publish.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tests.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/akretion/sped-extractor/tests.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tests.yml:24: update your workflow using https://app.stepsecurity.io/secureworkflow/akretion/sped-extractor/tests.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/tests.yml:35: update your workflow using https://app.stepsecurity.io/secureworkflow/akretion/sped-extractor/tests.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tests.yml:44: update your workflow using https://app.stepsecurity.io/secureworkflow/akretion/sped-extractor/tests.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tests.yml:45: update your workflow using https://app.stepsecurity.io/secureworkflow/akretion/sped-extractor/tests.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/tests.yml:46: update your workflow using https://app.stepsecurity.io/secureworkflow/akretion/sped-extractor/tests.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tests.yml:51: update your workflow using https://app.stepsecurity.io/secureworkflow/akretion/sped-extractor/tests.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tests.yml:54: update your workflow using https://app.stepsecurity.io/secureworkflow/akretion/sped-extractor/tests.yml/master?enable=pin","Warn: pipCommand not pinned by hash: .github/workflows/publish.yml:25","Warn: pipCommand not pinned by hash: .github/workflows/tests.yml:60","Warn: pipCommand not pinned by hash: .github/workflows/tests.yml:61","Warn: pipCommand not pinned by hash: .github/workflows/tests.yml:29","Warn: pipCommand not pinned by hash: .github/workflows/tests.yml:30","Info:   0 out of   8 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   3 third-party GitHubAction dependencies pinned","Info:   0 out of   5 pipCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 28 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-16T17:48:05.472Z","repository_id":41284542,"created_at":"2025-08-16T17:48:05.472Z","updated_at":"2025-08-16T17:48:05.472Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001507,"owners_count":26083118,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["brasil","erp","odoo","sped"],"created_at":"2024-12-03T20:12:17.682Z","updated_at":"2025-10-09T14:41:44.427Z","avatar_url":"https://github.com/akretion.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":".. image:: https://img.shields.io/pypi/v/sped-extractor.svg\n    :target: https://pypi.org/project/sped-extractor/\n    :alt: PyPI Version\n\n.. image:: https://img.shields.io/github/actions/workflow/status/akretion/sped-extractor/main.yml?branch=master\n    :target: https://github.com/akretion/sped-extractor/actions/workflows/main.yml\n    :alt: Build Status\n\n.. image:: https://img.shields.io/codecov/c/github/akretion/sped-extractor.svg\n    :target: https://codecov.io/gh/akretion/sped-extractor\n    :alt: Coverage Status\n\n.. image:: https://img.shields.io/pypi/l/sped-extractor.svg\n    :target: https://opensource.org/licenses/MIT\n    :alt: License\n\n==============\nsped-extractor\n==============\n\n\nEsse package extrai as tabelas dos pdf das `especificações do SPED \u003chttp://sped.rfb.gov.br/pasta/show/9\u003e`_ usando o package python `camelot-py`_ e cria arquivos CSV com as informações **dos registros e campos de cada módulo**, levemente formatados para ser utilizados por outros programas.\n\nOs módulos da SPED tratados por esse package são :\n\n- `ECD \u003chttp://sped.rfb.gov.br/pasta/show/1569\u003e`_\n- `ECF \u003chttp://sped.rfb.gov.br/pasta/show/1644\u003e`_\n- `EFD ICMS IPI \u003chttp://sped.rfb.gov.br/pasta/show/1573\u003e`_\n- `EFD Contribuições (PIS, COFINS) \u003chttp://sped.rfb.gov.br/pasta/show/1989\u003e`_\n\n\n📚  Para cada módulo estão gerados 4 arquivos :\n\n- *registers.csv* : a lista detalhada dos **registros** do módulo ``MODULE``.\n- *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).\n- *fields.csv* : a lista dos mesmos campos porém **com atributos \"interpretados\"**, utilizáveis mais facilmente por outros programas.\n\n📇 Uma vez ``sped-extractor`` for instalado, os campos, registros e blocos de cada módulo são facilmente accessiveis como **dicionários python**  :\n\n\u003e\u003e\u003e from spedextractor import get_fields, get_registers, get_blocks\n\u003e\u003e\u003e get_fields(\"ecd\")\n  [{'register': '0000', 'index': 2, 'code': 'LECD', 'desc': 'Texto fixo contendo “LECD”.', 'length': '004', 'type': 'char', 'required': True, [...]}, [...] ]\n\n\n\n**Índice**\n\n.. contents::\n   :local:\n\nArquivos extraidos\n==================\n\n=============================  ==========================\nRegistros                      CSV utilizável\n=============================  ==========================\nECD_registers.csv_             ECD_fields.csv_\nECF_registers.csv_             ECF_fields.csv_\nEFD_ICMS_IPI_registers.csv_    EFD_ICMS_IPI_fields.csv_\nEFD_PIS_COFINS_registers.csv_  EFD_PIS_COFINS_fields.csv_\n=============================  ==========================\n\nInstalação\n============\n\n.. code-block:: shell\n\n  $ pip install sped-extractor\n\n\nUtilização\n==========\n\nUma 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 :\n\n\u003e\u003e\u003e from spedextractor import get_fields, get_registers, get_blocks\n\u003e\u003e\u003e ecd_fields_2020 = get_fields(\"ecd\")\n  323 fields catched in ECD\n\u003e\u003e\u003e ecd_fields_2019 = get_fields(\"ecd\", 2019)\n  282 fields catched in ECD\n\u003e\u003e\u003e efd_pis_cofins_registers_2020 = get_registers(\"efd_pis_cofins\")\n  203 registers catched in EFD_PIS_COFINS\n\nÉ só indicar o nome do módulo (``\"ecd\"``, ``\"ecf\"``, ``\"efd_icms_ipi\"`` ou ``\"efd_pis_cofins\"``).\n\n\nExtração dos campos e registros\n===============================\n\nO package é composto de todos os scripts necessários à construção desses 4 tipos de arquivos CSV. Para usá-los e extrair as informações de novos pdfs do SPED, primeiro é necessário baixar o `repositório github \u003chttps://github.com/akretion/sped-extractor/\u003e`_ do projeto ::\n\n  $ git clone https://github.com/akretion/sped-extractor/\n\n🗄️ A pasta *spedextractor/specs/* reúne **os pdf** baixados, **os CSV** 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 :\n\n::\n\n  .\n  specs\n    ├── ecd/9\n    |   ├── ecd.pdf\n    │   ├── accurate_fields.csv\n    │   ├── fields.csv\n    │   └── registers.csv\n    ├── ecf/10\n    |   ├── ecf.pdf\n    |   [...]\n    ├── efd_icms_ipi/19\n    |   ├── efd_icms_ipi.pdf\n    |   [...]\n    ├── efd_pis_cofins/6\n    |   └── efd_pis_cofins.pdf\n    |   [...]\n\n\nVocê pode lançar o script principal do package (posicionando-se na raiz do projeto *sped-extractor/*)::\n\n  PATH/TO/sped-extractor$ python -m spedextractor\n\nEsse script vai realizar automaticamente as 3 etapas para a construção dos arquivos CSV :\n\n1. 📥 Baixar os pdf graça aos URLs informados (módulo ``download.py``) se for preciso.\n2. ⛏️ Extrair todas as tabelas desses pdfs com `camelot`_ e colocar os CSV brutos extraidos na subpasta *MODULE/LAYOUT/raw_camelot_csv/* (módulo ``extract_tables.py``)\n3. 🏗️ Construir os arquivos CSV interpretando essas tabelas brutas (módulo ``build_csv.py``)\n\n  ⚠️ É bom verificar se o package ``sped-extractor`` não for instalado no seu ambiente de trabalho com ``pip 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.\n\nObviamente 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: ::\n\n  $ python -m sped-download\n  $ python -m sped-extract-tables\n\n\nConfiguração\n============\n\nPatches\n~~~~~~~\n\nApesar 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.\n\nPara isso basta escrever a linha correta no arquivo *specs/MODULE/LAYOUT/camelot_patch/camelot_patch.csv* para ela ser applicada no lugar certo no CSV *accurate_fields.csv*.\n\n  🔎  O ``spedextractor`` aplica as linhas corretivas por padrão. Para não aplicar essas correções, usar a opção ``--no-patch``.\n\nCabeçalhos de Módulos\n~~~~~~~~~~~~~~~~~~~~~\n\nOs 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``.\n\nPara 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 :\n\n::\n\n  PATH/TO/sped-extractor$ python -m spedextractor.get_table_headers\n\n  ECD's headers :\n  ['Nº', 'Campo', 'Descrição', 'Tipo', 'Tamanho', 'Decimal']\n  ['Nº', 'Campo', 'Descrição', 'Tipo', 'Tamanho', 'Decimal', 'Valores Válidos', 'Obrigatório', 'Regras de Validação do Campo']\n  ['Nº', 'Campo', 'Descrição', '', 'Tipo Tamanho', 'Decimal', 'Valores Válidos', 'Obrigatório', 'Regras de Validação do Campo']\n  ['Nº', 'Campo', 'Descrição', 'Tipo', 'Tamanho', 'Decimal', 'Valores Válidos', 'Obrigatório', 'Regras de Validação de Campo']\n\n  [...]\n\n\nCréditos\n========\n\nAutores\n~~~~~~~\n\n* Akretion\n\nContributores\n~~~~~~~~~~~~~\n\n* Raphaël Valyi \u003craphael.valyi@akretion.com.br\u003e\n* Clément Mombereau \u003cclement.mombereau@akretion.com.br\u003e\n\n\nAdministradores\n~~~~~~~~~~~~~~~~\n\nEsse package está administrado por `Akretion \u003chttps://akretion.com/pt-BR\u003e`_.\n\n.. _camelot: https://github.com/atlanhq/camelot\n.. _python-sped: https://github.com/sped-br/python-sped/\n\n.. _ECD_registers.csv: https://github.com/akretion/sped-extractor/blob/master/spedextractor/specs/ecd/9/registers.csv\n.. _ECF_registers.csv: https://github.com/akretion/sped-extractor/blob/master/spedextractor/specs/ecf/10/registers.csv\n.. _EFD_ICMS_IPI_registers.csv: https://github.com/akretion/sped-extractor/blob/master/spedextractor/specs/efd_icms_ipi/19/registers.csv\n.. _EFD_PIS_COFINS_registers.csv: https://github.com/akretion/sped-extractor/blob/master/spedextractor/specs/efd_pis_cofins/6/registers.csv\n\n.. _ECD_fields.csv: https://github.com/akretion/sped-extractor/blob/master/spedextractor/specs/ecd/9/fields.csv\n.. _ECF_fields.csv: https://github.com/akretion/sped-extractor/blob/master/spedextractor/specs/ecf/10/fields.csv\n.. _EFD_ICMS_IPI_fields.csv: https://github.com/akretion/sped-extractor/blob/master/spedextractor/specs/efd_icms_ipi/19/fields.csv\n.. _EFD_PIS_COFINS_fields.csv: https://github.com/akretion/sped-extractor/blob/master/spedextractor/specs/efd_pis_cofins/6/fields.csv\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakretion%2Fsped-extractor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakretion%2Fsped-extractor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakretion%2Fsped-extractor/lists"}