Поиск доступных телефонных номеров

Выберите отдельный префикс

Используйте вызовы получения стран и зон покрытия каталога, затем вызовите getprefixes без группировки. Скопируйте идентификатор выбранного префикса из поля uuid. Если returns_numbers равно 0, номер для этого префикса назначается при заказе; используйте возвращённое значение next_function, не требуя списка отдельных номеров.

Просматривайте ограниченную выборку

Для обычного поиска используйте compact=1 и укажите желаемый размер выборки как в пути, так и в параметре запроса quantity, как показано ниже. Параметров страницы или курсора нет. Компактный результат представляет собой выборку; повторение запроса не гарантирует получения следующей страницы без пересечений с предыдущей. Пустой результат или небольшое число записей не означают, что таково общее количество доступных номеров.

Найдите запоминающееся сочетание цифр

Укажите number_filter_mode=contains или ends_with вместе с number_filter_value. Значение должно содержать 1–15 цифр. Перед применением фильтра поиск может получать ограниченные выборки кандидатов, поэтому другие подходящие доступные номера могут не попасть в результат. Если для выполнения требуемого поиска нужен источник с поддержкой такой фильтрации, получите селектор pid у MultiTEL и используйте filter_required=1; если источник не выбран или выбранный источник не поддерживается, API возвращает ошибку.

Проверьте выбранный номер

Из одного и того же результата получите number, info.uuid, выбранное значение price[].uuid, названия доступных функций и требования к регистрации. Массив price может содержать несколько тарифных планов с разным количеством каналов и разными ставками. Денежные значения и количества могут быть представлены строками. Необязательные метаданные, включая info.state, различаются у разных источников; не рассчитывайте на единый формат данных о штате и не определяйте цены по идентификатору.

При обработке без потоковой передачи сначала удаляются дубликаты кандидатов и распределяется выборка между источниками, а затем выбранная партия сортируется по ежемесячной цене первого тарифного плана. При других вариантах обработки потоковая передача может начаться раньше, поэтому общий порядок записей и удаление дубликатов не гарантируются для всех запросов. Сортировка также не доказывает, что возвращённая выборка содержит самый дешёвый номер во всём каталоге.

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

Поиск ничего не покупает и не резервирует. Сохраните возвращённые идентификаторы номера и тарифного плана для оформления заказа под той же учётной записью. Перед отправкой заказа проверьте фактический тарифный план, требования и платежи. Требования к регистрации могут задержать активацию; результат поиска не устанавливает фиксированный срок активации.

Запрос

Используйте действующую учётную запись API MultiTEL: учётные данные HTTP Basic для записи с паролем или Authorization: Bearer для записи с токеном. Применяются права доступа учётной записи и её ограничения по IP. См. общие рекомендации по аутентификации.

Параметры пути и параметры строки запроса URL. Для поиска через публичный API используйте GET. Обработчик также принимает некоторые значения из формы или запроса, но не является API поиска с телом запроса в формате JSON.

curl --fail-with-body --get \
  --user "${MULTITEL_API_USERNAME}:${MULTITEL_API_PASSWORD}" \
  --data-urlencode "compact=1" \
  --data-urlencode "quantity=10" \
  "https://api.multitel.net/v3/getnumbers/${PREFIX_ID}/10"

Ответ

Один объект JSON, содержащий status и response. При успехе status.code равно 200, а response представляет собой массив записей о номерах. status.results содержит количество элементов возвращённого массива; status.msg может иметь значение Results: N или OK для потокового ответа. Без compact=1 некоторые поисковые запросы записывают массив response постепенно и завершаются полем status, поэтому дождитесь полного тела JSON. Это не JSON с разделением записей переводами строк. Проверяйте status.code, даже если передача по HTTP прошла успешно. Ниже показаны типичные поля; метаданные отдельных источников и необязательные поля различаются. Считайте каждый идентификатор непрозрачным значением и сохраняйте номер вместе с выбранным для него price[].uuid.

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

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "number": "12125550123",
      "info": {
        "uuid": "NUMBER_ID_FROM_RESPONSE",
        "prefix_uuid": "PREFIX_ID_FROM_RESPONSE",
        "area_uuid": "AREA_ID_FROM_RESPONSE",
        "country_uuid": "COUNTRY_ID_FROM_RESPONSE",
        "country_iso": "US",
        "prefix": "+1212",
        "name": "Example area",
        "state": "US"
      },
      "price": [
        {
          "uuid": "PRICE_PLAN_ID_FROM_RESPONSE",
          "per_minute": "0.01",
          "per_sms": "0",
          "per_mms": "0",
          "free_minutes": "0",
          "setup_price": "1.00",
          "monthly_price": "2.00",
          "yearly_price": "0",
          "channels": "2"
        }
      ],
      "contract": {
        "term": "1 month",
        "renewal": "monthly",
        "notice": "none"
      },
      "restrictions": {
        "needs_registration": "0",
        "restrictions": ""
      },
      "features": [
        "voice"
      ],
      "overflow": "0"
    }
  ]
}

Ошибки

• 401: ошибка аутентификации. При неверных или отсутствующих учётных данных либо отказе в доступе к учётной записи API результаты поиска не возвращаются.
• 404: Invalid prefix ID, Invalid country, Invalid area или No numbers found. Прочитайте status.msg; ответ с ошибкой не является массивом номеров.
• 400: NUMBER_FILTER_INVALID в response.code: недопустимый режим, значение, не соответствующее требованию 1–15 цифр, либо filter_required без одновременного указания режима и значения.
• 422: NUMBER_FILTER_UNSUPPORTED в response.code: либо номер для префикса назначается при заказе (reason=order_only_prefix, а next_function указывает маршрут оформления заказа), либо явно выбранный источник не поддерживает требуемый фильтр.

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

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