Pain001 technická reference: CLI, Python API a REST

Tato reference popisuje rozhraní příkazové řádky, Python API, REST mikroslužbu a validační pipeline nástroje pain001 v0.0.57. Každý zde uvedený přepínač, endpoint i chování je převzato z dodávaného kódu, nikoli z přání.

Pain001 podporuje 11 definic zpráv ISO 20022: pain.001.001.03 až pain.001.001.12 (Customer Credit Transfer Initiation, deset verzí) a pain.008.001.02 (Customer Direct Debit Initiation).

1. Rozhraní příkazové řádky#

Spustitelný soubor pain001 člení svou funkcionalitu do podpříkazů. Spustíte-li jej pouze s přepínači pro generování, vyvolá se implicitně generate, takže stávající automatizace funguje dál.

Podpříkaz	Účel
`generate`	Převede datový soubor na XML podle ISO 20022 ověřené proti schématu (výchozí příkaz).
`validate`	Ověří vstupní data, aniž by zapsal XML.
`versions [--json]`	Vypíše všech 11 podporovaných definic zpráv.
`inspect [--json]`	Zobrazí povinná a volitelná pole pro daný typ zprávy.
`init [-o DIR]`	Vygeneruje výchozí šablonu CSV pro daný typ zprávy.
`serve [--host] [--port] [--reload]`	Spustí REST mikroslužbu na FastAPI (vyžaduje doplněk `api`).
`mcp`	Spustí vestavěný server Model Context Protocol (5 nástrojů; plný server se 17 nástroji se dodává jako `pain001-mcp`).
`plugins list / show / disable`	Prohlédne a spravuje nalezené pluginy typu loader, validator, scheme a writer.

Volby příkazu `generate`

Přepínač	Popis
`-t, --xml-message-type`	Definice zprávy, např. `pain.001.001.09`.
`-d, --data`	Vstupní data: `.csv`, `.json`, `.jsonl`, `.db` / `.sqlite`, `.parquet`, nebo soubory šifrované PGP `.gpg` / `.asc`.
`-o, --output-dir`	Adresář, do kterého se uloží vygenerované XML.
`-m, --template` / `-s, --schema`	Přepíše dodávanou šablonu Jinja2 nebo schéma XSD.
`-c, --config`	Načte výchozí hodnoty z konfiguračního profilu (`--profile`, `--show-config`).
`--dry-run` (alias `--validate-only`)	Ověří vstup proti JSON Schema, XSD a pravidlům schématu, aniž by zapsal výstup.
`--scheme`	Vynutí pravidla schématu: `sepa-sct`, `sepa-inst`, `sepa-sdd`, `sepa-b2b` nebo `xborder-ct`.
`--explain --scheme-format {text,json}`	Vypíše každé pravidlo schématu, které prošlo či selhalo, ve formě čitelné pro člověka nebo pro stroj.
`--streaming` / `--chunk-size`	Zpracování po částech s omezenou spotřebou paměti pro velké dávky (výchozí 1,000 transakcí na část; každá část se stane vlastním souborem XML s přepočtenými `NbOfTxs` a `CtrlSum`).
`--emit-metrics`	Vydá strojově čitelné metriky běhu pro nástroje observability.

Návratové kódy jsou vstřícné k CI: 0 úspěch, 1 selhání validace, 2 chyba použití.

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

Každý vygenerovaný dokument projde před zápisem třemi vrstvami:

Validace vstupu — každý záznam se ověří proti JSON Schema daného typu zprávy, včetně normalizace aliasů polí a kontroly syntaxe IBAN a BIC.
Pravidla schématu (volitelně) — pravidla SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B nebo přeshraniční úhrady.
Validace XSD — vykreslené XML se pomocí xmlschema ověří proti oficiálnímu schématu ISO 20022 dříve, než se na disk zapíše jediný bajt.

Peněžní částky se při generování XML i validaci schématu zpracovávají jako decimal.Decimal — nikdy jako čísla IEEE 754 s plovoucí řádovou čárkou — a kontrolní součty NbOfTxs / CtrlSum se přepočítávají z ověřených záznamů, místo aby se bez kontroly přebíraly ze vstupu.

Kromě generování pain.001 obsahuje jádro knihovny také parser a generátor stavových hlášení pain.002 (abyste si mohli přečíst odpověď banky o přijetí či zamítnutí) a parser a generátor výpisů camt.053 pro závěrečnou denní rekonciliaci a dále VersionMapper, který převádí záznamy mezi verzemi zpráv.

3. REST mikroslužba#

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

Všechny endpointy jsou dostupné pod /api/v1 (s neverzovaným aliasem /api):

Metoda a cesta	Účel
`GET /api/v1/health`	Kontrola živosti.
`POST /api/v1/validate`	Ověří záznamy; vrací chyby na úrovni jednotlivých polí.
`POST /api/v1/generate`	Synchronní generování XML.
`POST /api/v1/generate/async`	Zařadí velkou dávku do fronty pro generování na pozadí.
`GET /api/v1/status/{job_id}`	Zjistí stav asynchronní úlohy.
`GET /api/v1/download/{job_id}`	Stáhne dokončené XML.
`DELETE /api/v1/jobs/{job_id}`	Uklidí dokončenou úlohu.
`GET /metrics`	Metriky pro Prometheus.

Interaktivní dokumentace je k dispozici na /api/docs (Swagger UI), /api/redoc a /api/reference (Scalar), dokument OpenAPI pak na /openapi.json.

4. Normalizace vstupů#

Pain001 před validací převádí exporty z reálného provozu na platné záznamy:

Aliasy polí — běžné názvy sloupců z ERP se mapují na kanonická pole (například amount → payment_amount).
Normalizace IBAN a BIC — odstraní se mezery, sjednotí se velikost písmen a teprve poté se provede kontrola (ISO 13616 mod-97 u IBAN, struktura ISO 9362 u BIC).
Datumy — parsování podle ISO 8601 ve tvaru YYYY-MM-DD pro data provedení.
Částky — vedeny přes decimal.Decimal; chybně zapsané částky neprojdou validací, místo aby se tiše zaokrouhlily.
Znaková sada — pomocné funkce pro transliteraci omezí obsah na latinskou znakovou sadu ISO 20022, kterou přijímají SWIFT i SEPA.

5. Architektura pluginů#

Sada je rozšiřitelná prostřednictvím čtyř skupin vstupních bodů: pain001.loaders, pain001.validators, pain001.schemes a pain001.writers. pain001-loader-xlsx se registruje tímto mechanismem a po instalaci je nalezen automaticky; pain001-loader-mt101 je samostatná knihovna pro parsování, kterou lze používat přímo (a využívá ji nástroj convert_mt101 serveru MCP). Nouzový vypínač — PAIN001_DISABLE_PLUGINS=1 — v uzamčených prostředích zcela vypne vyhledávání pluginů třetích stran.

6. Kontrola kvality#

Jádro knihovny se vyvíjí proti přísným a ověřitelným kritériím: 100% pokrytí řádků i větví vynucené v CI (--cov-fail-under=100), přísné typování mypy, 100% pokrytí dokumentačními řetězci a bezpečnostní kontrola kódu (Bandit, pip-audit). Pro každý vydaný build se generuje SBOM ve formátu CycloneDX.

Pokračujte návodem k instalaci, serverem MCP pro agenty s umělou inteligencí nebo slovníkem platebních pojmů.