Pain001
デモを試す ›

リファレンス

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

pain001 v0.0.56 のすべてのフラグ・エンドポイント・挙動 — 願望ではなく、出荷済みコードに基づいています。

4 分で読めます 最終確認

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

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

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

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

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

generate のオプション

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

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

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 つの層を通過します:

  1. 入力検証 — 各レコードは、フィールドエイリアスの正規化と IBAN/BIC の構文チェックを伴って、メッセージタイプの JSON Schema に対して検査されます。
  2. スキームルールブック(任意)— SEPA SCT、SEPA Instant、SEPA SDD Core、SEPA B2B、またはクロスボーダー送金のルールです。
  3. 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 サーバー、または決済用語集をご覧ください。