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

Ez a referencia a pain001 v0.0.71 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 12 ISO 20022 üzenetdefiníciót támogat: a pain.001.001.03 verziótól a pain.001.001.13 verzióig (Customer Credit Transfer Initiation, tizenegy 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.

A generate beállításai

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

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.

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

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

1. 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.
2. Sémaszabálykönyv (opcionális): SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B vagy határon átnyúló átutalási szabályok.
3. 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):

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ó, a 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.