Знайдіть доступні телефонні номери

Виберіть окремий префікс

Скористайтеся викликами для отримання переліку країн і зон покриття, а потім викличте getprefixes без групування. Скопіюйте значення вибраного префікса в полі uuid. Якщо returns_numbers дорівнює 0, номер для цього префікса призначається під час замовлення; використовуйте повернене значення next_function замість того, щоб вимагати список окремих номерів.

Перегляньте порцію результатів обмеженого розміру

Для звичайного пошуку використовуйте compact=1 і вкажіть бажаний розмір порції як у шляху, так і в параметрі запиту quantity, як показано нижче. Параметрів сторінки чи курсора немає. Компактний результат є вибіркою; повторний запит не гарантує отримання наступної сторінки без повторів. Не вважайте порожній або невеликий результат показником загальної кількості доступних номерів.

Знайдіть комбінацію цифр, яку легко запам’ятати

Передайте number_filter_mode=contains або ends_with разом із number_filter_value. Значення має містити 1–15 цифр. Перш ніж застосувати фільтр, пошук може отримати обмежені порції номерів-кандидатів, тому інші доступні номери, що відповідають умовам, можуть не потрапити до результатів. Якщо для виконання потрібного пошуку вам необхідне джерело з відповідною підтримкою, отримайте селектор pid від MultiTEL і використовуйте filter_required=1; якщо джерело не вибрано або вибір не підтримується, API повертає помилку.

Перегляньте вибраний номер

Зчитайте number, info.uuid, вибране значення price[].uuid, назви доступних функцій і вимоги до реєстрації з того самого результату. Масив price може містити кілька тарифних планів із різною кількістю каналів і ставками. Грошові поля та кількісні значення можуть бути закодовані як рядки. Необов’язкові метадані, зокрема info.state, відрізняються залежно від джерела; не вимагайте єдиної універсальної структури поля стану й не визначайте ціни за ідентифікатором.

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

Оформіть замовлення окремо та перевірте результат

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

Запит

Використовуйте активний обліковий запис API MultiTEL: облікові дані HTTP Basic для облікового запису з паролем або Authorization: Bearer для облікового запису з токеном. Діють дозволи облікового запису та його обмеження за IP-адресами. Див. загальні вказівки щодо автентифікації.

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

curl --fail-with-body --get \
  --user "${MULTITEL_API_USERNAME}:${MULTITEL_API_PASSWORD}" \
  --data-urlencode "compact=1" \
  --data-urlencode "quantity=10" \
  "https://api.multitel.net/v3/getnumbers/${PREFIX_ID}/10"

Відповідь

Один об’єкт JSON, що містить status і response. У разі успіху status.code дорівнює 200, а response є масивом записів номерів. status.results — кількість елементів поверненого масиву; status.msg може мати значення Results: N або OK для потокової відповіді. Без compact=1 деякі пошуки записують масив response поступово й завершуються полем status, тому дочекайтеся повного тіла JSON. Це не JSON із розділенням записів символами нового рядка. Перевіряйте status.code, навіть якщо передавання через HTTP завершилося успішно. Нижче наведено типові поля; метадані окремих джерел і необов’язкові поля можуть відрізнятися. Вважайте кожен ідентифікатор непрозорим значенням і зберігайте номер разом із вибраним для нього price[].uuid.

Приклад структури відповіді; це не фактичні дані облікового запису й не актуальна цінова пропозиція.

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "number": "12125550123",
      "info": {
        "uuid": "NUMBER_ID_FROM_RESPONSE",
        "prefix_uuid": "PREFIX_ID_FROM_RESPONSE",
        "area_uuid": "AREA_ID_FROM_RESPONSE",
        "country_uuid": "COUNTRY_ID_FROM_RESPONSE",
        "country_iso": "US",
        "prefix": "+1212",
        "name": "Example area",
        "state": "US"
      },
      "price": [
        {
          "uuid": "PRICE_PLAN_ID_FROM_RESPONSE",
          "per_minute": "0.01",
          "per_sms": "0",
          "per_mms": "0",
          "free_minutes": "0",
          "setup_price": "1.00",
          "monthly_price": "2.00",
          "yearly_price": "0",
          "channels": "2"
        }
      ],
      "contract": {
        "term": "1 month",
        "renewal": "monthly",
        "notice": "none"
      },
      "restrictions": {
        "needs_registration": "0",
        "restrictions": ""
      },
      "features": [
        "voice"
      ],
      "overflow": "0"
    }
  ]
}

Помилки

• 401: Помилка автентифікації. За неправильних або відсутніх облікових даних чи відхиленого доступу до облікового запису API результати пошуку не надаються.
• 404: Invalid prefix ID, Invalid country, Invalid area або No numbers found. Прочитайте status.msg; відповідь із помилкою не є масивом номерів.
• 400: NUMBER_FILTER_INVALID у response.code: неправильний режим, значення, що не складається з 1–15 цифр, або filter_required без одночасного зазначення режиму та значення.
• 422: NUMBER_FILTER_UNSUPPORTED у response.code: або номер для префікса призначається під час замовлення (reason=order_only_prefix, а next_function вказує маршрут замовлення), або явно вибране джерело не може підтримувати потрібний фільтр.

Доступність і побічні дії

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