Pain001: технический справочник CLI, Python API и REST

Этот справочник описывает интерфейс командной строки, Python API, REST-микросервис и конвейер валидации для pain001 v0.0.57. Каждый флаг, эндпоинт и поведение, перечисленные здесь, взяты из выпущенного кода, а не из планов.

Pain001 поддерживает 11 определений сообщений ISO 20022: от pain.001.001.03 до pain.001.001.12 (Customer Credit Transfer Initiation, десять версий) и pain.008.001.02 (Customer Direct Debit Initiation).

1. Интерфейс командной строки#

Исполняемый файл pain001 группирует функциональность по подкомандам. Запуск только с флагами генерации неявно вызывает generate, поэтому существующая автоматизация продолжает работать.

Подкоманда	Назначение
`generate`	Преобразует файл данных в проверенный по схеме XML ISO 20022 (команда по умолчанию).
`validate`	Проверяет входные данные без записи XML.
`versions [--json]`	Выводит все 11 поддерживаемых определений сообщений.
`inspect [--json]`	Показывает обязательные и необязательные поля для типа сообщения.
`init [-o DIR]`	Создаёт стартовый CSV-шаблон для типа сообщения.
`serve [--host] [--port] [--reload]`	Запускает REST-микросервис на FastAPI (требуется экстра `api`).
`mcp`	Запускает встроенный сервер Model Context Protocol (5 инструментов; полный сервер с 17 инструментами поставляется как `pain001-mcp`).
`plugins list / show / disable`	Просмотр и управление обнаруженными плагинами загрузчиков, валидаторов, схем и записи.

Опции `generate`

Флаг	Описание
`-t, --xml-message-type`	Определение сообщения, например `pain.001.001.09`.
`-d, --data`	Входные данные: `.csv`, `.json`, `.jsonl`, `.db` / `.sqlite`, `.parquet` или зашифрованные PGP `.gpg` / `.asc`.
`-o, --output-dir`	Каталог, в который записывается сгенерированный XML.
`-m, --template` / `-s, --schema`	Переопределяет встроенный шаблон Jinja2 или XSD-схему.
`-c, --config`	Загружает значения по умолчанию из профиля конфигурации (`--profile`, `--show-config`).
`--dry-run` (псевдоним `--validate-only`)	Проверяет входные данные по JSON Schema, XSD и своду правил схемы без записи результата.
`--scheme`	Применяет свод правил схемы: `sepa-sct`, `sepa-inst`, `sepa-sdd`, `sepa-b2b` или `xborder-ct`.
`--explain --scheme-format {text,json}`	Сообщает о каждом правиле схемы — пройдено или нет — в человеко- или машиночитаемом виде.
`--streaming` / `--chunk-size`	Обработка больших пакетов блоками с ограничением памяти (по умолчанию 1,000 транзакций на блок; каждый блок становится отдельным XML-файлом с пересчитанными `NbOfTxs` и `CtrlSum`).
`--emit-metrics`	Выводит машиночитаемые метрики выполнения для конвейеров наблюдаемости.

Коды выхода удобны для CI: 0 — успех, 1 — ошибка валидации, 2 — ошибка использования.

2. Python API#

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

Каждый сгенерированный документ проходит три уровня, прежде чем будет записан:

Валидация входных данных — каждая запись проверяется по JSON Schema типа сообщения, с нормализацией псевдонимов полей и синтаксическими проверками IBAN/BIC.
Свод правил схемы (опционально) — правила SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B или трансграничных кредитовых переводов.
Валидация по XSD — сформированный XML проверяется по официальной схеме ISO 20022 через xmlschema, прежде чем на диск будет записан хоть один байт.

Денежные суммы обрабатываются как decimal.Decimal при генерации XML и проверке правил схемы — никогда как числа IEEE 754 с плавающей запятой — а контрольные итоги NbOfTxs / CtrlSum пересчитываются из проверенных записей, а не берутся на веру из входных данных.

Помимо генерации pain.001, базовая библиотека включает парсер и генератор отчётов о статусе pain.002 (чтобы читать ответ банка о приёме или отклонении) и парсер и генератор выписок camt.053 для сверки на конец дня, а также VersionMapper, переносящий записи между версиями сообщений.

3. REST-микросервис#

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

Все эндпоинты смонтированы под /api/v1 (с алиасом /api без версии):

Метод и путь	Назначение
`GET /api/v1/health`	Проверка живости.
`POST /api/v1/validate`	Проверяет записи; возвращает ошибки на уровне полей.
`POST /api/v1/generate`	Синхронная генерация XML.
`POST /api/v1/generate/async`	Ставит крупный пакет в очередь на фоновую генерацию.
`GET /api/v1/status/{job_id}`	Опрос асинхронного задания.
`GET /api/v1/download/{job_id}`	Скачивание готового XML.
`DELETE /api/v1/jobs/{job_id}`	Удаление завершённого задания.
`GET /metrics`	Метрики Prometheus.

Интерактивная документация доступна по адресам /api/docs (Swagger UI), /api/redoc и /api/reference (Scalar); документ OpenAPI — по адресу /openapi.json.

4. Нормализация входных данных#

Pain001 приводит реальные выгрузки к валидным записям до валидации:

Псевдонимы полей — распространённые имена столбцов ERP отображаются на канонические поля (например, amount → payment_amount).
Нормализация IBAN / BIC — пробелы удаляются, регистр приводится к единому, затем выполняется проверка (mod-97 по ISO 13616 для IBAN, структура ISO 9362 для BIC).
Даты — разбор дат исполнения в формате ISO 8601 YYYY-MM-DD.
Суммы — проходят через decimal.Decimal; некорректные суммы не проходят валидацию вместо тихого округления.
Набор символов — помощники транслитерации приводят содержимое к латинскому набору символов ISO 20022, принимаемому SWIFT и SEPA.

5. Архитектура плагинов#

Набор расширяется через четыре группы точек входа: pain001.loaders, pain001.validators, pain001.schemes и pain001.writers. pain001-loader-xlsx регистрируется через этот механизм и автоматически обнаруживается при установке; pain001-loader-mt101 — самостоятельная библиотека разбора, используемая напрямую (и инструментом convert_mt101 сервера MCP). Аварийный выключатель — PAIN001_DISABLE_PLUGINS=1 — полностью отключает обнаружение сторонних плагинов в изолированных средах.

6. Контроль качества#

Базовая библиотека разрабатывается под строгими проверяемыми контрольными точками: 100% покрытие строк и ветвей, обязательное в CI (--cov-fail-under=100), строгая типизация mypy, 100% покрытие docstring и линтинг безопасности (Bandit, pip-audit). Для каждой релизной сборки генерируется CycloneDX SBOM.

Продолжите с руководством по установке, сервером MCP для AI-агентов или глоссарием платежей.