Загрузка справочников для регистрации обмена сообщениями

Загрузите варианты перед созданием регистрационной формы

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

Выберите справочник

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

Обрабатывайте ответ TCR напрямую

Тело ответа поступает непосредственно от API TCR. В отличие от многих старых конечных точек /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 и старые аннотации цен в перечислениях нельзя считать контрактом этого маршрута в отношении цен.
Наличие поддерживаемой записи в справочнике не доказывает, что конкретный бренд соответствует требованиям этого сценария использования. Перед последующим запросом на регистрацию выполните проверку соответствия конкретного бренда требованиям, оформите декларации и согласия и проверьте цены для учётной записи.