เริ่มต้นใช้งาน

ข้อกำหนดเบื้องต้น

• Python 3.10 ถึง 3.14
• การเข้าถึง Terminal (macOS, Linux หรือ WSL)

การติดตั้ง

# ติดตั้งแบบพื้นฐาน (deterministic parsers เท่านั้น)
pip install bankstatementparser

ตัวเลือกเสริมสำหรับความสามารถเพิ่มเติม:

# เส้นทาง Text-LLM สำหรับ PDF ดิจิทัล (litellm + pypdf)
pip install 'bankstatementparser[hybrid]'

# การดึงตารางที่แม่นยำยิ่งขึ้น (เพิ่ม pdfplumber)
pip install 'bankstatementparser[hybrid-plus]'

# เส้นทาง Vision-LLM สำหรับ PDF สแกน (เพิ่ม pypdfium2)
pip install 'bankstatementparser[hybrid-vision]'

# การจัดหมวดหมู่ธุรกรรมด้วย LLM
pip install 'bankstatementparser[enrichment]'

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

# รองรับ Polars DataFrame (ตัวเลือกเสริม)
pip install 'bankstatementparser[polars]'

เริ่มต้นอย่างรวดเร็ว

ตรวจจับอัตโนมัติและแยกวิเคราะห์รูปแบบที่มีโครงสร้าง

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

ใช้ได้กับไฟล์ .xml (CAMT/PAIN.001), .csv, .ofx, .qfx, .mt940 และ .sta

แยกวิเคราะห์ CAMT.053

from bankstatementparser import CamtParser

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

แยกวิเคราะห์ PAIN.001

from bankstatementparser import Pain001Parser

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

แยกวิเคราะห์ใบแจ้งยอดธนาคาร PDF (ไปป์ไลน์ไฮบริด)

ไปป์ไลน์ไฮบริดจะส่ง PDF ผ่านเส้นทางการดึงข้อมูลสามเส้นทางอย่างชาญฉลาด:

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

การดึงข้อมูลทุกครั้งจะถูกตรวจสอบด้วย Golden Rule: opening + credits − debits == closing

การสตรีมไฟล์ขนาดใหญ่

สำหรับไฟล์ที่มีธุรกรรมหลายพันรายการ ใช้การสตรีมเพื่อจำกัดหน่วยความจำ:

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

การแยกวิเคราะห์ในหน่วยความจำ

แยกวิเคราะห์จากไบต์โดยไม่ต้องใช้ดิสก์ I/O -- เหมาะสำหรับเวิร์กโฟลว์ SFTP หรือ API:

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

การประมวลผลไฟล์แบบขนาน

แยกวิเคราะห์หลายไฟล์พร้อมกัน:

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

การสแกนไดเรกทอรีจำนวนมาก

ประมวลผลโฟลเดอร์ทั้งหมดพร้อมการขจัดข้อมูลซ้ำอัตโนมัติ:

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

การขจัดข้อมูลซ้ำ

Transaction hashes แบบ idempotent สำหรับการนำเข้าแบบ incremental อย่างปลอดภัย:

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

การจัดหมวดหมู่ธุรกรรม (Enrichment)

จัดหมวดหมู่ธุรกรรมอัตโนมัติโดยใช้การจำแนกด้วย LLM:

from bankstatementparser.enrichment import Categorizer

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

การส่งออก Ledger (hledger / beancount)

ส่งออกธุรกรรมเป็นรูปแบบ journal สำหรับบัญชีแบบ plaintext:

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

การตรวจสอบยอดคงเหลือหลายสกุลเงิน

ตรวจสอบยอดคงเหลือแยกตามกลุ่มสกุลเงิน:

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

ใช้งานเป็น FastAPI microservice:

# เริ่มต้นเซิร์ฟเวอร์ API
bankstatementparser-api --port 8000

# สำหรับการ deploy แบบ container
bankstatementparser-api --host 0.0.0.0 --port 9000

Endpoints:

• POST /ingest -- แยกวิเคราะห์ไฟล์ใบแจ้งยอดธนาคาร
• GET /health -- ตรวจสอบสถานะ

การประมวลผล ZIP อย่างปลอดภัย

ประมวลผลไฟล์ XML ที่บีบอัดพร้อมการตรวจสอบความปลอดภัยในตัว (ป้องกัน bomb, ปฏิเสธรายการที่เข้ารหัส):

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

การส่งออก

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

การใช้งาน CLI

# แยกวิเคราะห์รูปแบบที่มีโครงสร้าง
bankstatementparser --type camt --input statement.xml
bankstatementparser --type pain001 --input payment.xml

# ไปป์ไลน์ PDF แบบไฮบริด
bankstatementparser --type ingest --input statement.pdf
bankstatementparser --type ingest --input statement.pdf --output ledger.csv

# โหมดตรวจสอบแบบโต้ตอบ
bankstatementparser --type review --input result.json
bankstatementparser --type review --input result.json --output reviewed.json

# ส่งออกเป็น CSV พร้อมสตรีมมิง
bankstatementparser --type camt --input statement.xml --output transactions.csv
bankstatementparser --type camt --input statement.xml --streaming --show-pii

ตัวเลือก CLI:

• --type {camt,pain001,ingest,review} -- ประเภท parser หรือโหมด
• --input <path> -- ไฟล์อินพุต
• --output <path> -- ไฟล์ส่งออก (CSV หรือ JSON)
• --streaming -- สตรีมไฟล์ขนาดใหญ่
• --show-pii -- แสดงฟิลด์ที่ละเอียดอ่อน (ปกปิดตามค่าเริ่มต้น)
• --max-size <MB> -- ขีดจำกัดขนาดไฟล์

การตั้งค่าสำหรับการพัฒนาในเครื่อง

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

รันชุดทดสอบ:

pytest

API Reference

คลาส Parser

ฟังก์ชันยูทิลิตี

ฟังก์ชัน	วัตถุประสงค์
detect_statement_format(path)	ตรวจจับรูปแบบไฟล์อัตโนมัติ
create_parser(path, fmt)	สร้าง parser ที่เหมาะสม
parse_files_parallel(paths)	แยกวิเคราะห์หลายไฟล์พร้อมกัน
iter_secure_xml_entries(zip_path)	วนรายการ ZIP อย่างปลอดภัย
smart_ingest(path)	ดึงข้อมูล PDF แบบไฮบริดพร้อมการตรวจสอบ
scan_and_ingest(dir, pattern)	สแกนไดเรกทอรีจำนวนมาก
verify_balance_multi_currency(txns)	ตรวจสอบยอดคงเหลือตามสกุลเงิน
to_hledger(txns, account)	ส่งออกเป็นรูปแบบ hledger journal
to_beancount(txns, account)	ส่งออกเป็นรูปแบบ beancount journal

คลาสข้อมูล

คลาส	วัตถุประสงค์
Deduplicator	ตรวจจับธุรกรรมที่ซ้ำกัน
DeduplicationResult	ผลลัพธ์พร้อมรายการไม่ซ้ำ ซ้ำตรง และต้องสงสัย
InputValidator	ตรวจสอบเส้นทางและรูปแบบไฟล์
Transaction	บันทึกธุรกรรมที่ปรับมาตรฐานแล้ว
FileResult	ผลลัพธ์จากการแยกวิเคราะห์แบบขนาน
ZipXMLSource	wrapper สำหรับสมาชิก ZIP
IngestResult	ผลลัพธ์ไปป์ไลน์ไฮบริดพร้อมการตรวจสอบ
VerificationResult	ผลลัพธ์การตรวจสอบยอดคงเหลือ
Categorizer	การจัดหมวดหมู่ธุรกรรมด้วย LLM
AccountMapper	กฎแมปบัญชีด้วย regex

ข้อยกเว้น

ข้อยกเว้น	เมื่อถูกเรียก
ParserError	การแยกวิเคราะห์ล้มเหลว
ExportError	การส่งออกล้มเหลว (CSV/JSON/Excel)
ValidationError	การตรวจสอบอินพุตล้มเหลว
ZipSecurityError	การตรวจสอบความปลอดภัย ZIP ล้มเหลว