Pain001 Teknik Referans: CLI, Python API ve REST

Bu referans, pain001 v0.0.71 için komut satırı arayüzünü, Python API'sini, REST mikroservisini ve doğrulama hattını belgeler. Burada listelenen her bayrak, uç nokta ve davranış hedeflerden değil, yayımlanan koddan alınmıştır.

Pain001, 12 ISO 20022 mesaj tanımını destekler: pain.001.001.03'ten pain.001.001.13'e kadar (Customer Credit Transfer Initiation, on bir sürüm) ve pain.008.001.02 (Customer Direct Debit Initiation).

1. Komut Satırı Arayüzü#

pain001 çalıştırılabilir dosyası işlevselliğini alt komutlar halinde gruplar. Yalnızca üretim bayraklarıyla çalıştırıldığında generate örtük olarak çağrılır; böylece mevcut otomasyonlar çalışmaya devam eder.

Alt komut	Amaç
`generate`	Bir veri dosyasını şema doğrulamalı ISO 20022 XML'e dönüştürür (varsayılan komut).
`validate`	XML yazmadan girdi verilerini doğrular.
`versions [--json]`	Desteklenen 13 mesaj tanımının tamamını listeler.
`inspect <type> [--json]`	Bir mesaj türü için zorunlu ve isteğe bağlı alanları gösterir.
`init <type> [-o DIR]`	Bir mesaj türü için başlangıç CSV şablonu oluşturur.
`serve [--host] [--port] [--reload]`	FastAPI REST mikroservisini başlatır (`api` ekstrasını gerektirir).
`mcp`	Ağaç içi Model Context Protocol sunucusunu başlatır (5 araç; 22 araçlı tam sunucu `pain001-mcp` olarak yayımlanır).
`plugins list / show / disable`	Keşfedilen yükleyici, doğrulayıcı, şema ve yazıcı eklentilerini inceler ve yönetir.

`generate` seçenekleri

Bayrak	Açıklama
`-t, --xml-message-type <TYPE>`	Mesaj tanımı, örn. `pain.001.001.09`.
`-d, --data <FILE>`	Girdi verisi: `.csv`, `.json`, `.jsonl`, `.db` / `.sqlite`, `.parquet` veya PGP ile şifrelenmiş `.gpg` / `.asc`.
`-o, --output-dir <DIR>`	Üretilen XML'in yazıldığı dizin.
`-m, --template <FILE>` / `-s, --schema <FILE>`	Paketle gelen Jinja2 şablonunu veya XSD şemasını geçersiz kılar.
`-c, --config <FILE>`	Varsayılanları bir yapılandırma profilinden yükler (`--profile`, `--show-config`).
`--dry-run` (takma ad: `--validate-only`)	Çıktı yazmadan girdiyi JSON Schema'ya, XSD'ye ve şema kural kitabına göre doğrular.
`--scheme <NAME>`	Bir şema kural kitabı uygular: `sepa-sct`, `sepa-inst`, `sepa-sdd`, `sepa-b2b` veya `xborder-ct`.
`--explain --scheme-format {text,json}`	Geçen veya başarısız olan her şema kuralını insan veya makine tarafından okunabilir biçimde raporlar.
`--streaming` / `--chunk-size <N>`	Büyük partiler için bellek sınırlı parçalı işleme (varsayılan olarak parça başına 1,000 işlem; her parça, yeniden hesaplanan `NbOfTxs` ve `CtrlSum` değerleriyle kendi XML dosyası olur).
`--emit-metrics`	Gözlemlenebilirlik hatları için makine tarafından okunabilir çalışma metrikleri üretir.

Çıkış kodları CI dostudur: 0 başarı, 1 doğrulama hatası, 2 kullanım hatası.

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.

Bayrak	Açıklama
`--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",
)

Üretilen her belge, yazılmadan önce üç katmandan geçer:

Girdi doğrulama: her kayıt, alan takma adı normalizasyonu ve IBAN/BIC sözdizimi denetimleriyle birlikte mesaj türünün JSON Schema'sına göre denetlenir.
Şema kural kitabı (isteğe bağlı): SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B veya sınır ötesi havale kuralları.
XSD doğrulaması: üretilen XML, diske tek bir bayt yazılmadan önce xmlschema aracılığıyla resmi ISO 20022 şemasına göre doğrulanır.

Parasal tutarlar, XML üretimi ve şema doğrulaması sırasında decimal.Decimal olarak işlenir (asla IEEE 754 kayan noktalı sayılar olarak değil) ve NbOfTxs / CtrlSum kontrol toplamları girdiden alınmak yerine doğrulanmış kayıtlardan yeniden hesaplanır.

Çekirdek kütüphane, pain.001 üretiminin ötesinde bir pain.002 durum raporu ayrıştırıcısı ve üreticisi (böylece bankanın kabul/ret yanıtını okuyabilirsiniz) ve gün sonu mutabakatı için bir camt.053 hesap özeti ayrıştırıcısı ve üreticisi ile kayıtları mesaj sürümleri arasında taşıyan bir VersionMapper içerir.

3. REST Mikroservisi#

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

Tüm uç noktalar /api/v1 altında sunulur (sürümsüz /api takma adıyla birlikte):

Yöntem & Yol	Amaç
`GET /api/v1/health`	Canlılık denetimi.
`POST /api/v1/validate`	Kayıtları doğrular; alan düzeyinde hatalar döndürür.
`POST /api/v1/generate`	Eşzamanlı XML üretimi.
`POST /api/v1/generate/async`	Büyük bir partiyi arka planda üretim için kuyruğa alır.
`GET /api/v1/status/{job_id}`	Eşzamansız bir işi sorgular.
`GET /api/v1/download/{job_id}`	Tamamlanan XML'i indirir.
`DELETE /api/v1/jobs/{job_id}`	Tamamlanmış bir işi temizler.
`GET /metrics`	Prometheus metrikleri.

Etkileşimli dokümantasyon /api/docs (Swagger UI), /api/redoc ve /api/reference (Scalar) adreslerinde, OpenAPI belgesi ise /openapi.json adresinde sunulur.

4. Girdi Normalizasyonu#

Pain001, gerçek dünyadaki dışa aktarımları doğrulamadan önce geçerli kayıtlara dönüştürür:

Alan takma adları: yaygın ERP sütun adları kanonik alanlara eşlenir (örneğin amount → payment_amount).
IBAN / BIC normalizasyonu: boşluklar kaldırılır, harf büyüklüğü normalleştirilir, ardından denetlenir (IBAN'lar için ISO 13616 mod-97, BIC'ler için ISO 9362 yapısı).
Tarihler: yürütme tarihleri için ISO 8601 YYYY-MM-DD ayrıştırması.
Tutarlar: decimal.Decimal üzerinden yönlendirilir; hatalı biçimli tutarlar sessizce yuvarlanmak yerine doğrulamada başarısız olur.
Karakter kümesi: harf çevirisi yardımcıları, içeriği SWIFT ve SEPA tarafından kabul edilen ISO 20022 Latin karakter kümesine indirger.

5. Eklenti Mimarisi#

Paket, dört giriş noktası grubu aracılığıyla genişletilebilir: pain001.loaders, pain001.validators, pain001.schemes ve pain001.writers. pain001-loader-xlsx bu mekanizma üzerinden kaydolur ve kurulumda otomatik keşfedilir; pain001-loader-mt101 doğrudan (ve MCP sunucusunun convert_mt101 aracı tarafından) kullanılan bağımsız bir ayrıştırma kütüphanesidir. Bir kapatma anahtarı (PAIN001_DISABLE_PLUGINS=1), kilitli ortamlarda üçüncü taraf eklenti keşfini tamamen devre dışı bırakır.

6. Kalite Kapıları#

Çekirdek kütüphane katı, doğrulanabilir kapılarla geliştirilir: CI'da zorunlu tutulan %100 satır ve dal kapsamı (--cov-fail-under=100), katı mypy tiplemesi, %100 docstring kapsamı ve güvenlik denetimi (Bandit, pip-audit). Her sürüm derlemesi için bir CycloneDX SBOM üretilir.

Devamında Kurulum Kılavuzu, AI ajanları için MCP sunucusu veya ödeme sözlüğü ile ilerleyin.