Намерете налични телефонни номера

Изберете отделен префикс

Използвайте извикванията за откриване на държави и области на покритие, след което извикайте getprefixes без групиране. За избрания префикс копирайте стойността на uuid. Ако returns_numbers е 0, номерът за префикса се присвоява при поръчка; използвайте върнатата стойност на next_function вместо да изисквате списък с отделни номера.

Прегледайте партида с ограничен размер

За обичайно търсене използвайте compact=1 и задайте желания размер на партидата както в пътя, така и чрез параметъра quantity в URL заявката, както е показано по-долу. Няма параметър за страница или курсор. Компактният резултат е извадка; повторението на заявката не гарантира следваща страница без припокриване. Не приемайте празен резултат или резултат с малко записи за общия брой налични номера.

Намерете лесна за запомняне последователност от цифри

Подайте 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 не установява мобилните възможности на конкретен номер.