Pain001 技術リファレンス:CLI・Python API・REST

本リファレンスは、pain001 v0.0.71 のコマンドラインインターフェース、Python API、REST マイクロサービス、検証パイプラインを文書化しています。ここに記載されているフラグ・エンドポイント・挙動はすべて、願望ではなく出荷済みコードに基づいています。

Pain001 は 12 種類の ISO 20022 メッセージ定義をサポートしています:pain.001.001.03 から pain.001.001.13 まで(Customer Credit Transfer Initiation、11 バージョン)および pain.008.001.02(Customer Direct Debit Initiation)です。

1. コマンドラインインターフェース#

pain001 実行ファイルは、機能をサブコマンドにまとめています。生成用フラグのみで実行すると暗黙的に generate が呼び出されるため、既存の自動化はそのまま動作し続けます。

サブコマンド	目的
`generate`	データファイルをスキーマ検証済みの ISO 20022 XML に変換します(デフォルトコマンド)。
`validate`	XML を書き出さずに入力データを検証します。
`versions [--json]`	サポート対象の 13 種類のメッセージ定義をすべて一覧表示します。
`inspect <type> [--json]`	メッセージタイプの必須フィールドと任意フィールドを表示します。
`init <type> [-o DIR]`	メッセージタイプ用のスターター CSV テンプレートを生成します。
`serve [--host] [--port] [--reload]`	FastAPI REST マイクロサービスを起動します(`api` エクストラが必要です)。
`mcp`	ツリー内の Model Context Protocol サーバーを起動します(5 ツール。全 22 ツール版のサーバーは `pain001-mcp` として提供されます)。
`plugins list / show / disable`	検出されたローダー、バリデーター、スキーム、ライターの各プラグインを確認・管理します。

`generate` のオプション

フラグ	説明
`-t, --xml-message-type <TYPE>`	メッセージ定義。例:`pain.001.001.09`。
`-d, --data <FILE>`	入力データ:`.csv`、`.json`、`.jsonl`、`.db` / `.sqlite`、`.parquet`、または PGP 暗号化された `.gpg` / `.asc`。
`-o, --output-dir <DIR>`	生成された XML を受け取るディレクトリです。
`-m, --template <FILE>` / `-s, --schema <FILE>`	同梱の Jinja2 テンプレートまたは XSD スキーマを上書きします。
`-c, --config <FILE>`	設定プロファイルからデフォルト値を読み込みます(`--profile`、`--show-config`)。
`--dry-run`(エイリアス `--validate-only`)	出力を書き出さずに、JSON Schema、XSD、スキームルールブックに対して入力を検証します。
`--scheme <NAME>`	スキームルールブックを適用します:`sepa-sct`、`sepa-inst`、`sepa-sdd`、`sepa-b2b`、または `xborder-ct`。
`--explain --scheme-format {text,json}`	合格・不合格となった各スキームルールを、人間可読または機械可読の形式で報告します。
`--streaming` / `--chunk-size <N>`	大規模バッチ向けのメモリ制限付きチャンク処理です(デフォルトはチャンクあたり 1,000 トランザクション。各チャンクは、再計算された `NbOfTxs` と `CtrlSum` を持つ独立した XML ファイルになります)。
`--emit-metrics`	可観測性パイプライン向けに機械可読の実行メトリクスを出力します。

終了コードは CI に適しています:0 は成功、1 は検証失敗、2 は使用方法エラーです。

In the next release

These features are in development for the next pain001 release. They are not in pain001 0.0.71, the version this reference documents, and their names may change before they ship.

フラグ	説明
`--envelop-bah`	Wrap generated payment XML into an ISO 20022 Business Application Header (`head.001.001.03`) and `BizData` (`head.003.001.01`) envelope.
`--bah-sender <BIC/ID>`	Sender financial institution BIC or organisation identifier for BAH `<Fr>`.
`--bah-receiver <BIC/ID>`	Receiver financial institution BIC or organisation identifier for BAH `<To>`.
`--bah-msg-id <ID>`	Business Message Identifier for BAH `<BizMsgIdr>` (defaults to generated UUID).
`--xml-sign-key <FILE>`	PEM RSA private key for W3C XML Digital Signature (XML-DSig RSA-SHA256).
`--xml-sign-cert <FILE>`	Optional PEM X.509 certificate to embed in XML-DSig `<ds:KeyInfo>`.
`--xml-sign-passphrase-env <VAR>`	Environment variable holding passphrase to decrypt the RSA private key.

The Python API gains the matching process_files parameters: envelop_bah, xml_sign_key and xml_sign_cert.

Input normalisation gains formula injection shielding: cells starting with a formula trigger (=, +, -, @, tab, carriage return or line feed) are escaped with a leading single quote, preventing CSV injection (CWE-1236) when a file is opened in a spreadsheet.

2. Python API#

from pain001.core.core import process_files

# Generate a validated pain.001.001.09 file from CSV
process_files(
    xml_message_type="pain.001.001.09",
    xml_template_file_path="template.xml",
    xsd_schema_file_path="schema.xsd",
    data_file_path="payments.csv",
    output_dir="out",
)

生成されるすべてのドキュメントは、書き出される前に 3 つの層を通過します:

入力検証：各レコードは、フィールドエイリアスの正規化と IBAN/BIC の構文チェックを伴って、メッセージタイプの JSON Schema に対して検査されます。
スキームルールブック(任意):SEPA SCT、SEPA Instant、SEPA SDD Core、SEPA B2B、またはクロスボーダー送金のルールです。
XSD 検証：レンダリングされた XML は、1 バイトもディスクに書き込まれる前に、xmlschema を介して公式の ISO 20022 スキーマに対して検証されます。

金額は、XML 生成およびスキーム検証の間、decimal.Decimal として扱われ、IEEE 754 浮動小数点数は決して使用されません。また、NbOfTxs / CtrlSum のコントロールトータルは、入力を信頼するのではなく、検証済みレコードから再計算されます。

pain.001 の生成に加えて、コアライブラリには、pain.002 ステータスレポートのパーサーとジェネレーター(銀行の受理/拒否応答を読み取れます)と、日末照合のための camt.053 ステートメントのパーサーとジェネレーター、さらにメッセージバージョン間でレコードを移行する VersionMapper が含まれています。

3. REST マイクロサービス#

pip install "pain001[api]"
pain001 serve --host 0.0.0.0 --port 8000

すべてのエンドポイントは /api/v1 配下にマウントされています(バージョンなしの /api エイリアスもあります):

メソッドとパス	目的
`GET /api/v1/health`	死活監視プローブです。
`POST /api/v1/validate`	レコードを検証し、フィールドレベルのエラーを返します。
`POST /api/v1/generate`	同期的な XML 生成です。
`POST /api/v1/generate/async`	大規模バッチをバックグラウンド生成のためにキューに入れます。
`GET /api/v1/status/{job_id}`	非同期ジョブをポーリングします。
`GET /api/v1/download/{job_id}`	完成した XML をダウンロードします。
`DELETE /api/v1/jobs/{job_id}`	完了したジョブをクリーンアップします。
`GET /metrics`	Prometheus メトリクスです。

インタラクティブなドキュメントは /api/docs(Swagger UI)、/api/redoc、/api/reference(Scalar)で提供され、OpenAPI ドキュメントは /openapi.json にあります。

4. 入力の正規化#

Pain001 は、検証の前に、実務上のエクスポートデータを有効なレコードに変換します:

フィールドエイリアス：一般的な ERP のカラム名が正規のフィールドにマッピングされます(例:amount → payment_amount)。
IBAN / BIC の正規化：空白を除去し、大文字小文字を揃えたうえで検査します(IBAN は ISO 13616 の mod-97、BIC は ISO 9362 の構造)。
日付：実行日について ISO 8601 の YYYY-MM-DD 形式で解析します。
金額：decimal.Decimal を経由して処理されます。不正な金額は、暗黙に丸められるのではなく検証エラーになります。
文字セット：翻字ヘルパーが、SWIFT と SEPA が受け付ける ISO 20022 ラテン文字セットへとコンテンツを変換します。

5. プラグインアーキテクチャ#

本スイートは、pain001.loaders、pain001.validators、pain001.schemes、pain001.writers の 4 つのエントリポイントグループを通じて拡張できます。pain001-loader-xlsx はこの仕組みで登録され、インストール時に自動検出されます。pain001-loader-mt101 は、直接(および MCP サーバーの convert_mt101 ツールから)利用されるスタンドアロンの解析ライブラリです。キルスイッチ PAIN001_DISABLE_PLUGINS=1 により、ロックダウンされた環境ではサードパーティ製プラグインの検出を完全に無効化できます。

6. 品質ゲート#

コアライブラリは、厳格で検証可能なゲートのもとで開発されています:CI で強制される 100% のラインおよびブランチカバレッジ(--cov-fail-under=100)、厳格な mypy 型付け、100% の docstring カバレッジ、セキュリティリンティング(Bandit、pip-audit)です。すべてのリリースビルドで CycloneDX SBOM が生成されます。

続けて、インストールガイド、AI エージェント向け MCP サーバー、または決済用語集をご覧ください。