Перелік зон покриття для країни

Вибравши країну (а для США чи Канади за бажанням також штат із 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, за прапорцями мобільного зв’язку зони; завжди 0 для US, якщо для вашого облікового запису не ввімкнено мобільні номери 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 має довідковий характер і може змінитися до наступного кроку.