Держите бренд и вариант использования вместе
Используйте идентификатор бренда в вашей учётной записи и значение варианта использования, возвращённое списком квалификации того же бренда. Клиентский рабочий процесс проверяет принадлежность перед запросом к провайдеру. Убедитесь, что значение usecase возвращённого объекта совпадает с выбранным значением. Запрос для одного бренда или варианта использования не устанавливает требования для другого.
Прочитайте текущие требования
| Поле | Как портал его использует |
|---|---|
| minSubUsecases / maxSubUsecases | Минимальное и максимальное количество подвариантов использования для этого выбора. Выбирайте значения из каталога допустимых подвариантов использования, а не вводите произвольный текст. |
| mnoMetadata | Требования конкретных операторов, сгруппированные по идентификатору оператора. Для выбора операторов используйте идентификаторы, присутствующие в текущем ответе. |
| mnoSupport / qualify | Поддержка и квалификация оператора. Портал исключает операторов, у которых любое из этих полей явно имеет значение false, и требует хотя бы одного допустимого выбранного оператора. |
| minMsgSamples | Требуемое количество образцов для оператора. Портал требует хотя бы один непустой образец и выполняет наибольший минимум среди допустимых выбранных операторов. |
| reqSubscriberOptin / reqSubscriberOptout / reqSubscriberHelp | Обязательные декларации для абонентов. Там, где это требуется, соответствующая декларация должна иметь значение true. Для включённых деклараций также необходимы поля ключевых слов и ответных сообщений. |
| noEmbeddedLink / noEmbeddedPhone | Ограничения на встроенные ссылки или телефонные номера. Портал отклоняет заявленную функцию, если допустимый выбранный оператор её запрещает. |
Применяйте требования выбранных операторов совместно
Требования операторов могут различаться. Если явный список операторов не передан, портал учитывает все метаданные операторов в ответе; непустой список ограничивает проверки выбранными идентификаторами. Не используйте только количество образцов или декларации первого оператора. Выбирайте операторов из ответа, проверяйте поддержку и квалификацию, выполняйте наибольший применимый минимум образцов и удовлетворяйте обязательные декларации подписки, отписки и помощи по всему этому выбору. Портал отклоняет выбранные идентификаторы операторов, отсутствующие в текущем ответе, и отклоняет выбор без допустимого оператора.
Требования описывают, что должно быть предоставлено; они не доказывают, что процесс получения согласия клиента или содержимое кампании соответствует этим требованиям. Собирайте правдивые, репрезентативные образцы и декларации. Не включайте декларации автоматически, чтобы форма прошла проверку.
Подготовьте образцы и ответы абонентам
Текущая форма кампании использует поля с sample1 по sample5 для образцов сообщений. Если требования невозможно выполнить в рамках доступной формы, остановитесь и урегулируйте выбор со службой поддержки. Для включённой декларации абонента укажите соответствующие ключевые слова и текст ответа: optinKeywords/optinMessage, optoutKeywords/optoutMessage и helpKeywords/helpMessage. Образцы должны соответствовать выбранному варианту использования и реальным сообщениям клиента.
Проверьте перед любым запросом на регистрацию
Обновляйте требования при изменении бренда, варианта использования или выбора операторов. Портал повторно проверяет выбранный вариант использования, количество подвариантов использования, допустимость операторов, образцы и декларации перед созданием. Отдельно ознакомьтесь с тарифами учётной записи и условиями регистрации. Этот запрос GET не регистрирует и не одобряет кампанию, не передаёт её оператору обмена сообщениями и не назначает телефонный номер. Создание и подготовка к использованию являются отдельными операциями.
Обработка неудачного запроса требований
Если запрос завершается ошибкой, возвращает неожиданный JSON или не соответствует выбранному варианту использования, оставьте форму незавершённой и позвольте клиенту повторить попытку после устранения ошибки. Не заменяйте недоступные требования пустым объектом и не считайте, что отсутствие данных означает отсутствие требований. Учитывайте заголовок Retry-After и используйте экспоненциальную задержку при ограничениях частоты запросов и сбоях доступности.
Запрос
Используйте включённую учётную запись API по HTTPS с разрешённого IP-адреса источника. Текущий маршрут поддерживает политику аутентификации учётной записи, включая аутентификацию Basic и включённые учётные записи API с bearer-токеном. Не используйте учётные данные провайдера.
GET с идентификатором бренда и выбранным значением варианта использования в пути URL. Тело запроса не требуется.
curl --fail-with-body --silent --show-error \
--user "$API_USER:$API_PASSWORD" \
"https://api.multitel.net/tcr/v2/campaignBuilder/brand/$BRAND_ID/usecase/$USECASE"| Имя | Тип | Обязательный | Описание |
|---|---|---|---|
brand_id | string | Да | Идентификатор бренда в реестре, связанный с вашей аутентифицированной учётной записью MultiTEL. Используйте идентификатор бренда, а не идентификатор строки локальной базы данных, идентификатор кампании или налоговый номер компании. Кодируйте его как один сегмент пути URL. |
usecase | string | Да | Машиночитаемое значение usecase, выбранное из списка квалификации того же бренда. Сохраняйте его регистр; не отправляйте переведённую отображаемую метку. Кодируйте его как один сегмент пути URL. |
Ответ
Текущий маршрут TCR возвращает тело JSON реестра напрямую и сохраняет его HTTP-статус. Он не добавляет устаревшую обёртку status/response версии v3. Сокращённый вымышленный пример не является реальным результатом квалификации. Перед использованием проверьте HTTP-статус и ожидаемую структуру JSON. Портал ожидает объект, у которого usecase совпадает с выбранным вариантом использования. Требования операторов находятся в mnoMetadata, сгруппированные по идентификатору оператора. Идентификатор оператора и требования в примере вымышлены. Могут быть возвращены и другие поля провайдера.
Иллюстративная структура ответа; не реальные данные учётной записи и не актуальное ценовое предложение.
{
"usecase": "2FA",
"minSubUsecases": 0,
"maxSubUsecases": 0,
"mnoMetadata": {
"12345": {
"mnoSupport": true,
"qualify": true,
"minMsgSamples": 1,
"reqSubscriberOptin": true,
"reqSubscriberOptout": true,
"reqSubscriberHelp": true,
"noEmbeddedLink": false,
"noEmbeddedPhone": false
}
}
}Ошибки
- 401: Аутентификация учётной записи не удалась. Проверьте учётные данные API, состояние включения и применимые ограничения по IP-адресу источника.
- 404: Бренд не связан с аутентифицированной учётной записью, либо провайдер не может найти запрошенный бренд или выбор. Локальный отказ в принадлежности возвращается до запроса к провайдеру.
- Другие ошибки реестра: HTTP-статус и тело ответа вышестоящей системы сохраняются. Недопустимый или недоступный вариант использования не является успешным пустым набором требований.
- 429: Достигнут лимит запросов учётной записи или общий лимит провайдера. Учитывайте Retry-After.
- 502/503: Сбой доступности транспорта, провайдера или ограничителя частоты запросов. Сохраните форму и повторите попытку с экспоненциальной задержкой.
Доступность и побочные эффекты
- Проверенный запрос GET проверяет принадлежность существующего бренда, обращается к реестру и записывает записи аудита запросов. Он не создаёт бренд или кампанию и не взимает регистрационный сбор.
- Метаданные о сборах провайдера не являются розничным ценовым предложением для клиента MultiTEL. Портал отдельно проверяет тарифы учётной записи перед последующим запросом на регистрацию.
- Квалификация и требования могут меняться. Обновите их для выбранного бренда и варианта использования перед отправкой. Успешный запрос не является одобрением кампании, назначением номера или разрешением начать рассылку сообщений.