Rujukan

Rujukan Teknikal Pain001: CLI, Python API dan REST

Setiap flag, titik akhir dan gelagat pain001 v0.0.90, diambil daripada kod yang telah dikeluarkan, bukan daripada harapan semata-mata.

Rujukan ini mendokumentasikan antara muka baris perintah, Python API, perkhidmatan mikro REST dan saluran pengesahan bagi pain001 v0.0.90. Setiap flag, titik akhir dan gelagat yang disenaraikan di sini diambil daripada kod yang telah dikeluarkan, bukan daripada harapan semata-mata.

Pain001 menyokong 13 takrifan mesej ISO 20022: pain.001.001.03 hingga pain.001.001.13 (Customer Credit Transfer Initiation, sebelas versi) dan pain.008.001.02 / pain.008.001.08 (Customer Direct Debit Initiation).


1. Antara Muka Baris Perintah#

Fail boleh laku pain001 mengumpulkan fungsinya ke dalam subperintah. Menjalankannya dengan flag penjanaan sahaja akan memanggil generate secara tersirat, jadi automasi sedia ada terus berfungsi.

Subperintah Tujuan
generate Menukarkan fail data kepada XML ISO 20022 yang disahkan skema (perintah lalai).
validate Mengesahkan data input tanpa menulis XML.
check <file>... [--scheme] [--format] Check pain.001 or pain.008 files you already have: the XSD of the message type each file declares, the message definition's cross-element rules, and any scheme profiles, policy or Schematron rulebook you name.
verify-signature <file>... --cert <PEM> Verify the XML-DSig signature on each file against the signer's certificate or public key; --trust-embedded-cert checks integrity only (requires the sign extra).
versions [--format json] Menyenaraikan kesemua 13 takrifan mesej yang disokong.
inspect <type> [--format json] Memaparkan templat yang disertakan, skema, data contoh dan format input yang diterima untuk sesuatu jenis mesej.
init <type> [-o FILE] Menjana rangka templat CSV permulaan bagi sesuatu jenis mesej.
serve [--host] [--port] [--reload] Melancarkan perkhidmatan mikro REST FastAPI (memerlukan ekstra api).
mcp Memulakan pelayan Model Context Protocol terbina dalam pustaka teras melalui stdio (memerlukan ekstra mcp); pelayan penuh diedarkan sebagai pain001-mcp.
plugins list / show / disable Menyenaraikan pemalam pemuat, pengesah, skim dan penulis yang ditemui, memaparkan salah satu daripadanya, atau menunjukkan cara mematikan penemuan pemalam pihak ketiga.
face <file> [--face] [--bindings] [-o] [--loss-report] Project a pain.001 XML file into another standard's JSON shape, with a report of every element not carried.
upload [<file>] --sftp <url> Deliver a file atomically to an SFTP server you trust explicitly (requires the upload extra).

Pilihan generate

Pilihan Penerangan
-t, --xml-message-type <TYPE> Takrifan mesej, contohnya pain.001.001.09.
-d, --data <FILE> Data input: .csv, .json, .jsonl, .db / .sqlite, .parquet, atau .gpg / .asc yang disulitkan PGP.
-o, --output-dir <DIR> Direktori yang menerima XML yang dijana.
-m, --template <FILE> / -s, --schema <FILE> Menggantikan templat Jinja2 atau skema XSD terbina dalam.
-c, --config <FILE> Memuatkan nilai lalai daripada profil konfigurasi (--profile, --show-config).
--dry-run (alias --validate-only) Mengesahkan input terhadap JSON Schema, XSD dan rulebook skim tanpa menulis output.
--scheme <NAME[,NAME]> Menguatkuasakan satu atau lebih buku peraturan skim, dipisahkan dengan koma. pain001 plugins list menamakan setiap buku peraturan yang dipasang.
--explain / --format json Dengan --scheme, mencetak petunjuk pembetulan bagi setiap pelanggaran, sebagai teks atau JSON.
--rules <FILE> Enforce a private YAML CEL policy before generation (requires the rules extra).
--schematron <PRESET or FILE> Apply Schematron business rules: the sepa, fednow or cbpr preset, or your own .sch file.
--decrypt-key <FILE> / --decrypt-passphrase-env <VAR> Import a GPG private key, and name the variable that holds its passphrase, for .gpg / .asc input (requires the gpg extra).
--streaming / --chunk-size <N> Pemprosesan berbahagian yang terbatas memori untuk kelompok besar (lalai 1,000 transaksi bagi setiap bahagian; setiap bahagian menjadi fail XML tersendiri dengan NbOfTxs dan CtrlSum yang dikira semula).
--emit-metrics Mengeluarkan metrik larian yang boleh dibaca mesin untuk saluran kebolehcerapan.
--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 private key (RSA, or EC P-256/P-384) for a W3C XML Digital Signature (XML-DSig); the algorithm follows the key.
--xml-sign-cert <FILE> Optional PEM X.509 certificate to embed in XML-DSig <ds:KeyInfo>.
--xml-sign-alg <ALG> rsa-sha256, rsa-pss-sha256, ecdsa-sha256 or ecdsa-sha384; by default an RSA key signs rsa-sha256.
--xml-sign-passphrase-env <VAR> Environment variable holding the passphrase for --xml-sign-key.
--list-templates / --show-template <TYPE> List the bundled templates, or show one template's metadata, and exit.

Kod keluar mesra CI: 0 berjaya, 1 kegagalan pengesahan, 2 ralat penggunaan.

XML signing and verify-signature need the sign extra (pip install "pain001[sign]", which installs cryptography and lxml).

Signatures: pain001 verify-signature

pain001 verify-signature checks the signature on files you received or wrote. Pass the signer's certificate or public key with --cert; that is the trust anchor. --trust-embedded-cert verifies with each file's own certificate instead, which proves the file is unchanged since it was signed but not who signed it. It exits 0 when every file verifies, 1 when any does not, and 2 when it cannot run; --format json prints one report per file. Verification uses exclusive C14N 1.0 and accepts only RSA-SHA256, RSA-PSS and ECDSA signatures with SHA-256 to SHA-512 digests over the whole document; the certificate's chain and validity dates are not checked.

Faces: pain001 face

A face projects a validated pain.001 document into another standard's JSON request body. --face uk_open_banking targets the Open Banking Read/Write API v4.0.1 domestic payment, --face berlin_group targets NextGenPSD2 v1.3.16 payment initiation, and --face iso_2018 renames every element to its ISO 20022 name in snake_case. A face refuses a document that lacks an element its target requires instead of inventing a value; --loss-report lists every source element it did not carry. Faces are outbound only.

Delivery: pain001 upload

pain001 upload sends a finished file to an SFTP server you name, and only after you have trusted its host key: from a known_hosts file (--known-hosts) or an OpenSSH SHA256 fingerprint you verified independently (--accept-host-key). --print-host-key shows the server's fingerprint without logging in. It logs in with a private key (--identity-file, with --passphrase-env), a password read from an environment variable (--password-env), or your SSH agent. The file is written under a temporary name and renamed on the server, so the receiving side never sees a partial file.


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_path="out/payments.xml",
)

Setiap dokumen yang dijana melalui tiga lapisan sebelum ia ditulis:

  1. Pengesahan input: setiap rekod diperiksa terhadap JSON Schema bagi jenis mesej berkenaan, dengan penormalan alias medan serta pemeriksaan sintaks IBAN/BIC.
  2. Rulebook skim (pilihan): peraturan sistem pembayaran yang anda nyatakan, daripada SEPA (SCT, Instant, SDD Core, B2B) hingga sistem kebangsaan seperti UK Faster Payments, CHAPS dan Bacs, ACH dan pindahan kawat AS, serta Swift CBPR+; pain001 plugins list menamakan kesemuanya.
  3. Pengesahan XSD: XML yang telah dijana disahkan terhadap skema rasmi ISO 20022 melalui xmlschema sebelum satu bait pun ditulis ke cakera. Apabila ekstra pilihan fast (lxml) dipasang, libxml2 menerima dokumen yang sah dengan lebih pantas; dokumen yang ditolaknya diperiksa semula oleh xmlschema, dan keputusannya adalah muktamad.

Amaun kewangan dikendalikan sebagai decimal.Decimal sepanjang penjanaan XML dan pengesahan skim (tidak pernah sebagai apungan IEEE 754), dan jumlah kawalan NbOfTxs / CtrlSum dikira semula daripada rekod yang telah disahkan, bukannya dipercayai terus daripada input.

Selain penjanaan pain.001, pustaka terasnya turut menyertakan penghurai dan penjana laporan status pain.002 (supaya anda dapat membaca jawapan terima/tolak daripada bank) serta penghurai dan penjana penyata camt.053 untuk penyesuaian akhir hari, ditambah VersionMapper yang memindahkan rekod antara versi mesej.

pain001.faces.project_face is the Python entry point for faces. sign_xml_document signs a document with XML-DSig, and verify_signature(signed_xml, trust_anchor=cert_pem) verifies one and returns a SignatureReport (valid, trust, algorithm, signer, reason); both need the sign extra. verify_xml_signature without a key or certificate still trusts the certificate inside the document, with a DeprecationWarning; pain001 0.0.90 refuses it.

Runnable, self-checking scripts for the public API and the CLI live in the library's examples/ directory.


3. Perkhidmatan Mikro REST#

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

Kesemua titik akhir dilekapkan di bawah /api/v1 (dengan alias tanpa versi /api):

Kaedah & Laluan Tujuan
GET /api/v1/health Pemeriksaan keaktifan.
POST /api/v1/validate Mengesahkan rekod; mengembalikan ralat pada peringkat medan.
POST /api/v1/generate Penjanaan XML secara segerak.
POST /api/v1/generate/async Membariskan kelompok besar untuk penjanaan di latar belakang.
GET /api/v1/status/{job_id} Menyemak status kerja tak segerak.
GET /api/v1/download/{job_id} Memuat turun XML yang telah siap.
DELETE /api/v1/jobs/{job_id} Membersihkan kerja yang telah selesai.
GET /api/v1/faces List the faces and the binding keys each accepts.
POST /api/v1/faces/{face} Project a pain.001 document sent as XML text; returns the payload and the loss report, or 422 with the reason the face refused it.
GET /metrics Metrik Prometheus.

Dokumentasi interaktif disajikan di /api/docs (Swagger UI), /api/redoc dan /api/reference (Scalar), dengan dokumen OpenAPI di /openapi.json.

When the PAIN001_API_KEY environment variable is set, every endpoint except /health and /metrics requires it as a bearer token; when it is unset, the API is open. pain001 serve binds to 127.0.0.1 unless you pass --host.


4. Penormalan Input#

Pain001 menyesuaikan eksport data dunia sebenar menjadi rekod yang sah sebelum pengesahan:

  • Alias medan: nama lajur ERP yang lazim dipetakan kepada medan berkanun (contohnya amount → payment_amount).
  • Penormalan IBAN / BIC: ruang kosong dibuang, huruf diseragamkan, kemudian diperiksa (mod-97 ISO 13616 untuk IBAN, struktur ISO 9362 untuk BIC).
  • Tarikh: penghuraian ISO 8601 YYYY-MM-DD untuk tarikh pelaksanaan.
  • Amaun: disalurkan melalui decimal.Decimal; amaun yang cacat formatnya akan gagal pengesahan dan bukannya dibundarkan secara senyap.
  • Set aksara: pembantu transliterasi menurunkan kandungan kepada set aksara Latin ISO 20022 yang diterima SWIFT dan SEPA.
  • Formula cells: CSV cells that start with =, +, - or @ are kept as supplied by default, so phone numbers and references survive; load_csv_data(path, sanitize_formula=True) escapes them with a leading quote instead.

5. Seni Bina Plugin#

Rangkaian pakej ini boleh diperluas melalui empat kumpulan entry point: pain001.loaders, pain001.validators, pain001.schemes dan pain001.writers. pain001-loader-xlsx mendaftar melalui mekanisme ini dan ditemui secara automatik semasa pemasangan; pain001-loader-mt101 ialah pustaka penghuraian tersendiri yang digunakan secara terus (dan oleh alat convert_mt101 pada pelayan MCP). Suis mati, PAIN001_DISABLE_PLUGINS=1, melumpuhkan penemuan plugin pihak ketiga sepenuhnya dalam persekitaran yang dikawal ketat.


6. Get Kualiti#

Pustaka terasnya dibangunkan dengan get yang ketat dan boleh disahkan: liputan baris dan cabang 100% yang dikuatkuasakan dalam CI (--cov-fail-under=100), penaipan mypy yang ketat, liputan docstring 100%, serta linting keselamatan (Bandit, pip-audit). SBOM CycloneDX dijana bagi setiap binaan keluaran.

Teruskan dengan Panduan Pemasangan, pelayan MCP untuk ejen AI, atau glosari pembayaran.