Pain001 Teknikal na Sanggunian: CLI, Python API at REST

Idinodokumento ng sanggunian na ito ang command-line interface, Python API, REST microservice, at validation pipeline para sa pain001 v0.0.57. Bawat flag, endpoint, at gawing nakalista rito ay kinuha mula sa inilabas na code, hindi mula sa hangarin.

Sinusuportahan ng Pain001 ang 11 ISO 20022 message definition: pain.001.001.03 hanggang pain.001.001.12 (Customer Credit Transfer Initiation, sampung bersyon) at pain.008.001.02 (Customer Direct Debit Initiation).

1. Command-Line Interface#

Pinapangkat ng pain001 executable ang mga kakayahan nito sa mga subcommand. Kapag pinatakbo ito nang may mga generation flag lamang, tinatawag nito nang implicit ang generate, kaya patuloy na gumagana ang umiiral na automation.

Subcommand	Layunin
`generate`	I-convert ang isang data file sa schema-validated na ISO 20022 XML (default na command).
`validate`	I-validate ang input data nang hindi nagsusulat ng XML.
`versions [--json]`	Ilista ang lahat ng 11 suportadong message definition.
`inspect [--json]`	Ipakita ang mga kinakailangan at opsyonal na field para sa isang uri ng mensahe.
`init [-o DIR]`	Bumuo ng panimulang CSV template para sa isang uri ng mensahe.
`serve [--host] [--port] [--reload]`	Ilunsad ang FastAPI REST microservice (nangangailangan ng `api` extra).
`mcp`	Ilunsad ang in-tree na Model Context Protocol server (5 tool; ang buong 17-tool na server ay inilalabas bilang `pain001-mcp`).
`plugins list / show / disable`	Suriin at pamahalaan ang mga natuklasang loader, validator, scheme, at writer plugin.

Mga opsyon ng `generate`

Flag	Paglalarawan
`-t, --xml-message-type`	Message definition, hal. `pain.001.001.09`.
`-d, --data`	Input data: `.csv`, `.json`, `.jsonl`, `.db` / `.sqlite`, `.parquet`, o PGP-encrypted na `.gpg` / `.asc`.
`-o, --output-dir`	Ang directory na tatanggap ng nabuong XML.
`-m, --template` / `-s, --schema`	I-override ang kasamang Jinja2 template o XSD schema.
`-c, --config`	Mag-load ng mga default mula sa isang configuration profile (`--profile`, `--show-config`).
`--dry-run` (alias `--validate-only`)	I-validate ang input laban sa JSON Schema, XSD, at scheme rulebook nang hindi nagsusulat ng output.
`--scheme`	Ipatupad ang isang scheme rulebook: `sepa-sct`, `sepa-inst`, `sepa-sdd`, `sepa-b2b`, o `xborder-ct`.
`--explain --scheme-format {text,json}`	I-ulat ang bawat scheme rule na pumasa o bumagsak, nababasa ng tao o ng makina.
`--streaming` / `--chunk-size`	Memory-bounded na chunked na pagproseso para sa malalaking batch (default na 1,000 transaksyon bawat chunk; bawat chunk ay nagiging sarili nitong XML file na may muling kinuwentang `NbOfTxs` at `CtrlSum`).
`--emit-metrics`	Maglabas ng machine-readable na run metrics para sa mga observability pipeline.

CI-friendly ang mga exit code: 0 tagumpay, 1 bigo ang validation, 2 maling paggamit.

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

Bawat nabuong dokumento ay dumadaan sa tatlong layer bago ito isulat:

Validation ng input — bawat record ay sinusuri laban sa JSON Schema ng uri ng mensahe, na may normalisasyon ng field-alias at mga pagsusuri sa syntax ng IBAN/BIC.
Scheme rulebook (opsyonal) — mga panuntunan ng SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B, o cross-border credit transfer.
XSD validation — ang na-render na XML ay vina-validate laban sa opisyal na ISO 20022 schema sa pamamagitan ng xmlschema bago maisulat sa disk ang kahit isang byte.

Ang mga halaga ng pera ay hinahawakan bilang decimal.Decimal sa panahon ng pagbuo ng XML at scheme validation — hindi kailanman IEEE 754 float — at ang mga control total na NbOfTxs / CtrlSum ay muling kinukuwenta mula sa mga na-validate na record sa halip na pagkatiwalaan mula sa input.

Bukod sa pagbuo ng pain.001, kasama rin sa core library ang isang pain.002 status-report parser at generator (upang mabasa ninyo ang tanggap/tanggi na tugon ng bangko) at isang camt.053 statement parser at generator para sa end-of-day na reconciliation, pati na ang isang VersionMapper na naglilipat ng mga record sa pagitan ng mga bersyon ng mensahe.

3. REST Microservice#

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

Lahat ng endpoint ay naka-mount sa ilalim ng /api/v1 (na may unversioned na /api alias):

Method at Path	Layunin
`GET /api/v1/health`	Liveness probe.
`POST /api/v1/validate`	I-validate ang mga record; nagbabalik ng mga error sa antas ng field.
`POST /api/v1/generate`	Synchronous na pagbuo ng XML.
`POST /api/v1/generate/async`	I-queue ang isang malaking batch para sa pagbuo sa background.
`GET /api/v1/status/{job_id}`	I-poll ang isang async job.
`GET /api/v1/download/{job_id}`	I-download ang natapos na XML.
`DELETE /api/v1/jobs/{job_id}`	Linisin ang isang natapos na job.
`GET /metrics`	Prometheus metrics.

Ang interactive na dokumentasyon ay inihahain sa /api/docs (Swagger UI), /api/redoc, at /api/reference (Scalar), na may OpenAPI document sa /openapi.json.

4. Normalisasyon ng Input#

Ginagawang wastong mga record ng Pain001 ang mga totoong export bago ang validation:

Mga field alias — ang mga karaniwang pangalan ng ERP column ay imina-map sa mga canonical na field (halimbawa, amount → payment_amount).
Normalisasyon ng IBAN / BIC — inaalis ang whitespace, pinapantay ang case, pagkatapos ay sinusuri (ISO 13616 mod-97 para sa mga IBAN, istrukturang ISO 9362 para sa mga BIC).
Mga petsa — ISO 8601 YYYY-MM-DD na pag-parse para sa mga petsa ng pagpapatupad.
Mga halaga — idinadaan sa decimal.Decimal; ang mga maling halaga ay bumabagsak sa validation sa halip na tahimik na i-round.
Character set — binabawasan ng mga transliteration helper ang nilalaman sa ISO 20022 Latin character set na tinatanggap ng SWIFT at SEPA.

5. Plugin Architecture#

Napapalawak ang suite sa pamamagitan ng apat na entry-point group: pain001.loaders, pain001.validators, pain001.schemes, at pain001.writers. Ang pain001-loader-xlsx ay nagrerehistro sa pamamagitan ng mekanismong ito at awtomatikong natutuklasan sa pag-install; ang pain001-loader-mt101 ay isang standalone na parsing library na direktang ginagamit (at ng convert_mt101 tool ng MCP server). Isang kill switch — PAIN001_DISABLE_PLUGINS=1 — ang lubos na nagdi-disable ng third-party na pagtuklas ng plugin sa mga naka-lock-down na kapaligiran.

6. Mga Quality Gate#

Ang core library ay dinedevelop laban sa mahigpit at nabe-verify na mga gate: 100% line at branch coverage na ipinapatupad sa CI (--cov-fail-under=100), mahigpit na mypy typing, 100% docstring coverage, at security linting (Bandit, pip-audit). Isang CycloneDX SBOM ang binubuo para sa bawat release build.

Magpatuloy sa Gabay sa Pag-install, sa MCP server para sa mga AI agent, o sa glossary ng mga pagbabayad.