Empezando

Requisitos

• Python 3.10 a 3.14
• Acceso a terminal (macOS, Linux o WSL)

Instalar

# Core install (deterministic parsers only)
pip install bankstatementparser

Extras opcionales para funcionalidades adicionales:

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

# Higher-fidelity table extraction (adds pdfplumber)
pip install 'bankstatementparser[hybrid-plus]'

# Vision-LLM path for scanned PDFs (adds pypdfium2)
pip install 'bankstatementparser[hybrid-vision]'

# LLM-powered transaction categorisation
pip install 'bankstatementparser[enrichment]'

# REST API microservice (FastAPI + uvicorn)
pip install 'bankstatementparser[api]'

# Optional Polars DataFrame support
pip install 'bankstatementparser[polars]'

Inicio rápido

Detectar y analizar cualquier formato estructurado

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 con archivos .xml (CAMT/PAIN.001), .csv, .ofx, .qfx, .mt940 y .sta.

Analizar CAMT.053

from bankstatementparser import CamtParser

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

Analizar PAIN.001

from bankstatementparser import Pain001Parser

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

Analizar extractos bancarios en PDF (pipeline híbrido)

El pipeline híbrido enruta los PDF de forma inteligente por tres rutas de extracción:

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

Cada extracción se verifica con la Regla de Oro: opening + credits − debits == closing.

Streaming de archivos grandes

Para archivos con miles de transacciones, use streaming para mantener la memoria acotada:

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

Análisis en memoria

Analice desde bytes sin E/S de disco — útil para flujos de trabajo SFTP o API:

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

Procesamiento paralelo de archivos

Analice varios archivos de forma concurrente:

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")

Escaneo masivo de directorios

Procese árboles de carpetas completos con deduplicación 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}")

Deduplicación

Hashes de transacción idempotentes para ingesta 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)}")

Categorización de transacciones (enriquecimiento)

Categorice transacciones automáticamente con clasificación basada en LLM:

from bankstatementparser.enrichment import Categorizer

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

Exportación contable (hledger / beancount)

Exporte transacciones a formatos de diario de contabilidad en texto plano:

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")

Verificación de saldo multidivisa

Verifique saldos de forma independiente por grupo de divisa:

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

Despliegue como microservicio FastAPI:

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

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

Endpoints:

• POST /ingest -- Analizar un archivo de extracto bancario
• GET /health -- Comprobación de estado

Procesamiento ZIP seguro

Procese archivos XML comprimidos con controles de seguridad integrados (protección contra bombas, rechazo de entradas cifradas):

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 de CLI

# Parse structured formats
bankstatementparser --type camt --input statement.xml
bankstatementparser --type pain001 --input payment.xml

# Hybrid PDF pipeline
bankstatementparser --type ingest --input statement.pdf
bankstatementparser --type ingest --input statement.pdf --output ledger.csv

# Interactive review mode
bankstatementparser --type review --input result.json
bankstatementparser --type review --input result.json --output reviewed.json

# Export to CSV with streaming
bankstatementparser --type camt --input statement.xml --output transactions.csv
bankstatementparser --type camt --input statement.xml --streaming --show-pii

Opciones de CLI:

• --type {camt,pain001,ingest,review} -- tipo de analizador o modo
• --input <path> -- archivo de entrada
• --output <path> -- archivo de exportación (CSV o JSON)
• --streaming -- streaming de archivos grandes
• --show-pii -- mostrar campos sensibles (redactados por defecto)
• --max-size <MB> -- límite de tamaño de archivo

Configuración de desarrollo 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

Ejecute el conjunto de pruebas:

pytest

Referencia de API

Clases de analizador

Funciones de utilidad

Función	Propósito
detect_statement_format(path)	Detectar formato de archivo automáticamente
create_parser(path, fmt)	Crear el analizador apropiado
parse_files_parallel(paths)	Analizar varios archivos de forma concurrente
iter_secure_xml_entries(zip_path)	Iterar entradas ZIP de forma segura
smart_ingest(path)	Extracción híbrida de PDF con verificación
scan_and_ingest(dir, pattern)	Escaneo masivo de directorios
verify_balance_multi_currency(txns)	Verificación de saldo por divisa
to_hledger(txns, account)	Exportar a formato de diario hledger
to_beancount(txns, account)	Exportar a formato de diario beancount

Clases de datos

Clase	Propósito
Deduplicator	Detectar transacciones duplicadas
DeduplicationResult	Resultado con coincidencias únicas, exactas y sospechosas
InputValidator	Validar rutas y formatos de archivos
Transaction	Registro de transacción normalizado
FileResult	Resultado del análisis paralelo
ZipXMLSource	Envoltorio de miembros ZIP
IngestResult	Resultado del pipeline híbrido con verificación
VerificationResult	Resultado de la verificación de saldo
Categorizer	Categorización de transacciones con LLM
AccountMapper	Reglas de mapeo de cuentas basadas en regex

Excepciones

Excepción	Cuándo se lanza
ParserError	Fallos de análisis
ExportError	Fallos de exportación (CSV/JSON/Excel)
ValidationError	Fallos de validación de entrada
ZipSecurityError	Fallos en controles de seguridad ZIP