はじめる

必要要件

• Python 3.10〜3.14
• ターミナルアクセス（macOS、Linux、または WSL）

インストール

# コアインストール（確定的パーサーのみ）
pip install bankstatementparser

追加機能のオプションエクストラ:

# デジタル PDF 用のテキスト LLM パス（litellm + pypdf）
pip install 'bankstatementparser[hybrid]'

# 高精度テーブル抽出（pdfplumber 追加）
pip install 'bankstatementparser[hybrid-plus]'

# スキャン PDF 用のビジョン LLM パス（pypdfium2 追加）
pip install 'bankstatementparser[hybrid-vision]'

# LLM によるトランザクション分類
pip install 'bankstatementparser[enrichment]'

# REST API マイクロサービス（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 を 3 つの抽出パスにインテリジェントに振り分けます。

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

すべての抽出はゴールデンルールで検証されます: 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}")

重複排除

べき等なトランザクションハッシュで安全なインクリメンタル取り込みを実現します。

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

トランザクション分類（エンリッチメント）

LLM による自動トランザクション分類を行います。

from bankstatementparser.enrichment import Categorizer

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

台帳エクスポート（hledger / beancount）

トランザクションをプレーンテキスト会計のジャーナル形式にエクスポートします。

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 マイクロサービスとしてデプロイします。

# API サーバーの起動
bankstatementparser-api --port 8000

# コンテナデプロイ用
bankstatementparser-api --host 0.0.0.0 --port 9000

エンドポイント:

• POST /ingest -- 銀行取引明細書ファイルを解析する
• GET /health -- ヘルスチェック

安全な ZIP 処理

組み込みのセキュリティチェック（爆弾保護、暗号化エントリ拒否）で ZIP 形式の XML ファイルを処理します。

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} -- パーサータイプまたはモード
• --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 リファレンス

パーサークラス

ユーティリティ関数

関数	目的
detect_statement_format(path)	ファイル形式を自動検出
create_parser(path, fmt)	適切なパーサーを作成する
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 ジャーナル形式にエクスポート
to_beancount(txns, account)	beancount ジャーナル形式にエクスポート

データクラス

クラス	目的
Deduplicator	重複トランザクションを検出する
DeduplicationResult	一意、完全一致、疑わしい一致を含む結果
InputValidator	ファイルパスと形式を検証する
Transaction	正規化された取引レコード
FileResult	並列解析の結果
ZipXMLSource	ZIP メンバーラッパー
IngestResult	検証付きハイブリッドパイプライン結果
VerificationResult	残高検証の結果
Categorizer	LLM によるトランザクション分類
AccountMapper	正規表現ベースのアカウントマッピングルール

例外

例外	発生条件
ParserError	解析の失敗
ExportError	エクスポートの失敗（CSV/JSON/Excel）
ValidationError	入力検証の失敗
ZipSecurityError	ZIP セキュリティチェックの失敗