Começando

Requisitos

• Python 3.10 a 3.14
• Acesso ao terminal (macOS, Linux ou WSL)

Instalar

# Instalação básica (apenas parsers determinísticos)
pip install bankstatementparser

Extras opcionais para recursos adicionais:

# Text-LLM path para PDFs digitais (litellm + pypdf)
pip install 'bankstatementparser[hybrid]'

# Extração de tabelas com maior fidelidade (adiciona pdfplumber)
pip install 'bankstatementparser[hybrid-plus]'

# Vision-LLM path para PDFs digitalizados (adiciona pypdfium2)
pip install 'bankstatementparser[hybrid-vision]'

# Categorização de transações via LLM
pip install 'bankstatementparser[enrichment]'

# Microsserviço REST API (FastAPI + uvicorn)
pip install 'bankstatementparser[api]'

# Suporte opcional a DataFrames Polars
pip install 'bankstatementparser[polars]'

Início Rápido

Detectar e Analisar Qualquer Formato Estruturado

from bankstatementparser import create_parser, detect_statement_format

fmt = detect_statement_format("transactions.ofx")
parser = create_parser("transactions.ofx", fmt)
df = parser.parse()  # pandas DataFrame
print(df.head())

Funciona com arquivos .xml (CAMT/PAIN.001), .csv, .ofx, .qfx, .mt940 e .sta.

Analisar CAMT.053

from bankstatementparser import CamtParser

parser = CamtParser("statement.xml")
transactions = parser.parse()

Analisar PAIN.001

from bankstatementparser import Pain001Parser

parser = Pain001Parser("payment.xml")
payments = parser.parse()

Analisar Extratos Bancários em PDF (Pipeline Híbrido)

O pipeline híbrido roteia PDFs de forma inteligente por três caminhos de extração:

from bankstatementparser.hybrid import smart_ingest

result = smart_ingest("statement.pdf")
print(result.source_method)         # "deterministic" | "llm" | "vision"
print(result.verification.status)   # VERIFIED | DISCREPANCY | FAILED
print(result.transactions)          # List of extracted transactions

Toda extração é verificada com a Golden Rule: opening + credits − debits == closing.

Streaming de Arquivos Grandes

Para arquivos com milhares de transações, use streaming para manter a memória limitada:

parser = CamtParser("large_statement.xml")
for transaction in parser.parse_streaming(redact_pii=True):
    process(transaction)  # Memory stays constant

Análise em Memória

Analise bytes sem E/S de disco — útil para fluxos de trabalho SFTP ou API:

xml_bytes = download_from_sftp()
parser = CamtParser.from_bytes(xml_bytes, source_name="daily.xml")
transactions = parser.parse()

Processamento Paralelo de Arquivos

Analise vários arquivos simultaneamente:

from bankstatementparser import parse_files_parallel

results = parse_files_parallel([
    "statements/jan.xml",
    "statements/feb.xml",
    "statements/mar.xml",
])
for r in results:
    print(r.path, r.status, len(r.transactions), "rows")

Varredura de Diretórios em Massa

Processe árvores de pastas inteiras com deduplicação automática:

from bankstatementparser.hybrid import scan_and_ingest

batch = scan_and_ingest("statements/2026/", pattern="**/*.pdf")
print(f"Processed: {len(batch.results)} files")
print(f"Unique transactions: {batch.unique_count}")

Deduplicação

Hashes de transação idempotentes para ingestão incremental segura:

from bankstatementparser import CamtParser, Deduplicator

parser = CamtParser("statement.xml")
dedup = Deduplicator()
result = dedup.deduplicate(dedup.from_dataframe(parser.parse()))

print(f"Unique: {len(result.unique_transactions)}")
print(f"Exact duplicates: {len(result.exact_duplicates)}")
print(f"Suspected matches: {len(result.suspected_matches)}")

Categorização de Transações (Enriquecimento)

Categorize transações automaticamente com classificação via LLM:

from bankstatementparser.enrichment import Categorizer

categorizer = Categorizer()
enriched = categorizer.categorize_batch(transactions)
for txn in enriched:
    print(f"{txn.description}: {txn.category}")

Exportação Contábil (hledger / beancount)

Exporte transações para formatos de journal de contabilidade em texto simples:

from bankstatementparser.export import to_hledger, to_beancount

journal = to_hledger(transactions, account="Assets:Bank:Checking")
beancount_journal = to_beancount(transactions, account="Assets:Bank:Checking")

Verificação de Saldo Multimoeda

Verifique saldos de forma independente por grupo de moeda:

from bankstatementparser.hybrid import verify_balance_multi_currency

results = verify_balance_multi_currency(transactions)
for currency, verification in results.items():
    print(f"{currency}: {verification.status}")

REST API

Implante como microsserviço FastAPI:

# Start the API server
bankstatementparser-api --port 8000

# For container deployments
bankstatementparser-api --host 0.0.0.0 --port 9000

Endpoints:

• POST /ingest -- Analisa um arquivo de extrato bancário
• GET /health -- Verificação de saúde

Processamento ZIP Seguro

Processe arquivos XML compactados com verificações de segurança integradas (proteção contra bombas, rejeição de entradas criptografadas):

from bankstatementparser import iter_secure_xml_entries, CamtParser

for entry in iter_secure_xml_entries("statements.zip"):
    parser = CamtParser.from_bytes(entry.xml_bytes, source_name=entry.source_name)
    print(f"{entry.source_name}: {len(parser.parse())} transactions")

Exportar

parser = CamtParser("statement.xml")
parser.export_csv("output.csv")
parser.export_json("output.json")

# Polars (requires bankstatementparser[polars])
polars_df = parser.to_polars()

# Excel
parser.camt_to_excel("output.xlsx")

Uso da CLI

# Analisar formatos estruturados
bankstatementparser --type camt --input statement.xml
bankstatementparser --type pain001 --input payment.xml

# Pipeline híbrido de PDF
bankstatementparser --type ingest --input statement.pdf
bankstatementparser --type ingest --input statement.pdf --output ledger.csv

# Modo de revisão interativa
bankstatementparser --type review --input result.json
bankstatementparser --type review --input result.json --output reviewed.json

# Exportar para CSV com streaming
bankstatementparser --type camt --input statement.xml --output transactions.csv
bankstatementparser --type camt --input statement.xml --streaming --show-pii

Opções da CLI:

• --type {camt,pain001,ingest,review} -- tipo de parser ou modo
• --input <path> -- arquivo de entrada
• --output <path> -- arquivo de exportação (CSV ou JSON)
• --streaming -- streaming de arquivos grandes
• --show-pii -- mostra campos sensíveis (redados por padrão)
• --max-size <MB> -- limite de tamanho do arquivo

Configuração de Desenvolvimento Local

git clone https://github.com/sebastienrousseau/bankstatementparser.git
cd bankstatementparser
python3 -m venv .venv && source .venv/bin/activate
pip install poetry && poetry install --with dev
make install-hooks   # pre-commit hook runs `make verify` before every commit

Execute o conjunto de testes:

pytest

Referência da API

Classes de Parser

Funções Utilitárias

Função	Propósito
detect_statement_format(path)	Detectar formato do arquivo automaticamente
create_parser(path, fmt)	Criar o parser apropriado
parse_files_parallel(paths)	Analisar vários arquivos simultaneamente
iter_secure_xml_entries(zip_path)	Iterar entradas ZIP com segurança
smart_ingest(path)	Extração híbrida de PDF com verificação
scan_and_ingest(dir, pattern)	Varredura de diretórios em massa
verify_balance_multi_currency(txns)	Verificação de saldo por moeda
to_hledger(txns, account)	Exportar para formato journal hledger
to_beancount(txns, account)	Exportar para formato journal beancount

Classes de Dados

Classe	Propósito
Deduplicator	Detectar transações duplicadas
DeduplicationResult	Resultado com correspondências únicas, exatas e suspeitas
InputValidator	Validar caminhos e formatos de arquivos
Transaction	Registro de transação normalizado
FileResult	Resultado da análise paralela
ZipXMLSource	Wrapper de membro ZIP
IngestResult	Resultado do pipeline híbrido com verificação
VerificationResult	Resultado da verificação de saldo
Categorizer	Categorização de transações via LLM
AccountMapper	Regras de mapeamento de contas baseadas em regex

Exceções

Exceção	Quando levantada
ParserError	Falhas na análise
ExportError	Falhas na exportação (CSV/JSON/Excel)
ValidationError	Falhas na validação de entrada
ZipSecurityError	Falhas na verificação de segurança ZIP