Noțiuni de bază

Cerințe

• Python 3.10 până la 3.14
• Acces la terminal (macOS, Linux sau WSL)

Instalare

# Instalare de bază (doar parsere deterministe)
pip install bankstatementparser

Extensii opționale pentru funcționalități suplimentare:

# Calea Text-LLM pentru PDF-uri digitale (litellm + pypdf)
pip install 'bankstatementparser[hybrid]'

# Extracție de tabele cu fidelitate mai mare (adaugă pdfplumber)
pip install 'bankstatementparser[hybrid-plus]'

# Calea Vision-LLM pentru PDF-uri scanate (adaugă pypdfium2)
pip install 'bankstatementparser[hybrid-vision]'

# Categorizare a tranzacțiilor prin LLM
pip install 'bankstatementparser[enrichment]'

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

# Suport opțional pentru DataFrames Polars
pip install 'bankstatementparser[polars]'

Pornire rapidă

Detectare automată și analizare a oricărui format structurat

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

Funcționează cu fișiere .xml (CAMT/PAIN.001), .csv, .ofx, .qfx, .mt940 și .sta.

Analizare CAMT.053

from bankstatementparser import CamtParser

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

Analizare PAIN.001

from bankstatementparser import Pain001Parser

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

Analizare extrase bancare PDF (pipeline hibrid)

Pipeline-ul hibrid rutează inteligent PDF-urile prin trei căi de extracție:

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

Fiecare extracție este verificată cu Regula de Aur: opening + credits − debits == closing.

Streaming pentru fișiere mari

Pentru fișiere cu mii de tranzacții, folosiți streaming pentru a menține memoria limitată:

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

Parsare în memorie

Analizați din octeți fără I/O pe disc — util pentru fluxuri SFTP sau API:

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

Procesare paralelă a fișierelor

Analizați mai multe fișiere simultan:

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

Scanare în masă a directoarelor

Procesați arbori întregi de foldere cu deduplicare automată:

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

Deduplicare

Hash-uri idempotente ale tranzacțiilor pentru ingestie incrementală sigură:

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

Categorizare tranzacții (îmbogățire)

Categorizați automat tranzacțiile folosind clasificare prin LLM:

from bankstatementparser.enrichment import Categorizer

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

Export registru (hledger / beancount)

Exportați tranzacții în formate de jurnal pentru contabilitate în text simplu:

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

Verificare sold multi-valută

Verificați soldurile independent pe fiecare grup de valută:

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

Implementați ca microserviciu FastAPI:

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

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

Endpoint-uri:

• POST /ingest -- Analizează un fișier de extras bancar
• GET /health -- Verificare de stare

Procesare ZIP securizată

Procesați fișiere XML arhivate cu verificări de securitate încorporate (protecție bomb, respingere intrări criptate):

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

Export

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

Utilizare 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

Opțiuni CLI:

• --type {camt,pain001,ingest,review} -- tipul parserului sau modul
• --input <path> -- fișier de intrare
• --output <path> -- fișier de export (CSV sau JSON)
• --streaming -- streaming pentru fișiere mari
• --show-pii -- afișează câmpurile sensibile (redactate implicit)
• --max-size <MB> -- limită de dimensiune a fișierului

Configurare dezvoltare 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

Rulați suita de teste:

pytest

Referință API

Clase parser

Funcții utilitare

Funcție	Scop
detect_statement_format(path)	Detectare automată a formatului fișierului
create_parser(path, fmt)	Crearea parserului corespunzător
parse_files_parallel(paths)	Analizare a mai multor fișiere simultan
iter_secure_xml_entries(zip_path)	Iterare securizată a intrărilor ZIP
smart_ingest(path)	Extracție hibridă PDF cu verificare
scan_and_ingest(dir, pattern)	Scanare în masă a directoarelor
verify_balance_multi_currency(txns)	Verificare sold pe fiecare valută
to_hledger(txns, account)	Export în format jurnal hledger
to_beancount(txns, account)	Export în format jurnal beancount

Clase de date

Clasă	Scop
Deduplicator	Detectare tranzacții duplicate
DeduplicationResult	Rezultat cu potriviri unice, exacte și suspectate
InputValidator	Validare căi și formate de fișiere
Transaction	Înregistrare normalizată a tranzacțiilor
FileResult	Rezultat din parsare paralelă
ZipXMLSource	Wrapper pentru membrii ZIP
IngestResult	Rezultat pipeline hibrid cu verificare
VerificationResult	Rezultat verificare sold
Categorizer	Categorizare tranzacții prin LLM
AccountMapper	Reguli de mapare conturi bazate pe regex

Excepții

Excepție	Când este ridicată
ParserError	Erori de parsare
ExportError	Erori la export (CSV/JSON/Excel)
ValidationError	Erori de validare a intrărilor
ZipSecurityError	Erori la verificarea securității ZIP