ქვეყნის დაფარვის არეალების სია

ქვეყნის არჩევის შემდეგ (ხოლო აშშ-ისა და კანადისთვის, სურვილისამებრ, შტატის არჩევის შემდეგ შემდეგი ფუნქციიდან: getstates), გამოიძახეთ getareas იმის სანახავად, თუ სად არის ნომრები შემოთავაზებული. შეინახეთ არეალის იდენტიფიკატორი uuid შემდეგი ნაბიჯისთვის.

თითოეული არეალის შემდეგ შესაძლებელია ორი ნაბიჯიდან ერთ-ერთი:

• available > 0: next_function არის v3/getprefixes/{uuid}, რომელსაც ემატება ?state= შტატის მიხედვით გაფილტვრის შემთხვევაში. გამოიყენეთ ის პრეფიქსების დასათვალიერებლად.
• available = 0: არეალს აქვს პრეფიქსები, მაგრამ არ აქვს მარაგი, ხოლო next_function არის v3/order/{uuid}. ამ ნაბიჯის მოთხოვნები იხილეთ შეკვეთის დოკუმენტაციაში.

available არის მთელი არეალის ჯამური რაოდენობა მაშინაც კი, როცა შტატის მიხედვით ფილტრავთ. შტატის ფილტრი იღებს კოდს ან სრულ სახელს, მაგრამ მუშაობს მხოლოდ US და CA ქვეყნებისთვის. თუ შტატის ფილტრით მიიღეთ პასუხი No areas found, ხელახლა სცადეთ ამ ფილტრის გარეშე. შემოწმებები სრულდება შემდეგი თანმიმდევრობით: ქვეყნის კოდის არარსებობა, უცნობი ქვეყანა, სხვა ქვეყნისთვის გამოყენებული შტატის ფილტრი, არასწორი შტატი, შესაბამისი არეალების არარსებობა. თითოეულ ასეთ შემთხვევაში ბრუნდება კოდი 500 ან 404 შემდეგ ველში: status.code, შესაბამისი HTTP სტატუსის გარეშე.

მოთხოვნა

სავალდებულოა: HTTP Basic ავთენტიფიკაცია ან Bearer ტოკენი (იხილეთ „ავთენტიფიკაცია და API-ის პასუხები“). ავთენტიფიკაციის წარუმატებლობის შემთხვევაში, ძიების დაწყებამდე ბრუნდება HTTP 401 პასუხი.

GET მოთხოვნა, რომლის გზაში მითითებულია isocode, ხოლო მოთხოვნის პარამეტრების სტრიქონში — არასავალდებულო state და pid პარამეტრები. თუ გზის სეგმენტი გამოტოვებულია, მის ნაცვლად იკითხება ფორმის კოდირებით გადაცემული isocode ველი.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US'
curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US?state=NY'

პასუხი

პასუხის სტანდარტული გარე სტრუქტურა. წარმატების შემთხვევაში status.code არის 200, status.msg არის 'Results: N', status.results არის N, ხოლო response არის არეალის სახელის მიხედვით დალაგებული სია. ველები: uuid (არეალის იდენტიფიკატორი, რომლის შიდა სტრუქტურას მნიშვნელობა არ ენიჭება და რომელიც შემდეგ ნაბიჯზე გამოიყენება); country_uuid (ქვეყნის 32-სიმბოლოიანი იდენტიფიკატორი, რომლის შიდა სტრუქტურას მნიშვნელობა არ ენიჭება და რომელიც მოგვიანებით საჭირო არ არის); name; area_type და number_type (კატალოგის აღმწერები; ჩანაწერები აუცილებელი არ არის ადგილობრივი ნომრების ტიპებს წარმოადგენდეს); country_iso; is_mobile (0 ან 1, არეალის მობილური კავშირის ინდიკატორების მიხედვით; US ქვეყნისთვის ყოველთვის 0, თუ თქვენს ანგარიშზე US ქვეყნის მობილური ნომრების გამოყენება ჩართული არ არის); available (არეალის შესაბამისი პრეფიქსების მთლიანი მარაგი, რომელიც მოთხოვნილი შტატით არ შემოიფარგლება); sms_coverage (0 ან 1); returns_numbers (0 ან 1, არეალის პრეფიქსებს შორის ამ ინდიკატორის უმაღლესი მნიშვნელობა); latitude და longitude; state_iso; next_function. state_iso: შტატის ფილტრის გამოყენებისას ეს არის ფილტრის მიხედვით განსაზღვრული კოდი. US და CA ქვეყნებისთვის, ფილტრის გარეშე, ეს არის იმ შტატის კოდი, რომლის სახელიც არეალის სახელს ემთხვევა; სხვა შემთხვევაში — არეალისთვის შენახული მნიშვნელობა, ხოლო თუ არც ის არის — არეალის პრეფიქსების მონაცემებიდან მიღებული კოდი. სხვა ქვეყნებისთვის ეს არის შენახული მნიშვნელობა და შეიძლება ცარიელი იყოს. next_function არის 'v3/getprefixes/{uuid}' (გაფილტვრისას ემატება '?state={code}'), როცა available მეტია 0-ზე, სხვა შემთხვევაში კი — 'v3/order/{uuid}'. არეალები, რომლებსაც არცერთი შესაბამისი პრეფიქსი არ აქვთ, შედეგებში არ შედის. არეალები, რომლებსაც პრეფიქსები აქვთ, მაგრამ მარაგი არ აქვთ, ბრუნდება შემდეგი მნიშვნელობით: available 0.

პასუხის სტრუქტურის საილუსტრაციო მაგალითი; ეს არ არის ანგარიშის რეალური მიმდინარე მონაცემები ან მოქმედი ფასის შეთავაზება.

{
  "status": {
    "code": 200,
    "msg": "Results: 2",
    "results": 2
  },
  "response": [
    {
      "uuid": "0000000000000000000000000000a001",
      "country_uuid": "0000000000000000000000000000c001",
      "name": "Example City",
      "area_type": "City",
      "number_type": "Local",
      "country_iso": "US",
      "is_mobile": 0,
      "available": 58,
      "sms_coverage": 1,
      "returns_numbers": 1,
      "latitude": "40.0000",
      "longitude": "-75.0000",
      "state_iso": "NY",
      "next_function": "v3/getprefixes/0000000000000000000000000000a001"
    },
    {
      "uuid": "0000000000000000000000000000a002",
      "country_uuid": "0000000000000000000000000000c001",
      "name": "Sample Town",
      "area_type": "City",
      "number_type": "Local",
      "country_iso": "US",
      "is_mobile": 0,
      "available": 0,
      "sms_coverage": 0,
      "returns_numbers": 0,
      "latitude": "41.0000",
      "longitude": "-76.0000",
      "state_iso": "PA",
      "next_function": "v3/order/0000000000000000000000000000a002"
    }
  ]
}

შეცდომები

• 500: msg 'ISO Code parameter is required': isocode არ არის მითითებული ან ცარიელია. ეს მოთხოვნის გამოსწორებადი შეცდომაა. შესაბამისი HTTP სტატუსი არ განისაზღვრება.
• 404: msg 'Error: no such country': ქვეყნის კოდი უცნობია. შესაბამისი HTTP სტატუსი არ განისაზღვრება.
• 404: msg 'State filter is only available for US and CA': სხვა ქვეყნისთვის გაიგზავნა არაცარიელი state პარამეტრი. შესაბამისი HTTP სტატუსი არ განისაზღვრება.
• 404: msg 'Invalid state': state ამ ქვეყნისთვის არც ცნობილ კოდს და არც ცნობილ სახელს არ წარმოადგენს. შესაბამისი HTTP სტატუსი არ განისაზღვრება.
• 404: msg 'No areas found': ქვეყნის, წყაროსა და შტატის ფილტრებს არცერთი არეალი არ შეესაბამება. შესაბამისი HTTP სტატუსი არ განისაზღვრება.
• 401: ავთენტიფიკაცია არ არის წარმოდგენილი ან წარუმატებელია. იგზავნება HTTP სტატუსით 401.

ხელმისაწვდომობა და გვერდითი ეფექტები

• მომხმარებელთა ანგარიშებისთვის სრულდება მხოლოდ ძიება. ის არაფერს ჯავშნის, არ უკვეთავს და არ ცვლის.
• available საინფორმაციო მნიშვნელობაა და შეიძლება შემდეგ ნაბიჯამდე შეიცვალოს.