Pain001: referencia técnica de CLI, API de Python y REST

Esta referencia documenta la interfaz de línea de comandos, la API de Python, el microservicio REST y el pipeline de validación de pain001 v0.0.57. Cada opción, endpoint y comportamiento aquí listado está tomado del código publicado, no de aspiraciones.

Pain001 admite 11 definiciones de mensaje ISO 20022: de pain.001.001.03 a pain.001.001.12 (Customer Credit Transfer Initiation, diez versiones) y pain.008.001.02 (Customer Direct Debit Initiation).

1. Interfaz de línea de comandos#

El ejecutable pain001 agrupa su funcionalidad en subcomandos. Si se ejecuta solo con opciones de generación, invoca generate implícitamente, de modo que la automatización existente sigue funcionando.

Subcomando	Propósito
`generate`	Convierte un archivo de datos en XML ISO 20022 validado contra esquema (comando por defecto).
`validate`	Valida los datos de entrada sin escribir XML.
`versions [--json]`	Lista las 11 definiciones de mensaje admitidas.
`inspect [--json]`	Muestra los campos obligatorios y opcionales de un tipo de mensaje.
`init [-o DIR]`	Genera una plantilla CSV inicial para un tipo de mensaje.
`serve [--host] [--port] [--reload]`	Inicia el microservicio REST de FastAPI (requiere el extra `api`).
`mcp`	Inicia el servidor Model Context Protocol integrado (5 herramientas; el servidor completo de 17 herramientas se distribuye como `pain001-mcp`).
`plugins list / show / disable`	Inspecciona y gestiona los plugins detectados de tipo loader, validador, esquema y writer.

Opciones de `generate`

Opción	Descripción
`-t, --xml-message-type`	Definición de mensaje, p. ej. `pain.001.001.09`.
`-d, --data`	Datos de entrada: `.csv`, `.json`, `.jsonl`, `.db` / `.sqlite`, `.parquet`, o `.gpg` / `.asc` cifrados con PGP.
`-o, --output-dir`	Directorio que recibe el XML generado.
`-m, --template` / `-s, --schema`	Sustituye la plantilla Jinja2 o el esquema XSD incluidos.
`-c, --config`	Carga valores por defecto desde un perfil de configuración (`--profile`, `--show-config`).
`--dry-run` (alias `--validate-only`)	Valida la entrada contra el JSON Schema, el XSD y el reglamento del esquema sin escribir salida.
`--scheme`	Aplica un reglamento de esquema: `sepa-sct`, `sepa-inst`, `sepa-sdd`, `sepa-b2b` o `xborder-ct`.
`--explain --scheme-format {text,json}`	Informa de cada regla del esquema superada o incumplida, en formato legible por humanos o por máquinas.
`--streaming` / `--chunk-size`	Procesamiento por bloques con memoria acotada para lotes grandes (por defecto 1,000 transacciones por bloque; cada bloque se convierte en su propio archivo XML con `NbOfTxs` y `CtrlSum` recalculados).
`--emit-metrics`	Emite métricas de ejecución legibles por máquinas para pipelines de observabilidad.

Los códigos de salida son aptos para CI: 0 éxito, 1 fallo de validación, 2 error de uso.

2. API de 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",
)

Cada documento generado atraviesa tres capas antes de escribirse:

Validación de entradas — cada registro se comprueba contra el JSON Schema del tipo de mensaje, con normalización de alias de campos y comprobaciones sintácticas de IBAN/BIC.
Reglamento del esquema (opcional) — reglas de SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B o transferencia transfronteriza.
Validación XSD — el XML renderizado se valida contra el esquema ISO 20022 oficial mediante xmlschema antes de que un solo byte se escriba en disco.

Los importes monetarios se manejan como decimal.Decimal durante la generación del XML y la validación del esquema — nunca como flotantes IEEE 754 — y los totales de control NbOfTxs / CtrlSum se recalculan a partir de los registros validados en lugar de confiarse a la entrada.

Más allá de la generación de pain.001, la biblioteca principal también incluye un analizador y generador de informes de estado pain.002 (para leer la respuesta de aceptación o rechazo del banco) y un analizador y generador de extractos camt.053 para la conciliación de fin de día, además de un VersionMapper que migra registros entre versiones de mensaje.

3. Microservicio REST#

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

Todos los endpoints están montados bajo /api/v1 (con un alias sin versión /api):

Método y ruta	Propósito
`GET /api/v1/health`	Sonda de actividad (liveness).
`POST /api/v1/validate`	Valida registros; devuelve errores a nivel de campo.
`POST /api/v1/generate`	Generación de XML síncrona.
`POST /api/v1/generate/async`	Encola un lote grande para su generación en segundo plano.
`GET /api/v1/status/{job_id}`	Consulta el estado de un trabajo asíncrono.
`GET /api/v1/download/{job_id}`	Descarga el XML terminado.
`DELETE /api/v1/jobs/{job_id}`	Limpia un trabajo completado.
`GET /metrics`	Métricas de Prometheus.

La documentación interactiva se sirve en /api/docs (Swagger UI), /api/redoc y /api/reference (Scalar), con el documento OpenAPI en /openapi.json.

4. Normalización de entradas#

Pain001 convierte las exportaciones del mundo real en registros válidos antes de la validación:

Alias de campos — los nombres de columna habituales de los ERP se asignan a campos canónicos (por ejemplo amount → payment_amount).
Normalización de IBAN / BIC — se eliminan los espacios, se normaliza la caja y luego se comprueba (mod-97 de ISO 13616 para los IBAN, estructura ISO 9362 para los BIC).
Fechas — análisis ISO 8601 YYYY-MM-DD para las fechas de ejecución.
Importes — canalizados a través de decimal.Decimal; los importes mal formados fallan la validación en lugar de redondearse silenciosamente.
Juego de caracteres — utilidades de transliteración reducen el contenido al juego de caracteres latino de ISO 20022 aceptado por SWIFT y SEPA.

5. Arquitectura de plugins#

La suite es extensible mediante cuatro grupos de puntos de entrada: pain001.loaders, pain001.validators, pain001.schemes y pain001.writers. pain001-loader-xlsx se registra por este mecanismo y se detecta automáticamente al instalarse; pain001-loader-mt101 es una biblioteca de análisis independiente que se consume directamente (y por la herramienta convert_mt101 del servidor MCP). Un interruptor de emergencia — PAIN001_DISABLE_PLUGINS=1 — desactiva por completo la detección de plugins de terceros en entornos restringidos.

6. Controles de calidad#

La biblioteca principal se desarrolla contra controles estrictos y verificables: cobertura de líneas y de ramas al 100% exigida en CI (--cov-fail-under=100), tipado mypy estricto, cobertura de docstrings al 100% y análisis de seguridad (Bandit, pip-audit). Se genera un SBOM CycloneDX para cada build de release.

Continúe con la guía de instalación, el servidor MCP para agentes de IA o el glosario de pagos.