Покупка выбранного телефонного номера

Выбирайте номер и цену вместе

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

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

Отправьте запрос на покупку методом POST с защитными проверками

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

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode "restore_quote_price_id=$PRICE_ID" \
  --data-urlencode "restore_quote_setup=$SETUP_PRICE" \
  --data-urlencode "restore_quote_monthly=$MONTHLY_PRICE" \
  --data-urlencode "restore_quote_per_minute=$PER_MINUTE_PRICE" \
  --data-urlencode "restore_quote_channels=$CHANNELS" \
  "https://api.multitel.net/v3/rentnumber/$NUMBER_ID/$PRICE_ID"

Отправляйте данные формы методом POST, как показано в примере. Вспомогательная функция также разбирает JSON и обёртку параметров, но в рамках этой проверки не установлена полная эквивалентность для всех вариантов обработки ценовых предложений и поставщиков. Не используйте GET для покупки, хотя в этом устаревшем координаторе нет явной проверки метода.

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

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

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

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

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

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

Не допускайте незаметной подмены тарифа

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

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

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

Дополнительно: маршрутизация учётной записи по умолчанию

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

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

Ответ

Вымышленный пример простой покупки без осложнений; значения и возможности зависят от выбранного тарифа.

{
  "status": {
    "code": 200,
    "msg": ""
  },
  "response": {
    "number": "12025550123",
    "price": {
      "per_minute": "0.0100",
      "free_minutes": "100",
      "setup_price": "2.00",
      "monthly_price": "4.00",
      "channels": "2",
      "overflow": "0"
    },
    "features": [
      "voice"
    ],
    "needs_registration": 0,
    "registration_requirements": null
  }
}

Координатор использует собственные поля status.code/status.msg и структуру response; наличие поля status.results не гарантируется. При ошибке список в ответе обычно пуст. При успехе проверьте возвращённые номер и цену, затем сверьте список номеров учётной записи и состояние регистрации. Принятие заказа поставщиком не является проверкой реальной работы голосовых вызовов, SMS или факса.

Ошибки и неопределённые результаты

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

Сверьте состояние перед повторной попыткой

1. Сохраните согласованные номер, цену и предельные значения ценового предложения в записи заказа вашего приложения перед однократной отправкой запроса.
2. После запроса, в том числе после тайм-аута или ошибки, прочитайте список приобретённых номеров и сведения о номере в той же учётной записи.
3. Если номер присутствует, проверьте его цену, продление, маршрутизацию и состояние регистрации вместо отправки ещё одного запроса на покупку.
4. Если результат по-прежнему неясен, перед повторной попыткой попросите службу поддержки сверить заказ у поставщика и начисления по учётной записи. Одного сообщения об ошибке или флага успеха в устаревшем журнале недостаточно для вывода о результате.
5. После подтверждения принадлежности номера и его активации выполните обычные для учётной записи проверки маршрутизации и тесты услуг.