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

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

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

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

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

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

Опции `generate`

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

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

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.

Флаг	Описание
`--envelop-bah`	Wrap generated payment XML into an ISO 20022 Business Application Header (`head.001.001.03`) and `BizData` (`head.003.001.01`) envelope.
`--bah-sender <BIC/ID>`	Sender financial institution BIC or organisation identifier for BAH `<Fr>`.
`--bah-receiver <BIC/ID>`	Receiver financial institution BIC or organisation identifier for BAH `<To>`.
`--bah-msg-id <ID>`	Business Message Identifier for BAH `<BizMsgIdr>` (defaults to generated UUID).
`--xml-sign-key <FILE>`	PEM RSA private key for W3C XML Digital Signature (XML-DSig RSA-SHA256).
`--xml-sign-cert <FILE>`	Optional PEM X.509 certificate to embed in XML-DSig `<ds:KeyInfo>`.
`--xml-sign-passphrase-env <VAR>`	Environment variable holding passphrase to decrypt the RSA private key.

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. 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-агентов или глоссарием платежей.