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（客戶貸記轉帳發動，共十個版本）以及 pain.008.001.02（客戶直接扣款發動）。

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 筆交易；每個分塊各自產生一個 XML 檔案，並重新計算 NbOfTxs 與 CtrlSum）。
--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",
)

每份產生的文件在寫出前都會通過三層檢查：

  1. 輸入驗證——每筆記錄都依該電文類型的 JSON Schema 檢查，並進行欄位別名正規化與 IBAN/BIC 語法檢查。
  2. 方案規則手冊（選用）——SEPA SCT、SEPA Instant、SEPA SDD Core、SEPA B2B 或跨境貸記轉帳規則。
  3. XSD 驗證——產出的 XML 在寫入磁碟前，先透過 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。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 伺服器，或支付詞彙表。