Pain001 Technische Referenz: CLI, Python-API und REST

Diese Referenz dokumentiert die Kommandozeilenschnittstelle, die Python-API, den REST-Microservice und die Validierungspipeline von pain001 v0.0.57. Jedes hier aufgeführte Flag, jeder Endpunkt und jedes Verhalten ist dem ausgelieferten Code entnommen, nicht dem Wunschdenken.

Pain001 unterstützt 11 ISO 20022-Nachrichtendefinitionen: pain.001.001.03 bis pain.001.001.12 (Customer Credit Transfer Initiation, zehn Versionen) und pain.008.001.02 (Customer Direct Debit Initiation).

1. Kommandozeilenschnittstelle#

Das pain001-Programm gliedert seine Funktionalität in Subcommands. Wird es nur mit Generierungs-Flags aufgerufen, ruft es implizit generate auf, sodass bestehende Automatisierung weiter funktioniert.

Subcommand	Zweck
`generate`	Wandelt eine Datendatei in schemavalidiertes ISO 20022-XML um (Standardbefehl).
`validate`	Validiert Eingabedaten, ohne XML zu schreiben.
`versions [--json]`	Listet alle 11 unterstützten Nachrichtendefinitionen auf.
`inspect [--json]`	Zeigt die Pflicht- und optionalen Felder eines Nachrichtentyps an.
`init [-o DIR]`	Erzeugt eine CSV-Startvorlage für einen Nachrichtentyp.
`serve [--host] [--port] [--reload]`	Startet den FastAPI-REST-Microservice (erfordert das Extra `api`).
`mcp`	Startet den mitgelieferten Model Context Protocol-Server (5 Tools; der vollständige Server mit 17 Tools wird als `pain001-mcp` ausgeliefert).
`plugins list / show / disable`	Zeigt und verwaltet erkannte Loader-, Validator-, Scheme- und Writer-Plugins.

Optionen von `generate`

Flag	Beschreibung
`-t, --xml-message-type`	Nachrichtendefinition, z. B. `pain.001.001.09`.
`-d, --data`	Eingabedaten: `.csv`, `.json`, `.jsonl`, `.db` / `.sqlite`, `.parquet` oder PGP-verschlüsselt `.gpg` / `.asc`.
`-o, --output-dir`	Verzeichnis, in dem das generierte XML abgelegt wird.
`-m, --template` / `-s, --schema`	Überschreibt die mitgelieferte Jinja2-Vorlage bzw. das XSD-Schema.
`-c, --config`	Lädt Standardwerte aus einem Konfigurationsprofil (`--profile`, `--show-config`).
`--dry-run` (Alias `--validate-only`)	Validiert die Eingabe gegen das JSON-Schema, das XSD und das Scheme-Regelwerk, ohne Ausgabe zu schreiben.
`--scheme`	Erzwingt ein Scheme-Regelwerk: `sepa-sct`, `sepa-inst`, `sepa-sdd`, `sepa-b2b` oder `xborder-ct`.
`--explain --scheme-format {text,json}`	Meldet jede bestandene oder verletzte Scheme-Regel, wahlweise menschen- oder maschinenlesbar.
`--streaming` / `--chunk-size`	Speicherbegrenzte, blockweise Verarbeitung großer Stapel (standardmäßig 1,000 Transaktionen pro Block; jeder Block wird zu einer eigenen XML-Datei mit neu berechneten `NbOfTxs` und `CtrlSum`).
`--emit-metrics`	Gibt maschinenlesbare Laufmetriken für Observability-Pipelines aus.

Die Exit-Codes sind CI-freundlich: 0 Erfolg, 1 Validierungsfehler, 2 Bedienfehler.

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

Jedes generierte Dokument durchläuft drei Schichten, bevor es geschrieben wird:

Eingabevalidierung — jeder Datensatz wird gegen das JSON-Schema des Nachrichtentyps geprüft, mit Feld-Alias-Normalisierung und IBAN/BIC-Syntaxprüfungen.
Scheme-Regelwerk (optional) — Regeln für SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B oder grenzüberschreitende Überweisungen.
XSD-Validierung — das gerenderte XML wird über xmlschema gegen das offizielle ISO 20022-Schema validiert, bevor auch nur ein Byte auf die Festplatte geschrieben wird.

Geldbeträge werden bei der XML-Generierung und Scheme-Validierung als decimal.Decimal behandelt — niemals als IEEE 754-Gleitkommazahlen — und die Kontrollsummen NbOfTxs / CtrlSum werden aus den validierten Datensätzen neu berechnet, statt der Eingabe zu vertrauen.

Über die pain.001-Generierung hinaus liefert die Kernbibliothek auch einen pain.002-Statusbericht-Parser und -Generator (damit Sie die Annahme- bzw. Ablehnungsantwort der Bank lesen können) und einen camt.053-Kontoauszug-Parser und -Generator für den Tagesabschluss-Abgleich, dazu einen VersionMapper, der Datensätze zwischen Nachrichtenversionen migriert.

3. REST-Microservice#

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

Alle Endpunkte sind unter /api/v1 eingebunden (mit einem unversionierten Alias /api):

Methode & Pfad	Zweck
`GET /api/v1/health`	Liveness-Probe.
`POST /api/v1/validate`	Validiert Datensätze; liefert Fehler auf Feldebene zurück.
`POST /api/v1/generate`	Synchrone XML-Generierung.
`POST /api/v1/generate/async`	Stellt einen großen Stapel zur Hintergrundgenerierung in die Warteschlange.
`GET /api/v1/status/{job_id}`	Fragt einen asynchronen Job ab.
`GET /api/v1/download/{job_id}`	Lädt das fertige XML herunter.
`DELETE /api/v1/jobs/{job_id}`	Räumt einen abgeschlossenen Job auf.
`GET /metrics`	Prometheus-Metriken.

Interaktive Dokumentation wird unter /api/docs (Swagger UI), /api/redoc und /api/reference (Scalar) bereitgestellt, das OpenAPI-Dokument unter /openapi.json.

4. Eingabenormalisierung#

Pain001 überführt Exporte aus der Praxis vor der Validierung in gültige Datensätze:

Feld-Aliase — gängige ERP-Spaltennamen werden auf kanonische Felder abgebildet (zum Beispiel amount → payment_amount).
IBAN-/BIC-Normalisierung — Leerzeichen entfernt, Groß-/Kleinschreibung vereinheitlicht, dann geprüft (ISO 13616 mod-97 für IBANs, ISO 9362-Struktur für BICs).
Datumsangaben — ISO 8601-YYYY-MM-DD-Parsing für Ausführungsdaten.
Beträge — laufen durch decimal.Decimal; fehlerhafte Beträge scheitern an der Validierung, statt stillschweigend gerundet zu werden.
Zeichensatz — Transliterationshelfer reduzieren Inhalte auf den von SWIFT und SEPA akzeptierten lateinischen ISO 20022-Zeichensatz.

5. Plugin-Architektur#

Die Suite ist über vier Entry-Point-Gruppen erweiterbar: pain001.loaders, pain001.validators, pain001.schemes und pain001.writers. pain001-loader-xlsx registriert sich über diesen Mechanismus und wird bei der Installation automatisch erkannt; pain001-loader-mt101 ist eine eigenständige Parsing-Bibliothek, die direkt genutzt wird (sowie vom convert_mt101-Tool des MCP-Servers). Ein Notschalter — PAIN001_DISABLE_PLUGINS=1 — deaktiviert die Erkennung von Drittanbieter-Plugins in abgeschotteten Umgebungen vollständig.

6. Quality Gates#

Die Kernbibliothek wird gegen strenge, überprüfbare Schranken entwickelt: 100% Zeilen- und Zweigabdeckung, in der CI erzwungen (--cov-fail-under=100), striktes mypy-Typing, 100% Docstring-Abdeckung und Sicherheits-Linting (Bandit, pip-audit). Für jeden Release-Build wird eine CycloneDX-SBOM erzeugt.

Fahren Sie fort mit der Installationsanleitung, dem MCP-Server für KI-Agenten oder dem Zahlungsverkehrsglossar.