Pain001
试用演示 ›

参考

Pain001 技术参考：CLI、Python API 与 REST

pain001 v0.0.56 的每个标志、端点与行为——均取自已发布的代码，而非愿景。

4 分钟阅读 最近审核

本参考文档介绍 pain001 v0.0.58 的命令行界面、Python API、REST 微服务与校验流水线。此处列出的每个标志、端点与行为均取自已发布的代码，而非愿景。

Pain001 支持 12 种 ISO 20022 报文定义：pain.001.001.03 至 pain.001.001.13（客户贷记转账发起，共十一个版本）以及 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 服务器或支付术语表。