Список областей покрытия для страны

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