Pain001

Dokumentacja

Pain001 – dokumentacja techniczna: CLI, API Python i REST

Każda flaga, endpoint i zachowanie pain001 v0.0.71, opisane na podstawie dostarczonego kodu, nie deklaracji.

5 min czytaniaOstatnia weryfikacja

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

Pain001 obsługuje 12 definicji komunikatów ISO 20022: od pain.001.001.03 do pain.001.001.13 (Customer Credit Transfer Initiation, jedenaście 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 13 obsługiwanych definicji komunikatów.
inspect <type> [--json] Pokazuje pola wymagane i opcjonalne dla danego typu komunikatu.
init <type> [-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 22 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 <TYPE> Definicja komunikatu, np. pain.001.001.09.
-d, --data <FILE> Dane wejściowe: .csv, .json, .jsonl, .db / .sqlite, .parquet lub zaszyfrowane PGP .gpg / .asc.
-o, --output-dir <DIR> Katalog, do którego trafia wygenerowany XML.
-m, --template <FILE> / -s, --schema <FILE> Zastępuje dołączony szablon Jinja2 lub schemat XSD.
-c, --config <FILE> 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 <NAME> 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 <N> 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 oznacza sukces, 1 błąd walidacji, 2 błąd użycia.

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.

Flaga Opis
--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. 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:

  1. 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.
  2. Reguły schematu płatności (opcjonalnie): SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B lub reguły transgranicznych poleceń przelewu.
  3. 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.