Pain001, riferimento tecnico: CLI, API Python e REST

Questo riferimento documenta l'interfaccia a riga di comando, l'API Python, il microservizio REST e la pipeline di validazione di pain001 v0.0.58. Ogni flag, endpoint e comportamento qui elencato è tratto dal codice distribuito, non dalle aspirazioni.

Pain001 supporta 12 definizioni di messaggio ISO 20022: da pain.001.001.03 a pain.001.001.13 (Customer Credit Transfer Initiation, undici versioni) e pain.008.001.02 (Customer Direct Debit Initiation).

1. Interfaccia a riga di comando#

L'eseguibile pain001 raggruppa le funzionalità in sottocomandi. Eseguendolo con soli flag di generazione viene invocato implicitamente generate, così l'automazione esistente continua a funzionare.

Sottocomando	Scopo
`generate`	Converte un file di dati in XML ISO 20022 validato rispetto allo schema (comando predefinito).
`validate`	Valida i dati di input senza scrivere XML.
`versions [--json]`	Elenca tutte le 11 definizioni di messaggio supportate.
`inspect [--json]`	Mostra i campi obbligatori e facoltativi di un tipo di messaggio.
`init [-o DIR]`	Genera un modello CSV iniziale per un tipo di messaggio.
`serve [--host] [--port] [--reload]`	Avvia il microservizio REST FastAPI (richiede l'extra `api`).
`mcp`	Avvia il server Model Context Protocol integrato (5 strumenti; il server completo con 17 strumenti è distribuito come `pain001-mcp`).
`plugins list / show / disable`	Ispeziona e gestisce i plugin individuati di tipo loader, validator, scheme e writer.

Opzioni di `generate`

Flag	Descrizione
`-t, --xml-message-type`	Definizione di messaggio, ad es. `pain.001.001.09`.
`-d, --data`	Dati di input: `.csv`, `.json`, `.jsonl`, `.db` / `.sqlite`, `.parquet`, oppure file cifrati PGP `.gpg` / `.asc`.
`-o, --output-dir`	Directory in cui viene scritto l'XML generato.
`-m, --template` / `-s, --schema`	Sostituisce il template Jinja2 o lo schema XSD inclusi.
`-c, --config`	Carica i valori predefiniti da un profilo di configurazione (`--profile`, `--show-config`).
`--dry-run` (alias `--validate-only`)	Valida l'input rispetto a JSON Schema, XSD e rulebook di schema senza scrivere output.
`--scheme`	Applica un rulebook di schema: `sepa-sct`, `sepa-inst`, `sepa-sdd`, `sepa-b2b` o `xborder-ct`.
`--explain --scheme-format {text,json}`	Riporta ogni regola dello schema superata o fallita, in forma leggibile dall'uomo o dalla macchina.
`--streaming` / `--chunk-size`	Elaborazione a blocchi con memoria limitata per batch di grandi dimensioni (impostazione predefinita 1,000 transazioni per blocco; ogni blocco diventa un file XML autonomo con `NbOfTxs` e `CtrlSum` ricalcolati).
`--emit-metrics`	Emette metriche di esecuzione machine-readable per le pipeline di osservabilità.

I codici di uscita sono adatti alla CI: 0 successo, 1 errore di validazione, 2 errore d'uso.

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

Ogni documento generato attraversa tre livelli prima di essere scritto:

Validazione dell'input — ogni record è verificato rispetto al JSON Schema del tipo di messaggio, con normalizzazione degli alias di campo e controlli sintattici su IBAN e BIC.
Rulebook di schema (facoltativo) — regole SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B o bonifico transfrontaliero.
Validazione XSD — l'XML generato è validato rispetto allo schema ufficiale ISO 20022 tramite xmlschema prima che un solo byte sia scritto su disco.

Gli importi monetari sono gestiti come decimal.Decimal durante la generazione dell'XML e la validazione di schema — mai come float IEEE 754 — e i totali di controllo NbOfTxs / CtrlSum sono ricalcolati dai record validati anziché essere accettati dall'input.

Oltre alla generazione di pain.001, la libreria core include anche un parser e generatore di report di stato pain.002 (per leggere la risposta di accettazione o rifiuto della banca) e un parser e generatore di estratti camt.053 per la riconciliazione di fine giornata, oltre a un VersionMapper che migra i record tra versioni di messaggio.

3. Microservizio REST#

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

Tutti gli endpoint sono esposti sotto /api/v1 (con un alias non versionato /api):

Metodo e percorso	Scopo
`GET /api/v1/health`	Probe di liveness.
`POST /api/v1/validate`	Valida i record; restituisce errori a livello di campo.
`POST /api/v1/generate`	Generazione XML sincrona.
`POST /api/v1/generate/async`	Accoda un batch di grandi dimensioni per la generazione in background.
`GET /api/v1/status/{job_id}`	Interroga un job asincrono.
`GET /api/v1/download/{job_id}`	Scarica l'XML completato.
`DELETE /api/v1/jobs/{job_id}`	Elimina un job completato.
`GET /metrics`	Metriche Prometheus.

La documentazione interattiva è disponibile su /api/docs (Swagger UI), /api/redoc e /api/reference (Scalar), con il documento OpenAPI su /openapi.json.

4. Normalizzazione degli input#

Pain001 trasforma le esportazioni del mondo reale in record validi prima della validazione:

Alias di campo — i nomi di colonna comuni negli ERP vengono mappati sui campi canonici (ad esempio amount → payment_amount).
Normalizzazione IBAN / BIC — spazi rimossi, maiuscole normalizzate, poi verifica (mod-97 ISO 13616 per gli IBAN, struttura ISO 9362 per i BIC).
Date — parsing ISO 8601 YYYY-MM-DD per le date di esecuzione.
Importi — instradati attraverso decimal.Decimal; gli importi malformati falliscono la validazione invece di essere arrotondati silenziosamente.
Set di caratteri — gli helper di traslitterazione riducono il contenuto al set di caratteri latini ISO 20022 accettato da SWIFT e SEPA.

5. Architettura a plugin#

La suite è estensibile tramite quattro gruppi di entry point: pain001.loaders, pain001.validators, pain001.schemes e pain001.writers. pain001-loader-xlsx si registra tramite questo meccanismo e viene rilevato automaticamente all'installazione; pain001-loader-mt101 è una libreria di parsing autonoma utilizzata direttamente (e dallo strumento convert_mt101 del server MCP). Un interruttore di emergenza — PAIN001_DISABLE_PLUGINS=1 — disabilita completamente la scoperta di plugin di terze parti negli ambienti blindati.

6. Quality gate#

La libreria core è sviluppata rispetto a gate rigorosi e verificabili: copertura di riga e di ramo al 100% imposta in CI (--cov-fail-under=100), tipizzazione mypy strict, copertura delle docstring al 100% e linting di sicurezza (Bandit, pip-audit). Per ogni build di release viene generato un SBOM CycloneDX.

Proseguite con la Guida all'installazione, il server MCP per agenti AI o il glossario dei pagamenti.