Отримання списку префіксів для зони покриття

Перед початком

Виберіть зону покриття за допомогою getareas. Скопіюйте ідентифікатор зони покриття з відповіді або з повернутого значення next_function. Для зони покриття у США або Канаді скористайтеся getstates, якщо хочете обмежити результати одним штатом або провінцією.

Перегляд результату

Перевіряйте status.code у тілі JSON, а також статус HTTP. Успішні результати містить масив response. За замовчуванням відповідь відсортовано за назвою. Значення available є орієнтовним, а ознаки в каталозі не замінюють перевірки фактичних можливостей вибраного номера та вимог до його реєстрації.

Вибір наступного кроку

Використовуйте незгрупований результат. Коли значення returns_numbers дорівнює 1, повернуте значення next_function вказує на пошук номерів. Коли це значення дорівнює 0, номери призначаються під час замовлення, а шлях вказує на операцію замовлення. Перш ніж надсилати запит, ознайомтеся з операцією та її вимогами: запит на замовлення може призвести до списання коштів із вашого рахунку. Не надсилайте автоматично запити за кожним повернутим шляхом.

Ціну тут не наведено. Перед придбанням ознайомтеся з відповідною ціновою пропозицією, переліком необхідних документів та інструкціями щодо замовлення. Зберігайте повернуті ідентифікатори окремого префікса та цінової пропозиції, а не формуйте їх із телефонного префікса, що відображається.

Додаткові параметри відображення

compact=1 повертає перемішану вибірку щонайбільше зі 100 рядків, а не сторінку більшого набору результатів. Групування створює зведені рядки та штучні ідентифікатори; щоб вибрати окремий префікс, використовуйте звичайну незгруповану відповідь. Не використовуйте вибіркові або згруповані результати для тверджень про вичерпний перелік наявних номерів чи точні можливості.

Запит

Використовуйте облікові дані свого активованого облікового запису API через HTTPS. Підтримуються автентифікація Basic та активовані токени bearer облікового запису API; діють обмеження облікового запису.

Використовуйте GET і передавайте необов’язкові параметри в рядку запиту. Не покладайтеся на резервне зчитування параметрів із тіла форми.

curl --fail-with-body --silent --show-error \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/v3/getprefixes/$AREA_ID?state=NY"

Відповідь

Стандартна оболонка JSON із полями status/response. status.results містить кількість повернутих рядків з урахуванням вибірки або групування. response містить об’єкти префіксів. Поля з цінами не повертаються. У звичайній незгрупованій відповіді uuid є ідентифікатором префікса; area_uuid і country_uuid — повернуті ідентифікатори; prefix і name — інформація для відображення; available — оцінка доступності, а не резервування; needs_registration і restrictions описують відомості про реєстрацію; sms_coverage, is_mobile і number_type — підказки з каталогу, а не гарантія певної можливості конкретного номера. number_type може бути порожнім або містити інший рядок із каталогу, тому не вимагайте фіксованого набору допустимих значень. state є рядком і може бути порожнім або містити форматування каталогу. latitude і longitude можуть бути порожніми. metered і overflow — ознаки в каталозі, а не грошові суми. returns_numbers вибирає маршрут отримання списку номерів (1) або маршрут призначення номера під час замовлення (0). next_function визначає цей наступний маршрут. Згруповані відповіді додатково містять об’єднані характеристики, зокрема резервні значення характеристик; не сприймайте їх як перевірені можливості кожного номера.

Приклад структури відповіді; це не поточні дані облікового запису й не актуальна цінова пропозиція.

{
  "status": {
    "code": 200,
    "msg": "",
    "results": 1
  },
  "response": [
    {
      "uuid": "PREFIX_ID_FROM_RESPONSE",
      "area_uuid": "AREA_ID_FROM_RESPONSE",
      "country_uuid": "COUNTRY_ID_FROM_RESPONSE",
      "prefix": "+1212",
      "name": "Example area",
      "metered": 0,
      "overflow": 0,
      "needs_registration": 0,
      "restrictions": "",
      "state": "NY",
      "country_iso": "US",
      "is_mobile": 0,
      "number_type": "local",
      "latitude": "",
      "longitude": "",
      "available": 12,
      "sms_coverage": 1,
      "returns_numbers": 1,
      "next_function": "v3/getnumbers/PREFIX_ID_FROM_RESPONSE"
    }
  ]
}

Помилки

• 404: Invalid area ID: отримайте актуальний ідентифікатор зони покриття на етапі пошуку в каталозі.
• 404: State filter is only available for US and CA: для інших країн не передавайте state.
• 404: Invalid state: використовуйте штат або провінцію, які повертає getstates для цієї країни.
• 404: No prefixes found: відповідних рядків каталогу не повернуто. Це не доводить, що певний номер ніколи не можна буде замовити.
• 500: Помилка: 'Failed loading prefixes': пошук у каталозі завершився невдало. Повторіть спробу пізніше та зверніться до служби підтримки, якщо проблема не зникне.

Доступність і побічні ефекти

• Це етап пошуку в каталозі, а не підтвердження замовлення. Відомості про доступність можуть оновлюватися за допомогою додаткових звернень до каталогу, тому час очікування відповіді може змінюватися.
• Ціни не повертаються. Перш ніж оформлювати замовлення, отримайте відповідну цінову пропозицію для номера або замовлення та ознайомтеся з вимогами до реєстрації.
• Не сприймайте available як точну кількість наявних номерів, нуль — як безумовну заборону замовлення, а успішний пошук — як резервування. Доступність може змінитися до оформлення замовлення.