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