Bắt đầu

Yêu cầu

• Python 3.10 đến 3.14
• Truy cập terminal (macOS, Linux, hoặc WSL)

Cài đặt

# Cài đặt cơ bản (chỉ trình phân tích xác định)
pip install bankstatementparser

Các gói mở rộng tùy chọn cho khả năng bổ sung:

# Đường dẫn Text-LLM cho PDF kỹ thuật số (litellm + pypdf)
pip install 'bankstatementparser[hybrid]'

# Trích xuất bảng độ chính xác cao hơn (thêm pdfplumber)
pip install 'bankstatementparser[hybrid-plus]'

# Đường dẫn Vision-LLM cho PDF quét (thêm pypdfium2)
pip install 'bankstatementparser[hybrid-vision]'

# Phân loại giao dịch bằng LLM
pip install 'bankstatementparser[enrichment]'

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

# Hỗ trợ Polars DataFrame tùy chọn
pip install 'bankstatementparser[polars]'

Bắt đầu nhanh

Tự động nhận dạng và phân tích mọi định dạng có cấu trúc

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

Hoạt động với các tệp .xml (CAMT/PAIN.001), .csv, .ofx, .qfx, .mt940, và .sta.

Phân tích CAMT.053

from bankstatementparser import CamtParser

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

Phân tích PAIN.001

from bankstatementparser import Pain001Parser

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

Phân tích sao kê PDF ngân hàng (Pipeline Hybrid)

Pipeline hybrid tự động định tuyến PDF qua ba đường dẫn trích xuất:

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

Mọi kết quả trích xuất đều được xác minh bằng Golden Rule: opening + credits − debits == closing.

Streaming tệp lớn

Với các tệp có hàng nghìn giao dịch, sử dụng streaming để giữ bộ nhớ giới hạn:

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

Phân tích trong bộ nhớ

Phân tích từ bytes mà không cần I/O đĩa -- hữu ích cho quy trình SFTP hoặc API:

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

Xử lý tệp song song

Phân tích đồng thời nhiều tệp:

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

Quét thư mục hàng loạt

Xử lý toàn bộ cây thư mục với tự động chống trùng lặp:

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

Chống trùng lặp

Hash giao dịch idempotent cho nhập dữ liệu gia tăng an toàn:

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

Phân loại giao dịch (Làm giàu dữ liệu)

Tự động phân loại giao dịch bằng LLM:

from bankstatementparser.enrichment import Categorizer

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

Xuất sổ cái (hledger / beancount)

Xuất giao dịch sang định dạng sổ nhật ký kế toán 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")

Xác minh số dư đa tiền tệ

Xác minh số dư độc lập theo nhóm tiền tệ:

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

Triển khai dưới dạng microservice FastAPI:

# Khởi động máy chủ API
bankstatementparser-api --port 8000

# Cho triển khai container
bankstatementparser-api --host 0.0.0.0 --port 9000

Các endpoint:

• POST /ingest -- Phân tích tệp sao kê ngân hàng
• GET /health -- Kiểm tra sức khỏe

Xử lý ZIP an toàn

Xử lý các tệp XML nén với kiểm tra bảo mật tích hợp (bảo vệ bomb, từ chối mục nhập mã hóa):

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

Xuất dữ liệu

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

Sử dụng CLI

# Phân tích các định dạng có cấu trúc
bankstatementparser --type camt --input statement.xml
bankstatementparser --type pain001 --input payment.xml

# Pipeline PDF hybrid
bankstatementparser --type ingest --input statement.pdf
bankstatementparser --type ingest --input statement.pdf --output ledger.csv

# Chế độ xem xét tương tác
bankstatementparser --type review --input result.json
bankstatementparser --type review --input result.json --output reviewed.json

# Xuất CSV với streaming
bankstatementparser --type camt --input statement.xml --output transactions.csv
bankstatementparser --type camt --input statement.xml --streaming --show-pii

Tùy chọn CLI:

• --type {camt,pain001,ingest,review} -- loại trình phân tích hoặc chế độ
• --input <path> -- tệp đầu vào
• --output <path> -- tệp xuất (CSV hoặc JSON)
• --streaming -- streaming tệp lớn
• --show-pii -- hiển thị trường nhạy cảm (ẩn danh mặc định)
• --max-size <MB> -- giới hạn kích thước tệp

Thiết lập phát triển cục bộ

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

Chạy bộ kiểm tra:

pytest

Tham chiếu API

Lớp Parser

Hàm tiện ích

Hàm	Mục đích
detect_statement_format(path)	Tự động nhận dạng định dạng tệp
create_parser(path, fmt)	Tạo trình phân tích phù hợp
parse_files_parallel(paths)	Phân tích đồng thời nhiều tệp
iter_secure_xml_entries(zip_path)	Lặp qua các mục ZIP an toàn
smart_ingest(path)	Trích xuất PDF hybrid với xác minh
scan_and_ingest(dir, pattern)	Quét thư mục hàng loạt
verify_balance_multi_currency(txns)	Xác minh số dư theo tiền tệ
to_hledger(txns, account)	Xuất sang định dạng hledger journal
to_beancount(txns, account)	Xuất sang định dạng beancount journal

Lớp dữ liệu

Lớp	Mục đích
Deduplicator	Phát hiện giao dịch trùng lặp
DeduplicationResult	Kết quả với giao dịch duy nhất, trùng chính xác, và nghi ngờ trùng
InputValidator	Xác thực đường dẫn và định dạng tệp
Transaction	Bản ghi giao dịch chuẩn hóa
FileResult	Kết quả từ phân tích song song
ZipXMLSource	Wrapper thành viên ZIP
IngestResult	Kết quả pipeline hybrid với xác minh
VerificationResult	Kết quả xác minh số dư
Categorizer	Phân loại giao dịch bằng LLM
AccountMapper	Quy tắc ánh xạ tài khoản dựa trên regex

Ngoại lệ

Ngoại lệ	Khi nào phát sinh
ParserError	Lỗi phân tích
ExportError	Lỗi xuất dữ liệu (CSV/JSON/Excel)
ValidationError	Lỗi xác thực đầu vào
ZipSecurityError	Lỗi kiểm tra bảo mật ZIP