Tài liệu kỹ thuật Pain001: CLI, Python API và REST

Tài liệu tham khảo này mô tả giao diện dòng lệnh, Python API, vi dịch vụ REST và quy trình xác thực của pain001 v0.0.57. Mọi cờ lệnh, điểm cuối và hành vi được liệt kê tại đây đều lấy từ mã nguồn đã phát hành, không phải từ kỳ vọng.

Pain001 hỗ trợ 11 định nghĩa thông điệp ISO 20022: từ pain.001.001.03 đến pain.001.001.12 (Customer Credit Transfer Initiation — Khởi tạo chuyển khoản tín dụng của khách hàng, mười phiên bản) và pain.008.001.02 (Customer Direct Debit Initiation — Khởi tạo ghi nợ trực tiếp của khách hàng).

1. Giao diện dòng lệnh#

Tệp thực thi pain001 nhóm các chức năng thành những lệnh con. Khi chạy chỉ với các cờ tạo tệp, lệnh generate được gọi ngầm định, nên các quy trình tự động hoá hiện có vẫn tiếp tục hoạt động.

Lệnh con	Mục đích
`generate`	Chuyển một tệp dữ liệu thành XML ISO 20022 đã được xác thực theo lược đồ (lệnh mặc định).
`validate`	Xác thực dữ liệu đầu vào mà không ghi XML.
`versions [--json]`	Liệt kê toàn bộ 11 định nghĩa thông điệp được hỗ trợ.
`inspect [--json]`	Hiển thị các trường bắt buộc và tuỳ chọn của một loại thông điệp.
`init [-o DIR]`	Tạo sẵn một mẫu CSV khởi đầu cho một loại thông điệp.
`serve [--host] [--port] [--reload]`	Khởi chạy vi dịch vụ REST FastAPI (yêu cầu phần mở rộng `api`).
`mcp`	Khởi chạy máy chủ Model Context Protocol tích hợp sẵn (5 công cụ; máy chủ đầy đủ 17 công cụ được phát hành dưới tên `pain001-mcp`).
`plugins list / show / disable`	Kiểm tra và quản lý các plugin loader, validator, scheme và writer đã được phát hiện.

Tuỳ chọn của `generate`

Cờ	Mô tả
`-t, --xml-message-type`	Định nghĩa thông điệp, ví dụ `pain.001.001.09`.
`-d, --data`	Dữ liệu đầu vào: `.csv`, `.json`, `.jsonl`, `.db` / `.sqlite`, `.parquet`, hoặc tệp mã hoá PGP `.gpg` / `.asc`.
`-o, --output-dir`	Thư mục nhận tệp XML được tạo.
`-m, --template` / `-s, --schema`	Ghi đè mẫu Jinja2 hoặc lược đồ XSD đi kèm.
`-c, --config`	Nạp giá trị mặc định từ một hồ sơ cấu hình (`--profile`, `--show-config`).
`--dry-run` (bí danh `--validate-only`)	Xác thực dữ liệu đầu vào theo JSON Schema, XSD và bộ quy tắc scheme mà không ghi kết quả.
`--scheme`	Áp dụng một bộ quy tắc scheme: `sepa-sct`, `sepa-inst`, `sepa-sdd`, `sepa-b2b`, hoặc `xborder-ct`.
`--explain --scheme-format {text,json}`	Báo cáo từng quy tắc scheme đạt hoặc không đạt, ở dạng cho người đọc hoặc cho máy.
`--streaming` / `--chunk-size`	Xử lý theo khối với bộ nhớ giới hạn cho các lô lớn (mặc định 1,000 giao dịch mỗi khối; mỗi khối trở thành một tệp XML riêng với `NbOfTxs` và `CtrlSum` được tính lại).
`--emit-metrics`	Phát ra số liệu chạy ở định dạng máy đọc được cho các hệ thống giám sát.

Mã thoát thân thiện với CI: 0 thành công, 1 lỗi xác thực, 2 lỗi cách dùng.

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

Mỗi tài liệu được tạo phải vượt qua ba lớp kiểm tra trước khi được ghi:

Xác thực đầu vào — mỗi bản ghi được kiểm tra theo JSON Schema của loại thông điệp, kèm chuẩn hoá bí danh trường và kiểm tra cú pháp IBAN/BIC.
Bộ quy tắc scheme (tuỳ chọn) — các quy tắc SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B hoặc chuyển khoản tín dụng xuyên biên giới.
Xác thực XSD — XML sau khi kết xuất được xác thực theo lược đồ ISO 20022 chính thức bằng xmlschema trước khi một byte nào được ghi xuống đĩa.

Số tiền được xử lý dưới dạng decimal.Decimal trong suốt quá trình tạo XML và xác thực scheme — không bao giờ dùng số thực IEEE 754 — và các tổng kiểm soát NbOfTxs / CtrlSum được tính lại từ các bản ghi đã xác thực thay vì tin vào dữ liệu đầu vào.

Ngoài việc tạo pain.001, thư viện lõi còn cung cấp bộ phân tích và bộ tạo báo cáo trạng thái pain.002 (để quý vị đọc phản hồi chấp nhận/từ chối của ngân hàng) và bộ phân tích và bộ tạo sao kê camt.053 phục vụ đối soát cuối ngày, cùng một VersionMapper di trú bản ghi giữa các phiên bản thông điệp.

3. Vi dịch vụ REST#

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

Tất cả các điểm cuối được gắn dưới /api/v1 (kèm bí danh không phiên bản /api):

Phương thức & đường dẫn	Mục đích
`GET /api/v1/health`	Đầu dò kiểm tra hoạt động.
`POST /api/v1/validate`	Xác thực các bản ghi; trả về lỗi ở cấp trường.
`POST /api/v1/generate`	Tạo XML đồng bộ.
`POST /api/v1/generate/async`	Đưa một lô lớn vào hàng đợi để tạo trong nền.
`GET /api/v1/status/{job_id}`	Thăm dò trạng thái một tác vụ bất đồng bộ.
`GET /api/v1/download/{job_id}`	Tải về tệp XML đã hoàn tất.
`DELETE /api/v1/jobs/{job_id}`	Dọn dẹp một tác vụ đã hoàn thành.
`GET /metrics`	Số liệu Prometheus.

Tài liệu tương tác được phục vụ tại /api/docs (Swagger UI), /api/redoc và /api/reference (Scalar), với tài liệu OpenAPI tại /openapi.json.

4. Chuẩn hoá dữ liệu đầu vào#

Pain001 chuyển các tệp xuất từ thực tế thành bản ghi hợp lệ trước khi xác thực:

Bí danh trường — các tên cột ERP phổ biến được ánh xạ về trường chuẩn (ví dụ amount → payment_amount).
Chuẩn hoá IBAN / BIC — loại bỏ khoảng trắng, chuẩn hoá chữ hoa/chữ thường, sau đó kiểm tra (mod-97 theo ISO 13616 cho IBAN, cấu trúc ISO 9362 cho BIC).
Ngày tháng — phân tích theo ISO 8601 YYYY-MM-DD cho ngày thực hiện.
Số tiền — được xử lý qua decimal.Decimal; số tiền sai định dạng sẽ không vượt qua xác thực thay vì bị làm tròn âm thầm.
Bộ ký tự — các bộ chuyển tự đưa nội dung về bộ ký tự Latinh ISO 20022 được SWIFT và SEPA chấp nhận.

5. Kiến trúc plugin#

Bộ công cụ có thể mở rộng qua bốn nhóm điểm vào: pain001.loaders, pain001.validators, pain001.schemes và pain001.writers. pain001-loader-xlsx đăng ký qua cơ chế này và được tự động phát hiện khi cài đặt; pain001-loader-mt101 là thư viện phân tích độc lập được dùng trực tiếp (và bởi công cụ convert_mt101 của máy chủ MCP). Một công tắc ngắt — PAIN001_DISABLE_PLUGINS=1 — vô hiệu hoá hoàn toàn việc phát hiện plugin bên thứ ba trong các môi trường bị khoá chặt.

6. Cổng chất lượng#

Thư viện lõi được phát triển theo các cổng kiểm soát nghiêm ngặt, có thể kiểm chứng: bao phủ 100% dòng và nhánh được thực thi trong CI (--cov-fail-under=100), kiểu mypy nghiêm ngặt, bao phủ docstring 100%, và kiểm tra bảo mật (Bandit, pip-audit). Một SBOM CycloneDX được tạo cho mỗi bản dựng phát hành.

Tiếp tục với Hướng dẫn cài đặt, máy chủ MCP cho tác tử AI, hoặc bảng thuật ngữ thanh toán.