Cielo EDI Parser: Biblioteca Open-Source Para Processar Extratos Eletrônicos CIELO (Inclui Pix)

Conciliar pagamentos de cartão é um problema que quase todo e-commerce e sistema de gestão financeira enfrenta.

Os arquivos EDI (Extrato Eletrônico) da Cielo vêm em formatos posicionais (CIELO03/04/09/15/16 - incluindo transações Pix via CIELO16) com estrutura complexa e documentação limitada.

Parsing manual? Propenso a erros. Cada linha tem formato diferente. Validação manual é inviável em escala.

Nossa solução: biblioteca open-source Python que transforma arquivos EDI em JSON/CSV com validação robusta via Pydantic v2.

Publicada no PyPI. 5 tipos de arquivo suportados. Pronta para produção.

O Problema: Arquivos EDI São Difíceis de Processar

Formato Posicional e Heterogêneo

Arquivos EDI da Cielo não são JSON ou CSV limpos. São texto posicional (padrão atual da Cielo, incluindo Pix via CIELO16) com múltiplos tipos de registro:

• Header (0): Metadados do arquivo
• UR Agenda (D): Resumo de valores por dia
• Detalhe (E): Transações individuais
• Pix (8): Transações Pix
• Negociação (A/B): Antecipação de recebíveis
• Conta (C): Dados bancários
• Reserva (R): Valores bloqueados
• Trailer (9): Totalizadores

Cada registro tem posições fixas para cada campo. Um erro de 1 caractere quebra o parsing.

Tipos de Arquivo Diferentes

Cada tipo tem estrutura diferente. Parsing genérico falha.

Problema Real em Produção

Clientes vinham com soluções artesanais:

• Scripts Python quebravam com campos novos
• Excel com macros VBA (impossível manter)
• Parsing regex (frágil e lento)
• Sem validação de integridade

Resultado: horas de retrabalho manual toda vez que Cielo mudava formato.

A Solução: Parser Robusto com Pydantic v2

Decisões de Design

Validação forte com Pydantic v2:

• Tipos estáticos (int, Decimal, datetime)
• Validação automática de campos
• Erros descritivos quando parsing falha

Streaming para arquivos grandes:

• Processa linha por linha (não carrega tudo em memória)
• Suporta arquivos de 10GB+
• Yield de registros individuais

Exportação flexível:

• JSON estruturado
• CSV (1 arquivo por tipo de registro)
• Acesso direto aos objetos Python

CLI incluída:

• Conversão rápida via terminal
• Scripts de automação

Implementação Técnica

Parsing com Validação Pydantic

Cada tipo de registro é um modelo Pydantic v2:

Campo posicional: caracteres 1-10 = número estabelecimento (10 dígitos)

Validação automática: se não for numérico de 10 dígitos → erro descritivo

Conversão de tipo: string → Decimal para valores monetários

Streaming de Arquivos Grandes

Problema: arquivo de 10GB não cabe em memória.

Solução: generator que processa linha por linha.

Memória constante: ~50MB independente do tamanho do arquivo.

Exportação Multi-Formato

JSON estruturado: ideal para APIs e integrações

CSV por tipo: facilita análise em Excel/BI

Objetos Python: para processamento customizado

Uso na Prática

Instalação

pip install cielo-edi

Requisitos: Python 3.9+, Pydantic 2.5+

Código Python

Processa arquivo completo em memória. Acessa dados com autocomplete.

Detecta automaticamente tipo CIELO03/04/09/15/16.

Streaming (Arquivos Grandes)

Processa arquivo de 10GB linha por linha sem explodir memória.

CLI

Converter para JSON:

cielo-edi arquivo.txt -o resultado.json

Converter para CSV:

cielo-edi arquivo.txt --formato csv --diretorio ./saida

Apenas informações:

cielo-edi arquivo.txt --info

Estrutura Interna

Tipos de Registro

0 - Header: Metadados do arquivo (tipo, data, estabelecimento)

D - UR Agenda: Unidade de Recebimento (valores por data)

E - Detalhe: Transação individual (NSU, valor, bandeira, parcelas)

8 - Pix: Transações Pix com identificador único

A - Resumo Negociação: Antecipação de recebíveis

B - Detalhe Negociação: Detalhe de cada antecipação

C - Conta: Dados bancários para crédito

R - Reserva: Valores bloqueados/reservados

9 - Trailer: Totalizadores e validação de integridade

Validação de Integridade

Quantidade de registros: Trailer.quantidade == registros processados

Valores totais: Soma de detalhes == totalizador do Trailer

Datas válidas: Formato YYYYMMDD estrito

Decimal correto: Valores com 2 casas decimais (centavos)

Casos de Uso Reais

1. Conciliação Bancária Automatizada

Problema: Conciliar 50k transações/mês manualmente

Solução: Parser + pipeline automatizado

Resultado: De 3 dias manual → 15 minutos automatizado

2. Integração com ERP

Problema: ERP precisa importar vendas Cielo

Solução: cielo-edi exporta JSON → API ERP importa

Resultado: Integração em tempo real (antes era D+7)

3. Dashboards BI

Problema: Analistas precisam de dados em SQL

Solução: cielo-edi → CSV → importação PostgreSQL

Resultado: Dashboards atualizados diariamente

4. Auditoria Financeira

Problema: Auditor precisa validar todos os recebíveis

Solução: cielo-edi gera CSV completo com validação

Resultado: Auditoria passou sem ressalvas (antes tinha divergências)

Métricas de Produção

Arquivos processados: 10.000+ em produção

Taxa de sucesso: 99.8% (erros apenas em arquivos corrompidos)

Performance: 1.2M linhas/minuto em streaming

Tamanho médio de arquivo: 5-50MB (mas suporta GB+)

Validações detectadas: 847 arquivos com inconsistências (que teriam passado sem validação)

Por Que Open-Source?

Benefício para a Comunidade

Parsing de EDI bancário é um problema comum. Cada empresa resolvendo do zero é retrabalho.

Open-source centraliza conhecimento e esforço.

Qualidade do Código

Código aberto = revisão pública = menos bugs

Issues e PRs melhoram a biblioteca constantemente

Adoção Mais Rápida

PyPI = pip install = adoção imediata

Sem vendor lock-in ou custos de licença

Stack Técnica

Linguagem: Python 3.9+

Validação: Pydantic v2 (performance + tipos)

Testes: Pytest com cobertura 95%+

Linting: Ruff + mypy (type checking)

CI/CD: GitHub Actions (testes automatizados)

Publicação: PyPI (pip install cielo-edi)

Docs: README completo + exemplos

Licença: MIT (uso comercial permitido)

Lições Aprendidas

Pydantic v2 É Perfeito Para Parsing

Validação de tipos + performance + erros descritivos = combinação ideal.

Antes usávamos dataclasses simples → muitos bugs silenciosos.

Streaming É Essencial

Arquivos bancários crescem. Hoje é 50MB, amanhã é 5GB.

Design para streaming desde o início evita refatoração dolorosa depois.

CLI Aumenta Adoção

Muitos usuários não querem escrever Python. Querem: cielo-edi arquivo.txt -o saida.json e pronto.

CLI simples = adoção 3x maior.

Documentação > Código

README bem escrito com exemplos práticos = menos issues de "como usar?"

Investir em docs economiza horas de suporte.

Testes Automatizados São Obrigatórios

Pytest com arquivos reais de teste evitou dezenas de bugs em produção.

Cada bug reportado vira um test case.

Quando Usar Esta Biblioteca

Quando NÃO Usar

Conclusão

Parsing de EDI bancário é um problema resolvido. Não precisa reinventar a roda.

cielo-edi é:

• Open-source (MIT)
• Validação robusta (Pydantic v2)
• Streaming para arquivos grandes
• CLI incluída
• Publicado no PyPI
• 5 tipos de arquivo suportados
• Produção-ready

pip install cielo-edi e comece a usar.

Contribuições, issues e feedback são bem-vindos!

Links:

PyPI: https://pypi.org/project/cielo-edi/

GitHub: https://github.com/jhamerski/cielo-edi

Docs: README completo no repositório

Issues: https://github.com/jhamerski/cielo-edi/issues

"Do formato posicional ao Pythonic: parsing EDI sem fricção."