Pain001

Довідник

Pain001: технічний довідник CLI, Python API та REST

Кожен прапорець, ендпоінт і поведінка pain001 v0.0.71, узяті з випущеного коду, а не з планів.

5 хв читанняОстання перевірка

Цей довідник описує інтерфейс командного рядка, 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",
)

Кожен згенерований документ проходить три рівні, перш ніж буде записаний:

  1. Валідація вхідних даних: кожен запис перевіряється за JSON Schema типу повідомлення, з нормалізацією псевдонімів полів і синтаксичними перевірками IBAN/BIC.
  2. Збірник правил схеми (опційно): правила SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B або транскордонних кредитових переказів.
  3. Валідація за 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-агентів або глосарієм платежів.