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.71. 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.

Opzioni di generate

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

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.

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. 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:

1. 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.
2. Rulebook di schema (facoltativo): regole SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B o bonifico transfrontaliero.
3. 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):

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.