Дізнатися ім’я абонента, що телефонує

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

Повернуте ім’я не підтверджує особу, право власності або дозвіл на дзвінок. Ім’я може бути відсутнім, застарілим, скороченим, позначенням місцевості або замінюватися номером телефону.

Запит

Використовуйте свій активований обліковий запис API з дозволеної для нього вихідної IP-адреси. Зберігайте облікові дані в серверному сховищі секретів. У прикладі використано змінні середовища та вигаданий північноамериканський номер; не розміщуйте облікові дані в URL-адресах або загальнодоступному коді для браузера.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  https://api.multitel.net/v3/cnam/12025550123

Передавайте повний номер цифрами, включно з кодом країни, наприклад одинадцять цифр, що починаються з 1, для Північної Америки. Не покладайтеся на те, що обробник нормалізує розділові знаки або знак плюса. Тіло запиту чи засіб вибору регіону не потрібні. Уточніть у MultiTEL підтримуване покриття для запланованого використання.

Відповідь

Значення наведено лише для прикладу; зазначена вартість не є ціновою пропозицією.

{
  "status": {
    "code": 200,
    "msg": ""
  },
  "response": {
    "number": "12025550123",
    "name": "EXAMPLE NAME",
    "cost": 0.0037,
    "balance": 9.9963
  }
}

Поля запиту імені абонента
Поле	Значення
number	Номер, щодо якого надіслано запит.
name	Доступне ім’я або резервний текст. Це не підтвердження особи.
cost	Налаштована для облікового запису чи служби ціна запиту, яку повертає цей шлях виконання. Керуйтеся поточним тарифом облікового запису, а не значенням із прикладу.
balance	Баланс, розрахований для відповіді. Це не новий транзакційний запит балансу облікового запису.

Нарахування та звіряння

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

Існує відоме обмеження відповіді для порожнього імені в кеші: обробник може повернути код API 200 з порожнім іменем, ненульовою вартістю та зменшеним розрахованим балансом, хоча ця гілка виконання не списує кошти з облікового запису. Не вважайте саму цю відповідь доказом списання. Звірте дані з платіжними записами облікового запису та результатом нового запиту: перевірка балансу; якщо результати неоднозначні, зверніться до служби підтримки.

Наразі перевірка передоплати вимагає балансу щонайменше 0.004 перед виконанням запиту, незалежно від налаштованої ціни за запит. Запит також відхиляється, якщо для облікового запису вимкнено покупки. Ці перевірки не перетворюють цю кінцеву точку на API для отримання цінових пропозицій або обмеження витрат.

Помилки та повторні спроби

Перевіряйте як статус HTTP, так і поля status.code/status.msg у JSON. Код API 403 може означати недостатній залишок передоплати, заборону покупок, проблему з авторизацією облікового запису або те, що ім’я абонента не знайдено. Шлях виконання для відсутнього імені може повернути код як рядок. Переглядайте повідомлення, а не трактуйте кожен 403 як ознаку неправильних облікових даних. Конфлікти конфігурації можуть спричинити повернення коду API 500.

Час очікування може сплинути вже після виконання платного запиту. Застосовуйте обмежену кількість повторних спроб зі збільшенням інтервалу очікування лише тоді, коли це доречно для вашого застосунку, і спочатку звіряйте спроби з невизначеним результатом. Не повторюйте запити багаторазово для відхиленого номера або після помилки, пов’язаної з дозволами чи балансом облікового запису. Кеш відповідей у вашому застосунку може зменшити кількість повторних запитів за умови дотримання вашої угоди та вимог до точності.

Інші операції з номерами

Ця операція читання є окремою від оновлення імені для вихідних викликів / LIDB, внесення до телефонного довідника чи реєстрації абонента, що телефонує. Для цих операцій передбачені власні обов’язкові поля, авторизація та плата. Використовуйте перевірку покриття розподілу номерів для перевірки за таблицею префіксів або пошук номерів для пошуку номерів, доступних для замовлення. Жодна з цих операцій не підтверджує, що абонент є тим, за кого себе видає.