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

Замовлення за префіксом

Використовуйте цю операцію, коли каталог префіксів пропонує замовити певну кількість номерів за префіксом замість вибору окремих доступних номерів. Почніть із країн, регіонів або штатів і префіксів. Збережіть ідентифікатор префікса й тарифний план з одного й того самого свіжого результату. Для конкретного номера, вибраного зі списку доступних номерів, скористайтеся операцією Придбання вибраного телефонного номера.

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

Надсилання запиту на придбання

Використовуйте активований обліковий запис 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-адресою зворотного виклику не оновлює початкове замовлення; воно створює окрему спробу придбання. Збережіть початковий ідентифікатор замовлення, коли просите службу підтримки дослідити його зворотний виклик.

Помилки, які потрібно обробляти