Referensi Teknis Pain001: CLI, Python API, dan REST

Referensi ini mendokumentasikan antarmuka baris perintah, Python API, layanan mikro REST, dan alur validasi untuk pain001 v0.0.57. Setiap flag, endpoint, dan perilaku yang tercantum di sini diambil dari kode yang dirilis, bukan dari harapan semata.

Pain001 mendukung 11 definisi pesan ISO 20022: pain.001.001.03 hingga pain.001.001.12 (Customer Credit Transfer Initiation, sepuluh versi) dan pain.008.001.02 (Customer Direct Debit Initiation).

1. Antarmuka Baris Perintah#

Berkas eksekusi pain001 mengelompokkan fungsinya ke dalam subperintah. Menjalankannya hanya dengan flag pembuatan akan memanggil generate secara implisit, sehingga otomatisasi yang sudah ada tetap berfungsi.

Subperintah	Tujuan
`generate`	Mengonversi berkas data menjadi XML ISO 20022 yang tervalidasi skema (perintah bawaan).
`validate`	Memvalidasi data input tanpa menulis XML.
`versions [--json]`	Menampilkan seluruh 11 definisi pesan yang didukung.
`inspect [--json]`	Menampilkan bidang wajib dan opsional untuk sebuah tipe pesan.
`init [-o DIR]`	Membuat kerangka templat CSV awal untuk sebuah tipe pesan.
`serve [--host] [--port] [--reload]`	Menjalankan layanan mikro REST FastAPI (memerlukan ekstra `api`).
`mcp`	Menjalankan server Model Context Protocol bawaan repositori (5 alat; server lengkap dengan 17 alat tersedia sebagai `pain001-mcp`).
`plugins list / show / disable`	Memeriksa dan mengelola plugin loader, validator, scheme, dan writer yang terdeteksi.

Opsi `generate`

Flag	Deskripsi
`-t, --xml-message-type`	Definisi pesan, misalnya `pain.001.001.09`.
`-d, --data`	Data input: `.csv`, `.json`, `.jsonl`, `.db` / `.sqlite`, `.parquet`, atau `.gpg` / `.asc` yang terenkripsi PGP.
`-o, --output-dir`	Direktori tempat XML yang dihasilkan disimpan.
`-m, --template` / `-s, --schema`	Mengganti templat Jinja2 atau skema XSD bawaan.
`-c, --config`	Memuat nilai bawaan dari profil konfigurasi (`--profile`, `--show-config`).
`--dry-run` (alias `--validate-only`)	Memvalidasi input terhadap JSON Schema, XSD, dan rulebook skema tanpa menulis keluaran.
`--scheme`	Menerapkan rulebook skema: `sepa-sct`, `sepa-inst`, `sepa-sdd`, `sepa-b2b`, atau `xborder-ct`.
`--explain --scheme-format {text,json}`	Melaporkan setiap aturan skema yang lolos atau gagal, dalam bentuk terbaca manusia atau terbaca mesin.
`--streaming` / `--chunk-size`	Pemrosesan per bagian dengan batas memori untuk batch besar (bawaan 1,000 transaksi per bagian; setiap bagian menjadi berkas XML tersendiri dengan `NbOfTxs` dan `CtrlSum` yang dihitung ulang).
`--emit-metrics`	Menghasilkan metrik eksekusi yang terbaca mesin untuk pipeline observabilitas.

Kode keluar ramah CI: 0 berhasil, 1 kegagalan validasi, 2 kesalahan penggunaan.

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

Setiap dokumen yang dihasilkan melewati tiga lapisan sebelum ditulis:

Validasi input — setiap rekaman diperiksa terhadap JSON Schema milik tipe pesan terkait, disertai normalisasi alias bidang serta pemeriksaan sintaks IBAN/BIC.
Rulebook skema (opsional) — aturan SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B, atau transfer kredit lintas negara.
Validasi XSD — XML yang telah dirender divalidasi terhadap skema resmi ISO 20022 melalui xmlschema sebelum satu byte pun ditulis ke disk.

Nominal uang ditangani sebagai decimal.Decimal selama pembuatan XML dan validasi skema — tidak pernah sebagai float IEEE 754 — dan total kendali NbOfTxs / CtrlSum dihitung ulang dari rekaman yang tervalidasi, bukan dipercaya begitu saja dari input.

Selain pembuatan pain.001, pustaka intinya juga menyertakan parser dan generator laporan status pain.002 (sehingga Anda dapat membaca jawaban terima/tolak dari bank) serta parser dan generator laporan rekening camt.053 untuk rekonsiliasi akhir hari, ditambah VersionMapper yang memigrasikan rekaman antarversi pesan.

3. Layanan Mikro REST#

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

Seluruh endpoint dipasang di bawah /api/v1 (dengan alias tanpa versi /api):

Metode & Jalur	Tujuan
`GET /api/v1/health`	Pemeriksaan liveness.
`POST /api/v1/validate`	Memvalidasi rekaman; mengembalikan kesalahan pada tingkat bidang.
`POST /api/v1/generate`	Pembuatan XML secara sinkron.
`POST /api/v1/generate/async`	Mengantrekan batch besar untuk pembuatan di latar belakang.
`GET /api/v1/status/{job_id}`	Memeriksa status pekerjaan asinkron.
`GET /api/v1/download/{job_id}`	Mengunduh XML yang telah selesai.
`DELETE /api/v1/jobs/{job_id}`	Membersihkan pekerjaan yang telah selesai.
`GET /metrics`	Metrik Prometheus.

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

4. Normalisasi Input#

Pain001 menyesuaikan hasil ekspor data dunia nyata menjadi rekaman yang valid sebelum validasi:

Alias bidang — nama kolom ERP yang umum dipetakan ke bidang kanonis (misalnya amount → payment_amount).
Normalisasi IBAN / BIC — spasi dihapus, huruf diseragamkan, lalu diperiksa (mod-97 ISO 13616 untuk IBAN, struktur ISO 9362 untuk BIC).
Tanggal — penguraian ISO 8601 YYYY-MM-DD untuk tanggal eksekusi.
Nominal — dialirkan melalui decimal.Decimal; nominal yang formatnya keliru akan gagal validasi alih-alih dibulatkan diam-diam.
Set karakter — pembantu transliterasi menyederhanakan konten ke set karakter Latin ISO 20022 yang diterima SWIFT dan SEPA.

5. Arsitektur Plugin#

Rangkaian ini dapat diperluas melalui empat grup entry point: pain001.loaders, pain001.validators, pain001.schemes, dan pain001.writers. pain001-loader-xlsx mendaftar melalui mekanisme ini dan ditemukan otomatis saat dipasang; pain001-loader-mt101 adalah pustaka penguraian mandiri yang digunakan secara langsung (dan oleh alat convert_mt101 pada server MCP). Sebuah kill switch — PAIN001_DISABLE_PLUGINS=1 — menonaktifkan penemuan plugin pihak ketiga sepenuhnya di lingkungan yang terkunci ketat.

6. Gerbang Kualitas#

Pustaka intinya dikembangkan dengan gerbang yang ketat dan dapat diverifikasi: cakupan baris dan cabang 100% yang ditegakkan di CI (--cov-fail-under=100), pengetikan mypy yang ketat, cakupan docstring 100%, serta linting keamanan (Bandit, pip-audit). SBOM CycloneDX dihasilkan untuk setiap build rilis.

Lanjutkan dengan Panduan Instalasi, server MCP untuk agen AI, atau glosarium pembayaran.