Pain001 तकनीकी संदर्भ: CLI, Python API और REST

यह संदर्भ pain001 v0.0.71 के कमांड-लाइन इंटरफ़ेस, Python API, REST माइक्रोसर्विस और सत्यापन पाइपलाइन का दस्तावेज़ीकरण है। यहाँ सूचीबद्ध हर फ़्लैग, एंडपॉइंट और व्यवहार शिप किए गए कोड से लिया गया है, आकांक्षा से नहीं।

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 विकल्प

एग्ज़िट कोड 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.

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 डिस्क पर एक भी बाइट लिखे जाने से पहले 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 उपनाम के साथ):

इंटरैक्टिव दस्तावेज़ीकरण /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 सर्वर, या भुगतान शब्दावली के साथ आगे बढ़ें।