Завантаження довідників для реєстрації обміну повідомленнями

Завантажуйте варіанти перед створенням реєстраційної форми

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

Виберіть довідник

Довідники, які використовує портал
Назва	Призначення
usecase	Визначення сценаріїв використання кампаній. Додавайте validSubUsecase=true під час завантаження варіантів підсценаріїв.
entityType	Тип підприємства або організації бренду.
vertical	Варіанти галузі для бренду.
altBusinessIdType	Категорії альтернативних ідентифікаторів бізнесу.
brandRelationship	Варіанти зв’язку, які використовуються в реєстраційній формі.
country	Варіанти країн у реєстрі; вони відокремлені від країн, у яких доступні телефонні номери.
usState	Варіанти штатів США для реєстраційних адрес.
stockExchange	Варіанти фондових бірж, якщо їх вимагає тип бізнесу бренду.
cnp	Ідентифікатори партнерів із забезпечення зв’язку. Виберіть партнера, якого підтримує процес роботи з кампаніями у вашому обліковому записі.

Обробляйте відповідь TCR безпосередньо

Тіло відповіді надходить безпосередньо від TCR API. На відміну від багатьох старіших кінцевих точок /v3, воно не має додаткової обгортки status/response. Перш ніж інтерпретувати тіло, перевірте статус HTTP. Довідник може містити текстові назви або структуровані визначення, тому не припускайте, що всі значення мають однакові поля. Якщо запит HTTP успішний, але тіло не є коректним JSON очікуваної структури, повідомте про невдалий пошук, а не замінюйте результат порожнім списком без попередження.

Відокремлюйте варіанти довідника від перевірки відповідності вимогам і ціноутворення

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

Обробляйте недоступність довідників

Якщо пошук не вдався, збережіть дані, введені клієнтом у формі. Покажіть помилку, дотримуйтеся вказівок Retry-After за наявності цього заголовка у відповіді та збільшуйте інтервали між повторними спробами. Не завантажуйте всі довідники знову й знову та не трактуйте помилку обмеження частоти запитів чи передавання даних як порожній коректний довідник. Цей запит GET не потребує ключа ідемпотентності, а його відповідь не відтворюється зі сховища ідемпотентності операцій зміни даних.

Запит

Використовуйте ввімкнений обліковий запис API через HTTPS з дозволеної вихідної IP-адреси. Поточний маршрут підтримує політику автентифікації облікового запису, зокрема автентифікацію Basic та ввімкнені облікові записи API з автентифікацією за токеном пред’явника. Не використовуйте облікові дані постачальника.

Надсилайте запит GET з підтримуваною назвою довідника в шляху. Відповідні фільтри довідника передавайте в рядку запиту. Тіло запиту не потрібне.

curl --fail-with-body --silent --show-error \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/tcr/v2/enum/usecase?validSubUsecase=true"

Параметри шляху
Назва	Тип	Обов’язковий	Опис
`type`	рядок	Так	Назва довідника зі збереженням оригінального регістру літер. Портал використовує usecase, entityType, vertical, altBusinessIdType, brandRelationship, country, usState, stockExchange та cnp. Це назви довідників, а не ідентифікатори брендів чи кампаній.

Параметри рядка запиту
Назва	Тип	Обов’язковий	Опис
`validSubUsecase`	логічне значення	Ні	Для довідника usecase портал передає true, щоб завантажити допустимі варіанти підсценаріїв використання. Не вказуйте цей параметр під час завантаження звичайного довідника сценаріїв використання. Доступність і визначення надає реєстр.

Відповідь

Цей маршрут TCR повертає тіло відповіді реєстру безпосередньо разом із його статусом HTTP. Він не використовує старішу обгортку v3 status.code/status.msg/response. Структури довідників різняться: одні зіставляють значення з описовими об’єктами, інші — з рядками. Зберігайте машинозчитувані ключі під час подальшого надсилання форми. Скорочений вигаданий приклад usecase ілюструє відображення зі значеннями-об’єктами, а не актуальний довідник чи гарантовано повну схему. Перевіряйте і статус HTTP, і очікувану структуру JSON.

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

{
  "2FA": {
    "displayName": "Authentication",
    "description": "Example authentication use case"
  }
}

Помилки

401: Не вдалося автентифікувати обліковий запис. Перевірте облікові дані API, чи ввімкнено обліковий запис, і застосовні обмеження вихідних IP-адрес.
400/404 та інші помилки реєстру: некоректний або недоступний довідник чи фільтр. Поточний маршрут зберігає статус HTTP і тіло відповіді вищестоящого сервісу; універсальної обгортки помилок v3 немає.
429: Досягнуто ліміту запитів облікового запису або спільного ліміту постачальника. Дотримуйтеся вказівок Retry-After і повторюйте спроби зі збільшенням інтервалів.
502: Не вдалося зв’язатися з реєстром. Доступність невідома; не підставляйте порожній список варіантів як успішний результат.
503: Обмежувач запитів або вищестоящий сервіс недоступний. Перш ніж повторювати спробу, перевірте тіло відповіді та заголовок Retry-After, якщо він є.

Доступність і побічні ефекти

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