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

Подтвердите, что мобильный инвентарь включён

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

Текущий устаревший маршрут не отклоняет надёжно каждый неприемлемый запрос. Учётная запись без включённого мобильного инвентаря может получить обычный инвентарь, в то время как ответ всё ещё говорит info.is_mobile: 1. Префикс бесплатных вызовов также может попасть в ветку инвентаря бесплатных номеров с этой меткой. Не используйте эту метку саму по себе для идентификации мобильной службы и не отправляйте обычные или бесплатные префиксы на эту конечную точку. Используйте подтверждённый мобильный каталог учётной записи и включённый рабочий процесс.

Храните каждый номер вместе с его собственным выбором цены

Для каждого кандидата храните number, info.uuid и список цен той же записи price вместе. Ответ также содержит метаданные префикса/области/страны, условия договора и регистрационные ограничения. Кандидаты отсортированы по месячной цене первого варианта цены по возрастанию; гарантированного стабильного порядка для равных цен нет. Не заменяйте возвращённый идентификатор номера на идентификатор области или префикса и не сочетайте его с идентификатором цены другого кандидата.

Полный ответ может содержать дополнительные метаданные и поля цен. Возвращённые features, значения каналов и restrictions описывают кандидата; они не являются гарантией того, что звонки, SMS, MMS или факс уже пригодны к использованию. Права учётной записи, регистрация и выбранный тарифный план по-прежнему применяются. Не считайте заполнители из примера действительными идентификаторами или ценами.

Используйте небольшое положительное количество

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

Различайте отсутствие запасов и сбой поиска

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

Перепроверьте перед покупкой

Поиск не резервирует запасы. Проверенная ветка пытается исключить уже купленные номера, но неудачный локальный поиск резервирований может оставить такого кандидата в результате. Доступность, владение, согласованные цены и регистрация должны быть проверены рабочим процессом покупки. Используйте свежий выбор с защищённым запросом покупки и сверьте инвентарь учётной записи после любого неопределённого результата покупки перед повторной попыткой. Никогда не покупайте только потому, что кандидат был возвращён.

Запрос

Используйте включённую API-учётную запись через HTTPS с разрешённого исходного IP-адреса. Мобильный инвентарь также должен быть включён для клиентской учётной записи; одной аутентификации API недостаточно для его включения.

GET с актуальным идентификатором индивидуального префикса и положительным целочисленным количеством в пути URL. Количество по умолчанию равно 1, если оно опущено. Используйте пример с 1; этот маршрут не обеспечивает единообразную проверку и применение универсального лимита результатов.

curl --fail-with-body --silent --show-error \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/v3/getmobiles/$PREFIX_ID/1"

Параметры пути
Имя	Тип	Обязательный	Описание
`prefix_id`	string	Да	Непрозрачный видимый идентификатор подходящего индивидуального мобильного префикса, полученный через обнаружение. Используйте префикс мобильной станции NPA/NXX, поддерживаемый вашей учётной записью; не подставляйте идентификатор области, сгруппированный идентификатор отображения, буквальный префикс набора номера или бесплатный префикс.
`quantity`	integer	Нет	Запрашиваемое количество кандидатов. По умолчанию 1. Укажите умеренное положительное целое число. Обычный запрос к провайдеру ограничивает количество на уровне 300, но это не является универсально валидированным вводом или гарантией размера ответа.

Ответ

Проверяйте status.code и status.msg в теле JSON, а также HTTP-статус. В случае успеха response является списком кандидатов-номеров, status.msg — это Results: с последующим числом возвращённых, а status.results — сериализованная длина списка. Цены кандидатов специфичны для учётной записи. Иллюстративный сокращённый пример использует заполнители вместо реального инвентаря или тарифного предложения. Номера содержат код страны без знака плюс; идентификаторы являются непрозрачными строками.

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

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "number": "12025550123",
      "info": {
        "uuid": "NUMBER_ID",
        "prefix_uuid": "PREFIX_ID",
        "country_iso": "US",
        "is_mobile": 1
      },
      "price": [
        {
          "uuid": "PRICE_ID",
          "monthly_price": "ACCOUNT_MONTHLY_PRICE",
          "setup_price": "ACCOUNT_SETUP_PRICE",
          "per_minute": "ACCOUNT_INCOMING_RATE",
          "channels": "PLAN_CHANNELS"
        }
      ],
      "features": [
        "voice",
        "sms",
        "mms",
        "t38"
      ]
    }
  ]
}

Ошибки

404: недопустимый идентификатор префикса, страны или области: обновите выбор индивидуального мобильного префикса.
404: номера не найдены: может означать отсутствие пригодных запасов, отключённую службу, сбой поиска провайдера, неподдерживаемый выбор или ограничения учётной записи. Это не является доказательством авторитетного нулевого подсчёта инвентаря.

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

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