Заказ телефонных номеров по префиксу

Заказ по префиксу

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

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

Отправка запроса на покупку

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

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'quantity=1' \
  --data-urlencode "price_id=$PRICE_ID" \
  --data-urlencode "channels=$CHANNELS" \
  --data-urlencode "reference=$ORDER_REFERENCE" \
  --data-urlencode "uri=$VOICE_URI" \
  "https://api.multitel.net/v3/order/$PREFIX_ID"

Выше показан запрос POST с данными формы. Координатор также считывает объект JSON, если Content-Type имеет значение application/json. Поля JSON имеют приоритет над одноимёнными полями формы или запроса. Последовательно используйте один формат кодирования; не отправляйте противоречащие друг другу значения в строке запроса и теле.

Настройки доставки и продления

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

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

Проверка полного результата

Разберите тело JSON и проверьте status.code и status.msg, даже если HTTP-запрос выполнен успешно. Этот маршрут формирует собственный ответ JSON, а общая вспомогательная функция ответа также не обязательно сопоставляет код приложения со статусом HTTP. Коды приложения могут быть числами JSON или строками с числами. Не требуйте наличия status.results; в обычном результате заказа это поле отсутствует.

{
  "status": {"code": "200", "msg": ""},
  "response": {
    "id": "o_fictional_example",
    "numbers": ["12025550123"],
    "price": {
      "per_minute": "0.01",
      "free_minutes": 0,
      "setup_price": "1.25",
      "monthly_price": "2.50",
      "channels": 2
    },
    "features": ["voice"],
    "needs_registration": 0,
    "restrictions": "",
    "registration_requirements": null
  }
}

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

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

Частичные покупки и неопределённые результаты

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

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

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

Регистрация и активация

Купленный или выделенный номер всё ещё может требовать регистрации или активации. Если needs_registration равно 1, проверьте restrictions и registration_requirements. Последнее поле может указывать на v3/get_requirements со значениями country и number_type. Пройдите соответствующую процедуру подтверждения личности или адреса и убедитесь в статусе номера, прежде чем рассчитывать на входящие звонки или обмен сообщениями.

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

Обратные уведомления о заказе

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

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

Ошибки, которые необходимо обрабатывать