Pain001

संदर्भ

Pain001 तांत्रिक संदर्भ: CLI, Python API व REST

pain001 v0.0.71 चा प्रत्येक फ्लॅग, एंडपॉइंट आणि वर्तन, प्रत्यक्ष शिप केलेल्या कोडमधून घेतलेले, आकांक्षेतून नव्हे.

5 मिनिटे वाचनशेवटची तपासणी

हा संदर्भ 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 डेटा फाइलचे स्कीमा-प्रमाणित ISO 20022 XML मध्ये रूपांतर करते (डीफॉल्ट आदेश).
validate XML न लिहिता इनपुट डेटा प्रमाणित करते.
versions [--json] समर्थित सर्व 13 संदेश व्याख्या सूचीबद्ध करते.
inspect <type> [--json] संदेश प्रकारासाठी आवश्यक व पर्यायी फील्ड दर्शवते.
init <type> [-o DIR] संदेश प्रकारासाठी प्रारंभिक CSV टेम्पलेट तयार करते.
serve [--host] [--port] [--reload] FastAPI REST मायक्रोसर्व्हिस सुरू करते (api एक्स्ट्रा आवश्यक).
mcp अंतर्भूत Model Context Protocol सर्व्हर सुरू करते (5 साधने; संपूर्ण 22-साधनी सर्व्हर pain001-mcp म्हणून उपलब्ध आहे).
plugins list / show / disable शोधलेले लोडर, व्हॅलिडेटर, स्कीम आणि रायटर प्लगइन तपासते व व्यवस्थापित करते.

generate पर्याय

फ्लॅग वर्णन
-t, --xml-message-type <TYPE> संदेश व्याख्या, उदा. pain.001.001.09.
-d, --data <FILE> इनपुट डेटा: .csv, .json, .jsonl, .db / .sqlite, .parquet, किंवा PGP-एन्क्रिप्टेड .gpg / .asc.
-o, --output-dir <DIR> तयार झालेले XML जिथे साठवले जाते ती डिरेक्टरी.
-m, --template <FILE> / -s, --schema <FILE> अंतर्भूत Jinja2 टेम्पलेट किंवा XSD स्कीमा अधिक्रमित करते.
-c, --config <FILE> कॉन्फिगरेशन प्रोफाइलमधून डीफॉल्ट मूल्ये लोड करते (--profile, --show-config).
--dry-run (उपनाव --validate-only) आउटपुट न लिहिता इनपुट JSON Schema, XSD आणि स्कीम नियमपुस्तिकेविरुद्ध प्रमाणित करते.
--scheme <NAME> स्कीम नियमपुस्तिका लागू करते: sepa-sct, sepa-inst, sepa-sdd, sepa-b2b, किंवा xborder-ct.
--explain --scheme-format {text,json} उत्तीर्ण किंवा अनुत्तीर्ण झालेला प्रत्येक स्कीम नियम मानव- किंवा यंत्र-वाचनीय स्वरूपात नोंदवते.
--streaming / --chunk-size <N> मोठ्या बॅचसाठी स्मृती-मर्यादित तुकड्यांमध्ये प्रक्रिया (डीफॉल्ट प्रति तुकडा 1,000 व्यवहार; प्रत्येक तुकडा पुन्हा मोजलेल्या NbOfTxs व CtrlSum सह स्वतंत्र XML फाइल बनतो).
--emit-metrics ऑब्झर्व्हेबिलिटी पाइपलाइनसाठी यंत्र-वाचनीय रन मेट्रिक्स उत्सर्जित करते.

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

फ्लॅग वर्णन
--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",
)

तयार होणारा प्रत्येक दस्तऐवज लिहिला जाण्यापूर्वी तीन स्तरांतून जातो:

  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 उपनावासह):

मेथड व पथ उद्देश
GET /api/v1/health लाइव्हनेस प्रोब.
POST /api/v1/validate नोंदी प्रमाणित करते; फील्ड-स्तरीय त्रुटी परत करते.
POST /api/v1/generate समकालिक XML निर्मिती.
POST /api/v1/generate/async पार्श्वभूमीवरील निर्मितीसाठी मोठी बॅच रांगेत ठेवते.
GET /api/v1/status/{job_id} असिंक्रोनस जॉबची स्थिती तपासते.
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% डॉकस्ट्रिंग कव्हरेज आणि सुरक्षा लिंटिंग (Bandit, pip-audit). प्रत्येक रिलीज बिल्डसाठी CycloneDX SBOM तयार केला जातो.

पुढे इन्स्टॉलेशन मार्गदर्शक, AI एजंटसाठीचा MCP सर्व्हर किंवा पेमेंट्स शब्दकोश पाहा.