Pain001

อ้างอิง

เอกสารอ้างอิงทางเทคนิค Pain001: CLI, Python API และ REST

ทุกแฟล็ก ทุก endpoint และทุกพฤติกรรมของ pain001 v0.0.71 นำมาจากโค้ดที่เผยแพร่จริง ไม่ใช่จากความคาดหวัง

5 นาทีในการอ่านตรวจสอบล่าสุด

เอกสารอ้างอิงนี้อธิบายอินเทอร์เฟซบรรทัดคำสั่ง Python API ไมโครเซอร์วิส REST และไปป์ไลน์การตรวจสอบความถูกต้องของ pain001 v0.0.71 ทุกแฟล็ก ทุก endpoint และทุกพฤติกรรมที่ระบุไว้ที่นี่นำมาจากโค้ดที่เผยแพร่จริง ไม่ใช่จากความคาดหวัง

Pain001 รองรับนิยามข้อความ ISO 20022 จำนวน 12 รายการ ได้แก่ pain.001.001.03 ถึง pain.001.001.13 (Customer Credit Transfer Initiation จำนวนสิบเอ็ดเวอร์ชัน) และ pain.008.001.02 (Customer Direct Debit Initiation)

1. อินเทอร์เฟซบรรทัดคำสั่ง#

ไฟล์ปฏิบัติการ pain001 จัดกลุ่มความสามารถไว้เป็นคำสั่งย่อย หากเรียกใช้ด้วยแฟล็กสำหรับการสร้างไฟล์เพียงอย่างเดียว ระบบจะเรียก generate โดยปริยาย ระบบอัตโนมัติที่มีอยู่เดิมจึงทำงานได้ต่อไป

คำสั่งย่อย วัตถุประสงค์
generate แปลงไฟล์ข้อมูลเป็น XML ตามมาตรฐาน ISO 20022 ที่ผ่านการตรวจสอบกับสกีมา (คำสั่งเริ่มต้น)
validate ตรวจสอบความถูกต้องของข้อมูลนำเข้าโดยไม่เขียนไฟล์ XML
versions [--json] แสดงรายการนิยามข้อความที่รองรับทั้ง 13 รายการ
inspect <type> [--json] แสดงฟิลด์ที่จำเป็นและฟิลด์ทางเลือกของข้อความแต่ละประเภท
init <type> [-o DIR] สร้างเทมเพลต CSV ตั้งต้นสำหรับข้อความแต่ละประเภท
serve [--host] [--port] [--reload] เริ่มไมโครเซอร์วิส REST ที่พัฒนาด้วย FastAPI (ต้องติดตั้งส่วนเสริม api)
mcp เริ่มเซิร์ฟเวอร์ Model Context Protocol ที่มาพร้อมในตัว (5 เครื่องมือ ส่วนเซิร์ฟเวอร์ฉบับเต็ม 22 เครื่องมือเผยแพร่ในชื่อ pain001-mcp)
plugins list / show / disable ตรวจสอบและจัดการปลั๊กอินประเภท loader, validator, scheme และ writer ที่ค้นพบ

ตัวเลือกของ 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 รายการต่อก้อน แต่ละก้อนจะกลายเป็นไฟล์ XML ของตนเอง พร้อมคำนวณ NbOfTxs และ CtrlSum ขึ้นใหม่)
--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",
)

เอกสารทุกฉบับที่สร้างขึ้นต้องผ่านการตรวจสามชั้นก่อนถูกเขียนลงไฟล์:

  1. การตรวจสอบข้อมูลนำเข้า: แต่ละระเบียนจะถูกตรวจกับ JSON Schema ของข้อความประเภทนั้น พร้อมการปรับชื่อฟิลด์พ้องให้เป็นมาตรฐานและการตรวจรูปแบบ IBAN/BIC
  2. กฎเกณฑ์ของสกีม (ทางเลือก): กฎของ SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B หรือการโอนเงินข้ามพรมแดน
  3. การตรวจสอบด้วย XSD: XML ที่สร้างขึ้นจะถูกตรวจกับสกีมา ISO 20022 อย่างเป็นทางการผ่าน xmlschema ก่อนที่จะเขียนข้อมูลแม้แต่ไบต์เดียวลงดิสก์

ระหว่างการสร้าง 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

endpoint ทั้งหมดอยู่ภายใต้ /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 ให้เป็นมาตรฐาน: ตัดช่องว่างออก ปรับตัวพิมพ์ให้สม่ำเสมอ แล้วจึงตรวจสอบ (mod-97 ตาม ISO 13616 สำหรับ IBAN และโครงสร้างตาม ISO 9362 สำหรับ BIC)
  • วันที่: อ่านค่าวันที่ดำเนินการตามรูปแบบ ISO 8601 YYYY-MM-DD
  • จำนวนเงิน: ประมวลผลผ่าน decimal.Decimal จำนวนเงินที่รูปแบบไม่ถูกต้องจะไม่ผ่านการตรวจสอบ แทนที่จะถูกปัดเศษอย่างเงียบ ๆ
  • ชุดอักขระ: ตัวช่วยถอดอักษรจะลดทอนเนื้อหาให้อยู่ในชุดอักขระละตินของ ISO 20022 ที่ SWIFT และ SEPA ยอมรับ

5. สถาปัตยกรรมปลั๊กอิน#

ชุดเครื่องมือนี้ขยายความสามารถได้ผ่านกลุ่ม entry point สี่กลุ่ม ได้แก่ pain001.loaders, pain001.validators, pain001.schemes และ pain001.writers โดย pain001-loader-xlsx ลงทะเบียนผ่านกลไกนี้และถูกค้นพบโดยอัตโนมัติเมื่อติดตั้ง ส่วน pain001-loader-mt101 เป็นไลบรารีอ่านข้อมูลแบบเอกเทศที่เรียกใช้ได้โดยตรง (และถูกเรียกใช้โดยเครื่องมือ convert_mt101 ของเซิร์ฟเวอร์ MCP ด้วย) นอกจากนี้ยังมีสวิตช์ปิดการทำงาน PAIN001_DISABLE_PLUGINS=1 ซึ่งปิดการค้นหาปลั๊กอินจากบุคคลที่สามทั้งหมดในสภาพแวดล้อมที่ควบคุมเข้มงวด

6. เกณฑ์คุณภาพ#

ไลบรารีหลักพัฒนาภายใต้เกณฑ์ที่เข้มงวดและตรวจสอบยืนยันได้ ได้แก่ ความครอบคลุมของโค้ดระดับบรรทัดและระดับสาขา 100% ที่บังคับใช้ใน CI (--cov-fail-under=100), การกำหนดชนิดข้อมูลแบบเข้มงวดด้วย mypy, ความครอบคลุมของ docstring 100% และการตรวจความปลอดภัยของโค้ด (Bandit, pip-audit) พร้อมทั้งสร้าง SBOM รูปแบบ CycloneDX สำหรับทุกบิลด์ที่เผยแพร่

อ่านต่อได้ที่ คู่มือการติดตั้ง, เซิร์ฟเวอร์ MCP สำหรับเอเจนต์ AI หรืออภิธานศัพท์การชำระเงิน