Pain001 : référence technique CLI, API Python et REST

Cette référence documente l'interface en ligne de commande, l'API Python, le microservice REST et le pipeline de validation de pain001 v0.0.57. Chaque option, point d'accès et comportement listé ici est tiré du code livré, non d'aspirations.

Pain001 prend en charge 11 définitions de message ISO 20022 : pain.001.001.03 à pain.001.001.12 (Customer Credit Transfer Initiation, dix versions) et pain.008.001.02 (Customer Direct Debit Initiation).

1. Interface en ligne de commande#

L'exécutable pain001 regroupe ses fonctionnalités en sous-commandes. Lancé avec les seules options de génération, il invoque implicitement generate, si bien que l'automatisation existante continue de fonctionner.

Sous-commande	Rôle
`generate`	Convertit un fichier de données en XML ISO 20022 validé par schéma (commande par défaut).
`validate`	Valide les données d'entrée sans écrire de XML.
`versions [--json]`	Liste les 11 définitions de message prises en charge.
`inspect [--json]`	Affiche les champs obligatoires et optionnels d'un type de message.
`init [-o DIR]`	Génère un modèle CSV de départ pour un type de message.
`serve [--host] [--port] [--reload]`	Lance le microservice REST FastAPI (nécessite l'extra `api`).
`mcp`	Lance le serveur Model Context Protocol intégré (5 outils ; le serveur complet à 17 outils est livré sous `pain001-mcp`).
`plugins list / show / disable`	Inspecte et gère les plugins découverts : loaders, validateurs, schémas et writers.

Options de `generate`

Option	Description
`-t, --xml-message-type`	Définition de message, p. ex. `pain.001.001.09`.
`-d, --data`	Données d'entrée : `.csv`, `.json`, `.jsonl`, `.db` / `.sqlite`, `.parquet`, ou `.gpg` / `.asc` chiffrés PGP.
`-o, --output-dir`	Répertoire qui reçoit le XML généré.
`-m, --template` / `-s, --schema`	Remplace le modèle Jinja2 ou le schéma XSD fournis.
`-c, --config`	Charge les valeurs par défaut depuis un profil de configuration (`--profile`, `--show-config`).
`--dry-run` (alias `--validate-only`)	Valide l'entrée contre le schéma JSON, le XSD et le recueil de règles du schéma, sans écrire de sortie.
`--scheme`	Applique un recueil de règles : `sepa-sct`, `sepa-inst`, `sepa-sdd`, `sepa-b2b` ou `xborder-ct`.
`--explain --scheme-format {text,json}`	Signale chaque règle du schéma réussie ou échouée, en format lisible par l'humain ou par la machine.
`--streaming` / `--chunk-size`	Traitement par blocs à mémoire bornée pour les gros lots (1,000 transactions par bloc par défaut ; chaque bloc devient son propre fichier XML avec `NbOfTxs` et `CtrlSum` recalculés).
`--emit-metrics`	Émet des métriques d'exécution lisibles par la machine pour les pipelines d'observabilité.

Les codes de sortie sont adaptés à la CI : 0 succès, 1 échec de validation, 2 erreur d'utilisation.

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

Chaque document généré franchit trois couches avant d'être écrit :

Validation des entrées — chaque enregistrement est vérifié contre le schéma JSON du type de message, avec normalisation des alias de champs et contrôles syntaxiques IBAN/BIC.
Recueil de règles du schéma (optionnel) — règles SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B ou virement transfrontalier.
Validation XSD — le XML rendu est validé contre le schéma ISO 20022 officiel via xmlschema avant qu'un seul octet ne soit écrit sur disque.

Les montants monétaires sont traités en decimal.Decimal pendant la génération XML et la validation de schéma — jamais en flottants IEEE 754 — et les totaux de contrôle NbOfTxs / CtrlSum sont recalculés à partir des enregistrements validés plutôt qu'acceptés tels quels depuis l'entrée.

Au-delà de la génération pain.001, la bibliothèque cœur embarque aussi un analyseur et générateur de rapports d'état pain.002 (pour lire la réponse d'acceptation ou de rejet de la banque) et un analyseur et générateur de relevés camt.053 pour le rapprochement de fin de journée, ainsi qu'un VersionMapper qui migre les enregistrements entre versions de message.

3. Microservice REST#

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

Tous les points d'accès sont montés sous /api/v1 (avec un alias non versionné /api) :

Méthode et chemin	Rôle
`GET /api/v1/health`	Sonde de vivacité.
`POST /api/v1/validate`	Valide les enregistrements ; renvoie des erreurs au niveau du champ.
`POST /api/v1/generate`	Génération XML synchrone.
`POST /api/v1/generate/async`	Met en file d'attente un gros lot pour génération en arrière-plan.
`GET /api/v1/status/{job_id}`	Interroge un travail asynchrone.
`GET /api/v1/download/{job_id}`	Télécharge le XML terminé.
`DELETE /api/v1/jobs/{job_id}`	Nettoie un travail terminé.
`GET /metrics`	Métriques Prometheus.

La documentation interactive est servie sur /api/docs (Swagger UI), /api/redoc et /api/reference (Scalar), avec le document OpenAPI sur /openapi.json.

4. Normalisation des entrées#

Pain001 convertit les exports du monde réel en enregistrements valides avant validation :

Alias de champs — les noms de colonnes ERP courants sont mappés sur des champs canoniques (par exemple amount → payment_amount).
Normalisation IBAN / BIC — espaces supprimés, casse normalisée, puis vérification (mod-97 ISO 13616 pour les IBAN, structure ISO 9362 pour les BIC).
Dates — analyse ISO 8601 YYYY-MM-DD pour les dates d'exécution.
Montants — acheminés via decimal.Decimal ; les montants mal formés échouent à la validation au lieu d'être arrondis silencieusement.
Jeu de caractères — des utilitaires de translittération ramènent le contenu au jeu de caractères latin ISO 20022 accepté par SWIFT et SEPA.

5. Architecture de plugins#

La suite est extensible via quatre groupes de points d'entrée : pain001.loaders, pain001.validators, pain001.schemes et pain001.writers. pain001-loader-xlsx s'enregistre par ce mécanisme et est découvert automatiquement à l'installation ; pain001-loader-mt101 est une bibliothèque d'analyse autonome consommée directement (et par l'outil convert_mt101 du serveur MCP). Un interrupteur d'arrêt — PAIN001_DISABLE_PLUGINS=1 — désactive entièrement la découverte de plugins tiers dans les environnements verrouillés.

6. Contrôles qualité#

La bibliothèque cœur est développée contre des portes strictes et vérifiables : couverture de lignes et de branches à 100% imposée en CI (--cov-fail-under=100), typage mypy strict, couverture de docstrings à 100% et analyse de sécurité (Bandit, pip-audit). Un SBOM CycloneDX est généré pour chaque build de release.

Poursuivez avec le guide d'installation, le serveur MCP pour agents IA ou le glossaire des paiements.