Обновление бренда для обмена сообщениями

Исправьте данные существующего бренда для обмена сообщениями

Обновляйте существующий бренд при изменении контактных данных компании или адреса. Сохраните идентификатор бренда; создание ещё одной регистрации не подходит для исправления данных существующей компании. Используйте активированную учётную запись API и подключайтесь по HTTPS с разрешённого исходного IP-адреса. Бренд должен принадлежать этой учётной записи.

Сначала получите текущую запись. Обеспечьте конфиденциальность локальной копии, поскольку она содержит идентификационные и контактные данные компании.

curl --silent --show-error --fail-with-body --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/tcr/v2/brand/$BRAND_ID" \
  --output current-brand.json

Сохраните текущие поля бренда

Подготовьте brand-update.json на основе текущей записи, выбрав только доступные для записи поля бренда. При внесении нужного исправления сохраните идентификационные данные компании и другие обязательные значения. Не отправляйте ответ GET целиком: brandId, результаты проверки идентификационных данных и статуса, временные метки и другие поля, предназначенные только для ответа, не должны включаться в обновление.

Схема обновления требует указать entityType, displayName, country, email и brandRelationship. Правила для соответствующего типа субъекта продолжают действовать. Для организации сохраните её юридическое наименование, налоговый идентификатор и страну его выдачи, адрес и отрасль, если они применимы. Для индивидуального предпринимателя вместо этого сохраните соответствующие поля имени и контактного мобильного телефона. Используйте реальные актуальные значения, а не заполнители из примера регистрации.

Группы полей обновления бренда
Поля	Как их использовать
displayName, email, phone	Узнаваемое название бренда и действительные контактные данные. Максимальная длина: 255, 100 и 20 символов. Указывайте телефон в международном формате со знаком + и кодом страны.
street, city, state, postalCode, country	Реальный адрес компании с согласованными данными. Ограничения: 255, 100, 20, 10 и 2 символа. Где применимо, используйте актуальные коды штатов США.
entityType, companyName, ein, einIssuingCountry	Юридические идентификационные данные. Их изменение ограничено, если кампании или внешняя проверка ожидают выполнения либо уже активны. Не удаляйте работающие кампании лишь для обхода ограничения на изменение идентификационных данных.
firstName, lastName, mobilePhone, businessContactEmail	Идентификационные данные или контакты для проверки, если они применимы к данному типу субъекта. Ограничения: 100, 100, 20 и 255 символов.
brandRelationship, vertical	Актуальные коды типа отношений и отрасли. Тип отношений можно менять не чаще одного раза в три месяца. Обычная форма редактирования на портале не позволяет менять тип отношений.
website, altBusinessIdType, altBusinessId, stockSymbol, stockExchange	Веб-сайт, альтернативные идентификационные данные компании и сведения о публичной компании, если применимо. Сохраните значения, необходимые для валидации субъекта.
referenceId, ipAddress	Поддерживаемые метаданные ссылки на компанию и исходного IP-адреса. Ни одно из этих полей не определяет принадлежность учётной записи и не служит ключом идемпотентности запроса.

Используйте актуальные каталоги обмена сообщениями для выбора кодов. Схема обновления не предусматривает использование mock для изменения среды бренда. Используйте отдельный проверенный процесс перехода из тестовой среды в рабочую, а не меняйте этот флаг при редактировании.

Отправьте проверенное исправление

curl --silent --show-error --fail-with-body --user "$API_USER:$API_PASSWORD" \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data-binary @brand-update.json \
  "https://api.multitel.net/tcr/v2/brand/$BRAND_ID"

Используйте один ключ для этого запланированного обновления и сохраните точные байты тела запроса. Повторное использование ключа с изменённым методом, путём, строкой запроса или телом вызывает конфликт; изменение форматирования JSON также меняет отпечаток. Дубликат запроса, который ещё обрабатывается, может вернуть 409 с Retry-After. Для завершённого запроса может быть повторно возвращён сохранённый результат, в том числе ошибка. При выяснении результата после истечения времени ожидания сохраняйте сведения о запросе, а не создавайте автоматически новый ключ.

Проверьте сохранённую запись и состояние валидации

При успешном обновлении возвращаются HTTP 200 и непосредственно объект бренда в формате JSON, без устаревшей оболочки v3 status/response. Проверьте его brandId, затем снова получите тот же бренд запросом GET и сравните нужные поля. Публичный маршрут обновления не принимает используемую порталом оболочку changes/version и не выполняет его оптимистическую проверку конкурентных изменений. Согласовывайте одновременное редактирование; ключ идемпотентности предотвращает повторную отправку, но не изменения, вносимые другим редактором.

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

Сохранение исправленных сведений не запрашивает автоматически новую проверку идентификационных данных и не гарантирует одобрение. Повторная проверка — отдельное действие, которое может быть платным; проверьте текущее состояние на портале и явно подтвердите указанную плату, если она предусмотрена. Обычные обновления бренда методом PUT не вызывают отдельного списания за регистрацию в текущем сервисе API. Существующие платежи за кампании, обмен сообщениями и другие услуги учитываются отдельно.

Устраните ошибки без создания дублирующей регистрации

Прочитайте статус HTTP и сведения об ошибке в JSON. При 400 исправьте указанное поле или соблюдайте ограничение на изменение идентификационных данных либо типа отношений. При 401, 403 или 404 проверьте учётные данные, разрешённый исходный IP-адрес и принадлежность бренда учётной записи. При 429 соблюдайте Retry-After. Ошибка 500 или 502 может возникнуть уже после того, как реестр принял обновление; сохраните requestId, если он есть, и получите существующую запись перед повторной отправкой.

Непустой, но неполный ответ на обновление может привести к неполному локальному снимку; пустое тело успешного ответа может оставить в снимке старые значения полей. Не делайте вывод о сохранении полей только по статусу успешного выполнения. Повторно получите полную запись бренда и устраните любые расхождения через службу поддержки. Это руководство не гарантирует атомарность обновлений реестра, локального кэша и биллинга.