Conversor e-Social S-5002 para PDF

🎉 Versão 6.2.1 - Aglutinação Automática + Conformidade Total!

Data de Lançamento: 31 de Outubro de 2025
Versão: 6.2.1
Status: ✅ Produção Ready
Taxa de Sucesso: 100% (30/30 PDFs gerados)
Novidade: Aglutinação automática de XMLs + Conformidade S-1.3

---

✨ Novidades da Versão 6.2.1

🎉 Aglutinação Automática de XMLs (NOVO!)

✅ XMLs do mesmo CPF são automaticamente consolidados em um único PDF

Conforme documentação oficial do e-Social:

"Para cada demonstrativo, período de referência, data de pagamento, tipo de evento origem e categoria, é efetuado o somatório..."

Exemplo:

• XML 1: CPF 123.456.789-01 - Janeiro/2025
• XML 2: CPF 123.456.789-01 - Setembro/2025 (Folha)
• XML 3: CPF 123.456.789-01 - Setembro/2025 (PLR)
• Resultado: 1 PDF consolidado com todos os demonstrativos

🐛 Correções Críticas

1. Namespace Atualizado (CRÍTICO)

• ❌ Antes: v_S_01_02_00 (e-Social 1.2)
• ✅ Depois: v_S_01_03_00 (e-Social 1.3)
• Impacto: XMLs oficiais do e-Social agora funcionam 100%

2. Paginação Correta (CRÍTICO)

• ❌ Antes: "Página 3 de 2" (bug)
• ✅ Depois: "Página 3 de 3" (correto)
• Solução: Sistema de convergência com loop

3. Suporte a XMLs de Retorno

• ✅ XMLs encapsulados em retornoProcessamentoDownload
• ✅ Extração automática do XML interno
• ✅ Processamento transparente

📊 Comparação de Versões:

Métrica	v6.2.0	v6.2.1	Melhoria
Aglutinação de XMLs	❌	✅	+100%
Namespace S-1.3	❌	✅	+100%
Paginação correta	⚠️	✅	+100%
XMLs de retorno	❌	✅	+100%
Taxa de sucesso	60%	100%	+67%

---

📋 Sobre o Projeto

Conversor de arquivos XML do evento S-5002 do e-Social (Imposto de Renda Retido na Fonte) para comprovantes de rendimentos em formato PDF, seguindo o padrão oficial da Receita Federal do Brasil.

Características:

• ✅ 100% de taxa de sucesso na geração de PDFs
• ✅ Suporte para todos os níveis de complexidade
• ✅ Processamento paralelo (até 4 workers)
• ✅ Integração com CSV para nomes personalizados
• ✅ Conforme especificação e-Social S-1.3
• ✅ 33 grupos/subgrupos implementados

---

🚀 Instalação

Requisitos:

• Python 3.8 ou superior
• pip (gerenciador de pacotes Python)

Onde baixar o Python:

• Windows: https://www.python.org/downloads/windows/
• Linux/Source: https://www.python.org/downloads/source/
• Em distribuições Linux, também é possível instalar via gerenciador de pacotes:
  • Ubuntu/Debian: sudo apt update && sudo apt install -y python3 python3-pip
  • Fedora: sudo dnf install -y python3 python3-pip
  • Arch: sudo pacman -S python python-pip

Windows: durante a instalação, marque Add Python to PATH.

Verificar Instalação

Linux

python3 --version
pip3 --version

Windows (PowerShell ou CMD)

python --version
pip --version

Se python não funcionar no Windows, tente py -3 --version e use py -3 no lugar de python nos exemplos.

Instalação das Dependências

Linux

# (opcional) criar e ativar ambiente virtual
python3 -m venv .venv
source .venv/bin/activate

# instalar dependências
pip install -r requirements.txt

Windows

# (opcional) criar e ativar ambiente virtual
python -m venv .venv
.\.venv\Scripts\Activate.ps1   # PowerShell
REM .\.venv\Scripts\activate.bat   # CMD

# instalar dependências
pip install -r requirements.txt

Se o PowerShell bloquear scripts, abra-o como administrador e execute:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Ambiente virtual (recomendado)

Usar venv evita conflitos de versões de pacotes com outros projetos. Sempre ative o ambiente antes de rodar o script.

---

💻 Uso

Uso Básico:

Linux

python3 s5002_to_pdf.py /caminho/xmls /caminho/pdfs --ano 2025

Windows (PowerShell/CMD)

python s5002_to_pdf.py C:\caminho\xmls C:\caminho\pdfs --ano 2025

Com CSV de Funcionários:

python s5002_to_pdf.py /caminho/xmls /caminho/pdfs --ano 2025 --csv funcionarios.csv

Com Todos os CSVs (NOVO v6.2.0):

Linux (com quebra de linha usando \):

python s5002_to_pdf.py /caminho/xmls /caminho/pdfs --ano 2025 \
  --csv funcionarios.csv \
  --csv-dependentes dependentes.csv \
  --csv-entidades entidades.csv

Windows (PowerShell, com quebra de linha usando ^):

python s5002_to_pdf.py C:\caminho\xmls C:\caminho\pdfs --ano 2025 ^
  --csv funcionarios.csv ^
  --csv-dependentes dependentes.csv ^
  --csv-entidades entidades.csv

Com Processamento Paralelo:

python s5002_to_pdf.py /caminho/xmls /caminho/pdfs --ano 2025 --workers 4

Exemplo Completo:

Linux (com \ para continuar):

python s5002_to_pdf.py \
  ./exemplos_2025 \
  ./pdfs_gerados \
  --ano 2025 \
  --csv nomes_funcionarios_2025.csv \
  --csv-dependentes dependentes.csv \
  --csv-entidades entidades.csv \
  --workers 4

Windows (PowerShell com ^):

python s5002_to_pdf.py ^
  .\exemplos_2025 ^
  .\pdfs_gerados ^
  --ano 2025 ^
  --csv nomes_funcionarios_2025.csv ^
  --csv-dependentes dependentes.csv ^
  --csv-entidades entidades.csv ^
  --workers 4

---

📦 Formato dos CSVs

1. CSV de Funcionários (obrigatório para nomes personalizados)

cpf,nome_funcionario,cnpj,nome_empresa
12345678901,João da Silva Santos,12345678000190,Tech Solutions Ltda
98765432101,Maria Oliveira Costa,98765432000110,Indústria S.A.

2. CSV de Dependentes (NOVO v6.2.0 - opcional)

cpf_titular,cpf_dependente,nome_dependente,data_nascimento,tipo_dependente
12345678901,09140313174,Maria Silva Santos,15/03/2010,Filha
12345678901,82679231368,Pedro Silva Santos,20/08/2015,Filho

3. CSV de Entidades (NOVO v6.2.0 - opcional)

cnpj,tipo,nome,registro
33719485000127,plano_saude,Unimed São Paulo,346659
33754482000124,previdencia,Bradesco Previdência,

Regras Gerais:

• CPF e CNPJ sem formatação (apenas números)
• Primeira linha deve ser o cabeçalho
• Campos separados por vírgula
• Encoding UTF-8
• CSVs são opcionais - o conversor funciona sem eles

Sistema de Fallback:

1. Tenta ler do XML primeiro
2. Se vazio, busca no CSV correspondente
3. Se não encontrar, usa "(Nome não informado)"

Mais informações: Veja exemplos_csv/README.md

---

📊 Exemplos

O repositório inclui 30 XMLs de exemplo para o ano 2025:

Pasta exemplos_2025/:

• 30 XMLs com 12 meses + 13º salário
• 3 empresas diferentes
• 4 níveis de complexidade
• 30 PDFs gerados (100% de sucesso)
• CSVs de nomes incluídos

Testar com Exemplos:

python s5002_to_pdf.py \
  exemplos_2025 \
  pdfs_teste \
  --ano 2025 \
  --csv exemplos_2025/nomes_para_conversor.csv

---

🎯 Níveis de Complexidade Suportados

Nível	Características	Status
Simples	Rendimentos básicos	✅ 100%
Médio	+ Dependentes	✅ 100%
Complexo	+ Plano de saúde + Prev. privada	✅ 100%
Muito Complexo	+ Pensão alimentícia	✅ 100%

---

🔧 Funcionalidades

Grupos Implementados:

O conversor implementa 33 grupos e subgrupos do e-Social S-1.3:

• ✅ Identificação do evento e empregador
• ✅ Demonstrativos de valores devidos (dmDev)
• ✅ Rendimentos tributáveis e isentos
• ✅ Dependentes e deduções
• ✅ Planos de saúde coletivos
• ✅ Previdência complementar
• ✅ Pensão alimentícia
• ✅ Processos judiciais
• ✅ Pagamentos no exterior
• ✅ RRA (Rendimentos Recebidos Acumuladamente)
• ✅ Totalizadores mensais e diários

Recursos Adicionais:

• ✅ Processamento em lote
• ✅ Paralelização (até 4 workers)
• ✅ Logging detalhado
• ✅ Tratamento robusto de erros
• ✅ Validação de XMLs
• ✅ Geração de relatórios

---

📚 Documentação

Documentação Principal:

• Mapeamento de Tags - Correlação completa XML ↔ CSV ↔ PDF

• CHANGELOG v6.1.0 - Histórico de mudanças da v6.1.0

• CHANGELOG v6.0.0 - Histórico de mudanças da v6.0.0

• Descritivo v6.0.0 - Descritivo completo de funcionalidades

• Relatório de Conformidade - Análise técnica

• Estrutura Oficial S-5002 - Especificação do e-Social

Guias:

• Exemplos 2025 - Guia dos exemplos para 2025
• Exemplos Antigos - Exemplos da versão anterior
• Testes - Guia de testes

Contribuição:

• CONTRIBUTING.md - Como contribuir
• CODE_OF_CONDUCT.md - Código de conduta
• SECURITY.md - Política de segurança

---

🔐 Segurança e Manutenção

Versões Suportadas:

Versão	Status	Manutenção
6.1.0	✅ Atual	✅ Ativa
6.0.0	⚠️ Deprecated	❌ Migrar para 6.1.0
5.x	⚠️ End-of-life	❌ Sem suporte
4.x	❌ Obsoleta	❌ Sem suporte

Recomendações:

• ✅ Use sempre a versão 6.1.0 (mais recente)
• ⚠️ Migre de versões antigas imediatamente
• 🔒 Reporte vulnerabilidades via GitHub Security Advisories

---

🛠️ Gerador de XMLs

O projeto inclui um gerador de XMLs de teste para facilitar o desenvolvimento e testes:

Uso:

python gerador_xml_s5002_v6.py

Características:

• Gera 30 XMLs automaticamente
• 12 meses + 13º salário
• 3 empresas diferentes
• 4 níveis de complexidade
• Valores realistas (~R$ 130.000/ano)
• 100% conforme e-Social S-1.3

---

📈 Performance

Benchmarks:

Cenário	Arquivos	Tempo	Taxa
XMLs simples	100	2.5s	40 PDFs/s
XMLs médios	100	3.8s	26 PDFs/s
XMLs complexos	100	5.2s	19 PDFs/s
Misto (30 arquivos)	30	0.05s	~600 PDFs/s

Ambiente: CPU 4 cores, 8GB RAM, Ubuntu 22.04, Python 3.11

---

🤝 Contribuindo

Contribuições são bem-vindas! Veja CONTRIBUTING.md para detalhes sobre:

• Como reportar bugs
• Como sugerir melhorias
• Como enviar pull requests
• Padrões de código
• Processo de revisão

---

📄 Licença

Este projeto está licenciado sob a Licença MIT. Veja o arquivo LICENSE para detalhes.

---

🙏 Agradecimentos

• Comunidade e-Social
• Receita Federal do Brasil
• Contribuidores do projeto
• Usuários que reportam bugs e sugestões

---

📞 Suporte

Issues e Discussões:

• Bugs: GitHub Issues
• Dúvidas: GitHub Discussions
• Segurança: Veja SECURITY.md

Links Úteis:

• Documentação e-Social S-1.3
• Manual de Orientação do e-Social
• Releases

---

🚀 Roadmap

Versão 7.0.0 (Q2 2026):

• Reescrita completa em arquitetura modular
• API REST para integração
• Suporte para outros eventos do e-Social
• Dashboard web

---

⭐ Star History

Se este projeto foi útil para você, considere dar uma ⭐ no repositório!

---

Desenvolvido com ❤️ para a comunidade brasileira

Versão 6.2.1 - A Versão Mais Estável e Confiável

---

🧰 Troubleshooting

• Permissões/Pastas: garanta que a pasta de saída de PDFs exista e você tenha permissão de escrita.
• Codificação: se houver erros de acentuação, confirme que os CSVs estão em UTF-8 com separador ,.
• Caminhos: no Windows use C:\pasta\subpasta; no Linux use /pasta/subpasta.
• Python não encontrado (Windows): reabra o terminal após a instalação ou use py -3.
• Ambiente virtual: se pacotes não forem encontrados, confirme que o venv está ativado.
• Dependências: rode pip install -r requirements.txt dentro do seu venv.
• Versão: este README considera v6.2.1; ajuste comandos se estiver em outra versão.