यह संदर्भ pain001 v0.0.57 के कमांड-लाइन इंटरफ़ेस, Python API, REST माइक्रोसर्विस और सत्यापन पाइपलाइन का दस्तावेज़ीकरण है। यहाँ सूचीबद्ध हर फ़्लैग, एंडपॉइंट और व्यवहार शिप किए गए कोड से लिया गया है, आकांक्षा से नहीं।
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 |
डेटा फ़ाइल को स्कीमा-सत्यापित ISO 20022 XML में बदलें (डिफ़ॉल्ट कमांड)। |
validate |
XML लिखे बिना इनपुट डेटा सत्यापित करें। |
versions [--json] |
सभी 11 समर्थित संदेश परिभाषाएँ सूचीबद्ध करें। |
inspect |
किसी संदेश प्रकार के अनिवार्य और वैकल्पिक फ़ील्ड दिखाएँ। |
init |
किसी संदेश प्रकार के लिए स्टार्टर CSV टेम्पलेट तैयार करें। |
serve [--host] [--port] [--reload] |
FastAPI REST माइक्रोसर्विस शुरू करें (api एक्स्ट्रा आवश्यक)। |
mcp |
इन-ट्री Model Context Protocol सर्वर शुरू करें (5 टूल; पूर्ण 17-टूल सर्वर pain001-mcp के रूप में उपलब्ध है)। |
plugins list / show / disable |
खोजे गए loader, validator, scheme और writer प्लगइन का निरीक्षण और प्रबंधन करें। |
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 लेनदेन प्रति चंक; हर चंक पुनर्गणित NbOfTxs और CtrlSum के साथ अपनी अलग XML फ़ाइल बनता है)। |
--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 डिस्क पर एक भी बाइट लिखे जाने से पहले
xmlschemaके ज़रिए आधिकारिक ISO 20022 स्कीमा के विरुद्ध सत्यापित होता है।
XML जनरेशन और स्कीम सत्यापन के दौरान मौद्रिक राशियाँ decimal.Decimal के रूप में संभाली जाती हैं — कभी भी 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} |
async जॉब की स्थिति पोल करें। |
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 सामान्यीकरण — रिक्त स्थान हटाए जाते हैं, केस समान किया जाता है, फिर जाँच होती है (IBAN के लिए ISO 13616 mod-97, BIC के लिए ISO 9362 संरचना)।
- दिनांक — निष्पादन तिथियों के लिए ISO 8601
YYYY-MM-DDपार्सिंग। - राशियाँ —
decimal.Decimalसे होकर गुज़रती हैं; विकृत राशियाँ चुपचाप पूर्णांकित होने के बजाय सत्यापन में विफल होती हैं। - वर्ण समूह — लिप्यंतरण सहायक सामग्री को SWIFT और SEPA द्वारा स्वीकृत ISO 20022 लैटिन वर्ण समूह तक सीमित करते हैं।
5. प्लगइन आर्किटेक्चर#
यह सुइट चार एंट्री-पॉइंट समूहों के माध्यम से विस्तार-योग्य है: pain001.loaders, pain001.validators, pain001.schemes और pain001.writers। pain001-loader-xlsx इसी तंत्र से पंजीकृत होता है और इंस्टॉल पर स्वतः खोजा जाता है; pain001-loader-mt101 एक स्वतंत्र पार्सिंग लाइब्रेरी है जिसका सीधे उपयोग होता है (और MCP सर्वर के convert_mt101 टूल द्वारा)। एक किल स्विच — PAIN001_DISABLE_PLUGINS=1 — लॉक-डाउन वातावरणों में तृतीय-पक्ष प्लगइन खोज को पूरी तरह अक्षम कर देता है।
6. गुणवत्ता गेट#
कोर लाइब्रेरी सख़्त, सत्यापन-योग्य गेट के विरुद्ध विकसित की जाती है: CI में लागू 100% लाइन और ब्रांच कवरेज (--cov-fail-under=100), सख़्त mypy टाइपिंग, 100% docstring कवरेज, और सुरक्षा लिंटिंग (Bandit, pip-audit)। हर रिलीज़ बिल्ड के लिए एक CycloneDX SBOM जनरेट किया जाता है।
इंस्टॉलेशन गाइड, AI एजेंटों के लिए MCP सर्वर, या भुगतान शब्दावली के साथ आगे बढ़ें।