Ìtọ́kasí Ìmọ̀-ẹ̀rọ Pain001: CLI, Python API àti REST

Ìtọ́kasí yìí ṣàlàyé ojú-ìbáṣepọ̀ ìlà àṣẹ, Python API, iṣẹ́ kékeré REST, àti ìlànà ìṣàyẹ̀wò fún pain001 v0.0.71. Gbogbo àsíá, endpoint, àti ìhùwàsí tí a kọ síbí wá láti inú kóòdù tí a ti tú jáde, kì í ṣe láti inú ìfẹ́-ọkàn.

Pain001 ń ṣe àtìlẹ́yìn fún ìtumọ̀ ìránṣẹ́ ISO 20022 méjìlá: láti pain.001.001.03 dé pain.001.001.13 (ìbẹ̀rẹ̀ ìfiránṣẹ́ owó ti oníbàárà, ẹ̀yà mọ́kànlá) àti pain.008.001.02 (ìbẹ̀rẹ̀ ìgbà owó tààrà ti oníbàárà).

1. Ojú-ìbáṣepọ̀ Ìlà Àṣẹ#

Fáìlì ìṣiṣẹ́ pain001 pín àwọn iṣẹ́ rẹ̀ sí àwọn àṣẹ-abẹ́. Bí ẹ bá ń lò ó pẹ̀lú àwọn àsíá ìṣẹ̀dá nìkan, ó ń pe generate lọ́nà tí kò hàn, nítorí náà àwọn ètò aládàáṣiṣẹ́ tí ẹ ti ní yóò máa bá iṣẹ́ rẹ̀ lọ.

Àṣẹ-abẹ́	Ìdí
`generate`	Yí fáìlì dátà padà sí XML ISO 20022 tí a ti ṣàyẹ̀wò pẹ̀lú schema (àṣẹ ìpìlẹ̀).
`validate`	Ṣàyẹ̀wò dátà ìtẹ̀wọlé láìkọ XML.
`versions [--json]`	Ṣe àkójọ gbogbo ìtumọ̀ ìránṣẹ́ mẹ́tàlá tí a ń ṣe àtìlẹ́yìn fún.
`inspect <type> [--json]`	Fi àwọn pápá tí ó pọn dandan àti àwọn tí ó jẹ́ àṣàyàn hàn fún irú ìránṣẹ́ kan.
`init <type> [-o DIR]`	Ṣẹ̀dá àwòṣe CSV ìbẹ̀rẹ̀ fún irú ìránṣẹ́ kan.
`serve [--host] [--port] [--reload]`	Tú iṣẹ́ kékeré REST FastAPI jáde (ó nílò àfikún `api`).
`mcp`	Tú olùpèsè Model Context Protocol tí ó wà nínú kóòdù jáde (irinṣẹ́ 5; olùpèsè kíkún tí ó ní irinṣẹ́ 22 wà gẹ́gẹ́ bí `pain001-mcp`).
`plugins list / show / disable`	Ṣàyẹ̀wò kí ẹ sì ṣàkóso àwọn plugin loader, validator, scheme, àti writer tí a ti ṣàwárí.

Àwọn àṣàyàn `generate`

Àsíá	Àpèjúwe
`-t, --xml-message-type <TYPE>`	Ìtumọ̀ ìránṣẹ́, fún àpẹẹrẹ `pain.001.001.09`.
`-d, --data <FILE>`	Dátà ìtẹ̀wọlé: `.csv`, `.json`, `.jsonl`, `.db` / `.sqlite`, `.parquet`, tàbí `.gpg` / `.asc` tí a fi PGP dí.
`-o, --output-dir <DIR>`	Fódà tí ó ń gba XML tí a ṣẹ̀dá.
`-m, --template <FILE>` / `-s, --schema <FILE>`	Rọ́pò àwòṣe Jinja2 tàbí schema XSD tí a kó wọlé.
`-c, --config <FILE>`	Kó àwọn iye ìpìlẹ̀ láti inú profáìlì ìṣètò (`--profile`, `--show-config`).
`--dry-run` (orúkọ mìíràn `--validate-only`)	Ṣàyẹ̀wò dátà ìtẹ̀wọlé lòdì sí JSON Schema, XSD, àti ìwé òfin ètò láìkọ àbájáde jáde.
`--scheme <NAME>`	Fi ìwé òfin ètò kan lélẹ̀: `sepa-sct`, `sepa-inst`, `sepa-sdd`, `sepa-b2b`, tàbí `xborder-ct`.
`--explain --scheme-format {text,json}`	Ròyìn gbogbo òfin ètò tí ó kọjá tàbí tí ó kùnà, ní ọ̀nà tí ènìyàn tàbí ẹ̀rọ lè kà.
`--streaming` / `--chunk-size <N>`	Ìṣiṣẹ́ ní àwọn ìdìpọ̀ pẹ̀lú ààlà ìrántí fún àwọn àkójọ ńlá (ìpìlẹ̀: ìdúnàádúrà 1,000 fún ìdìpọ̀ kọ̀ọ̀kan; ìdìpọ̀ kọ̀ọ̀kan yóò di fáìlì XML tirẹ̀ pẹ̀lú `NbOfTxs` àti `CtrlSum` tí a tún ṣírò).
`--emit-metrics`	Tú àwọn ìwọ̀n iṣẹ́ tí ẹ̀rọ lè kà jáde fún àwọn ìlànà àbójútó.

Àwọn kóòdù ìjáde bá CI mu: 0 àṣeyọrí, 1 ìkùnà ìṣàyẹ̀wò, 2 àṣìṣe ìlò.

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.

Àsíá	Àpèjúwe
`--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",
)

Gbogbo àkọsílẹ̀ tí a ṣẹ̀dá ń gba ipele mẹ́ta kọjá kí a tó kọ ọ́:

Ìṣàyẹ̀wò dátà ìtẹ̀wọlé: a ń ṣàyẹ̀wò àkọsílẹ̀ kọ̀ọ̀kan lòdì sí JSON Schema ti irú ìránṣẹ́ náà, pẹ̀lú ìmúdọ́gba orúkọ pápá àti àyẹ̀wò ìlànà IBAN/BIC.
Ìwé òfin ètò (àṣàyàn): àwọn òfin SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B, tàbí ti ìfiránṣẹ́ owó ààlà-kọjá.
Ìṣàyẹ̀wò XSD: a ń ṣàyẹ̀wò XML tí a ṣẹ̀dá lòdì sí schema ISO 20022 òṣìṣẹ́ nípasẹ̀ xmlschema kí a tó kọ báìtì kan sórí diskì.

A ń ṣàkóso iye owó gẹ́gẹ́ bí decimal.Decimal nígbà ìṣẹ̀dá XML àti ìṣàyẹ̀wò ètò (kì í ṣe float IEEE 754 láé), a sì ń tún ṣírò àpapọ̀ ìdarí NbOfTxs / CtrlSum láti inú àwọn àkọsílẹ̀ tí a ti ṣàyẹ̀wò dípò gbígbẹ́kẹ̀lé dátà ìtẹ̀wọlé.

Yàtọ̀ sí ìṣẹ̀dá pain.001, ilé-ìkàwé ìpìlẹ̀ tún ní olùkàwé àti olùṣẹ̀dá ìròyìn ipò pain.002 (kí ẹ lè ka ìdáhùn ìtẹ́wọ́gbà tàbí ìkọ̀sílẹ̀ báńkì yín) àti olùkàwé àti olùṣẹ̀dá ìsọ̀rọ̀ àkọọ́lẹ̀ camt.053 fún ìbáradọ́gba ní òpin ọjọ́, pẹ̀lú VersionMapper tí ó ń gbé àwọn àkọsílẹ̀ láàrin àwọn ẹ̀yà ìránṣẹ́.

3. Iṣẹ́ Kékeré REST#

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

A gbé gbogbo endpoint kalẹ̀ lábẹ́ /api/v1 (pẹ̀lú orúkọ mìíràn /api tí kò ní ẹ̀yà):

Ọ̀nà & Ipa-ọ̀nà	Ìdí
`GET /api/v1/health`	Àyẹ̀wò ìwàláàyè.
`POST /api/v1/validate`	Ṣàyẹ̀wò àwọn àkọsílẹ̀; ó ń dá àwọn àṣìṣe ní ipele pápá padà.
`POST /api/v1/generate`	Ìṣẹ̀dá XML lẹ́sẹ̀kẹsẹ̀.
`POST /api/v1/generate/async`	Fi àkójọ ńlá sí ìlà fún ìṣẹ̀dá lẹ́yìn ìran.
`GET /api/v1/status/{job_id}`	Ṣàyẹ̀wò ipò iṣẹ́ async.
`GET /api/v1/download/{job_id}`	Ṣe àgbàsílẹ̀ XML tí ó ti parí.
`DELETE /api/v1/jobs/{job_id}`	Nu iṣẹ́ tí ó ti parí kúrò.
`GET /metrics`	Àwọn ìwọ̀n Prometheus.

A ń pèsè àkọsílẹ̀ ìbáṣepọ̀ ní /api/docs (Swagger UI), /api/redoc, àti /api/reference (Scalar), pẹ̀lú àkọsílẹ̀ OpenAPI ní /openapi.json.

4. Ìmúdọ́gba Dátà Ìtẹ̀wọlé#

Pain001 ń yí àwọn fáìlì tí a tú jáde láti inú ètò gidi padà sí àwọn àkọsílẹ̀ tí ó tọ́ kí ìṣàyẹ̀wò tó bẹ̀rẹ̀:

Orúkọ mìíràn fún pápá: àwọn orúkọ kọ́lọ́mù ERP tí ó wọ́pọ̀ bá àwọn pápá ìpìlẹ̀ mu (fún àpẹẹrẹ amount → payment_amount).
Ìmúdọ́gba IBAN / BIC: a ń yọ àyè kúrò, a ń mú ìwọ̀n lẹ́tà dọ́gba, lẹ́yìn náà a ń ṣàyẹ̀wò (ISO 13616 mod-97 fún IBAN, ìlànà ISO 9362 fún BIC).
Àwọn ọjọ́: a ń kà àwọn ọjọ́ ìṣiṣẹ́ ní ìlànà ISO 8601 YYYY-MM-DD.
Iye owó: wọ́n ń gba decimal.Decimal kọjá; iye owó tí kò ní ìlànà tó tọ́ yóò kùnà ìṣàyẹ̀wò dípò kí a yí i ká ní ìdákẹ́jẹ́ẹ́.
Àkójọ lẹ́tà: àwọn irinṣẹ́ ìyípadà lẹ́tà ń dín àkóónú kù sí àkójọ lẹ́tà Látìn ISO 20022 tí SWIFT àti SEPA gbà.

5. Ìkọ́lé Plugin#

A lè fẹ̀ ètò yìí sí i nípasẹ̀ àwùjọ ojú-ọ̀nà mẹ́rin: pain001.loaders, pain001.validators, pain001.schemes, àti pain001.writers. pain001-loader-xlsx ń forúkọsílẹ̀ nípasẹ̀ ọ̀nà yìí, a sì ń ṣàwárí rẹ̀ fúnra rẹ̀ lẹ́yìn ìfìsínú; pain001-loader-mt101 jẹ́ ilé-ìkàwé ìtúpalẹ̀ tí ó dá dúró tí a ń lò tààrà (irinṣẹ́ convert_mt101 ti olùpèsè MCP náà sì ń lò ó). Bọ́tìnì ìpakúpa PAIN001_DISABLE_PLUGINS=1 ń pa ìṣàwárí plugin ẹnikẹta rẹ́ pátápátá nínú àwọn àyíká tí a ti dí mọ́lẹ̀.

6. Àwọn Ẹnu-ọ̀nà Ìdára#

A ń ṣe ìdàgbàsókè ilé-ìkàwé ìpìlẹ̀ lábẹ́ àwọn ẹnu-ọ̀nà líle tí a lè fẹ̀rí hàn: ìbòrí ìdánwò 100% fún ìlà àti ẹ̀ka tí a fi lélẹ̀ nínú CI (--cov-fail-under=100), ìtọ́kasí irú dátà mypy líle, ìbòrí docstring 100%, àti ìṣàyẹ̀wò ààbò (Bandit, pip-audit). A ń ṣẹ̀dá SBOM CycloneDX fún gbogbo ìtújáde.

Ẹ tẹ̀síwájú pẹ̀lú Ìtọ́sọ́nà Ìfìsínú, olùpèsè MCP fún àwọn aṣojú AI, tàbí àkójọ ìtumọ̀ ọ̀rọ̀ ìsanwó.