Pain001 – referință tehnică: CLI, API Python și REST

Această referință documentează interfața de linie de comandă, API-ul Python, microserviciul REST și fluxul de validare pentru pain001 v0.0.57. Fiecare flag, endpoint și comportament enumerat aici este preluat din codul livrat, nu din intenții.

Pain001 acceptă 11 definiții de mesaje ISO 20022: de la pain.001.001.03 la pain.001.001.12 (Customer Credit Transfer Initiation, zece versiuni) și pain.008.001.02 (Customer Direct Debit Initiation).

1. Interfața de linie de comandă#

Executabilul pain001 își grupează funcționalitatea în subcomenzi. Rulat doar cu flagurile de generare, invocă implicit generate, astfel încât automatizările existente continuă să funcționeze.

Subcomandă	Scop
`generate`	Convertește un fișier de date în XML ISO 20022 validat față de schemă (comanda implicită).
`validate`	Validează datele de intrare fără a scrie XML.
`versions [--json]`	Listează toate cele 11 definiții de mesaje acceptate.
`inspect [--json]`	Afișează câmpurile obligatorii și opționale pentru un tip de mesaj.
`init [-o DIR]`	Generează un șablon CSV inițial pentru un tip de mesaj.
`serve [--host] [--port] [--reload]`	Pornește microserviciul REST FastAPI (necesită extra-ul `api`).
`mcp`	Pornește serverul Model Context Protocol inclus în proiect (5 instrumente; serverul complet, cu 17 instrumente, se livrează ca `pain001-mcp`).
`plugins list / show / disable`	Inspectați și gestionați plugin-urile de încărcare, validare, scheme și scriere care au fost detectate.

Opțiuni `generate`

Flag	Descriere
`-t, --xml-message-type`	Definiția mesajului, de exemplu `pain.001.001.09`.
`-d, --data`	Date de intrare: `.csv`, `.json`, `.jsonl`, `.db` / `.sqlite`, `.parquet` sau fișiere criptate PGP `.gpg` / `.asc`.
`-o, --output-dir`	Directorul în care este scris XML-ul generat.
`-m, --template` / `-s, --schema`	Înlocuiește șablonul Jinja2 sau schema XSD incluse în pachet.
`-c, --config`	Încarcă valorile implicite dintr-un profil de configurare (`--profile`, `--show-config`).
`--dry-run` (alias `--validate-only`)	Validează datele de intrare față de JSON Schema, XSD și regulamentul de schemă, fără a scrie niciun rezultat.
`--scheme`	Impune un regulament de schemă: `sepa-sct`, `sepa-inst`, `sepa-sdd`, `sepa-b2b` sau `xborder-ct`.
`--explain --scheme-format {text,json}`	Raportează fiecare regulă de schemă trecută sau eșuată, în format lizibil pentru oameni sau pentru mașini.
`--streaming` / `--chunk-size`	Procesare pe fragmente, cu memorie limitată, pentru loturi mari (implicit 1,000 de tranzacții per fragment; fiecare fragment devine propriul fișier XML, cu `NbOfTxs` și `CtrlSum` recalculate).
`--emit-metrics`	Emite metrici de execuție lizibile automat, pentru fluxurile de observabilitate.

Codurile de ieșire sunt prietenoase cu CI: 0 succes, 1 eșec de validare, 2 eroare de utilizare.

2. API Python#

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

Fiecare document generat trece prin trei straturi înainte de a fi scris:

Validarea datelor de intrare — fiecare înregistrare este verificată față de JSON Schema a tipului de mesaj, cu normalizarea aliasurilor de câmp și verificări de sintaxă IBAN/BIC.
Regulamentul de schemă (opțional) — reguli SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B sau pentru transferuri credit transfrontaliere.
Validare XSD — XML-ul generat este validat față de schema oficială ISO 20022 prin xmlschema, înainte ca vreun octet să fie scris pe disc.

Sumele monetare sunt tratate ca decimal.Decimal pe parcursul generării XML și al validării de schemă — niciodată ca numere în virgulă mobilă IEEE 754 — iar totalurile de control NbOfTxs / CtrlSum sunt recalculate din înregistrările validate, nu preluate pe încredere din datele de intrare.

Dincolo de generarea pain.001, biblioteca de bază include și un parser și generator de rapoarte de stare pain.002 (astfel încât să puteți citi răspunsul de acceptare/respingere al băncii) și un parser și generator de extrase camt.053 pentru reconcilierea de la sfârșitul zilei, plus un VersionMapper care migrează înregistrările între versiunile de mesaje.

3. Microserviciul REST#

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

Toate endpointurile sunt montate sub /api/v1 (cu un alias neversionat /api):

Metodă și cale	Scop
`GET /api/v1/health`	Sondă de disponibilitate.
`POST /api/v1/validate`	Validează înregistrările; returnează erori la nivel de câmp.
`POST /api/v1/generate`	Generare XML sincronă.
`POST /api/v1/generate/async`	Pune un lot mare în coadă pentru generare în fundal.
`GET /api/v1/status/{job_id}`	Interoghează starea unei sarcini asincrone.
`GET /api/v1/download/{job_id}`	Descarcă XML-ul finalizat.
`DELETE /api/v1/jobs/{job_id}`	Curăță o sarcină finalizată.
`GET /metrics`	Metrici Prometheus.

Documentația interactivă este servită la /api/docs (Swagger UI), /api/redoc și /api/reference (Scalar), iar documentul OpenAPI la /openapi.json.

4. Normalizarea datelor de intrare#

Pain001 transformă exporturile din lumea reală în înregistrări valide înainte de validare:

Aliasuri de câmp — denumirile uzuale de coloane din sistemele ERP sunt mapate pe câmpurile canonice (de exemplu amount → payment_amount).
Normalizare IBAN / BIC — spațiile sunt eliminate, literele uniformizate, apoi valoarea este verificată (mod-97 conform ISO 13616 pentru IBAN, structura ISO 9362 pentru BIC).
Date calendaristice — interpretare ISO 8601 YYYY-MM-DD pentru datele de execuție.
Sume — trecute prin decimal.Decimal; sumele malformate eșuează la validare, în loc să fie rotunjite în tăcere.
Set de caractere — funcțiile de transliterare reduc conținutul la setul de caractere latine ISO 20022 acceptat de SWIFT și SEPA.

5. Arhitectura de plugin-uri#

Suita este extensibilă prin patru grupuri de puncte de intrare: pain001.loaders, pain001.validators, pain001.schemes și pain001.writers. pain001-loader-xlsx se înregistrează prin acest mecanism și este detectat automat la instalare; pain001-loader-mt101 este o bibliotecă de parsare autonomă, folosită direct (și de instrumentul convert_mt101 al serverului MCP). Un comutator de oprire — PAIN001_DISABLE_PLUGINS=1 — dezactivează complet detectarea plugin-urilor terțe în mediile restricționate.

6. Praguri de calitate#

Biblioteca de bază este dezvoltată respectând praguri stricte și verificabile: acoperire 100% pe linii și pe ramuri, impusă în CI (--cov-fail-under=100), tipizare strictă mypy, acoperire 100% a docstring-urilor și analiză statică de securitate (Bandit, pip-audit). Pentru fiecare build de lansare se generează un SBOM CycloneDX.

Continuați cu Ghidul de instalare, cu serverul MCP pentru agenți AI sau cu glosarul de plăți.