Pain001
Probeer de demo ›

Referentie

Pain001 Technische Referentie: CLI, Python-API en REST

Elke vlag, elk endpoint en elk gedrag van pain001 v0.0.56 — ontleend aan de uitgeleverde code, niet aan wensdenken.

4 min. leestijd Laatst gecontroleerd

Deze referentie documenteert de opdrachtregelinterface, de Python-API, de REST-microservice en de validatiepijplijn van pain001 v0.0.57. Elke vlag, elk endpoint en elk gedrag dat hier staat, is ontleend aan de uitgeleverde code, niet aan wensdenken.

Pain001 ondersteunt 11 ISO 20022-berichtdefinities: pain.001.001.03 tot en met pain.001.001.12 (Customer Credit Transfer Initiation, tien versies) en pain.008.001.02 (Customer Direct Debit Initiation).

1. Opdrachtregelinterface#

Het uitvoerbare bestand pain001 groepeert zijn functionaliteit in subcommando's. Roept u het alleen met generatievlaggen aan, dan wordt generate impliciet uitgevoerd, zodat bestaande automatisering blijft werken.

Subcommando Doel
generate Zet een gegevensbestand om in schemagevalideerde ISO 20022-XML (standaardcommando).
validate Valideer invoergegevens zonder XML te schrijven.
versions [--json] Toon alle 11 ondersteunde berichtdefinities.
inspect [--json] Toon de verplichte en optionele velden voor een berichttype.
init [-o DIR] Genereer een CSV-startsjabloon voor een berichttype.
serve [--host] [--port] [--reload] Start de FastAPI REST-microservice (vereist de extra api).
mcp Start de meegeleverde Model Context Protocol-server (5 tools; de volledige server met 17 tools wordt geleverd als pain001-mcp).
plugins list / show / disable Bekijk en beheer de gevonden loader-, validator-, scheme- en writer-plugins.

Opties voor generate

Vlag Beschrijving
-t, --xml-message-type Berichtdefinitie, bijv. pain.001.001.09.
-d, --data Invoergegevens: .csv, .json, .jsonl, .db / .sqlite, .parquet, of met PGP versleutelde .gpg / .asc.
-o, --output-dir Map waarin de gegenereerde XML terechtkomt.
-m, --template / -s, --schema Overschrijf het meegeleverde Jinja2-sjabloon of XSD-schema.
-c, --config Laad standaardwaarden uit een configuratieprofiel (--profile, --show-config).
--dry-run (alias --validate-only) Valideer de invoer tegen het JSON Schema, het XSD en het scheme-rulebook zonder uitvoer te schrijven.
--scheme Dwing een scheme-rulebook af: sepa-sct, sepa-inst, sepa-sdd, sepa-b2b of xborder-ct.
--explain --scheme-format {text,json} Rapporteer elke scheme-regel die slaagde of faalde, leesbaar voor mens of machine.
--streaming / --chunk-size Geheugenbegrensde verwerking in chunks voor grote batches (standaard 1,000 transacties per chunk; elke chunk wordt een eigen XML-bestand met herberekende NbOfTxs en CtrlSum).
--emit-metrics Geef machineleesbare uitvoeringsmetrieken af voor observability-pijplijnen.

De exitcodes zijn CI-vriendelijk: 0 geslaagd, 1 validatiefout, 2 gebruiksfout.

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

Elk gegenereerd document doorloopt drie lagen voordat het wordt weggeschreven:

  1. Invoervalidatie — elk record wordt gecontroleerd tegen het JSON Schema van het berichttype, met normalisatie van veldaliassen en syntaxiscontroles op IBAN en BIC.
  2. Scheme-rulebook (optioneel) — de regels van SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B of de grensoverschrijdende overboeking.
  3. XSD-validatie — de gerenderde XML wordt via xmlschema gevalideerd tegen het officiële ISO 20022-schema voordat er ook maar één byte naar schijf gaat.

Geldbedragen worden tijdens XML-generatie en scheme-validatie behandeld als decimal.Decimal — nooit als IEEE 754-floats — en de controletotalen NbOfTxs / CtrlSum worden herberekend uit de gevalideerde records in plaats van blind uit de invoer overgenomen.

Naast het genereren van pain.001 levert de kernbibliotheek ook een parser en generator voor pain.002-statusrapporten (zodat u het accepteer- of afwijsantwoord van de bank kunt lezen) en een parser en generator voor camt.053-afschriften voor de reconciliatie aan het eind van de dag, plus een VersionMapper die records tussen berichtversies migreert.

3. REST-microservice#

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

Alle endpoints hangen onder /api/v1 (met een ongeversioneerde alias /api):

Methode & pad Doel
GET /api/v1/health Liveness-probe.
POST /api/v1/validate Valideert records; geeft fouten op veldniveau terug.
POST /api/v1/generate Synchrone XML-generatie.
POST /api/v1/generate/async Zet een grote batch in de wachtrij voor generatie op de achtergrond.
GET /api/v1/status/{job_id} Vraag de status van een asynchrone taak op.
GET /api/v1/download/{job_id} Download de voltooide XML.
DELETE /api/v1/jobs/{job_id} Ruim een afgeronde taak op.
GET /metrics Prometheus-metrieken.

Interactieve documentatie wordt aangeboden op /api/docs (Swagger UI), /api/redoc en /api/reference (Scalar), met het OpenAPI-document op /openapi.json.

4. Invoernormalisatie#

Pain001 vormt exports uit de praktijk om tot geldige records vóór de validatie:

  • Veldaliassen — gangbare ERP-kolomnamen worden op canonieke velden afgebeeld (bijvoorbeeld amount → payment_amount).
  • IBAN-/BIC-normalisatie — spaties verwijderd, hoofdlettergebruik genormaliseerd en daarna gecontroleerd (ISO 13616 mod-97 voor IBAN's, ISO 9362-structuur voor BIC's).
  • Datums — ISO 8601-parsing in de vorm YYYY-MM-DD voor uitvoeringsdatums.
  • Bedragen — verwerkt via decimal.Decimal; onjuist opgemaakte bedragen falen de validatie in plaats van stilzwijgend te worden afgerond.
  • Tekenset — transliteratiehulpmiddelen brengen de inhoud terug tot de Latijnse ISO 20022-tekenset die SWIFT en SEPA accepteren.

5. Plugin-architectuur#

De suite is uitbreidbaar via vier entry-pointgroepen: pain001.loaders, pain001.validators, pain001.schemes en pain001.writers. pain001-loader-xlsx registreert zich via dit mechanisme en wordt bij installatie automatisch gevonden; pain001-loader-mt101 is een zelfstandige parsingbibliotheek die rechtstreeks wordt gebruikt (en door de tool convert_mt101 van de MCP-server). Een noodschakelaar — PAIN001_DISABLE_PLUGINS=1 — schakelt de detectie van plugins van derden volledig uit in afgeschermde omgevingen.

6. Kwaliteitspoorten#

De kernbibliotheek wordt ontwikkeld tegen strikte, verifieerbare poorten: 100% regel- en branchdekking, afgedwongen in CI (--cov-fail-under=100), strikte mypy-typing, 100% docstringdekking en security-linting (Bandit, pip-audit). Voor elke releasebuild wordt een CycloneDX-SBOM gegenereerd.

Ga verder met de installatiehandleiding, de MCP-server voor AI-agents of het betalingsglossarium.