Pagsisimula

Mga Kinakailangan

• Python 3.10 hanggang 3.14
• Terminal access (macOS, Linux, o WSL)

I-install

# Core install (mga deterministikong parser lamang)
pip install bankstatementparser

Mga opsyonal na extra para sa karagdagang kakayahan:

# Text-LLM path para sa mga digital PDF (litellm + pypdf)
pip install 'bankstatementparser[hybrid]'

# Mas mataas na katumpakan sa table extraction (nagdadagdag ng pdfplumber)
pip install 'bankstatementparser[hybrid-plus]'

# Vision-LLM path para sa mga na-scan na PDF (nagdadagdag ng pypdfium2)
pip install 'bankstatementparser[hybrid-vision]'

# LLM-powered na kategorisasyon ng transaksyon
pip install 'bankstatementparser[enrichment]'

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

# Opsyonal na suporta sa Polars DataFrame
pip install 'bankstatementparser[polars]'

Mabilis na Pagsisimula

Auto-Detect at I-parse ang Anumang Structured na Format

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

Gumagana ito sa .xml (CAMT/PAIN.001), .csv, .ofx, .qfx, .mt940, at .sta na mga file.

I-parse ang CAMT.053

from bankstatementparser import CamtParser

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

I-parse ang PAIN.001

from bankstatementparser import Pain001Parser

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

I-parse ang mga PDF Bank Statement (Hybrid Pipeline)

Matalinong niru-route ng hybrid pipeline ang mga PDF sa tatlong extraction path:

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

Bawat extraction ay bineberipika gamit ang Golden Rule: opening + credits − debits == closing.

Pag-stream ng Malalaking File

Para sa mga file na may libu-libong transaksyon, gumamit ng streaming upang panatilihing limitado ang memorya:

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

In-Memory Parsing

I-parse mula sa mga byte na walang disk I/O -- kapaki-pakinabang para sa mga SFTP o API workflow:

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

Parallel File Processing

Mag-parse ng maraming file nang sabay-sabay:

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

Bulk Directory Scanning

Iproseso ang buong folder tree na may awtomatikong deduplikasyon:

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

Deduplication

Idempotent na transaction hash para sa ligtas na incremental ingestion:

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

Kategorisasyon ng Transaksyon (Enrichment)

Awtomatikong ikategorya ang mga transaksyon gamit ang LLM-powered na klasipikasyon:

from bankstatementparser.enrichment import Categorizer

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

Ledger Export (hledger / beancount)

I-export ang mga transaksyon sa plaintext-accounting na journal format:

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

Multi-Currency na Beripikasyon ng Balanse

Beripikasyon ng balanse nang independyente sa bawat currency group:

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

I-deploy bilang FastAPI microservice:

# Simulan ang API server
bankstatementparser-api --port 8000

# Para sa mga container deployment
bankstatementparser-api --host 0.0.0.0 --port 9000

Mga endpoint:

• POST /ingest -- Mag-parse ng bank statement file
• GET /health -- Health check

Secure na Pagproseso ng ZIP

Iproseso ang mga naka-zip na XML file na may built-in na mga pagsusuri sa seguridad (bomb protection, encrypted entry rejection):

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

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

Paggamit ng CLI

# I-parse ang mga structured format
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

# I-export sa CSV gamit ang streaming
bankstatementparser --type camt --input statement.xml --output transactions.csv
bankstatementparser --type camt --input statement.xml --streaming --show-pii

Mga opsyon sa CLI:

• --type {camt,pain001,ingest,review} -- uri ng parser o mode
• --input <path> -- input file
• --output <path> -- export file (CSV o JSON)
• --streaming -- stream ng malalaking file
• --show-pii -- ipakita ang mga sensitibong field (na-redact bilang default)
• --max-size <MB> -- limitasyon sa laki ng file

Local Development Setup

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

Patakbuhin ang test suite:

pytest

Sanggunian ng API

Mga Klase ng Parser

Mga Utility Function

Function	Layunin
detect_statement_format(path)	Auto-detect ang format ng file
create_parser(path, fmt)	Lumikha ng naaangkop na parser
parse_files_parallel(paths)	Mag-parse ng maraming file nang sabay-sabay
iter_secure_xml_entries(zip_path)	Ulitin ang mga entry sa ZIP nang secure
smart_ingest(path)	Hybrid PDF extraction na may beripikasyon
scan_and_ingest(dir, pattern)	Bulk directory scanning
verify_balance_multi_currency(txns)	Beripikasyon ng balanse sa bawat currency
to_hledger(txns, account)	I-export sa hledger journal format
to_beancount(txns, account)	I-export sa beancount journal format

Mga Klase ng Data

Klase	Layunin
Deduplicator	I-detect ang mga duplicate na transaksyon
DeduplicationResult	Resulta na may natatangi, eksakto, at pinaghihinalaang mga tugma
InputValidator	I-validate ang mga path at format ng file
Transaction	Normalised na rekord ng transaksyon
FileResult	Resulta mula sa parallel parsing
ZipXMLSource	ZIP member wrapper
IngestResult	Resulta ng hybrid pipeline na may beripikasyon
VerificationResult	Kinalabasan ng beripikasyon ng balanse
Categorizer	LLM-powered na kategorisasyon ng transaksyon
AccountMapper	Regex-based na account mapping rule

Mga Exception

Exception	Kailan Itinaas
ParserError	Mga pagkabigo sa pag-parse
ExportError	Mga pagkabigo sa pag-export (CSV/JSON/Excel)
ValidationError	Mga pagkabigo sa pagpapatunay ng input
ZipSecurityError	Mga pagkabigo sa pagsusuri sa seguridad ng ZIP