پیغام رسانی کی رجسٹریشن کے کیٹلاگ لوڈ کریں

رجسٹریشن فارم بنانے سے پہلے اختیارات لوڈ کریں

رجسٹری کی قدریں کوڈ میں مستقل طور پر درج کرنے کے بجائے، اختیارات پُر کرنے کے لیے پیغام رسانی کی رجسٹریشن کا موجودہ کیٹلاگ استعمال کریں۔ برانڈ فارم کے لیے پورٹل کاروبار کی قسم، صنعت، متبادل کاروباری شناخت کنندہ کی قسم، برانڈ سے تعلق، ملک، امریکی ریاست اور اسٹاک ایکسچینج کے کیٹلاگ لوڈ کرتا ہے۔ مہم کے فارم کے لیے یہ استعمال کی صورتیں، درست ذیلی صورتیں اور رابطہ فراہم کرنے والے شراکت دار لوڈ کرتا ہے۔ واپس ملنے والی ہر مشینی قدر کو اس کے نمائشی لیبل کے ساتھ محفوظ رکھیں؛ بعد میں درخواست بناتے وقت ترجمہ شدہ لیبل کے بجائے اصل قدر استعمال کریں۔

کیٹلاگ منتخب کریں

TCR کے جواب کو براہ راست سنبھالیں

جواب کا متن براہ راست TCR کے API سے آتا ہے۔ بہت سے پرانے /v3 اینڈ پوائنٹس کے برعکس، اس میں اضافی status/response غلاف شامل نہیں ہوتا۔ اس کی تشریح سے پہلے HTTP کی حیثیت دیکھیں۔ کیٹلاگ میں سٹرنگ لیبل یا ساخت یافتہ تعریفیں ہو سکتی ہیں، اس لیے یہ فرض نہ کریں کہ ہر قدر میں ایک جیسے خانے ہوں گے۔ اگر HTTP درخواست کامیاب ہو جائے لیکن جواب کا متن متوقع ساخت کے مطابق درست JSON نہ ہو تو اسے خاموشی سے خالی فہرست سے بدلنے کے بجائے معلومات حاصل کرنے میں ناکامی کی اطلاع دیں۔

کیٹلاگ کے اختیارات کو اہلیت اور قیمتوں سے الگ رکھیں

استعمال کی صورتوں کا عمومی کیٹلاگ یہ نہیں بتاتا کہ کوئی مخصوص برانڈ کن صورتوں کے لیے اہل ہے۔ موجودہ پورٹل مہم بنانے سے پہلے برانڈ کی مخصوص اہلیت معلوم کرتا ہے اور منتخب نیٹ ورک آپریٹر کی ضروریات جانچتا ہے۔ اسی طرح، سپلائر کی فیس سے متعلق میٹا ڈیٹا اکاؤنٹ کی حتمی خوردہ قیمت نہیں ہے۔ اکاؤنٹ پر لاگو قیمت اور رجسٹریشن کی شرائط کا الگ سے جائزہ لیں۔ کیٹلاگ لوڈ کرنے سے کسی برانڈ، مہم یا پیغام رسانی کے نمبر کو منظوری نہیں ملتی۔

غیر دستیاب کیٹلاگ کی صورت میں کارروائی کریں

اگر معلومات حاصل کرنے میں ناکامی ہو تو صارف کی فارم میں درج کردہ معلومات محفوظ رکھیں۔ خرابی دکھائیں اور Retry-After واپس ملنے پر اس کی ہدایت کے مطابق وقفہ رکھیں، اور دوبارہ کوششوں کے درمیان وقفہ بڑھاتے جائیں۔ ہر کیٹلاگ کو بار بار لوڈ نہ کریں اور شرح کی حد یا ترسیل کی خرابی کو خالی مگر درست کیٹلاگ نہ سمجھیں۔ اس GET کے لیے تکرار سے بے اثری کی کلید درکار نہیں، اور اسے تبدیلی کی کارروائیوں کے تکرار سے بے اثری کے ذخیرے سے دوبارہ نہیں چلایا جاتا۔

درخواست

کسی مجاز ماخذ آئی پی پتے سے HTTPS کے ذریعے فعال API اکاؤنٹ استعمال کریں۔ موجودہ راستہ اکاؤنٹ کی توثیقی پالیسی کی معاونت کرتا ہے، جس میں Basic توثیق اور بیئرر ٹوکن استعمال کرنے والے فعال API اکاؤنٹس شامل ہیں۔ فراہم کنندہ کی اسناد استعمال نہ کریں۔

راستے میں کسی معاونت یافتہ کیٹلاگ کے نام کے ساتھ GET درخواست بھیجیں۔ متعلقہ کیٹلاگ فلٹر استفسار کی سٹرنگ میں دیں۔ درخواست کا متن درکار نہیں۔

curl --fail-with-body --silent --show-error \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/tcr/v2/enum/usecase?validSubUsecase=true"

جواب

TCR کا یہ راستہ رجسٹری کے جواب کا متن اس کی HTTP حیثیت سمیت براہ راست واپس کرتا ہے۔ یہ v3 کا پرانا status.code/status.msg/response غلاف استعمال نہیں کرتا۔ کیٹلاگ کی ساختیں مختلف ہوتی ہیں: بعض قدروں کو وضاحتی آبجیکٹس سے منسلک کرتے ہیں، جبکہ دوسرے قدروں کو سٹرنگز سے منسلک کرتے ہیں۔ بعد میں فارم جمع کراتے وقت مشین کے لیے قابلِ مطالعہ کلیدیں برقرار رکھیں۔ usecase کی مختصر فرضی مثال ایسی میپنگ دکھاتی ہے جس کی قدریں آبجیکٹس ہیں؛ یہ کوئی براہِ راست فعال کیٹلاگ نہیں اور نہ ہی اس کی اسکیما کے مکمل ہونے کی ضمانت ہے۔ HTTP کی حیثیت اور JSON کی متوقع ساخت، دونوں جانچیں۔

جواب کی ساخت کی وضاحتی مثال؛ یہ اکاؤنٹ کا براہِ راست ڈیٹا یا موجودہ قیمت کی پیش کش نہیں ہے۔

{
  "2FA": {
    "displayName": "Authentication",
    "description": "Example authentication use case"
  }
}

خرابیاں

• 401: اکاؤنٹ کی توثیق ناکام ہو گئی۔ API کی سند، اکاؤنٹ کے فعال ہونے کی حالت اور ماخذ آئی پی پر لاگو پابندیاں جانچیں۔
• 400/404 اور رجسٹری کی دیگر خرابیاں: کیٹلاگ یا فلٹر غلط یا غیر دستیاب ہے۔ موجودہ راستہ بالائی سروس کی HTTP حیثیت اور جواب کا متن برقرار رکھتا ہے؛ v3 کی خرابیوں کا کوئی یکساں غلاف موجود نہیں۔
• 429: اکاؤنٹ یا فراہم کنندہ کی مشترکہ درخواستوں کی حد پوری ہو گئی ہے۔ Retry-After کی ہدایت کے مطابق وقفہ رکھیں اور کوششوں کے درمیان وقفہ بڑھاتے ہوئے دوبارہ کوشش کریں۔
• 502: رجسٹری تک رسائی ممکن نہیں ہوئی۔ دستیابی نامعلوم ہے؛ کامیاب نتیجے کے متبادل کے طور پر خالی اختیارات پیش نہ کریں۔
• 503: درخواستوں کی حد نافذ کرنے والا نظام یا بالائی سروس غیر دستیاب ہے۔ دوبارہ کوشش کرنے سے پہلے جواب کا متن اور موجود ہونے والا کوئی بھی Retry-After ہیڈر دیکھیں۔

دستیابی اور ضمنی اثرات

• جائزہ لیے گئے راستے میں کیٹلاگ کی یہ GET درخواست نہ کوئی برانڈ یا مہم بناتی ہے، نہ رجسٹریشن جمع کراتی ہے، نہ کوئی وسیلہ محفوظ کرتی ہے اور نہ رجسٹریشن فیس وصول کرتی ہے۔ یہ فراہم کنندہ سے رابطہ کرتی ہے اور درخواست کے آڈٹ ریکارڈ لکھتی ہے۔
• کیٹلاگ کی تعریفیں اور سپلائر کی فیس سے متعلق کوئی بھی میٹا ڈیٹا صارف کے لیے خوردہ قیمت کی پیش کش نہیں ہیں۔ موجودہ پورٹل مہم کی خوردہ قیمتیں الگ سے حاصل کرتا ہے؛ پرانے getCampaignPrice معاون فنکشن اور شمار شدہ اقسام کی قیمتوں کے پرانے توضیحی نوٹس کو اس راستے کے قیمت کے معاہدے کے طور پر نہیں لینا چاہیے۔
• کیٹلاگ میں کسی اندراج کی معاونت موجود ہونا اس بات کا ثبوت نہیں کہ کوئی مخصوص برانڈ استعمال کی اس صورت کے لیے اہل ہے۔ بعد میں رجسٹریشن کی درخواست بھیجنے سے پہلے برانڈ کی مخصوص اہلیت کی جانچ، اقرارات، رضامندی اور اکاؤنٹ کی قیمتوں کا جائزہ مکمل کریں۔