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.71. 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 13 meddelandedefinitioner som stöds.
`inspect <type> [--json]`	Visar obligatoriska och valfria fält för en meddelandetyp.
`init <type> [-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 22 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 <TYPE>`	Meddelandedefinition, t.ex. `pain.001.001.09`.
`-d, --data <FILE>`	Indata: `.csv`, `.json`, `.jsonl`, `.db` / `.sqlite`, `.parquet` eller PGP-krypterade `.gpg` / `.asc`.
`-o, --output-dir <DIR>`	Katalog som tar emot den genererade XML-filen.
`-m, --template <FILE>` / `-s, --schema <FILE>`	Ersätter den medföljande Jinja2-mallen eller XSD-schemat.
`-c, --config <FILE>`	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 <NAME>`	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 <N>`	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.

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.

Flagga	Beskrivning
`--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 RSA private key for W3C XML Digital Signature (XML-DSig RSA-SHA256).
`--xml-sign-cert <FILE>`	Optional PEM X.509 certificate to embed in XML-DSig `<ds:KeyInfo>`.
`--xml-sign-passphrase-env <VAR>`	Environment variable holding passphrase to decrypt the RSA private key.

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

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.