Diese Referenz dokumentiert die Kommandozeilenschnittstelle, die Python-API, den REST-Microservice und die Validierungspipeline von pain001 v0.0.71. Jedes hier aufgeführte Flag, jeder Endpunkt und jedes Verhalten ist dem ausgelieferten Code entnommen, nicht dem Wunschdenken.
Pain001 unterstützt 12 ISO 20022-Nachrichtendefinitionen: pain.001.001.03 bis pain.001.001.13 (Customer Credit Transfer Initiation, elf 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.
| Unterbefehl | Zweck |
|---|---|
generate | Wandelt eine Datendatei in schemavalidiertes ISO 20022-XML um (Standardbefehl). |
validate | Validiert Eingabedaten, ohne XML zu schreiben. |
versions [--json] | Listet alle 13 unterstützten Nachrichtendefinitionen auf. |
inspect <type> [--json] | Zeigt die Pflicht- und optionalen Felder eines Nachrichtentyps an. |
init <type> [-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 22 Tools wird als pain001-mcp ausgeliefert). |
plugins list / show / disable | Zeigt und verwaltet erkannte Loader-, Validator-, Scheme- und Writer-Plugins. |
Optionen von generate
| Option | Beschreibung |
|---|---|
-t, --xml-message-type <TYPE> | Nachrichtendefinition, z. B. pain.001.001.09. |
-d, --data <FILE> | Eingabedaten: .csv, .json, .jsonl, .db / .sqlite, .parquet oder PGP-verschlüsselt .gpg / .asc. |
-o, --output-dir <DIR> | Verzeichnis, in dem das generierte XML abgelegt wird. |
-m, --template <FILE> / -s, --schema <FILE> | Überschreibt die mitgelieferte Jinja2-Vorlage bzw. das XSD-Schema. |
-c, --config <FILE> | 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 <NAME> | 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 <N> | 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.
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.
| Option | Beschreibung |
|---|---|
--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#
# Generate a validated pain.001.001.09 file from CSV
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
xmlschemagegen 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#
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. Qualitätsprüfungen#
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.