Pain001 műszaki referencia: CLI, Python API és REST

Ez a referencia a pain001 v0.0.57 parancssori felületét, Python API-ját, REST mikroszolgáltatását és validálási folyamatát dokumentálja. Az itt felsorolt összes kapcsoló, végpont és viselkedés a leszállított kódból származik, nem tervekből.

A Pain001 11 ISO 20022 üzenetdefiníciót támogat: a pain.001.001.03 verziótól a pain.001.001.12 verzióig (Customer Credit Transfer Initiation, tíz verzió), valamint a pain.008.001.02 üzenetet (Customer Direct Debit Initiation).

1. Parancssori felület#

A pain001 futtatható állomány alparancsokba szervezi a funkcióit. Ha csak generálási kapcsolókkal futtatja, implicit módon a generate alparancsot hívja meg, így a meglévő automatizmusok továbbra is működnek.

Alparancs	Rendeltetés
`generate`	Adatfájl átalakítása sémával validált ISO 20022 XML-lé (alapértelmezett parancs).
`validate`	A bemeneti adatok validálása XML írása nélkül.
`versions [--json]`	A 11 támogatott üzenetdefiníció listázása.
`inspect [--json]`	Egy üzenettípus kötelező és opcionális mezőinek megjelenítése.
`init [-o DIR]`	Kiinduló CSV sablon létrehozása egy üzenettípushoz.
`serve [--host] [--port] [--reload]`	A FastAPI REST mikroszolgáltatás indítása (az `api` extra szükséges hozzá).
`mcp`	A projektbe épített Model Context Protocol kiszolgáló indítása (5 eszköz; a teljes, 17 eszközt tartalmazó kiszolgáló `pain001-mcp` néven érhető el).
`plugins list / show / disable`	A felismert betöltő-, validátor-, séma- és írómodulok áttekintése és kezelése.

A `generate` beállításai

Kapcsoló	Leírás
`-t, --xml-message-type`	Üzenetdefiníció, például `pain.001.001.09`.
`-d, --data`	Bemeneti adatok: `.csv`, `.json`, `.jsonl`, `.db` / `.sqlite`, `.parquet`, illetve PGP-vel titkosított `.gpg` / `.asc` fájlok.
`-o, --output-dir`	Az a könyvtár, amelybe a generált XML kerül.
`-m, --template` / `-s, --schema`	A csomaggal szállított Jinja2 sablon vagy XSD séma felülbírálása.
`-c, --config`	Alapértelmezések betöltése konfigurációs profilból (`--profile`, `--show-config`).
`--dry-run` (alias `--validate-only`)	A bemenet validálása a JSON Schema, az XSD és a sémaszabálykönyv alapján, kimenet írása nélkül.
`--scheme`	Sémaszabálykönyv kikényszerítése: `sepa-sct`, `sepa-inst`, `sepa-sdd`, `sepa-b2b` vagy `xborder-ct`.
`--explain --scheme-format {text,json}`	Minden teljesült vagy megbukott sémaszabály jelentése, ember vagy gép által olvasható formában.
`--streaming` / `--chunk-size`	Memóriakorlátos, darabokra bontott feldolgozás nagy kötegekhez (alapértelmezetten 1,000 tranzakció darabonként; minden darabból önálló XML fájl lesz, újraszámolt `NbOfTxs` és `CtrlSum` értékekkel).
`--emit-metrics`	Gépi feldolgozásra alkalmas futásmetrikák kibocsátása megfigyelhetőségi rendszerek számára.

A kilépési kódok CI-barátok: 0 sikeres futás, 1 validálási hiba, 2 használati hiba.

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

Minden generált dokumentum három rétegen halad át, mielőtt kiírásra kerülne:

Bemenet-validálás — a rendszer minden rekordot az üzenettípus JSON Schema definíciójához mér, mezőalias-normalizálással, valamint IBAN/BIC szintaktikai ellenőrzéssel.
Sémaszabálykönyv (opcionális) — SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B vagy határon átnyúló átutalási szabályok.
XSD-validálás — az előállított XML-t az xmlschema ellenőrzi a hivatalos ISO 20022 séma alapján, még mielőtt egyetlen bájt is lemezre kerülne.

A pénzösszegeket az XML generálása és a sémavalidálás során decimal.Decimal típus kezeli — soha nem IEEE 754 lebegőpontos számok —, a NbOfTxs / CtrlSum ellenőrző összegeket pedig a rendszer a validált rekordokból számolja újra, nem pedig készpénznek veszi a bemenetből.

A pain.001 generálásán túl az alapkönyvtár pain.002 státuszjelentés-értelmezőt és -generátort is tartalmaz (így elolvashatja a bank elfogadó vagy elutasító válaszát), valamint camt.053 kivonatértelmezőt és -generátort a napvégi egyeztetéshez, továbbá egy VersionMapper osztályt, amely a rekordokat átvezeti az üzenetverziók között.

3. REST mikroszolgáltatás#

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

Minden végpont a /api/v1 útvonal alatt érhető el (verziószám nélküli /api aliasszal):

Metódus és útvonal	Rendeltetés
`GET /api/v1/health`	Életjel-ellenőrzés.
`POST /api/v1/validate`	Rekordok validálása; mezőszintű hibákat ad vissza.
`POST /api/v1/generate`	Szinkron XML-generálás.
`POST /api/v1/generate/async`	Nagy köteg sorba állítása háttérben történő generáláshoz.
`GET /api/v1/status/{job_id}`	Aszinkron feladat állapotának lekérdezése.
`GET /api/v1/download/{job_id}`	Az elkészült XML letöltése.
`DELETE /api/v1/jobs/{job_id}`	Befejezett feladat takarítása.
`GET /metrics`	Prometheus metrikák.

Az interaktív dokumentáció a /api/docs (Swagger UI), a /api/redoc és a /api/reference (Scalar) címen érhető el, az OpenAPI dokumentum pedig a /openapi.json címen.

4. Bemenet normalizálása#

A Pain001 a valós életből származó exportokat érvényes rekordokká alakítja a validálás előtt:

Mezőaliasok — a gyakori ERP-oszlopnevek a kanonikus mezőkre képződnek le (például amount → payment_amount).
IBAN / BIC normalizálás — a szóközök eltávolítása, a kis- és nagybetűk egységesítése, majd ellenőrzés (ISO 13616 szerinti mod-97 az IBAN-oknál, ISO 9362 szerinti szerkezet a BIC-eknél).
Dátumok — ISO 8601 YYYY-MM-DD formátum értelmezése a teljesítési dátumoknál.
Összegek — a decimal.Decimal típuson keresztül; a hibás összegek megbuknak a validáláson ahelyett, hogy csendben kerekítésre kerülnének.
Karakterkészlet — az átírást segítő függvények a tartalmat a SWIFT és a SEPA által elfogadott ISO 20022 latin karakterkészletre szűkítik.

5. Bővítményarchitektúra#

A csomagcsalád négy belépésipont-csoporton keresztül bővíthető: pain001.loaders, pain001.validators, pain001.schemes és pain001.writers. A pain001-loader-xlsx ezen a mechanizmuson keresztül regisztrál, és telepítéskor automatikusan felismerésre kerül; a pain001-loader-mt101 önálló értelmezőkönyvtár, amelyet közvetlenül lehet használni (és amelyet az MCP kiszolgáló convert_mt101 eszköze is használ). Egy vészkapcsoló — PAIN001_DISABLE_PLUGINS=1 — zárt környezetekben teljesen kikapcsolja a külső bővítmények felismerését.

6. Minőségi kapuk#

Az alapkönyvtár szigorú, ellenőrizhető kapuk mentén készül: 100%-os sor- és áglefedettség a CI-ban kikényszerítve (--cov-fail-under=100), szigorú mypy típusellenőrzés, 100%-os docstring-lefedettség és biztonsági linteres vizsgálat (Bandit, pip-audit). Minden kiadási buildhez CycloneDX SBOM készül.

Folytassa a telepítési útmutatóval, az AI-ügynököknek szánt MCP kiszolgálóval vagy a fizetési szakszótárral.