# ADR-0027. Касса МоегоСклада

- Статус: принято, реализовано; этап 9 — 9.2-1 (решение в каталоге МоегоСклада, подключение аккаунта, магазины),
  9.2-2 (запросы кассы)
- Дата: 2026-11-11

## Контекст

Пункт 9.2 roadmap — касса МоегоСклада. По исследованию это самый дешёвый в поддержке коннектор: касса сама вызывает
сервер системы лояльности по Loyalty API 1.0 МоегоСклада, у мерчанта ничего не устанавливается. Владелец продукта
поставил до пилота 9.1 и этап 11; продукт для 9.1 не назван, поэтому этап 9 начинается с 9.2, который в объёме
пилота по исследованию.

Что задаёт МойСклад:

- **Loyalty API 1.0**: касса вызывает систему лояльности — поиск покупателя, его создание, баланс, код подтверждения
  регистрации, расчёт скидок продажи, код подтверждения списания, создание продажи, возврата, поиск подарочного
  сертификата. Каждый запрос несёт ключ в заголовке `Lognex-Discount-API-Auth-Token`, ошибки — массив `errors` с
  `code` и `error_message` при статусе не 200/201/204. Код подтверждения система лояльности отправляет покупателю **и
  возвращает кассе**, которая сама сравнивает его с введённым кассиром: проверить код на своей стороне система
  лояльности не может.
- **Подключение только через серверное решение** в каталоге решений МоегоСклада (Vendor API 1.0) с блоком
  `<loyaltyApi/>` в дескрипторе: МойСклад активирует решение на аккаунте (`PUT`, подпись JWT HS256 секретным ключом
  решения), решение отвечает `SettingsRequired`, администратор аккаунта открывает главное окно решения (iframe),
  решение передаёт МоемуСкладу адрес и ключ системы лояльности (`PUT /apps/{appId}/{accountId}/loyalty`) и сообщает
  `Activated`. Неопубликованное решение отлаживается на аккаунте разработчика (подписка на 24 часа); доступ в кабинет
  разработчика — по анкете (шаг владельца продукта).

## Решение

### Решение в каталоге МоегоСклада (9.2-1)

- Одно решение на платформу. Его id, appUid и секретный ключ — настройки окружения `MOYSKLAD_APP_ID`,
  `MOYSKLAD_APP_UID`, `MOYSKLAD_SECRET_KEY` из кабинета разработчика; без них маршруты МоегоСклада отвечают 404.
  Дескриптор — `docs/integrations/moysklad/descriptor.xml`: `vendorApi` с `endpointBase` = `<APP_URL>/moysklad`,
  `access` с правами `custom` только на чтение точек продаж (чтобы показать мерчанту его магазины), `loyaltyApi`,
  главное окно `<APP_URL>/moysklad/window`.
- Модуль `moy-sklad` (`Modules\MoySklad`): жизненный цикл решения, окно настроек, связь аккаунта с программой мерчанта, магазины. Запросы
  кассы принимает `processing` — дом протоколов касс: тот же поиск участника, расчёт, коды и их лимиты, что у
  Runtime API; аккаунт и магазин он узнаёт через `MoySklad\Contracts\MoySkladTills`.
- JWT в обе стороны — только HS256 (другой `alg`, в том числе `none`, — отказ), подпись секретным ключом
  (`hash_equals`), срок не дольше `iat` + 300 с (МойСклад ограничивает так же), каждый `jti` — один раз (кэш на
  время жизни токена и запас на расхождение часов). Наши запросы: `sub` = appUid, `iat`, `exp` = `iat` + 60, новый
  `jti`, `Accept-Encoding: gzip` (МойСклад требует), без перехода по перенаправлениям. Ключ у обеих сторон один, поэтому
  наш токен на входе не принимается: он называет наше решение (`sub`), а токены МоегоСклада — никого.
- Без https платформа (вне локальной разработки и тестов) считает решение не настроенным: адрес, который получает
  МойСклад, несёт ключ касс.

### Жизненный цикл на аккаунте

- `moysklad_accounts` — данные платформы, не мерчанта (без `tenant_id`): аккаунт МоегоСклада (id — первичный ключ),
  его имя, статус установки и токен JSON API, запечатанный `PiiCipher` (контекст аккаунта).
- `PUT …/apps/{appId}/{accountId}` идемпотентен: аккаунт записывается, ответ — `Activated` для аккаунта, уже
  связанного с программой мерчанта (возобновление сохраняет настройки, как советует МойСклад), иначе
  `SettingsRequired`. Приостановленное решение возобновляет только `Install` или `Resume`: смена тарифа
  (`TariffChanged`, `Autoprolongation`) и причина, которую МойСклад добавит позже, состояние не меняют. Чужой appId —
  404; 4xx МойСклад считает окончательным отказом, поэтому отказ (400) — только запросу без причины.
- `DELETE`: `Uninstall` — связь удаляется, ключ кассы забывается, при новой установке мерчант подключает аккаунт заново;
  `Suspend` и любая другая причина — аккаунт приостановлен, связь сохраняется, запросы кассы получают отказ.
  Неизвестный аккаунт — 204.
- Каждый запрос держит строку аккаунта, а запись в журнал аудита мерчанта (канал `moysklad`, актор — аккаунт
  МоегоСклада) идёт в той же транзакции: повтор запроса не пишет её второй раз.
- Лимиты: сначала на адрес (неподписанные запросы тоже), потом подпись, потом лимит подписанных на аккаунт. Иначе
  чужие неподписанные запросы исчерпали бы лимит аккаунта, и МойСклад получал бы 429, который для него окончательный
  отказ. Превышение лимита аккаунта — 503 с `Retry-After`: такой запрос МойСклад повторяет. Если мы ответили 5xx,
  `jti` токена освобождается для повтора.

### Подключение аккаунта к программе

- В кабинете мерчанта страница «МойСклад». Для `keys.manage`:
  - «Получить код подключения» с выбором программы и точки для новых магазинов;
  - смена точки для новых магазинов;
  - перенос магазина в другую точку.

  Код показывается один раз (`RevealsSecretOnce`): 12 знаков, 30 минут (`MoySkladLinks::CODE_MINUTES`). Хранится его
  SHA-256 — это первичный ключ: хеш случайного секрета, найденный до тенанта функцией `moysklad_link_code_tenant()`. У
  мерчанта один код, новый заменяет прежний. Страница предупреждает, что код нельзя никому передавать, и говорит, до
  какого времени ждёт код. Защитное `keys.revoke` (работает и у приостановленного мерчанта):
  - «Отменить код»;
  - «Отключить» — заодно отменяет код.

  После отключения наш статус аккаунта становится `settings_required`, и МоемуСкладу сообщается `SettingsRequired`
  (если не ответит, связь всё равно разорвана).
- Окно настроек `GET <APP_URL>/moysklad/window` работает только во фрейме (`Sec-Fetch-Dest: iframe`), держать который
  может только МойСклад (`frame-ancestors`), а форма — только из самого окна (ещё и `Sec-Fetch-Site: same-origin`). Иначе
  человека, которому прислали адрес окна или форму чужого сайта, можно было бы уговорить подключить чужой аккаунт.
  Сервер обменивает `contextKey` на сотрудника МоегоСклада (`POST /context/{contextKey}`, не дольше 5 секунд;
  неизвестный ключ не спрашивается снова 5 минут). Подключать может только администратор аккаунта
  (`permissions.admin.view = ALL`). Куки в чужом фрейме не работают, поэтому форма несёт запечатанный контекст
  (аккаунт, сотрудник, `Crypt`), который заодно защищает от подделки запроса. Контекст действует 30 минут от открытия
  окна: отказ возвращает форму с тем же контекстом, а не продлевает его. Форма называет подключаемый аккаунт. Политика:
  `frame-ancestors` — только `https://online.moysklad.ru`, без скриптов. Лимиты — на адрес и на все окна вместе.
- `POST <APP_URL>/moysklad/window` с кодом. Неверные коды считаются по аккаунту; после 10 за час окно аккаунта до конца
  часа не принимает ни одного, а каждый отказ пишется в журнал приложения без кода. Код (буквы русской раскладки,
  похожие на латинские, читаются как латинские) находит тенанта и расходуется сразу. Дальше проверки:
  - мерчант работает: приостановленный или закрытый ничего не подключает;
  - программа и точка кода открыты;
  - у мерчанта нет другого аккаунта.

  В тенанте под блокировкой связи — связь `moysklad_connections` (первичный ключ — id аккаунта: один аккаунт — одна
  программа на платформе) с новым ключом кассы (32 случайных байта, хранится SHA-256). Затем `PUT /loyalty` (`url` —
  `<APP_URL>/moysklad/loyalty/<аккаунт>`, `token`, `externalSearch: true`) и `PUT /status` `Activated`. Только после
  них — запись `moysklad.link` в журнале аудита и письмо владельцам мерчанта (`TeamNotices::moySkladLinked`, со
  ссылкой на страницу «МойСклад»): код мог ввести не человек мерчанта.

  Если МойСклад отказал:
  - новая связь удаляется;
  - обновлённая сохраняет новый ключ — прежний, обновлённый, может быть, из-за утечки, не открывает ничего, что бы
    МойСклад ни сделал с новым;
  - в журнал пишется `moysklad.link` со статусом 502.
- Магазины: точка продаж МоегоСклада — касса нашего типа `pos` в точке для новых магазинов, создаётся при связи (магазины
  из JSON API) или при первом запросе кассы этого магазина, не больше 500 на аккаунт. Создание идёт под блокировкой связи:
  два первых запроса одного магазина дают одну кассу. Мерчант переносит магазин в другую точку на странице
  «МойСклад»: в новой точке появляется новая касса, прежняя отключается, а чеки остаются с той кассой, где были. Перенос
  в его же точку снова включает отключённую там кассу. Что меняет магазины, держит сначала связь, потом магазин, потом
  кассы. Поэтому перенос, отключение и удаление решения ждут друг друга, а не попадают во взаимоблокировку.

### Запросы кассы (9.2-2)

- `<APP_URL>/moysklad/loyalty/<аккаунт>/…` вне групп web и API, модуль `processing`. Порядок проверок:
  - лимит от потока — по сети адреса и аккаунту: МойСклад может слать запросы всех мерчантов с нескольких адресов,
    и запросы одного мерчанта не должны исчерпать лимит другого;
  - тенант — функцией `moysklad_account_tenant()`;
  - ключ из `Lognex-Discount-API-Auth-Token` сравнивается по SHA-256;
  - лимит на аккаунт — после ключа, иначе чужие запросы исчерпали бы лимит касс мерчанта (превышение — 429 с
    `Retry-After`).

  Ответы без верного ключа одинаковы для подключённых и неподключённых аккаунтов. Касса работает, пока работает мерчант
  (`MerchantData::isOpen()`: приостановленный тоже, как любая касса) и пока МойСклад запускает решение на аккаунте.
  Магазин — по `retailStore` (у поиска — `retailStoreId`). Касса создаётся только для магазина, который МойСклад числит
  за аккаунтом: незнакомый id сверяется со списком магазинов JSON API (список живёт 5 минут, после сбоя МоегоСклада
  его не спрашивают минуту). Иначе ключ в чужих руках делал бы кассы из выдуманных id, у каждой свои лимиты кодов.
  Каждый отказ — JSON МоегоСклада, и на неизвестный запрос тоже: `errors` с текстом для кассира по-русски, `code` —
  28001 там, где его называет протокол, иначе HTTP-статус.
- Числа JSON читаются текстом, без плавающей точки (`MoySkladJson`): деньги — копейки (2 знака), количество — тысячные
  (3 знака), баллы — в точности программы; что тратится, округляется вниз. Числа ответа пишутся из целых тем же текстом.
  Тело читается, только если это корректный JSON не больше 2 МБ (проверка линейная, разметка чисел — тоже). Пустые
  объекты запроса возвращаются объектами.
- **Поиск** — только точные идентификаторы: телефон, номер карты, код из приложения, наш id; не больше одного
  покупателя. Покупатель в ответе:
  - `id` — наш id участника, `discountCardNumber` — он же: следующие запросы кассы находят участника, каким бы id
    МойСклад ни назвал своего покупателя;
  - имя — имя участника, а без него «Участник программы» и маска телефона;
  - телефон — только тот, что ввёл кассир, иначе его нет.
- **Покупатель запроса** узнаётся по нашему id, по запомненной связи с покупателем МоегоСклада
  (`moysklad_counterparties`), по `discountCardNumber` (наш id или номер карты), по телефону. Найденный не по нашему id
  запоминается за id покупателя МоегоСклада. Объединённый участник — это его наследник (ADR-0019): назвать участника
  заново на кассе некому. Покупатель, которого программа не знает (так МойСклад может назвать и розничного покупателя), для
  расчёта и продажи — никто: скидки акций он получает, баллов — нет.
- **Расчёт** — `Checkout::calculate`:
  - строка — позиции одного товара по одной цене: их количество вместе, сумма — цена × количество каждой, полкопейки
    вверх. Так позиция, которую расчёт вернул двумя, при продаже — та же строка, а акция «от N штук» считает все.
    Товар — id ассортимента МоегоСклада, по нему каталог программы узнаёт категории;
  - сумма строки к оплате делится между её позициями по их суммам;
  - ответ — цена со скидкой за единицу и процент по каждой позиции;
  - позиция в штуках, сумму которой единицы не делят до копейки, делится на две (МойСклад это разрешает), серийные
    номера — между ними; весовая получает цену за вычетом скидки на единицу, без скидки — свою цену;
  - списание баллами — скидка позиций, `paidByBonusPoints` — её сумма; без `preferredBonusToSpend` списывается
    столько, сколько разрешают правила;
  - `needVerification` — как требуют правила программы. Касса МоегоСклада называет участника нашим id, а не кодом из
    приложения, поэтому при правиле «код, кроме входа по коду из приложения» код нужен всегда.
- **Продажа** — `Checkout::open(…, confirm: true)` с теми же строками и `bonusValueToSpend`. Время покупки — когда
  пришла продажа (часовой пояс `moment` МойСклад не называет), бизнес-дата — по часовому поясу программы.
  - Повтор узнаётся по ключам продажи (`moysklad_sales`) под их блокировками. Ключи — id продажи МоегоСклада (в `meta.id`
    и в конце `meta.href`) и магазин с номером и `moment`, так что продажа узнаётся и без id, и с id, которого раньше
    не было.
  - Номер, который в тот день уже заняла другая продажа кассы, получает метку ключа.
  - Если программа списала бы не столько баллов, сколько сняла касса — баланс или правила изменились после расчёта
    (участник заморожен, лимит списаний за день, баллов меньше), или баллы списываются у покупателя, которого программа
    не знает, — продажа не регистрируется: 409 «Баллы не списаны». Тихо записать меньшее списание значило бы
    начислить баллы на деньги, которых покупатель не платил.
- **Возврат** — по продаже, на которую он ссылается (по любому её id), по товарам и количествам: количество товара
  берётся из строк продажи по порядку, сколько в них осталось, а чек держится, пока это считается. Повтор узнаётся по
  ключу возврата. Номер, который у этого чека уже занял другой возврат, получает метку ключа. Возврат без известной
  продажи, как и возврат, которому нечего вернуть, принимается (касса не может его переделать), но баллы не трогает.
  Страница «МойСклад» считает такие возвраты за 30 дней: баллы по ним мерчант забирает вручную.
- Подарочных сертификатов у платформы нет — 404.
- **Регистрация**:
  - если программа подтверждает телефон кодом, покупатель без проверки получает 412 с кодом 28001, и касса
    запрашивает код;
  - `CHECKED` берёт код, который эта касса отправила на этот телефон;
  - пропущенная проверка (`IGNORE`) — отказ.

  Покупатель, которого программа знает — по нашему id, номеру карты или телефону, — этот участник (повтор регистрации),
  телефон для него не нужен. Новый вступает с согласиями, без которых нельзя: правила программы и обработка
  персональных данных. Почта, которая есть у другого участника, не мешает: покупатель вступает без неё. Канал — касса
  (`pos`), в доказательствах — касса и аккаунт МоегоСклада.

### Коды, которые проверяет касса

- `Verification::startForTill` — новый вид кода: отправляется, как код кассы (те же каналы, лимиты, остановки,
  текст с баллами), но значение возвращается вызывающему, а запись получает статус `delegated` и признак `delegated`
  навсегда.
  - `consume` берёт такой код только для его цели, телефона и всего контекста (регистрация Runtime API, которая кассу не
    называет, его не возьмёт), до 15 минут после срока — продажа может прийти позже, — и только тогда считает
    подтверждённым.
  - Код, которым не воспользовалась продажа, считается неподтверждённым, как любой. В остановку отправки кодов за низкую
    долю подтверждённых такие коды не входят: кто их запросил, тот их и держит, и подтвердит или нет как захочет.
  - `verify` его не проверяет. Код нигде не пишется — ни в журнал, ни в аудит. `timeForRepeat` — пауза до следующего
    кода по нарастающей шкале повторов.
- Код списания привязан к кассе и к баллам последнего расчёта этого участника на этой кассе (`moysklad_quotes`,
  30 минут). Идёт он на телефон участника, а не на тот, что назван в запросе. Продажа со списанием, если правила
  требуют код, расходует последний такой код (`moysklad_codes`). Без него — отказ; код на другие баллы — тоже. Когда
  код использован, забываются все коды этой цели для этого участника или телефона на этой кассе: более старый код не
  подтвердит продажу, о которой участник не получил SMS. Так у участника всегда есть SMS с суммой, а ввод кода
  проверяет касса МоегоСклада.
- Расчёты после 30 минут и коды через час после их срока стираются ежечасно (`receipts:prune-moysklad`).

### Безопасность и остаточные риски

- **Утечка ключа кассы** позволяет действовать от имени касс мерчанта. В отличие от ключа нашего API, это включает
  списание баллов: код подтверждения достаётся тому, кто вызывает. Ограничения:
  - код и сумма всегда приходят на телефон участника;
  - после списания участник получает уведомление «Не вы?», если мерчант включил его в автосообщениях (страница
    «МойСклад» это советует);
  - действуют лимиты кодов на кассу и лимит списаний участника в день;
  - мерчант отключает аккаунт на странице «МойСклад» — ключ перестаёт работать сразу.

  Адресов, с которых ходит МойСклад, он не публикует, поэтому ограничить запросы по IP нельзя.
- По времени ответа на неверный ключ можно узнать, подключён ли аккаунт: id аккаунтов не секрет, и это принято.
- Токен МоегоСклада не привязан к запросу. В нём нет ни метода, ни пути, ни аккаунта, поэтому перехваченный и ещё не
  использованный токен действует один раз на любом аккаунте. Это свойство протокола МоегоСклада. Защита от повтора
  держится на кэше приложения: он должен быть общим для всех процессов (база данных или Redis, не `array`).
- `contextKey` окна приходит в адресе. Журналы веб-сервера не хранят query-строк (правило ADR-0025), а окно работает
  только во фрейме МоегоСклада.
- Подтверждения подключения в кабинете нет. Связь сразу видна в журнале аудита, о ней получают письмо владельцы, а
  «Отключить» действует мгновенно.
- Ключ кассы и токен JSON API не показываются ни мерчанту, ни в ответах, ни в журнале. Ключ кассы хранится как
  SHA-256. Токен JSON API запечатан: нужен только для списка магазинов.

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

- Мерчант на кассе МоегоСклада подключает программу без разработки: решение из каталога, код из кабинета, магазины
  сами становятся кассами.
- Публикация решения в каталоге — шаг владельца продукта: анкета разработчика, черновик решения, секретный ключ в
  настройках окружения, модерация.
- Списание баллами через МойСклад слабее, чем через наш API, на величину доверия к кассе МоегоСклада. Это свойство
  протокола МоегоСклада, и мерчант видит его в описании страницы «МойСклад».
- Документация оставляет открытыми несколько мест, и код написан так, чтобы работать при любом их прочтении:
  - примеры с пустыми id продажи и возврата — поэтому повтор узнаётся по номеру и `moment`, а возврат такой продажи
    баллы не трогает и виден на странице «МойСклад»;
  - рубли или копейки в сумме возврата — платформа читает только товары и количества;
  - каким id МойСклад называет покупателя после внешнего поиска — поэтому покупатель узнаётся четырьмя способами;
  - часовой пояс `moment` — поэтому время покупки — время, когда продажа пришла;
  - списание баллами как скидка позиций;
  - повторяет ли касса создание покупателя со `statusCheck: CHECKED` после кода — так прочитан пример протокола;
  - что касса делает с отказом продажи (409 «Баллы не списаны») — продажа к тому времени может быть уже оплачена;
  - каким покупателем МойСклад называет продажу без покупателя программы.

  Всё это проверяется на отладочном аккаунте до публикации решения.
