ტელეფონის ნომრების შეკვეთა პრეფიქსიდან

შეკვეთა პრეფიქსიდან

გამოიყენეთ ეს ოპერაცია, როდესაც პრეფიქსების კატალოგი გთავაზობთ პრეფიქსიდან ნომრების რაოდენობის შეკვეთას და არა ცალკეული ხელმისაწვდომი ნომრების არჩევას. დასაწყებად იხილეთ ქვეყნები, რეგიონები ან შტატები და პრეფიქსები. პრეფიქსის იდენტიფიკატორი და სატარიფო გეგმა ერთი და იმავე ახლად მიღებული შედეგიდან შეინახეთ. ხელმისაწვდომი ნომრების სიიდან არჩეული კონკრეტული ნომრისთვის გამოიყენეთ არჩეული ტელეფონის ნომრის შეძენა.

ამ მოთხოვნამ შეიძლება ნომრები შეიძინოს და საფასურის დარიცხვა გამოიწვიოს. ეს არ არის ფასის შეთავაზება, დაჯავშნა ან საცდელი გაშვება. გაგზავნამდე გაეცანით ჩართვისა და ყოველთვიურ საფასურს, შემომავალი ზარების წუთობრივ ტარიფებს, ჩართულ წუთებს, არხებს, რეგისტრაციის მოთხოვნებსა და ანგარიშის შეძენის ლიმიტებს. კატალოგის შედეგი მარაგს არ ჯავშნის და ფასებს არ აფიქსირებს. ანგარიშის დაფინანსების შემოწმებები შეიძლება შესრულებამდე მოხდეს; შეცდომა თავისთავად არ ადასტურებს, რომ შეძენა ან ანგარიშის დაფინანსება არ მომხდარა.

შეძენის მოთხოვნის გაგზავნა

გამოიყენეთ ჩართული API ანგარიში HTTPS-ის მეშვეობით, ნებადართული წყაროს IP მისამართიდან. ცვლადები შეავსეთ კატალოგში თქვენი მიმდინარე არჩევანისა და მიწოდების დამტკიცებული კონფიგურაციის მიხედვით. შემდეგი ბრძანება ერთ ნომერს ყიდულობს.

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 მოთხოვნა. კოორდინატორი JSON ობიექტსაც კითხულობს, როდესაც Content-Type არის application/json. JSON ველები ანაცვლებს ფორმის/მოთხოვნის შესაბამის ველებს. თანმიმდევრულად გამოიყენეთ კოდირების ერთი ფორმატი; არ გაგზავნოთ ურთიერთგამომრიცხავი მნიშვნელობები მოთხოვნის პარამეტრებსა და სხეულში.

შეკვეთის არჩევისა და შეტყობინების პარამეტრები
პარამეტრი	მნიშვნელობა
პრეფიქსის იდენტიფიკატორი მისამართის გზაში	კატალოგის მიერ დაბრუნებული პრეფიქსის UUID. მას ვერ ჩაანაცვლებს ქვეყნის, რეგიონის, ფასის ან ცალკეული ნომრის იდენტიფიკატორი.
quantity	გაგზავნეთ მთელი რიცხვი 1-დან 100-მდე. ნაგულისხმევია 1. 1-ზე ნაკლები მნიშვნელობები იძულებით გარდაიქმნება 1-ად; ეს მხოლოდ ვალიდაციის მოთხოვნა არ არის. 100-ზე მეტი მნიშვნელობები გამონაკლისს იწვევს მანამ, სანამ ამ კოორდინატორის პასუხის ჩვეულებრივი დამუშავება დაიწყება, ამიტომ ასეთი არასწორი შემავალი მონაცემისთვის მის ჩვეულ JSON სტრუქტურას ნუ დაეყრდნობით.
price_id	არჩეული გეგმის ფასის საჯარო იდენტიფიკატორი. priceid ძველი ალტერნატიული სახელია. შეუსაბამო იდენტიფიკატორის შემთხვევაში სისტემა შეიძლება შეტყობინების გარეშე სხვა გეგმაზე გადავიდეს; ეს ველი ფასს მკაცრად არ აფიქსირებს. შეძენამდე გადაამოწმეთ ანგარიშის ფასის ზედა ზღვრები, შემდეგ კი შეამოწმეთ დაბრუნებული ფასი.
channels	არხების რაოდენობა არჩეული გეგმიდან. როდესაც ფასის ზუსტი დამთხვევა არ გამოიყენება, არხების რაოდენობის დამთხვევამ შეიძლება გავლენა მოახდინოს ალტერნატიული გეგმის შერჩევაზე. ეს თავისთავად არ იძლევა კონკრეტული გეგმის შეძენის გარანტიას.
reference	თქვენი მონიშვნა შეძენის ან პაკეტისთვის. გამოიყენეთ მოკლე ASCII მნიშვნელობა, მაქსიმუმ 255 ბაიტი; უფრო გრძელი მნიშვნელობები იჭრება. მითითების შემთხვევაში ის ინახება წარმატებულ შეძენებთან ერთად და შედის უკუგამოძახებებში. ცალკეულ შეკვეთებს შეიძლება ერთი და იგივე მითითება ჰქონდეს. ეს არ არის იდემპოტენტურობის გასაღები: ამ ოპერაციის ხელახლა გაგზავნამ შეიძლება დამატებითი ნომრები შეიძინოს და მათი საფასური დაარიცხოს, იმავე მითითებისა და იდენტური ველების შემთხვევაშიც კი.
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-ს, ნაგულისხმევ ჩართულ პარამეტრად აღიქვამს. პორტალში შეამოწმეთ შეძენილი ნომრის განახლება და საჭიროების შემთხვევაში შეცვალეთ იგი.

ეს ველები ნორმალიზდება და გადაეცემა შეძენის გაფორმების პროცესს, თუმცა მათი შენახვა მარაგის დამუშავების სხვადასხვა გზაზე განსხვავდება. შეკვეთის მიმდინარე მარშრუტი არჩეული ნომრის შეძენის სახელმძღვანელოში აღწერილ შეთავაზებული ფასის მკაცრი ზედა ზღვრის ველებს ეკვივალენტურ დამცავ მექანიზმებად არ გთავაზობთ. გამოიყენეთ ანგარიშის შეძენის უფლებები და ფასის ლიმიტები და შეამოწმეთ ნომრის მიღებული კონფიგურაცია.

სრული შედეგის წაკითხვა

გაარჩიეთ JSON სხეული და შეამოწმეთ status.code და status.msg მაშინაც კი, როცა HTTP მოთხოვნა წარმატებულია. ეს მარშრუტი საკუთარ 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 გაფრთხილებებით ან ნაკლები ნომრით	ზოგიერთი ნომერი შეძენილია. დამატებითი ნომრების შეკვეთამდე შეაჯერეთ დაბრუნებული გამოყოფილი ნომრები და ტრანზაქციები.
სერვერის/ტრანსპორტის წარუმატებლობა ან წაუკითხავი პასუხი	შედეგი პოტენციურად გაურკვევლად მიიჩნიეთ, სანამ მარაგისა და ტრანზაქციების მონაცემები არ დაადგენს, რა მოხდა.