Référence API pacs008

Le projet fournit à la fois une API REST et une CLI pour les flux de traitement des messages de paiement.

Notes de mise en œuvre

• Utiliser la génération synchrone pour les contrôles opérateur et les petits lots lorsque l'appelant attend immédiatement un fichier XML.
• Utiliser la génération asynchrone lorsque les fichiers d'entrée sont volumineux, que les traitements doivent être rejouables ou que la génération s'insère dans un moteur d'orchestration plus large.
• Conserver à la fois la charge utile source et le rapport de validation afin que les équipes support puissent reproduire la sortie XML lors d'un incident.
• Verrouiller les chemins des modèles et des XSD dans la configuration de déploiement afin d'éviter les mises à niveau silencieuses.

Installation

Installez le paquet depuis PyPI. Python 3.10 ou version supérieure est requis.

python -m pip install pacs008
 

---

REST API

Démarrez le serveur FastAPI intégré pour exposer des points de terminaison HTTP pour la validation et la génération.

Démarrer le serveur

uvicorn pacs008.api.app:app --reload --host 0.0.0.0 --port 8000
 

Points de terminaison

• pacs.002.001.12 — Rapport de statut de paiement FI à FI
• pacs.003.001.09 — Prélèvement client FI à FI
• pacs.004.001.11 — Retour de paiement
• pacs.007.001.11 — Annulation de paiement FI à FI
• pacs.008.001.13 — Virement client FI à FI
• pacs.009.001.10 — Virement entre institutions financières
• pacs.010.001.05 — Prélèvement entre institutions financières
• pacs.028.001.05 — Demande de statut de paiement FI à FI

Exemple de validation

Soumettre des données de paiement pour validation avant la génération du XML.

curl -X POST http://localhost:8000/api/validate \
  -H "Content-Type: application/json" \
  -d '{
    "message_type": "pacs.008.001.13",
    "data": [{
      "msg_id": "MSG-2026-001",
      "creation_date_time": "2026-01-15T10:30:00",
      "nb_of_txs": "1",
      "settlement_method": "CLRG",
      "interbank_settlement_date": "2026-01-15",
      "end_to_end_id": "E2E-INV-2026-001",
      "interbank_settlement_amount": "25000.00",
      "interbank_settlement_currency": "EUR",
      "charge_bearer": "SHAR",
      "debtor_name": "Acme Corp GmbH",
      "debtor_agent_bic": "DEUTDEFF",
      "creditor_agent_bic": "COBADEFF",
      "creditor_name": "Widget Industries SA"
    }]
  }'
 

{
  "valid": true,
  "message_type": "pacs.008.001.13",
  "errors": [],
  "warnings": []
}
 

Exemple de génération synchrone

Générer un fichier XML pacs.008.001.13 à partir d'une charge utile JSON.

curl -X POST http://localhost:8000/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "message_type": "pacs.008.001.13",
    "template": "pacs008/templates/pacs.008.001.13/template.xml",
    "schema": "pacs008/templates/pacs.008.001.13/pacs.008.001.13.xsd",
    "data": [{
      "msg_id": "MSG-2026-001",
      "creation_date_time": "2026-01-15T10:30:00",
      "nb_of_txs": "1",
      "settlement_method": "CLRG",
      "interbank_settlement_date": "2026-01-15",
      "end_to_end_id": "E2E-INV-2026-001",
      "tx_id": "TX-001",
      "interbank_settlement_amount": "25000.00",
      "interbank_settlement_currency": "EUR",
      "charge_bearer": "SHAR",
      "debtor_name": "Acme Corp GmbH",
      "debtor_agent_bic": "DEUTDEFF",
      "creditor_agent_bic": "COBADEFF",
      "creditor_name": "Widget Industries SA"
    }]
  }' --output pacs008_output.xml
 

Génération asynchrone

Pour les fichiers volumineux ou l'utilisation en pipeline, soumettez un job asynchrone et interrogez jusqu'à complétion.

# Submit the job
JOB=$(curl -s -X POST http://localhost:8000/api/generate/async \
  -H "Content-Type: application/json" \
  -d '{"message_type":"pacs.008.001.13","data":[...]}')

JOB_ID=$(echo $JOB | jq -r '.job_id')

# Poll for completion
curl http://localhost:8000/api/status/$JOB_ID

# Download the result
curl http://localhost:8000/api/download/$JOB_ID --output result.xml
 

{
  "job_id": "8f7f0d4b-7df9-4d1a-8d47-19f4f28b6d38",
  "status": "completed",
  "message_type": "pacs.008.001.13",
  "download_url": "/api/download/8f7f0d4b-7df9-4d1a-8d47-19f4f28b6d38"
}
 

---

CLI

L'interface en ligne de commande accepte un fichier de données, une version de message, un gabarit et un schéma. Elle valide l'entrée et écrit le XML généré dans le répertoire de sortie.

Utilisation de base

pacs008 -t  \
  -m  \
  -s  \
  -d 
 

Exemple

pacs008 -t pacs.008.001.13 \
  -m pacs008/templates/pacs.008.001.13/template.xml \
  -s pacs008/templates/pacs.008.001.13/pacs.008.001.13.xsd \
  -d payments.csv
 

Mode simulation

Utilisez --dry-run pour valider les données d'entrée sans générer de XML. Le code de sortie indique si la validation a réussi (0) ou échoué (1).

pacs008 -t pacs.008.001.13 \
  -m pacs008/templates/pacs.008.001.13/template.xml \
  -s pacs008/templates/pacs.008.001.13/pacs.008.001.13.xsd \
  -d payments.csv \
  --dry-run
 

Ajoutez --verbose pour une sortie détaillée pendant la génération.

---

Python API

Utilisez la bibliothèque directement dans des scripts ou services Python.

Générer du XML à partir d'une liste d'enregistrements de paiement

from pacs008 import generate_xml_string

payments = [{
    "msg_id": "MSG-2026-001",
    "creation_date_time": "2026-01-15T10:30:00",
    "nb_of_txs": "1",
    "settlement_method": "CLRG",
    "interbank_settlement_date": "2026-01-15",
    "end_to_end_id": "E2E-INV-2026-001",
    "tx_id": "TX-001",
    "interbank_settlement_amount": "25000.00",
    "interbank_settlement_currency": "EUR",
    "charge_bearer": "SHAR",
    "debtor_name": "Acme Corp GmbH",
    "debtor_agent_bic": "DEUTDEFF",
    "creditor_agent_bic": "COBADEFF",
    "creditor_name": "Widget Industries SA",
}]

xml = generate_xml_string(
    payments,
    "pacs.008.001.13",
    "pacs008/templates/pacs.008.001.13/template.xml",
    "pacs008/templates/pacs.008.001.13/pacs.008.001.13.xsd",
)
print(xml)
 

Vérification de conformité SWIFT

Valider et nettoyer les données par rapport aux règles de jeu de caractères et de longueur de champ SWIFT avant la génération.

from pacs008.compliance import cleanse_data_with_report

raw = [{"debtor_name": "Müller & Söhne™", "msg_id": "X" * 50}]
clean, report = cleanse_data_with_report(raw)
print(report.summary())
 

---

Docker

Exécutez l'API dans un conteneur à l'aide du Dockerfile fourni.

docker build -t pacs008:latest .
docker run -p 8000:8000 pacs008:latest
 

docker run --rm   -e PACS008_LOG_LEVEL=INFO   -v $PWD/examples:/data   -p 8000:8000 pacs008:latest
 

---

Validation IBAN et BIC

Validez les identifiants financiers indépendamment de la génération XML.

from pacs008.validation import validate_iban, validate_bic

is_valid, error = validate_iban("DE89370400440532013000", strict=False)
is_valid, error = validate_bic("DEUTDEFF", strict=False)
 

---

Traitement par flux

Chargez les grands jeux de données par lots configurables pour limiter l'utilisation mémoire.

from pacs008.data.loader import load_payment_data_streaming

for chunk in load_payment_data_streaming("large_payments.csv", chunk_size=500):
    print(f"Processing {len(chunk)} records")
 

from pacs008.validation import validate_batch

for chunk in load_payment_data_streaming("large_payments.csv", chunk_size=500):
    report = validate_batch(chunk, "pacs.008.001.13")
    print(report.summary())
 

---

Service de validation

Exécutez le pipeline complet de validation pré-génération de manière programmatique.

from pacs008.validation import ValidationService, ValidationConfig

service = ValidationService()
report = service.validate_all(ValidationConfig(
    xml_message_type="pacs.008.001.13",
    xml_template_file_path="pacs008/templates/pacs.008.001.13/template.xml",
    xsd_schema_file_path="pacs008/templates/pacs.008.001.13/pacs.008.001.13.xsd",
    data_file_path="payments.csv",
))
print(report.is_valid, report.errors)
 

---

Champs de données requis

Chaque enregistrement de paiement doit inclure les champs suivants. Les champs spécifiques aux versions sont indiqués le cas échéant.

Champs spécifiques aux versions