# ADR-0028. Сайты на Tilda

- Статус: принято; этап 9 — 9.3-1 (заказы сайта начисляют баллы), 9.3-2 (возврат заказа из кабинета)
- Дата: 2026-11-11

## Контекст

Пункт 9.3 roadmap — JS-виджет для сайтов, Tilda и модуль для 1С-Битрикс. Виджеты участника для сайтов со своим
сервером уже есть (ADR-0018): сервер сайта открывает сессию участника через Management API. Модуль для Битрикса по
исследованию относится ко второй фазе (модуль `sale`, маркетплейс Битрикса) и требует установленного Битрикса для
проверки, поэтому 9.3 в объёме пилота — сайты на Tilda.

По исследованию у Tilda нет бэкенда для балансов: лояльность подключают через вебхуки и ссылку на карту. Что задаёт
Tilda (справка Tilda, интеграторы ApiMonster, Albato и Scaleo; прочитано 2026-11-11):

- **Вебхук** («Настройки сайта → Формы → Webhook»): Tilda отправляет POST на HTTPS-адрес при каждой отправке формы,
  к которой подключён этот приёмщик, поля — по именам переменных формы (`Name`, `Phone`, `Email`…) и `tranid`
  (номер заявки), `formid`. Сразу после подключения адреса приходит запрос `test=test`, на который нужно ответить 200.
  Ответ ждут 5 секунд, иначе делают ещё две попытки, каждую через минуту.
- **Заказ корзины** несёт `payment`: номер заказа `orderid`, сумму `amount`, товары `products`, платёжную систему
  `sys` и номер её транзакции `systranid`. Товары массивом (название, количество, сумма, цена, артикул, внешний код
  `externalid`) — отдельная галочка приёмщика; без неё товары приходят строками.
- **Ключ API**: в настройках приёмщика задаются имя и значение ключа и способ передачи — в заголовке или в теле запроса.
- **«Отправлять данные в сервисы приёма данных только после оплаты»** — галочка в настройках платёжных систем. Без
  неё данные заказа уходят при отправке формы, до оплаты.
- Поля формы Tilda пересылает как есть: их значения — и поля, которые посетитель допишет в форму на странице, — не
  подписаны ничем, кроме общего ключа приёмщика.
- Вебхука о возврате или отмене заказа нет. Промокоды Tilda — свой список до 2000 кодов, внешней проверки нет: списать
  баллы в корзине Tilda нельзя.
- Приём данных и корзина с оплатой доступны на платных тарифах Tilda.

## Решение

### Сайт и его адрес

Мерчант подключает сайт в кабинете («Интеграция → Tilda», `keys.manage`): название, программа и точка продаж. Сайт —
строка `tilda_sites` и терминал вида `ecommerce` в выбранной точке: заказы сайта — чеки этого терминала, отчёты по
точкам и акции по каналу видят их как продажи интернет-магазина. Адрес вебхука — `<APP_URL>/hooks/tilda/<id сайта>`;
ключ — 40 случайных символов, показывается один раз, хранится SHA-256 (`keys.manage` выпускает новый, прежний сразу
перестаёт работать). «Отключить» (`keys.revoke`) защищает и доступно приостановленному мерчанту: адрес больше ничего
не принимает, терминал выключается, чеки остаются. Не больше 20 подключённых сайтов у мерчанта. Сайт, чья касса
выключена (на странице «Кассы» или с закрытием точки), принимает заказы, но не может провести их чеки: страница так и
говорит.

Мерчанту предписано подключить приёмщик **только к форме корзины** и отметить «только после оплаты»: тогда каждое
сообщение приёмщика — оплаченный заказ корзины, который Tilda собрала на своём сервере.

### Заказ

`POST /hooks/tilda/<сайт>` — вне группы web и API (нет сессии, cookie и токена от подделки запроса; всё решает ключ):

1. Сайт ищется первым, до чтения тела: тенанта подключённого сайта находит SECURITY DEFINER-функция
   `tilda_site_tenant()`. Запрос к неизвестному или отключённому сайту — чужой (или Tilda с вебхуком, оставшимся после
   отключения): ограничен по сети (`tilda.strangers_per_address_per_minute`, только такие запросы — чтобы забытый
   вебхук одного мерчанта не закрыл заказы других), ответ — 200 на проверку адреса `test=test`, иначе 401.
2. Тело больше 512 КБ — 413.
3. Ключ — заголовок `X-Loyal-Key` (или поле тела с этим именем). Ключ из заголовка проверяется до чтения тела; в лимит
   адреса на сайте (`tilda.orders_per_address_per_minute`) идут только отказанные ключи: кто знает адрес сайта, может
   направить на него вебхук своего проекта Tilda с её же адресов, но верный ключ проходит и при полном лимите. Запрос
   без ключа в заголовке (проверка адреса, ключ в теле) читает тело и считается всегда. Неверный ключ и отключённый
   сайт отвечают одинаково 401; неверный ключ отмечает сайт для кабинета не чаще раза в минуту. После ключа — лимит
   сайта (`tilda.orders_per_site_per_minute`, 429 с `Retry-After`); закрытый мерчант — 403.
4. Тело читается своим разборщиком `application/x-www-form-urlencoded` (не `$_POST`: PHP отбрасывает поля сверх
   `max_input_vars`, а у заказа из сотни товаров их больше; не больше 10 000 полей) или как JSON, если Tilda пришлёт
   его. Числа читаются как текст, без float (`Kernel\Json\TextNumbers`). `payment` — вложенные поля формы или объект
   JSON; текст в поле `payment` (поле, которое может дописать страница) заказом не считается.
5. Поля `payment`, данные дважды — то же поле ещё раз или простое поле рядом с вложенными, — это поля посетителя рядом
   с полями Tilda: такой заказ не берётся (200, ничего не записано).
6. Отправка формы без `payment.orderid` — не заказ (заявка, подписка): 200, ничего не хранится.
7. Заказ берётся один раз по номеру под advisory-блокировкой сайта и номера (`tilda_orders`): повтор Tilda после
   медленного ответа получает 200 и ничего не меняет. Исключение — заказ, принятый неоплаченным: он принимается снова,
   когда приходит оплаченным (Tilda может прислать его до оплаты, а выдуманный страницей неоплаченный заказ не должен
   закрыть настоящему его баллы).
8. Оплачен заказ, который оплатила транзакция платёжной системы: непустой `systranid`, не из одних нулей, и `sys` — не
   «без оплаты» (`none`, `cash`). Неоплаченный заказ — `unpaid`, без чека и без чтения товаров: без галочки «только
   после оплаты» Tilda присылает заказ до оплаты, а наличные при получении Tilda не видит. Иначе брошенная корзина
   начисляла бы баллы.
9. Покупатель — участник программы с телефоном из поля формы (`Phone`, имя поля меняется в кабинете). Чек проводится
   как чек кассы без связи (`Checkout::upload`): заказ уже оплачен по ценам Tilda, поэтому только начисление по правилам
   программы на момент, когда платформа приняла заказ (Tilda не присылает время заказа), без скидочных акций, промокодов
   и списания; день чека — по поясу программы; объединённый участник — его преемнику, заблокированный — без баллов (как
   на кассе). Не участник, телефон не прочитан — анонимный чек (`anonymous`): продажи сайта видны в отчётах. Отказ
   кассы — `refused` с причиной (правила не опубликованы, касса выключена, заказ не прочитан).
10. Строки — товары массивом: артикул `sku`, иначе `externalid`, иначе `tilda-<хэш названия>`; количество в тысячных,
    сумма строки (`amount`, иначе цена × количество). Оплачено за товары — `amount` заказа без `delivery_price`, не
    больше суммы строк: скидки Tilda (промокод, динамические скидки) делятся между строками пропорционально
    (`Allocator`), доставка баллов не получает. Без массива товаров — одна строка `tilda-order` на сумму товаров.
11. Ответ — 200 `ok` на всё, что записано или оставлено; 503 на временную ошибку (Tilda повторит).

### Что видит мерчант

Страница «Tilda»: сайты с адресом, программой, точкой и состоянием (касса выключена — предупреждение); заказы за 30
дней — с баллами, без участника, не оплаченные, не принятые; время последнего заказа и последнего запроса с неверным
ключом (подсказка, что ключ вписан неверно); шаги настройки в Tilda; ссылка на кабинет покупателя программы — кнопка
«Бонусная карта» на сайте. Подключение сайта пишет в журнал аудита id нового сайта, а не его ключ.

### Возврат заказа (9.3-2)

Tilda о возвратах не сообщает, поэтому заказ возвращает мерчант: «Вернуть заказ» у сайта на странице «Tilda», номер
заказа из Tilda. Право — `members.adjust_points`, и только у ролей без лимитов ручных корректировок
(`cabinet.adjustment_limits`): возврат забирает всё, что начислил заказ, и эти лимиты его не ограничивают, поэтому
поддержка и оператор платформы в режиме поддержки заказы не возвращают; не чаще 120 раз в час на человека, у
приостановленного мерчанта действия нет. Возвращается всё, что осталось от чека заказа: если часть товаров уже вернули
на кассе программы — только остаток. Баллы заказа отменяются по правилам возврата программы, как при возврате на кассе:
уведомление называет баллы за возвращённые товары, а не то, что смог забрать леджер (потраченное списывается по
правилам). Возврат проводит касса сайта — и отключённого тоже, — номер `R-<номер заказа>`, день — по поясу программы.
Возврат кассы с тем же номером (кассир назвал возврат по номеру чека) касса программы считает повтором, поэтому остаток
тогда возвращается под номером с отметкой; возврат кассы между чтением чека и возвратом — чек читается заново, один раз.
Возврат держит ту же advisory-блокировку, что и приём заказа: повтор заказа от Tilda и второй возврат ждут и видят
результат первого. Номер заказа читается как номер от Tilda: без управляющих символов (NUL обрезал бы номер в базе и
вернул бы не тот заказ, который назовёт журнал аудита). Заказ без чека (не оплачен, не принят, не приходил) —
`tilda_order_not_found`; заказ, от которого ничего не осталось, или чек, который вернуть нельзя, —
`tilda_order_returned`. Журнал аудита называет сайт и чек. Время возврата — `tilda_orders.returned_at`, страница
считает возвращённые заказы за 30 дней. Возврат части заказа — по запросу: пока часть возвращают ручной
корректировкой.

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

- В теле заказа — имя, телефон, почта и адрес покупателя. Телефон только ищет участника (слепой индекс) и нигде не
  хранится; тело не пишется в журналы и исключения; в `tilda_orders` — номер заказа, итог и id чека.
- Ключ сравнивается по SHA-256 за постоянное время; адрес сайта не секрет, но без ключа ничего не открывает.
- **Подделка заказа.** Поля формы ничем не подписаны: кто знает ключ сайта, тот может прислать заказ на любой телефон
  участника — ключ равен ключу кассы. Посетитель, дописавший в форму поля `payment[...]`, получил бы баллы, если
  приёмщик подключён не только к корзине: повторы полей `payment` и текст в `payment` не принимаются, но форма без
  корзины, к которой мерчант всё-таки подключил приёмщик, остаётся уязвимой. Поэтому шаги настройки требуют подключать
  приёмщик только к корзине. Баллы с задержкой (`activationDelayDays` правил программы) оставляют время заметить
  такой заказ; убрать его баллы — «Вернуть заказ» (9.3-2). Ограничить сайт
  формой корзины по её `formid` и сумму заказа — если проверка покажет, что это нужно.
- Поля `systranid`, `sys` и `delivery_price`, кодировка `payment` (вложенные поля), значения `sys` для оплаты при
  получении, повторная отправка заказа после оплаты — из описаний интеграторов, не из справки Tilda: проверить на
  сайте с платным тарифом (шаг владельца продукта, docs/integrations/tilda) до пилота.

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

- Сайт на Tilda начисляет баллы за оплаченные онлайн заказы участников без программиста: адрес, ключ и три галочки в
  настройках Tilda.
- Списать баллы в корзине Tilda нельзя: участник тратит их на кассе; карту он открывает по ссылке на кабинет покупателя.
- Возвратов Tilda не присылает: заказ возвращают в кабинете по номеру, целиком или остаток после возврата на кассе.
- Модуль для 1С-Битрикс остаётся во второй фазе.
