Придбання вибраного телефонного номера

Вибирайте номер і ціну разом

Придбайте один конкретний номер, вибраний зі свіжих результатів пошуку доступних номерів. Використовуйте значення 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. Після підтвердження належності номера та його активації виконайте звичайні для облікового запису перевірки маршрутизації та тести послуг.