একটি প্রিফিক্স থেকে ফোন নম্বর অর্ডার করুন

একটি প্রিফিক্স থেকে অর্ডার করুন

প্রিফিক্সের ক্যাটালগ যখন আলাদা আলাদা উপলব্ধ নম্বর বেছে নেওয়ার পরিবর্তে একটি প্রিফিক্স থেকে নির্দিষ্ট পরিমাণ নম্বর অর্ডার করতে বলে, তখন এই অপারেশন ব্যবহার করুন। শুরুতে দেখুন দেশসমূহ, এলাকা বা রাজ্য এবং প্রিফিক্সসমূহ। একই সদ্য পাওয়া ফলাফল থেকে প্রিফিক্সের শনাক্তকারী ও মূল্য পরিকল্পনা সংরক্ষণ করুন। উপলব্ধ নম্বরের তালিকা থেকে বেছে নেওয়া কোনো নির্দিষ্ট নম্বরের জন্য ব্যবহার করুন বেছে নেওয়া একটি ফোন নম্বর কিনুন।

এই অনুরোধের মাধ্যমে নম্বর কেনা হতে পারে এবং চার্জ লাগতে পারে। এটি মূল্যের কোটেশন, সংরক্ষণ বা পরীক্ষামূলক অনুশীলন নয়। পাঠানোর আগে সেটআপ ও মাসিক চার্জ, ইনকামিং কলের প্রতি মিনিটের হার, অন্তর্ভুক্ত মিনিট, চ্যানেল, নিবন্ধনের শর্ত এবং অ্যাকাউন্টের ক্রয়সীমা পর্যালোচনা করুন। ক্যাটালগের কোনো ফলাফল নম্বর সংরক্ষণ করে না বা মূল্য স্থির রাখে না। ক্রয় পূরণ করার আগেই অ্যাকাউন্টে অর্থ যোগ করার সংক্রান্ত পরীক্ষা হতে পারে; শুধু একটি ত্রুটি থেকে প্রমাণ হয় না যে কোনো ক্রয় হয়নি বা অ্যাকাউন্টে অর্থ যোগ করা হয়নি।

ক্রয়ের অনুরোধ পাঠান

অনুমোদিত উৎস 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	ক্রয় বা ব্যাচের জন্য আপনার দেওয়া লেবেল। সর্বোচ্চ 255 বাইটের একটি ছোট ASCII মান ব্যবহার করুন; এর চেয়ে দীর্ঘ মান কেটে ছোট করা হয়। সফল ক্রয়ের সঙ্গে এটি সংরক্ষিত থাকে এবং দেওয়া হলে কলব্যাকেও অন্তর্ভুক্ত হয়। আলাদা অর্ডারে একই রেফারেন্স থাকতে পারে। এটি আইডেমপোটেন্সি কী নয়: একই রেফারেন্স ও অভিন্ন ফিল্ড থাকলেও এই অপারেশন আবার পাঠালে অতিরিক্ত নম্বর কেনা হতে পারে এবং তার জন্য চার্জ লাগতে পারে।
webhook_url	ঐচ্ছিক কলব্যাক URL। আপনার নিয়ন্ত্রণে থাকা একটি HTTPS এন্ডপয়েন্ট ব্যবহার করুন। HTTP ও HTTPS 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-এর সঙ্গে সতর্কবার্তা বা কম নম্বর	কিছু নম্বর কেনা হয়েছে। আরও অর্ডার করার আগে ফেরত পাওয়া বরাদ্দ ও লেনদেন মিলিয়ে নিন।
সার্ভার/ডেটা পরিবহনে ব্যর্থতা বা অপাঠ্য প্রতিক্রিয়া	নম্বরের মজুত ও লেনদেন থেকে কী ঘটেছে তা নিশ্চিত না হওয়া পর্যন্ত ফলাফলকে সম্ভাব্য অনিশ্চিত হিসেবে বিবেচনা করুন।