کسی سابقے سے آرڈر دیں
یہ کارروائی اس وقت استعمال کریں جب سابقوں کی فہرست آپ کو دستیاب نمبر الگ الگ منتخب کرنے کے بجائے کسی سابقے سے مطلوبہ تعداد کا آرڈر دینے کی ہدایت کرے۔ آغاز کریں: ممالک، علاقے یا ریاستیں، اور سابقے۔ سابقے کا شناخت کنندہ اور قیمت کا منصوبہ ایک ہی تازہ نتیجے سے محفوظ کریں۔ دستیاب نمبروں کی فہرست سے منتخب کسی مخصوص نمبر کے لیے استعمال کریں: منتخب فون نمبر خریدیں۔
یہ درخواست نمبر خرید سکتی ہے اور اس سے اخراجات عائد ہو سکتے ہیں۔ یہ قیمت کا تخمینہ، بکنگ یا محض آزمائشی اجرا نہیں ہے۔ جمع کرانے سے پہلے ابتدائی اور ماہانہ اخراجات، آنے والی کالوں کی فی منٹ شرحیں، شامل منٹ، چینلز، اندراج کے تقاضے اور اکاؤنٹ کی خریداری کی حدود دیکھیں۔ فہرست کا نتیجہ نہ ذخیرہ محفوظ کرتا ہے اور نہ قیمتیں منجمد کرتا ہے۔ تکمیل سے پہلے اکاؤنٹ میں رقم جمع کرنے سے متعلق جانچ ہو سکتی ہے؛ کوئی خرابی بذات خود یہ ثابت نہیں کرتی کہ خریداری نہیں ہوئی یا اکاؤنٹ میں رقم جمع نہیں کی گئی۔
خریداری کی درخواست جمع کرائیں
اجازت یافتہ ماخذ IP پتے سے HTTPS کے ذریعے فعال API اکاؤنٹ استعمال کریں۔ متغیرات کو فہرست میں اپنے موجودہ انتخاب اور اپنی منظور شدہ ترسیلی ترتیب کے مطابق مقرر کریں۔ درج ذیل کمانڈ ایک نمبر خریدتی ہے۔
curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
--data-urlencode 'quantity=1' \
--data-urlencode "price_id=$PRICE_ID" \
--data-urlencode "channels=$CHANNELS" \
--data-urlencode "reference=$ORDER_REFERENCE" \
--data-urlencode "uri=$VOICE_URI" \
"https://api.multitel.net/v3/order/$PREFIX_ID"اوپر فارم کے ذریعے POST دکھایا گیا ہے۔ جب Content-Type کی قدر application/json ہو تو رابطہ کار JSON آبجیکٹ بھی پڑھتا ہے۔ JSON فیلڈز اسی نام کی فارم/درخواست فیلڈز کی جگہ نافذ ہوتی ہیں۔ ایک ہی انکوڈنگ مستقل استعمال کریں؛ کوئری اور باڈی میں متضاد قدریں نہ بھیجیں۔
| پیرامیٹر | مطلب |
|---|---|
| پاتھ میں سابقے کا شناخت کنندہ | فہرست سے واپس ملنے والا سابقے کا UUID۔ ملک، علاقے، قیمت یا کسی انفرادی نمبر کا شناخت کنندہ اس کا متبادل نہیں ہے۔ |
| quantity | 1 سے 100 تک کوئی صحیح عدد بھیجیں۔ طے شدہ قدر 1 ہے۔ 1 سے کم قدروں کو 1 بنا دیا جاتا ہے؛ یہ صرف توثیق کی درخواست نہیں ہے۔ 100 سے زیادہ قدروں پر اس رابطہ کار کی معمول کی جوابی کارروائی سے پہلے استثنا پیدا ہوتا ہے، اس لیے اس غلط ان پٹ کے لیے اس کی معمول کی JSON ساخت پر انحصار نہ کریں۔ |
| price_id | منتخب منصوبے کی قیمت کا عوامی شناخت کنندہ۔ priceid اس کا پرانا متبادل نام ہے۔ شناخت کنندہ مطابقت نہ رکھنے پر بغیر اطلاع کسی دوسرے منصوبے کا انتخاب ہو سکتا ہے؛ یہ فیلڈ قیمت کو قطعی طور پر مقفل نہیں کرتی۔ خریداری سے پہلے اکاؤنٹ کی قیمت کی بالائی حدود کی تصدیق کریں اور بعد میں واپس ملنے والی قیمت دیکھیں۔ |
| channels | منتخب منصوبے میں چینلز کی تعداد۔ جب عین مطابق قیمت استعمال نہ ہو تو چینلز کی مماثل تعداد متبادل انتخاب پر اثر انداز ہو سکتی ہے۔ یہ بذات خود کسی مخصوص منصوبے کی خریداری کی ضمانت نہیں دیتی۔ |
| reference | خریداری یا مجموعے کے لیے آپ کا لیبل۔ مختصر ASCII قدر استعمال کریں، زیادہ سے زیادہ 255 بائٹس؛ زیادہ طویل قدریں کاٹ دی جاتی ہیں۔ کامیاب خریداریوں کے ساتھ اسے محفوظ رکھا جاتا ہے اور فراہم کیے جانے پر کال بیکس میں شامل کیا جاتا ہے۔ الگ آرڈرز کا حوالہ ایک جیسا ہو سکتا ہے۔ یہ تکرار پر یکساں نتیجہ یقینی بنانے کی کلید نہیں ہے: اس کارروائی کو دوبارہ جمع کرانے سے مزید نمبر خریدے جا سکتے ہیں اور ان کی رقم وصول ہو سکتی ہے، چاہے حوالہ اور تمام فیلڈز ایک جیسی ہوں۔ |
| webhook_url | اختیاری کال بیک URL۔ اپنے زیر اختیار HTTPS اینڈ پوائنٹ کا استعمال کریں۔ HTTP اور HTTPS دونوں کے URLs موجودہ بنیادی توثیق میں منظور ہو جاتے ہیں؛ غلط URL کی صورت میں خریداری مسترد کرنے کے بجائے URL نظرانداز کر دیا جاتا ہے۔ کال بیک ایک اضافی اطلاع ہے، اس بات کا ثبوت نہیں کہ درخواست کو محفوظ طور پر دہرایا جا سکتا ہے۔ |
ترسیل اور تجدید کی ترتیبات
ترسیل کی وہی ترتیبات منتخب کریں جو آپ پورٹل میں اس نمبر کے لیے استعمال کرتے۔ یہ اعلیٰ درجے کی ترتیب کی قدریں ہیں، ہوسٹڈ PBX یا کالوں کے آغاز کا ٹرنک بنانے کی ہدایات نہیں۔ اکاؤنٹ کی ایسی ترتیب دوبارہ استعمال کریں جس کا درست کام کرنا معلوم ہو، اور خریداری کے بعد محفوظ شدہ نمبر کی تصدیق کریں۔ صرف خریداری کی منظوری اس بات کی تصدیق نہیں کرتی کہ صوتی کالوں یا SMS کی ترسیل کام کرتی ہے۔
| فیلڈ | استعمال اور مطابقت |
|---|---|
| uri, uri2, uri3 | صوتی کالوں کی بنیادی اور اضافی منزلیں۔ منتخب فارورڈنگ اور گھنٹی کے طریقوں کے لیے موزوں منزلیں فراہم کریں۔ |
| forward_destination | صوتی کال آگے بھیجنے کا طریقہ۔ forwarding_destination اور type پرانے متبادل نام ہیں۔ اسے نہ دینے پر خریداری مکمل کرنے کے متعلقہ راستے کی طے شدہ قدر استعمال ہوتی ہے؛ خالی فیلڈ موجودہ ترجیح کو مٹانے کا قابل اعتماد طریقہ نہیں ہے۔ |
| ring_type | صوتی کال کی گھنٹی کا طریقہ؛ ringtype متبادل نام ہے۔ اپنے اکاؤنٹ میں نمبر کی ترتیب سے کوئی معاونت یافتہ قدر استعمال کریں۔ |
| sms_forward_destination, sms_uri | SMS کی ترسیل کا طریقہ اور منزل۔ پرانے متبادل نام smsringtype اور smsuri ہیں۔ یہ خالی ہو تو خریداری مکمل کرنے کے بعض راستے اکاؤنٹ کی طے شدہ SMS منزل نافذ کرتے ہیں۔ SMS کی دستیابی منتخب نمبر اور اس کی فعالیت/اندراج پر منحصر ہے۔ |
| overflow | گنجائش سے زائد کالوں کے لیے مطلوبہ ترتیب۔ اس کی معاونت دستیاب ہونے کا انحصار منصوبے کی دستیابی اور خریداری مکمل کرنے کے راستے پر ہے۔ |
| force_codec, force_dtmf | کوڈیک اور DTMF کی مطلوبہ ترتیبات۔ پرانے متبادل نام forcecodec اور forcedtmf ہیں۔ منتخب ذخیرے کے لیے محفوظ شدہ ترتیب کی تصدیق کریں۔ |
| origination_trunk_id | جہاں قابل اطلاق ہو، موجودہ ٹرنک ترتیب کا شناخت کنندہ۔ اس سے ٹرنک نہیں بنتا۔ اسے نہ دینے پر خریداری مکمل کرنے کی طے شدہ قدر استعمال ہوتی ہے۔ |
| autorenew | تجدید کی مطلوبہ ترتیب۔ یہ فرض نہ کریں کہ 0 سے تجدید غیر فعال ہو جاتی ہے: خریداری مکمل کرنے کے بعض راستے خالی جیسی قدر، بشمول 0، کو طے شدہ فعال ترتیب سمجھتے ہیں۔ پورٹل میں خریدے گئے نمبر کی تجدید کی ترتیب دیکھیں اور ضرورت ہو تو تبدیل کریں۔ |
ان فیلڈز کو یکساں صورت دے کر خریداری مکمل کرنے کے عمل کو بھیجا جاتا ہے، لیکن مختلف ذخیرہ جاتی راستوں میں ان کا مستقل محفوظ ہونا مختلف ہے۔ موجودہ آرڈر روٹ، منتخب نمبر کی خریداری کی رہنمائی میں موجود قیمت کے تخمینے کی سخت بالائی حد والی فیلڈز کو مساوی حفاظتی پابندیوں کے طور پر مہیا نہیں کرتا۔ اکاؤنٹ کی خریداری کی اجازتیں اور قیمت کی حدود استعمال کریں، اور نتیجے میں بننے والی نمبر کی ترتیب دیکھیں۔
مکمل نتیجہ پڑھیں
HTTP درخواست کامیاب ہونے پر بھی JSON باڈی کو پارس کریں اور status.code اور status.msg دیکھیں۔ یہ روٹ اپنا JSON جواب خود لکھتا ہے، اور مشترکہ جوابی مددگار بھی لازماً ایپلیکیشن کوڈ کو HTTP حیثیت کے مطابق نہیں بناتا۔ ایپلیکیشن کوڈز JSON اعداد یا عددی سٹرنگز ہو سکتے ہیں۔ status.results کی موجودگی کو لازمی شرط نہ بنائیں؛ یہ آرڈر کے معمول کے نتیجے میں موجود نہیں ہوتا۔
{
"status": {"code": "200", "msg": ""},
"response": {
"id": "o_fictional_example",
"numbers": ["12025550123"],
"price": {
"per_minute": "0.01",
"free_minutes": 0,
"setup_price": "1.25",
"monthly_price": "2.50",
"channels": 2
},
"features": ["voice"],
"needs_registration": 0,
"restrictions": "",
"registration_requirements": null
}
}اوپر دیے گئے شناخت کنندہ، نمبر اور قیمتیں فرضی ہیں۔ آرڈر ID کی اندرونی ساخت سے کوئی مفہوم اخذ نہ کریں۔ numbers میں وہ نمبر درج ہوتے ہیں جنہیں یہ جواب خریدے گئے نمبر بتاتا ہے؛ اس فہرست کی لمبائی کا اپنی مطلوبہ تعداد سے موازنہ کریں۔ قیمت کی رقوم سٹرنگز ہوتی ہیں اور یہ جواب مالی شرحوں کو اعشاریے کے بعد دو ہندسوں تک گول کرتا ہے، جن میں per_minute بھی شامل ہے؛ شرح کی اصل اعشاری درستگی کے لیے تازہ فہرست استعمال کریں۔ شامل منٹ اور چینلز عددی قدروں یا عددی سٹرنگز کی صورت میں آ سکتے ہیں۔
قیمت کا بلاک اس منتخب منصوبے کی وضاحت کرتا ہے جس سے جواب تیار کیا گیا ہے؛ یہ ہر نمبر کا تفصیلی بل یا آرڈر کی کل رقم نہیں ہے۔ ذخیرے میں انتخاب کے لیے موجود مختلف نمبروں کے منصوبے مختلف ہو سکتے ہیں۔ اس بلاک کی رقم کو ضرب دے کر یہ فرض کرنے کے بجائے کہ اس سے حتمی کل رقم ثابت ہوتی ہے، انفرادی خریدے گئے نمبروں اور اکاؤنٹ کے لین دین کا حساب ملائیں۔
جزوی خریداری اور غیر یقینی نتائج
ایپلیکیشن کوڈ 200 کے ساتھ انتباہ اور مطلوبہ تعداد سے کم نمبر بھی آ سکتے ہیں۔ بعد کی ناکامی پہلے سے خریدے گئے نمبروں کی خریداری منسوخ نہیں کرتی۔ واپس ملنے والا آرڈر ID، نمبر اور پیغام محفوظ رکھیں۔ باقی تعداد کا آرڈر دینے یا نہ دینے کا فیصلہ کرنے سے پہلے ان نمبروں کو اپنے ذخیرے اور اکاؤنٹ کے لین دین سے ملا کر تصدیق کریں۔
جمع کرانے کے بعد وقت کی حد ختم ہونا، درخواست کا رابطہ ٹوٹنا، غلط ساخت کا جواب یا خرابی اس بات کا ثبوت نہیں کہ کچھ نہیں ہوا۔ خودکار طور پر دوسری خریداری کی درخواست نہ بھیجیں، چاہے حوالہ وہی ہو۔ اصل درخواست، حوالہ اور واپس ملنے والا کوئی بھی آرڈر ID محفوظ رکھیں، ذخیرہ اور اکاؤنٹ کے لین دین دیکھیں، اور نتیجہ غیر یقینی رہنے پر معاونت سے رابطہ کریں۔
غیر مصدقہ آرڈر ایپلیکیشن کوڈ 400 کے ساتھ یہ پیغام دے سکتا ہے کہ اس کی تصدیق ابھی جاری ہے۔ واپس ملنے والا اس کا آرڈر ID محفوظ رکھیں اور اس خریداری کا حساب ملا کر تصدیق کریں؛ یہ اسے دوبارہ جمع کرانے کی ہدایت نہیں ہے۔ درج شدہ آرڈر کی بحالی کا عمل اندرونی طور پر اصل آرڈر کو ٹریک کرتا ہے۔ اس کارروائی کو نئی درخواست بھیجنے سے آپ کے حوالے کے ذریعے آرڈر دوبارہ جاری ہونے کے بجائے خریداری کی ایک الگ کوشش بنتی ہے، اس لیے مزید نمبر خریدے جا سکتے ہیں اور ان کی رقم وصول ہو سکتی ہے۔ حیثیت جانچنے یا ذخیرہ تلاش کرنے کے لیے خریداری کی درخواستیں بار بار نہ بھیجیں۔
اندراج اور فعالیت
خریدے گئے یا مختص کیے گئے نمبر کو اب بھی اندراج یا فعال کرنے کی ضرورت ہو سکتی ہے۔ اگر needs_registration کی قدر 1 ہو تو restrictions اور registration_requirements دیکھیں۔ مؤخر الذکر اس کی نشاندہی کر سکتا ہے: v3/get_requirements، جس کے ساتھ country اور number_type کی قدریں ہوں۔ آنے والی کالوں یا پیغام رسانی پر انحصار کرنے سے پہلے شناخت/پتے کا قابل اطلاق طریقۂ کار مکمل کریں اور نمبر کی حیثیت کی تصدیق کریں۔
features بیان کردہ صلاحیتوں کی وضاحت کرتا ہے؛ یہ عملی روٹنگ، مہم کی منظوری، SMS کی ترسیل یا فیکس وصول ہونے کی تصدیق نہیں کرتا۔ محفوظ شدہ ترسیلی ترتیبات دیکھیں اور نمبر فعال ہونے پر متعلقہ خدمت کی مناسب آزمائش کریں۔
آرڈر کے کال بیکس
کال بیکس POST کے ذریعے JSON بھیجتے ہیں جس میں آرڈر کی حیثیت اور جواب ہوتا ہے، اور آپ کا حوالہ فراہم کیا گیا ہو تو وہ بھی شامل کیا جاتا ہے۔ یہ اطلاع دی گئی خریداریوں کے لیے بھیجے جاتے ہیں، جن میں جزوی نتائج بھی شامل ہیں۔ ناکام کال بیک خریداری کو واپس منسوخ نہیں کرتا۔ ترسیل کی دوبارہ کوشش ہو سکتی ہے، اس لیے دوسری خریداری کی درخواست دینے کے بجائے آرڈر ID کے لحاظ سے دہرائی گئی اطلاعات سنبھالیں اور نمبروں کا حساب ملا کر تصدیق کریں۔
یہ روٹ کال بیک پر رمزنگاری پر مبنی دستخط شامل نہیں کرتا۔ کال بیک کو اپنے توثیق شدہ رسائی والے ذخیرے سے ملا کر تصدیق کرنے کی اطلاع سمجھیں، رقم وصول کرنے، خدمت مہیا کرنے یا رسائی دینے کی آزاد اجازت نہیں۔ کال بیک URL میں API کی اسناد نہ ڈالیں۔ مختلف کال بیک URL کے ساتھ دوسری خریداری جمع کرانے سے اصل آرڈر تبدیل نہیں ہوتا؛ اس سے خریداری کی الگ کوشش بنتی ہے۔ معاونت سے اس کے کال بیک کی تحقیق کی درخواست کرتے وقت اصل آرڈر ID محفوظ رکھیں۔
وہ ناکامیاں جنہیں سنبھالنا ضروری ہے
| نتیجہ | کیا کریں |
|---|---|
| 400 اور سابقہ غلط ہونے کا پیغام | سابقوں کی فہرست دوبارہ پڑھیں اور اس کا موجودہ شناخت کنندہ استعمال کریں۔ اسے اس پیغام سے الگ سمجھیں جس میں کہا گیا ہو کہ اصل آرڈر کی تصدیق ابھی جاری ہے۔ |
| 403 یا اکاؤنٹ کی پالیسی/بیلنس سے متعلق ناکامی | خریداری کی اجازت، اکاؤنٹ کی قیمت کی بالائی حدود، تعداد کی حدود اور رقم کی فراہمی کا جائزہ لیں۔ ان جانچوں سے دوسرے ایپلیکیشن کوڈز بھی آگے بھیجے جا سکتے ہیں؛ اصل پیغام محفوظ رکھیں۔ |
| 404 یا دستیاب ذخیرہ نہ ہونا | دستیابی کی تازہ معلومات حاصل کریں۔ جس سابقے کا ذخیرہ ختم ہو چکا ہو اس سے بار بار خریداری نہ کریں۔ |
| 409 اور خریداری کی تصدیق، فراہم کنندہ کے مسترد کرنے یا آرڈر منسوخ ہونے کا پیغام | واپس ملنے والا آرڈر ID اور اصل پیغام محفوظ رکھیں۔ دوسری خریداری جمع کرانے سے پہلے درخواست کو ذخیرے، اکاؤنٹ کے لین دین اور معاونت کی مدد سے ملا کر تصدیق کریں۔ وہی حوالہ دوبارہ استعمال کرنے سے دوسری درخواست محفوظ نہیں ہو جاتی۔ |
| 200 کے ساتھ انتباہات یا کم نمبر | کچھ نمبر خریدے جا چکے ہیں۔ مزید آرڈر دینے سے پہلے واپس ملنے والی تخصیص اور لین دین کا حساب ملا کر تصدیق کریں۔ |
| سرور/ڈیٹا کی منتقلی کی ناکامی یا ناقابل مطالعہ جواب | جب تک ذخیرے اور لین دین سے یہ ثابت نہ ہو جائے کہ کیا ہوا تھا، نتیجے کو ممکنہ طور پر غیر یقینی سمجھیں۔ |