Список префиксов для зоны покрытия

Перед началом работы

Выберите зону покрытия с помощью 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 точным количеством доступных номеров, нулевое значение — безусловным запретом на заказ, а успешный поиск — резервированием. Доступность может измениться до оформления заказа.