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 সার্ভার, অথবা পেমেন্ট শব্দকোষ।