# ADR-0025. Сообщения участникам через Management API

- Статус: принято; реализовано на этапе 7 — 7k-1 (каналы мерчанта и лимиты кодов), 7k-2 (шаблоны, автосообщения,
  настройки сообщений и кабинет покупателя), 7k-3 (журнал и очередь сообщений, согласия участника и вебхук согласий)
- Дата: 2026-11-08 (решения владельца продукта — 2026-11-07)

## Контекст

Всё, что дал этап 7, — каналы мерчанта (ADR-0020), кабинет покупателя (ADR-0021), автосообщения (ADR-0022), MAX
(ADR-0023) и ВКонтакте (ADR-0024) — мерчант настраивает только в своём кабинете. Партнёр встраивает платформу в свой
продукт (ADR-0006) и должен настраивать мерчанта целиком оттуда.

Решения владельца продукта (2026-11-07):

- в Management API — настройки этапа 7, журнал и очередь сообщений и вебхуки о согласиях на рекламу; своих сообщений
  участникам партнёр через API не отправляет;
- партнёр может подключать мерчанту SMS-аккаунт, почту, бота MAX и сообщество ВКонтакте, но пароли и ключи передаются
  только в одну сторону.

## Решение

### Скоуп `communications`

- Новый скоуп «Сообщения: каналы, шаблоны и рассылки»: каналы мерчанта и лимиты кодов, с 7k-2 — шаблоны,
  автосообщения и настройки сообщений.
- Каналы доходят до телефонов участников и тратят деньги мерчанта на SMS, поэтому разработчик партнёра этот скоуп не
  выдаёт (`Credentials::NOT_FOR_DEVELOPERS`, как `members`, `audit` и `widgets`, ADR-0013). Владелец и администратор
  партнёра выдают, мерчант может выпустить свой ключ с ним.
- **Подключить канал или заменить его пароль** — `POST /sms-channels`, `:replace-credentials`, `PUT /email-channel`,
  `/max-bot`, `/vk-community` — могут только учётные данные со скоупами `communications` и `members`. Через
  подключённый аккаунт идут номера, адреса и коды участников, и их видит хозяин аккаунта. Так же ключ кассы выпускают
  только с `organization` и `members` (ADR-0006).
- Кабинет перед подключением канала и публикацией просит недавнее подтверждение — код или пароль. У API его нет: права
  даёт сам ключ, как `programs` для акций.

### Каналы и лимиты кодов (7k-1)

- SMS-каналы: `GET`/`POST /sms-channels`, `PUT`/`DELETE /sms-channels/{channel}`, `:replace-credentials`, `:move`,
  `:check`, `:disable`, `:enable`. `PUT` меняет имя отправителя, коды в Telegram и название целиком: каждое поле —
  каким должно стать.
- Почта: `GET`/`PUT`/`DELETE /email-channel`, `:change-sender`, `:check`, `:disable`, `:enable`. У `:change-sender`
  оба поля обязательны: без `from_name` имя не сохранилось бы молча, а стёрлось бы.
- Бот MAX и сообщество ВКонтакте: `GET`/`PUT`/`DELETE /max-bot` и `/vk-community`, `:check`, `:disable`, `:enable`.
- `PUT` почты, бота и сообщества подключает или заменяет подключённое: 201, если его не было, и 200, если заменил.
  Ответ выбирается по id канала до и после: замена сохраняет id. Другой бот или сообщество, другая программа на месте
  прежних забывают подключения участников, как в кабинете.
- Каналов нет — 404 `channel_not_found`.
- **Удаление можно повторить.** SDK повторяют `DELETE`, чей ответ потерялся (sdk/README.md). Поэтому повтор отвечает
  204, как и само удаление: канала, удалённого раньше или чужого, нет. Повтор удаления почты, бота или сообщества
  удалит и то, что успели подключить между запросом и повтором. Это цена одиночного ресурса без id в адресе.
- **Лимиты кодов:** `GET`/`PUT /code-limits`. Остановку кодов из-за низкой доли подтверждённых API показывает
  (`suspended_until`), но не снимает. Это тормоз против накрутки SMS: скрипт, который снимал бы его сразу, сделал бы
  тормоз бесполезным. Снимает его человек в кабинете, подтвердив, кто он.
- **Пароли — только в одну сторону.**
  - `login`, `secret`, `password` и `token` читаются из тела таким, каким его прислали (`ReadsCredentialsAsSent`).
    Глобальный TrimStrings обрезал бы пробелы, и пароль с пробелом на краю дошёл бы до провайдера другим. Кабинет
    передаёт поля так же: Livewire обходит TrimStrings.
  - Дальше их берут контракты модуля `communications`. Как в кабинете, они проверяют пароли у провайдера, прежде чем
    сохранить, и хранят зашифрованными (ADR-0020).
  - Ответы знают только половину логина (`login_hint`).
  - Журнал аудита не хранит ни логина, ни пароля: ключ `login` стал чувствительным в `SensitiveDataRedactor`, а
    `secret`, `password` и `token` были им и раньше. Кроме того, редактор маскирует логин и пароль внутри адреса
    (`smtp://логин:пароль@сервер` и без схемы). Сервер почты иногда вводят именно так, а такая строка уходит в
    журнал и в логи.
  - PHP SDK помечает тело запроса как чувствительное (`#[\SensitiveParameter]`, `SensitiveParameterValue`). Дамп
    запроса показывает только размер тела, трассировка ошибки — не показывает его вовсе.
- **Отказы провайдера.**
  - При подключении и замене паролей — 422 `channel_refused` с причиной `reason`, ничего не сохраняется.
  - При проверке — не ошибка запроса, а состояние канала (`health`, `health_reason`). После отказа за нехваткой денег
    API, как и кабинет, не показывает прежний баланс.
  - Подключения и проверки считают лимиты контрактов (`RequestLimits`): 429 `channels_throttled` с `Retry-After`.
  - Отказы в логине останавливают запросы к этому провайдеру ступенями: сначала у мерчанта (3 за 10 минут), потом у
    всех мерчантов его партнёра (5), потом у всех (10). Ступень партнёра появилась в 7k-1. Партнёр достаёт все свои
    мерчанты через API и заводит новые, поэтому без неё он один закрыл бы провайдера остальным: провайдер блокирует
    адрес платформы.
- **Ошибки называют поле запроса.** Контракты называют пароль почты `secret`, а лимиты — `daily` и `monthly`. API
  отвечает `field` = `password`, `daily_limit` и `monthly_limit`, как в теле.
- **Проверочных SMS и писем API не отправляет.** Это было бы сообщение на номер или адрес, который назвал сервер.
  Проверочные отправки остаются в кабинете.
- **Приостановленный мерчант только читает.** Каждое изменение — 403 `merchant_suspended`, как в кабинете, где
  `channels.manage` — право на изменение.
- **Журнал аудита.**
  - Операции называются как действия кабинета (`channels.store`, `email-channel.update` и другие). Новые имена —
    чтения `channels.index`, `code-limits.show`, `email-channel.show`, `max-bot.show` и `vk-community.show`.
  - Пишется `management.audit`: данных участников в ответах нет.
  - У почты, бота и сообщества в адресе нет id. Запись всё равно называет канал (`RecordAudit::SUBJECT`), как
    записи кабинета.
  - Отказы 429 API в журнал не пишет: так для всех операций (ADR-0010).
- Коды ошибок каналов перешли из внутренних в каталог Management API.

### Автосообщения, настройки сообщений и кабинет покупателя (7k-2)

- **Шаблоны** (скоуп `communications`): `GET /programs/{program}/message-templates`, `…/{topic}/versions`,
  `…/{topic}/preview?text=`, `POST …/{topic}:publish` и `…/{topic}:restore`.
  - Публикация — новая версия поверх текущей, какой бы она ни была: так API пишет правила, акции и действия. Форма
    кабинета публикует от версии, с которой открылась, и только она получает `message_template_outdated`
    (`PublishTemplate::$basedOnVersion` null — поверх текущей).
  - Вернуть стандартный текст — отдельная операция `:restore`. Если бы стандартный текст означал `text: null`, пустая
    строка, которую ConvertEmptyStringsToNull превращает в null, молча вернула бы стандартный текст вместо отказа.
  - Текст читается таким, каким его прислали (`ReadsTextAsSent`: из строки запроса `GET`, из тела JSON или формы):
    пробелы и переводы строк по краям считаются в SMS, как в кабинете, где Livewire обходит TrimStrings.
  - Предпросмотр — `GET`: проверяет текст так же, как публикация, и показывает его, как прочтёт участник, — с
    примерами значений и ссылкой той длины, какую даёт платформа (`RedemptionNotices::sampleLink`), — и сколько SMS
    он займёт. Баллы поздравления с днём рождения в нём — пример, а не баллы правил программы, как в форме кабинета:
    размер может разойтись на несколько знаков.
  - Журнал аудита не хранит текст ни публикации, ни предпросмотра, даже отклонённых (`RecordAudit::WITHHELD`): запись
    таких операций хранит только, прислан ли текст, — и ничего больше, чтобы текст не остался в поле другой формы. Так
    решено для кабинета (ADR-0020). Что опубликовано, хранит история шаблона: версии не меняются.
- **Автосообщения** (`communications`): `GET /programs/{program}/auto-messages`, `POST …/{topic}:enable` (у темы дня —
  с `days`), `:disable`, `PUT …/{topic}/days`. Выключение только защищает. Тема, которую включают или выключают такой,
  какая она есть, с теми же днями, не меняется вовсе — ни время переключения, ни докуда дошёл её просмотр дня: повтор
  запроса или интеграция, которая «убеждается», не теряют пропущенных дней.
- **Настройки сообщений** (`communications`): `GET`/`PUT /message-settings`, `:pause`, `:resume`. Пауза только
  защищает. Снять её может ключ — в кабинете это обычная запись (`campaigns.publish`): пауза — выбор самого мерчанта,
  а не тормоз против накрутки, как остановка кодов. Остановки платформы API показывает, но не снимает.
- **Кабинет покупателя** (скоуп `programs`, как его страница в кабинете — страница программы): `GET`/`POST`/`DELETE
  /programs/{program}/portal`, `:move`, `:allow-joining`, `:stop-joining`, `:set-min-age`, `:set-colour`.
  - **Открыть кабинет и пускать новых** — `POST /portal` и `:allow-joining` — может только ключ со скоупами `programs`
    и `communications`. Открытый кабинет шлёт каналами мерчанта коды входа, а пока пускает новых — и регистрации, за
    счёт мерчанта; `programs` выдаёт и разработчик партнёра, а `communications` — нет. Так же ключ кассы выпускают
    только с `organization` и `members`. Остальное о кабинете — адрес, возраст, цвет, закрытие и остановка
    вступления — скоуп `programs`.
  - Открытие и перенос — разные операции и в контракте. `Portals::open` отказывает программе, у которой кабинет уже
    есть (409 `portal_exists`), `Portals::move` меняет адрес только открытому кабинету: закрытый, пока выбирали адрес,
    остаётся закрытым. Раньше `open` и открывал, и переносил, и устаревшая форма «Изменить адрес» в кабинете открыла
    бы закрытый кабинет заново — с вступлением по умолчанию.
  - Закрытие — `DELETE`, повтор тоже 204. Закрыть кабинет и остановить вступление только защищают.
  - Нет кабинета — 404 `portal_not_found`, и у кабинета, закрытого, пока менялись его адрес, вступление, возраст или
    цвет: контракт портала говорит об этом `PortalNotFound`, а не отказом программе. Адрес занят другой программой —
    409 `portal_address_taken`.
  - Кабинет архивной программы не работает: API показывает его без адреса (`url` null), как кабинет мерчанта.
  - Там, где платформа кабинетов покупателя не показывает (нет `PORTAL_DOMAIN`), кабинет откроется без адреса и
    заработает, когда платформа начнёт их показывать. Кабинет мерчанта такие действия не показывает, а API — не
    запрещает: мерчант готовит кабинет заранее.
  - Цвет читается таким, каким его прислали: пустая строка — не цвет, а не цвет платформы (его даёт null).
  - Освобождённый адрес сейчас сразу свободен для всех. Держать его за прежним мерчантом какое-то время — отдельная
    задача: через API адрес можно ждать скриптом.
- **Приостановленный мерчант** читает всё. Выключить автосообщение, поставить сообщения на паузу, остановить
  вступление и закрыть кабинет может (`RequireMerchant::WRITES_WHILE_SUSPENDED`), остальное — 403 `merchant_suspended`.
- **Журнал аудита.** Операции называются как действия кабинета (`message-templates.publish`, `auto-messages.enable`,
  `portals.open` и другие). Новые имена — чтения `message-templates.index`, `message-templates.versions`,
  `message-templates.preview`, `auto-messages.index`, `message-settings.show`, `portals.show`, и три операции, которые в
  кабинете — одно действие с разными данными: `message-templates.restore` (стандартный текст не должен означать
  пустой), `portals.allow-joining` и `portals.stop-joining` (приостановленному мерчанту доступна только вторая).
- **Имена полей в журнале.** Запись API хранит поля запроса только с именами, какие бывают у операций; поле с другим
  именем — `[redacted]`. Ошибка клиента может положить значение в имя: документ JSON, отправленный как форма
  (`curl -d` без типа), PHP делает именем одного поля целиком, вместе с паролем, а строку JSON, отправленную телом, —
  полем без имени; маскировка смотрит на имена полей и не нашла бы пароля там. Это закрывает и подключение каналов
  7k-1.
- Коды `invalid_message_template`, `invalid_auto_message`, `invalid_message_settings`, `invalid_portal`,
  `portal_address_taken`, `portal_not_found` и новый `portal_exists` перешли в каталог Management API.

### Журнал и очередь сообщений, согласия участника (7k-3)

- **Журнал сообщений** — `GET /messages`, как «Журнал» кабинета: коды, проверочные сообщения и сообщения участникам,
  новые первыми, по периоду, виду и итогу; кому — маской, каким путём и каналом, что стало и сколько стоило, каждый
  канал, которому предложено сообщение. Текстов, номеров и адресов в нём нет.
- **Очередь** — `GET /member-messages`, как «Очередь»: что ждёт отправки и чего, что ушло и дошло ли, что правила при
  отправке не пустили или ни один канал не принял, и почему; по периоду, состоянию и теме. `waits_for` — только пока
  не настало `send_after`: дальше сообщение ждёт одного отправителя, чего бы ни ждало раньше (как считает «Сколько
  ждёт»). `message_id` ведёт к записи журнала о последней попытке.
- **Сообщения участнику** — `GET /members/{member}/messages`, как «Сообщения» в карточке: его и участников,
  объединённых с ним (`member_id` говорит, чьё). Объединённого участника API читает по-прежнему (ADR-0019).
- **Скоупы.** Журнал, очередь и сообщения участнику называют участников и, маской, кому ушли коды — `communications` и
  `members`, каждое чтение в журнале аудита (`management.audit:reads`). «Сколько ждёт» — `GET
  /member-messages/waiting` — только числа, скоуп `communications`, чтения не пишутся.
- **Поиск получателя** — по номеру телефона (`phone`) или адресу (`email`) целиком, одному из двух. Номер, начатый с
  `+7`, `7` или `8`, — ровно 11 цифр, как в кабинете: без одной цифры он прочитался бы как чужой номер из десяти.
  - Журнал аудита не хранит ни номера, ни адреса: `phone` и `email` — чувствительные имена, запись хранит
    `[redacted]`.
  - Номер — в строке запроса, как у поиска участника (`GET /programs/{program}/members?phone=`). Журнал веб-сервера не
    должен хранить строку запроса.
  - **Поисков, которые ничего не нашли, одни учётные данные у мерчанта делают не больше 20 за 10 минут**, как человек в
    кабинете: дальше 429 `too_many_lookups` с `retry_after`. Поиск считается до того, как выполнится, так что
    одновременные запросы не проскочат лимит; нашедший сообщения ничего не тратит, как и не выполнившийся (неверный
    курсор): он никого не нашёл и ничего не показал. Журнал по номеру говорит больше, чем поиск участника: код
    регистрации на номер, которого нет в программе, — значит, кто-то пытался вступить с ним.
  - Поиск в журнале аудита — запись `messages.index` с `phone` или `email` в запросе; отказ 429 туда не пишется, как у
    всех операций API (ADR-0010): записи о промахах до лимита уже есть. Кабинет пишет свои поиски как `messages.lookup`
    и отказ — раз в несколько минут.
  - Класс отказа перешёл из кабинета в ядро (`Modules\Kernel\Http\Problems\TooManyLookups`), код — в каталог
    Management API.
- **Согласия участника** — `GET /members/{member}/consents`, скоуп `members`, как карточка: каждое согласие, как оно
  есть, — дано (к какой версии документа) или отозвано, когда и как; вида, которого не давали и не отзывали, нет.
  Менять согласия через API нельзя: их меняет участник сам — в кабинете покупателя, на сайте через API участника,
  отпиской, «стоп» в мессенджере.
- **Вебхук `member.consent_changed`** (docs/api/webhooks.md) — о каждом согласии на рекламу, данном или отозванном.
  - Модуль согласий — единственный, кто пишет `consent_events` (`ConsentService::record`). Каждую запись он
    сопровождает событием `ConsentChanged` в той же транзакции — своей, точкой сохранения в транзакции вызывающего.
    Outbox записывает из них согласия на рекламу, поэтому событие есть, если и только если запись сохранилась, кто бы
    ни вызвал.
  - Правила программы и обработка персональных данных в вебхук не входят: их дают при регистрации (`member.enrolled`)
    и отзывают, только когда участник уходит — объединением дубля или обезличиванием.
  - Отзыв при объединении и обезличивании приходит с `channel` = `system`, по ссылке «Не вы?» из SMS о подключённом
    мессенджере — с `sms`. Отказ от согласия, которого не было, тоже приходит: участник сказал «нет».
  - Доставки могут прийти не по порядку, повторы возможны: действует согласие с последним `changed_at`. Согласие,
    данное при регистрации, приходит раньше `member.enrolled`: согласия записываются до события регистрации. Текущее
    состояние всегда можно прочитать.
- **Журнал аудита.** Операции называются как действия кабинета: `messages.index` (журнал, с поиском тоже),
  `messages.queue`, `members.messages`. Новые имена — `members.consents` и `messages.waiting`.

## Последствия

- Партнёр настраивает каналы мерчанта из своего продукта, без кабинета.
- Утёкший ключ со скоупами `communications` и `members` может подключить мерчанту свой SMS-аккаунт и поставить его
  первым. Тогда через него пойдут коды подтверждения и сообщения, и их тексты увидит хозяин аккаунта. Это та же сила,
  что у сотрудника с правом `channels.manage` в кабинете, только без подтверждения кодом или паролем. Ключ с одним
  `communications` чужой аккаунт не подключит, но может выключить каналы или поднять лимиты кодов до потолка
  платформы. Защита:
  - разработчик партнёра такие ключи не выпускает;
  - каждое изменение — в журнале аудита;
  - мерчант и партнёр отзывают ключи.
- Утёкший ключ с `communications` может опубликовать свой текст автосообщения и включить тему: текст уйдёт всем
  участникам программы от отправителя мерчанта. Это сила маркетолога в кабинете (`campaigns.publish`), только без
  подтверждения. Защита та же; кто и когда опубликовал — в журнале аудита, что именно — в истории шаблона.
- API публикует шаблон поверх текущей версии без сигнала о правке в кабинете, сделанной тем временем; форма кабинета,
  наоборот, получает `message_template_outdated`, если API опубликовал версию, пока она была открыта.
- Об отказе провайдера интегратор узнаёт только проверкой. Вебхуки о состоянии каналов — если попросят.
- Свои рассылки мерчант может вести по согласиям платформы: вебхук сообщает о каждом согласии на рекламу, отзыв по
  ссылке из письма или «стоп» в мессенджере доходят и до его системы.
- Ключ с `communications` и `members` читает журнал сообщений целиком и ищет в нём по номеру, как сотрудник с правом
  видеть участников. Перебор номеров в журнале держит лимит поисков без результата, а не скоуп. Лимит — у каждых
  учётных данных, как у каждого сотрудника в кабинете: кто выпускает ключи, получает по 20 промахов на каждый.
- Поиск участника по номеру (`GET /programs/{program}/members?phone=`) такого лимита пока не имеет: его держит только
  общий лимит запросов, и ключ с `members` за несколько часов подберёт номер участника по его маске. Это отдельная
  задача — поиск участника в API ограничить, как в кабинете.
- Номер в строке запроса виден в журналах веб-сервера и прокси, а PHP SDK не помечает такие параметры
  чувствительными, как и у поиска участника.
- Подключение сообщества ВКонтакте делает несколько запросов к ВКонтакте подряд. Если ВКонтакте медленный, SDK может
  не дождаться ответа и сообщить об ошибке соединения, хотя подключение завершилось. Повтор с тем же ключом безопасен:
  он заменит сообщество тем же.
