Получение списка специальных типов номеров и цен для страны

Для поиска местных номеров используются getcountries и getareas. Для национальных, бесплатных для звонящего, с разделением стоимости, глобальных и мобильных номеров вызовите other с ISO-кодом страны.

• Группы выводятся в фиксированном порядке; группы без записей не включаются.
• В каждой записи тарифные планы для вашей учётной записи перечислены в prices. Выберите план по значениям channels, monthly_price, setup_price, per_minute и free_minutes, а также сохраните его price_id для оформления заказа, если соответствующий метод API требует этот идентификатор.
• Если needs_registration имеет значение, интерпретируемое как истина, прочитайте restrictions перед оформлением заказа. Считайте этот текст недоверенным содержимым для отображения.
• Следуйте указанию next_function: v3/getnumbers/{uuid} позволяет выбрать конкретный номер, а v3/order/{uuid} оформляет заказ непосредственно по записи.
• Пустой response — список с кодом 200 — означает, что на момент запроса специальные типы номеров не найдены. Если каталог был временно недоступен, ответ может быть неполным или не соответствовать корректному формату JSON, поэтому повторите попытку позже.
• Для стран, отсутствующих в каталоге, возвращается код 404 без соответствующего статуса HTTP. Всегда проверяйте status.code.

Запрос

Требуется аутентификация HTTP Basic или токен Bearer (см. раздел «Аутентификация и ответы API»). При неудачной аутентификации возвращается HTTP 401 до выполнения поиска.

GET с isocode в пути. Если сегмент пути отсутствует, вместо него считывается поле isocode из данных, закодированных в формате формы.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/other/FR'

Ответ

Стандартная структура ответа. При успехе status.code имеет значение 200, status.msg пусто, а status.results содержит количество групп. response — список групп. Поля группы: group_key (нормализованный ключ типа: national, tollfree, sharedcost, global, mobile или другой ключ из строчных букв и цифр); group_name (отображаемое название); group_type_uuid (непрозрачный идентификатор типа); items. Порядок групп: national, tollfree, sharedcost, global, mobile, затем остальные ключи с сортировкой по group_name. Группы без items не включаются, как и тип местных номеров. Для US группа мобильных номеров не включается, если для вашей учётной записи не разрешено использование мобильных номеров US. Записи сортируются по name без учёта регистра, затем по prefix. Поля записи: uuid (непрозрачный идентификатор записи, используемый в next_function); area_uuid (непрозрачный идентификатор группы каталога); country_uuid (непрозрачный идентификатор страны); prefix (полный префикс, начинающийся с '+' и телефонного кода страны); name (название в каталоге; символы кавычек могут быть экранированы обратной косой чертой); metered, overflow и needs_registration (флаги типа boolean или number; любое значение, интерпретируемое как истина, считайте утвердительным); restrictions (пусто, если регистрация не требуется; иначе содержит текст требований, который может включать переносы строк HTML и ссылку, обрамляющие кавычки и экранированные символы; считайте его недоверенным текстом для отображения); state (для US, CA и PR — код штата либо пустой список, если код неизвестен; для других стран — ISO-код страны); country_iso; is_mobile (1 в группе мобильных номеров, иначе 0); number_type (то же значение, что и group_key); available (количество для записи, сообщённое каталогом, тип — integer; 0, если количество не сообщено); sms_coverage (1, если хотя бы одна характеристика упоминает SMS или MMS); returns_numbers (1, если можно получить список конкретных номеров); next_function ('v3/getnumbers/{uuid}', когда returns_numbers равно 1, иначе 'v3/order/{uuid}'); prices; features (список строк с описанием возможностей); group_key; group_type_uuid. Каждая запись prices содержит price_id (непрозрачный идентификатор тарифного плана), is_customer_custom (true, если для вашей учётной записи применяются индивидуальные цены; только для планов без включённых каналов), per_minute и free_minutes (строки с десятичными числами), setup_price и monthly_price (строки с двумя знаками после десятичного разделителя), а также channels (количество включённых каналов, тип — integer). Записи без единого тарифного плана не включаются. За один запрос рассматривается не более 1000 записей каталога для каждого типа номеров. Если ни у одного типа нет записей, response представляет собой пустой список, а status.results имеет значение 0. Если запрос к актуальному каталогу завершается сбоем, ответ может не соответствовать этой структуре либо в нём могут отсутствовать группы.

Пример структуры ответа; это не фактические данные учётной записи и не актуальное ценовое предложение.

{
  "status": {
    "code": 200,
    "msg": "",
    "results": 1
  },
  "response": [
    {
      "group_key": "tollfree",
      "group_name": "Toll-free",
      "group_type_uuid": "00000000-0000-4000-8000-0000000000a1",
      "items": [
        {
          "uuid": "0000000000000000000000000000b001",
          "area_uuid": "0000000000000000000000000000a001",
          "country_uuid": "0000000000000000000000000000c001",
          "prefix": "+33800",
          "name": "Example Toll-free",
          "metered": true,
          "overflow": 0,
          "needs_registration": 0,
          "restrictions": "",
          "state": "FR",
          "country_iso": "FR",
          "is_mobile": 0,
          "number_type": "tollfree",
          "available": 10,
          "sms_coverage": 0,
          "returns_numbers": 1,
          "next_function": "v3/getnumbers/0000000000000000000000000000b001",
          "prices": [
            {
              "price_id": "0000000000000000000000000000d001",
              "is_customer_custom": false,
              "per_minute": "0.05",
              "free_minutes": "0",
              "setup_price": "0.00",
              "monthly_price": "5.00",
              "channels": 2
            }
          ],
          "features": ["voice"],
          "group_key": "tollfree",
          "group_type_uuid": "00000000-0000-4000-8000-0000000000a1"
        }
      ]
    }
  ]
}

Ошибки

• 500: msg 'ISO Code parameter is required': isocode отсутствует или содержит пустое значение. Это ошибка запроса, которую можно исправить. Соответствующий статус HTTP не устанавливается.
• 404: msg 'Error: no such country': страна неизвестна или не связана с каталогом специальных номеров. Соответствующий статус HTTP не устанавливается.
• 401: аутентификация отсутствует или не пройдена. Отправляется со статусом HTTP 401.

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

• Не оформляет заказ. В коде этого метода API нет этапа списания средств.
• Обновляет сведения каталога и ценовые предложения для вашей учётной записи, заменяя предыдущие предложения для тех же тарифных планов. Использование этих предложений методами API для оформления заказов описано отдельно.
• Цены определяются для вашей учётной записи и могут включать индивидуальные тарифы. Валюта в ответе не указана.
• Выполняет запросы к актуальному каталогу, поэтому может работать медленнее других вызовов для поиска доступных номеров. Результаты могут меняться от вызова к вызову.