Pain001 – dokumentacja techniczna: CLI, API Python i REST

Niniejsza dokumentacja opisuje interfejs wiersza poleceń, API Python, mikrousługę REST oraz potok walidacji dla pain001 v0.0.57. Każda wymieniona tu flaga, endpoint i zachowanie pochodzi z dostarczonego kodu, a nie z planów.

Pain001 obsługuje 11 definicji komunikatów ISO 20022: od pain.001.001.03 do pain.001.001.12 (Customer Credit Transfer Initiation, dziesięć wersji) oraz pain.008.001.02 (Customer Direct Debit Initiation).

1. Interfejs wiersza poleceń#

Program pain001 grupuje funkcje w podkomendy. Uruchomienie go wyłącznie z flagami generowania wywołuje niejawnie generate, dzięki czemu istniejąca automatyzacja działa bez zmian.

Podkomenda	Przeznaczenie
`generate`	Konwertuje plik danych na XML ISO 20022 zwalidowany względem schematu (komenda domyślna).
`validate`	Waliduje dane wejściowe bez zapisywania XML.
`versions [--json]`	Wyświetla wszystkie 11 obsługiwanych definicji komunikatów.
`inspect [--json]`	Pokazuje pola wymagane i opcjonalne dla danego typu komunikatu.
`init [-o DIR]`	Tworzy startowy szablon CSV dla typu komunikatu.
`serve [--host] [--port] [--reload]`	Uruchamia mikrousługę REST FastAPI (wymaga dodatku `api`).
`mcp`	Uruchamia wbudowany serwer Model Context Protocol (5 narzędzi; pełny serwer z 17 narzędziami jest dostarczany jako `pain001-mcp`).
`plugins list / show / disable`	Wyświetla wykryte wtyczki (loadery, walidatory, schematy, writery) i zarządza nimi.

Opcje `generate`

Flaga	Opis
`-t, --xml-message-type`	Definicja komunikatu, np. `pain.001.001.09`.
`-d, --data`	Dane wejściowe: `.csv`, `.json`, `.jsonl`, `.db` / `.sqlite`, `.parquet` lub zaszyfrowane PGP `.gpg` / `.asc`.
`-o, --output-dir`	Katalog, do którego trafia wygenerowany XML.
`-m, --template` / `-s, --schema`	Zastępuje dołączony szablon Jinja2 lub schemat XSD.
`-c, --config`	Wczytuje wartości domyślne z profilu konfiguracji (`--profile`, `--show-config`).
`--dry-run` (alias `--validate-only`)	Waliduje dane wejściowe względem JSON Schema, XSD i reguł schematu płatności bez zapisywania wyniku.
`--scheme`	Wymusza reguły schematu płatności: `sepa-sct`, `sepa-inst`, `sepa-sdd`, `sepa-b2b` lub `xborder-ct`.
`--explain --scheme-format {text,json}`	Raportuje każdą regułę schematu — zaliczoną lub nie — w formie czytelnej dla człowieka lub maszyny.
`--streaming` / `--chunk-size`	Przetwarzanie w porcjach o ograniczonym zużyciu pamięci dla dużych partii (domyślnie 1,000 transakcji na porcję; każda porcja staje się osobnym plikiem XML z przeliczonymi `NbOfTxs` i `CtrlSum`).
`--emit-metrics`	Emituje odczytywalne maszynowo metryki uruchomienia dla potoków obserwowalności.

Kody wyjścia są przyjazne dla CI: 0 — sukces, 1 — błąd walidacji, 2 — błąd użycia.

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

Każdy wygenerowany dokument przechodzi przez trzy warstwy, zanim zostanie zapisany:

Walidacja danych wejściowych — każdy rekord jest sprawdzany względem JSON Schema danego typu komunikatu, z normalizacją aliasów pól oraz kontrolą składni IBAN/BIC.
Reguły schematu płatności (opcjonalnie) — SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B lub reguły transgranicznych poleceń przelewu.
Walidacja XSD — wyrenderowany XML jest walidowany względem oficjalnego schematu ISO 20022 za pomocą xmlschema, zanim choć jeden bajt trafi na dysk.

Kwoty pieniężne są przetwarzane jako decimal.Decimal podczas generowania XML i walidacji schematu — nigdy jako liczby zmiennoprzecinkowe IEEE 754 — a sumy kontrolne NbOfTxs / CtrlSum są przeliczane na podstawie zwalidowanych rekordów, a nie przyjmowane z danych wejściowych.

Poza generowaniem pain.001 biblioteka podstawowa zawiera również parser i generator raportów statusu pain.002 (pozwalający odczytać odpowiedź banku o przyjęciu lub odrzuceniu) oraz parser i generator wyciągów camt.053 do uzgodnień na koniec dnia, a także VersionMapper, który migruje rekordy między wersjami komunikatów.

3. Mikrousługa REST#

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

Wszystkie endpointy są zamontowane pod /api/v1 (z niewersjonowanym aliasem /api):

Metoda i ścieżka	Przeznaczenie
`GET /api/v1/health`	Sonda żywotności (liveness).
`POST /api/v1/validate`	Waliduje rekordy; zwraca błędy na poziomie pól.
`POST /api/v1/generate`	Synchroniczne generowanie XML.
`POST /api/v1/generate/async`	Kolejkuje dużą partię do generowania w tle.
`GET /api/v1/status/{job_id}`	Sprawdza stan zadania asynchronicznego.
`GET /api/v1/download/{job_id}`	Pobiera gotowy XML.
`DELETE /api/v1/jobs/{job_id}`	Usuwa zakończone zadanie.
`GET /metrics`	Metryki Prometheus.

Interaktywna dokumentacja jest dostępna pod /api/docs (Swagger UI), /api/redoc i /api/reference (Scalar), a dokument OpenAPI pod /openapi.json.

4. Normalizacja danych wejściowych#

Pain001 przekształca rzeczywiste eksporty w poprawne rekordy jeszcze przed walidacją:

Aliasy pól — typowe nazwy kolumn z systemów ERP są mapowane na pola kanoniczne (na przykład amount → payment_amount).
Normalizacja IBAN / BIC — usunięcie spacji, ujednolicenie wielkości liter, a następnie kontrola (mod-97 wg ISO 13616 dla IBAN, struktura wg ISO 9362 dla BIC).
Daty — parsowanie dat wykonania w formacie ISO 8601 YYYY-MM-DD.
Kwoty — przetwarzane przez decimal.Decimal; zniekształcone kwoty nie przechodzą walidacji, zamiast być po cichu zaokrąglane.
Zestaw znaków — funkcje transliteracji sprowadzają treść do łacińskiego zestawu znaków ISO 20022 akceptowanego przez SWIFT i SEPA.

5. Architektura wtyczek#

Pakiet można rozszerzać poprzez cztery grupy punktów wejścia: pain001.loaders, pain001.validators, pain001.schemes i pain001.writers. pain001-loader-xlsx rejestruje się przez ten mechanizm i jest wykrywany automatycznie po instalacji; pain001-loader-mt101 to samodzielna biblioteka parsująca używana bezpośrednio (oraz przez narzędzie convert_mt101 serwera MCP). Wyłącznik awaryjny — PAIN001_DISABLE_PLUGINS=1 — całkowicie wyłącza wykrywanie wtyczek zewnętrznych w środowiskach o zaostrzonych restrykcjach.

6. Bramki jakości#

Biblioteka podstawowa jest rozwijana według ścisłych, weryfikowalnych bramek: 100% pokrycia linii i gałęzi wymuszane w CI (--cov-fail-under=100), ścisłe typowanie mypy, 100% pokrycia docstringów oraz linting bezpieczeństwa (Bandit, pip-audit). Dla każdej kompilacji wydania generowany jest SBOM w formacie CycloneDX.

Dalsze materiały: przewodnik instalacji, serwer MCP dla agentów AI oraz słownik płatności.