Pain001 teknisk referens: CLI, Python-API och REST

Denna referens dokumenterar kommandoradsgränssnittet, Python-API:et, REST-mikrotjänsten och valideringspipelinen för pain001 v0.0.58. Varje flagga, endpoint och beteende som listas här är hämtat från den levererade koden, inte från ambitioner.

Pain001 stöder 12 ISO 20022-meddelandedefinitioner: pain.001.001.03 till och med pain.001.001.13 (Customer Credit Transfer Initiation, elva versioner) samt pain.008.001.02 (Customer Direct Debit Initiation).

1. Kommandoradsgränssnitt#

Programmet pain001 grupperar sin funktionalitet i underkommandon. Körs det med enbart genereringsflaggor anropas generate implicit, så befintlig automation fortsätter att fungera.

Underkommando	Syfte
`generate`	Konverterar en datafil till schemavaliderad ISO 20022-XML (standardkommando).
`validate`	Validerar indata utan att skriva XML.
`versions [--json]`	Listar alla 11 meddelandedefinitioner som stöds.
`inspect [--json]`	Visar obligatoriska och valfria fält för en meddelandetyp.
`init [-o DIR]`	Skapar en CSV-startmall för en meddelandetyp.
`serve [--host] [--port] [--reload]`	Startar FastAPI-REST-mikrotjänsten (kräver extran `api`).
`mcp`	Startar den inbyggda Model Context Protocol-servern (5 verktyg; den fullständiga servern med 17 verktyg levereras som `pain001-mcp`).
`plugins list / show / disable`	Inspekterar och hanterar upptäckta plugins för inläsare, validerare, regelverk och skrivare.

Alternativ för `generate`

Flagga	Beskrivning
`-t, --xml-message-type`	Meddelandedefinition, t.ex. `pain.001.001.09`.
`-d, --data`	Indata: `.csv`, `.json`, `.jsonl`, `.db` / `.sqlite`, `.parquet` eller PGP-krypterade `.gpg` / `.asc`.
`-o, --output-dir`	Katalog som tar emot den genererade XML-filen.
`-m, --template` / `-s, --schema`	Ersätter den medföljande Jinja2-mallen eller XSD-schemat.
`-c, --config`	Läser in standardvärden från en konfigurationsprofil (`--profile`, `--show-config`).
`--dry-run` (alias `--validate-only`)	Validerar indata mot JSON Schema, XSD och regelverket utan att skriva utdata.
`--scheme`	Tillämpar ett regelverk: `sepa-sct`, `sepa-inst`, `sepa-sdd`, `sepa-b2b` eller `xborder-ct`.
`--explain --scheme-format {text,json}`	Rapporterar varje regel som godkänts eller underkänts, i läsbart eller maskinläsbart format.
`--streaming` / `--chunk-size`	Minnesbegränsad bearbetning i delar för stora batchar (som standard 1,000 transaktioner per del; varje del blir en egen XML-fil med omräknade `NbOfTxs` och `CtrlSum`).
`--emit-metrics`	Skickar ut maskinläsbar körningsmetrik för observabilitetspipelines.

Slutkoderna är CI-vänliga: 0 lyckad körning, 1 valideringsfel, 2 användningsfel.

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

Varje genererat dokument passerar tre lager innan det skrivs:

Indatavalidering — varje post kontrolleras mot meddelandetypens JSON Schema, med normalisering av fältalias och syntaxkontroll av IBAN/BIC.
Regelverk (valfritt) — SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B eller regler för gränsöverskridande betalningsöverföringar.
XSD-validering — den renderade XML-filen valideras mot det officiella ISO 20022-schemat via xmlschema innan en enda byte skrivs till disk.

Penningbelopp hanteras som decimal.Decimal under XML-generering och regelverksvalidering — aldrig som IEEE 754-flyttal — och kontrollsummorna NbOfTxs / CtrlSum räknas om från de validerade posterna i stället för att tas från indata.

Utöver pain.001-generering levererar kärnbiblioteket också en parser och generator för pain.002-statusrapporter (så att du kan läsa bankens svar om godkännande eller avslag) och en parser och generator för camt.053-kontoutdrag för avstämning vid dagens slut, samt en VersionMapper som migrerar poster mellan meddelandeversioner.

3. REST-mikrotjänst#

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

Alla endpoints är monterade under /api/v1 (med det oversionerade aliaset /api):

Metod och sökväg	Syfte
`GET /api/v1/health`	Liveness-kontroll.
`POST /api/v1/validate`	Validerar poster; returnerar fel på fältnivå.
`POST /api/v1/generate`	Synkron XML-generering.
`POST /api/v1/generate/async`	Köar en stor batch för generering i bakgrunden.
`GET /api/v1/status/{job_id}`	Frågar efter status för ett asynkront jobb.
`GET /api/v1/download/{job_id}`	Laddar ner den färdiga XML-filen.
`DELETE /api/v1/jobs/{job_id}`	Städar upp ett slutfört jobb.
`GET /metrics`	Prometheus-metrik.

Interaktiv dokumentation finns på /api/docs (Swagger UI), /api/redoc och /api/reference (Scalar), med OpenAPI-dokumentet på /openapi.json.

4. Normalisering av indata#

Pain001 omvandlar verkliga exporter till giltiga poster före valideringen:

Fältalias — vanliga ERP-kolumnnamn mappas till kanoniska fält (till exempel amount → payment_amount).
IBAN-/BIC-normalisering — blanksteg tas bort, skiftläget normaliseras och därefter kontrolleras värdena (ISO 13616 mod-97 för IBAN, ISO 9362-struktur för BIC).
Datum — ISO 8601-tolkning av YYYY-MM-DD för utförandedatum.
Belopp — hanteras via decimal.Decimal; felaktiga belopp underkänns i valideringen i stället för att avrundas i tysthet.
Teckenuppsättning — translittereringshjälpmedel reducerar innehållet till den latinska ISO 20022-teckenuppsättning som SWIFT och SEPA accepterar.

5. Pluginarkitektur#

Sviten kan utökas via fyra entry-point-grupper: pain001.loaders, pain001.validators, pain001.schemes och pain001.writers. pain001-loader-xlsx registrerar sig via denna mekanism och upptäcks automatiskt vid installation; pain001-loader-mt101 är ett fristående parsningsbibliotek som används direkt (och av MCP-serverns verktyg convert_mt101). En nödbrytare — PAIN001_DISABLE_PLUGINS=1 — stänger helt av upptäckt av tredjepartsplugins i låsta miljöer.

6. Kvalitetsgrindar#

Kärnbiblioteket utvecklas mot strikta, verifierbara grindar: 100% rad- och grentäckning som krav i CI (--cov-fail-under=100), strikt mypy-typning, 100% docstring-täckning och säkerhetslintning (Bandit, pip-audit). En CycloneDX-SBOM genereras för varje release-bygge.

Fortsätt med installationsguiden, MCP-servern för AI-agenter eller betalningsordlistan.