Referencia

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

A pain001 v0.0.90 minden kapcsolója, végpontja és viselkedése, a leszállított kódból véve, nem tervekből.

Ez a referencia a pain001 v0.0.90 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 13 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 / pain.008.001.08 ü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.
check <file>... [--scheme] [--format] Check pain.001 or pain.008 files you already have: the XSD of the message type each file declares, the message definition's cross-element rules, and any scheme profiles, policy or Schematron rulebook you name.
verify-signature <file>... --cert <PEM> Verify the XML-DSig signature on each file against the signer's certificate or public key; --trust-embedded-cert checks integrity only (requires the sign extra).
versions [--format json] A 13 támogatott üzenetdefiníció listázása.
inspect <type> [--format json] Megjeleníti a mellékelt sablont, a sémát, a példaadatokat és az elfogadott bemeneti formátumokat egy üzenettípushoz.
init <type> [-o FILE] 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 Elindítja a magkönyvtár beépített Model Context Protocol-kiszolgálóját stdio-n keresztül (a(z) mcp kiegészítő szükséges); a teljes kiszolgáló pain001-mcp néven érhető el.
plugins list / show / disable Felsorolja a talált betöltő, validáló, séma- és író bővítményeket, megjelenít egyet, vagy kiírja, hogyan kapcsolható ki a külső bővítmények felderítése.
face <file> [--face] [--bindings] [-o] [--loss-report] Project a pain.001 XML file into another standard's JSON shape, with a report of every element not carried.
upload [<file>] --sftp <url> Deliver a file atomically to an SFTP server you trust explicitly (requires the upload extra).

A generate beállításai

Kapcsoló Leírás
-t, --xml-message-type <TYPE> Üzenetdefiníció, például pain.001.001.09.
-d, --data <FILE> Bemeneti adatok: .csv, .json, .jsonl, .db / .sqlite, .parquet, illetve PGP-vel titkosított .gpg / .asc fájlok.
-o, --output-dir <DIR> Az a könyvtár, amelybe a generált XML kerül.
-m, --template <FILE> / -s, --schema <FILE> A csomaggal szállított Jinja2 sablon vagy XSD séma felülbírálása.
-c, --config <FILE> 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 <NAME[,NAME]> Egy vagy több, vesszővel elválasztott séma-szabálykönyvet alkalmaz. A(z) pain001 plugins list minden telepített szabálykönyvet megnevez.
--explain / --format json A(z) --scheme kapcsolóval minden szabálysértéshez javítási tippet ír ki, szövegként vagy JSON-ként.
--rules <FILE> Enforce a private YAML CEL policy before generation (requires the rules extra).
--schematron <PRESET or FILE> Apply Schematron business rules: the sepa, fednow or cbpr preset, or your own .sch file.
--decrypt-key <FILE> / --decrypt-passphrase-env <VAR> Import a GPG private key, and name the variable that holds its passphrase, for .gpg / .asc input (requires the gpg extra).
--streaming / --chunk-size <N> 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.
--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 private key (RSA, or EC P-256/P-384) for a W3C XML Digital Signature (XML-DSig); the algorithm follows the key.
--xml-sign-cert <FILE> Optional PEM X.509 certificate to embed in XML-DSig <ds:KeyInfo>.
--xml-sign-alg <ALG> rsa-sha256, rsa-pss-sha256, ecdsa-sha256 or ecdsa-sha384; by default an RSA key signs rsa-sha256.
--xml-sign-passphrase-env <VAR> Environment variable holding the passphrase for --xml-sign-key.
--list-templates / --show-template <TYPE> List the bundled templates, or show one template's metadata, and exit.

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

XML signing and verify-signature need the sign extra (pip install "pain001[sign]", which installs cryptography and lxml).

Signatures: pain001 verify-signature

pain001 verify-signature checks the signature on files you received or wrote. Pass the signer's certificate or public key with --cert; that is the trust anchor. --trust-embedded-cert verifies with each file's own certificate instead, which proves the file is unchanged since it was signed but not who signed it. It exits 0 when every file verifies, 1 when any does not, and 2 when it cannot run; --format json prints one report per file. Verification uses exclusive C14N 1.0 and accepts only RSA-SHA256, RSA-PSS and ECDSA signatures with SHA-256 to SHA-512 digests over the whole document; the certificate's chain and validity dates are not checked.

Faces: pain001 face

A face projects a validated pain.001 document into another standard's JSON request body. --face uk_open_banking targets the Open Banking Read/Write API v4.0.1 domestic payment, --face berlin_group targets NextGenPSD2 v1.3.16 payment initiation, and --face iso_2018 renames every element to its ISO 20022 name in snake_case. A face refuses a document that lacks an element its target requires instead of inventing a value; --loss-report lists every source element it did not carry. Faces are outbound only.

Delivery: pain001 upload

pain001 upload sends a finished file to an SFTP server you name, and only after you have trusted its host key: from a known_hosts file (--known-hosts) or an OpenSSH SHA256 fingerprint you verified independently (--accept-host-key). --print-host-key shows the server's fingerprint without logging in. It logs in with a private key (--identity-file, with --passphrase-env), a password read from an environment variable (--password-env), or your SSH agent. The file is written under a temporary name and renamed on the server, so the receiving side never sees a partial file.


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_path="out/payments.xml",
)

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): a megadott fizetési rendszer szabályai, a SEPA-tól (SCT, Instant, SDD Core, B2B) az olyan nemzeti rendszerekig, mint a UK Faster Payments, a CHAPS és a Bacs, az amerikai ACH és utalások, valamint a Swift CBPR+; a(z) pain001 plugins list mindet megnevezi.
  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. Ha az opcionális fast kiegészítő (lxml) telepítve van, a libxml2 gyorsabban fogadja el az érvényes dokumentumokat; az általa elutasított dokumentumot a(z) xmlschema újra ellenőrzi, és annak döntése a végleges.

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.

pain001.faces.project_face is the Python entry point for faces. sign_xml_document signs a document with XML-DSig, and verify_signature(signed_xml, trust_anchor=cert_pem) verifies one and returns a SignatureReport (valid, trust, algorithm, signer, reason); both need the sign extra. verify_xml_signature without a key or certificate still trusts the certificate inside the document, with a DeprecationWarning; pain001 0.0.90 refuses it.

Runnable, self-checking scripts for the public API and the CLI live in the library's examples/ directory.


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 /api/v1/faces List the faces and the binding keys each accepts.
POST /api/v1/faces/{face} Project a pain.001 document sent as XML text; returns the payload and the loss report, or 422 with the reason the face refused it.
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.

When the PAIN001_API_KEY environment variable is set, every endpoint except /health and /metrics requires it as a bearer token; when it is unset, the API is open. pain001 serve binds to 127.0.0.1 unless you pass --host.


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.
  • Formula cells: CSV cells that start with =, +, - or @ are kept as supplied by default, so phone numbers and references survive; load_csv_data(path, sanitize_formula=True) escapes them with a leading quote instead.

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.