# ADR-0006. Конвенции публичного API

- Статус: принято
- Дата: 2026-09-30

## Решение

- **Стиль:** REST/JSON, спецификация OpenAPI 3.1 — источник истины, ответы проверяются контрактными тестами.
- **Плоскости:** runtime (`/api/v1/...`: кассы, сайты, продукты-носители; высокий QPS), management
  (`/api/management/v1/...`: партнёры и кабинеты; провижининг) и плоскость участника (`/api/member/v1/...`: виджеты
  участника на сайте мерчанта с сеансом одного участника, с этапа 6j, ADR-0018).
- **Пути:** ресурсы во множественном числе; нестандартные действия — через двоеточие
  (`POST /api/v1/receipts:calculate`, `POST /api/v1/receipts/{id}:confirm`).
- **Поля:** `snake_case`; суммы — целые минимальные единицы с явной валютой или типом баллов;
  время — ISO 8601 в UTC; идентификаторы — UUID; enum'ы — `snake_case` строками.
- **Ошибки:** RFC 9457 `application/problem+json` с полями `type`, `title`, `status`, `detail`,
  `instance`, стабильным машинным кодом `code` и `errors` для ошибок валидации. Ответы API — на английском
  (`title`, сообщения `errors`), каким бы ни был язык приложения; русские названия кодов — в каталоге
  `x-problem-codes`. Запросы Livewire кабинетов problem+json не получают: их ошибки показывает кабинет (ADR-0014).
- **Идемпотентность:** заголовок `Idempotency-Key` обязателен для изменяющих вызовов runtime API;
  ключ живёт не меньше 24 часов; повтор с другим телом → 422; параллельный повтор → 409.
- **Пагинация:** курсорная (`limit`, `cursor`), ответ `{ "data": [...], "next_cursor": ... }`.
- **Версионирование:** мажорная версия в пути; внутри мажорной — только обратно совместимые изменения;
  несовместимые — датированные версии в заголовке `Loyal-Version`, закреплённые за ключом доступа.
- **Аутентификация:** `Authorization: Bearer <key>` для ключей касс и мерчантов; OAuth2 client credentials
  для партнёров и собственных продуктов с заголовком `Loyal-Merchant` для выбора мерчанта.
- **Трассировка и лимиты:** `X-Request-Id` в каждом ответе; при превышении лимитов — 429,
  заголовки `RateLimit-*` и `Retry-After`.
- **Спецификация** Runtime API — `docs/api/runtime-v1.yaml` (OpenAPI 3.1). Базовый `TestCase` проверяет
  по ней каждый ответ API и тело каждого успешного запроса во всех тестах; архитектурный тест сравнивает
  маршруты `/api/v1` с операциями спецификации. Изменение API начинается с изменения спецификации.
- **Собственные продукты** компании ходят через тот же публичный API, что и внешние клиенты: скрытых
  привилегированных путей нет.

## Management API (этап 5b)

- **Спецификация** — `docs/api/management-v1.yaml`; тесты проверяют по ней ответы так же, как ответы Runtime
  API, архитектурный тест сверяет маршруты `/api/management/v1` с операциями.
- **Партнёры** получают токен по OAuth 2.0 client credentials: `POST /api/management/v1/oauth/token`, клиент
  аутентифицируется HTTP Basic или полями тела (форма или JSON). Токен непрозрачный (`lat_...`), живёт час;
  хранится только SHA-256. Ошибки этой точки — в формате RFC 6749 (`error`, `error_description`), как
  ожидают OAuth-библиотеки; остальные — problem+json.
- **Мерчант** выбирается заголовком `Loyal-Merchant` и должен принадлежать партнёру (иначе 403
  `merchant_not_accessible`, без уточнения причины). Операциям над данными мерчанта без заголовка —
  400 `merchant_required`; операциям партнёра вне мерчантов (мерчанты, каталог событий) заголовок ничего не
  значит. Мерчант может работать своим ключом `lm_<префикс>.<секрет>` — только со своими
  данными, скоуп `merchants` ключу мерчанта не выдаётся.
- **Скоупы**: `merchants`, `programs`, `organization`, `members`, `webhooks`, `reports`, `audit`, `widgets` (сеансы
  виджетов участника, с 6j-1; `presentation_code` сеансу — только с `members`, ADR-0018), `communications`
  (сообщения участникам: SMS-каналы, почта, бот MAX, сообщество ВКонтакте, лимиты кодов, с 7k-1, ADR-0025). Операция может
  требовать несколько (`management.scope:organization,members`): ключ кассы выпускают только учётные данные с
  `organization` и `members` (с 6i-3b) — касса находит участников и тратит их баллы, поэтому выпустить её ключ может
  лишь тот, кто сам видит участников. Отзыв ключа кассы только защищает: ему хватает `organization`.
- **Кэш аутентификации** — минута: приостановка партнёра вступает в силу в её пределах.
  - Токены отозванного клиента удаляются и перестают приниматься со следующего запроса (с 6d-2): метка отзыва в кэше
    переживает любую запись, которую успел сделать запрос, читавший клиента до отзыва.
  - Отзыв ключа забывает ключ в кэше: обычно он перестаёт работать сразу, в худшем случае — в течение минуты.
  - Статус мерчанта Management API читает на каждом запросе, поэтому закрытие и приостановка мерчанта действуют в нём
    сразу, а для ключей касс — в пределах минуты (ADR-0015).
- **Идемпотентность** в Management API не обязательна (частота изменений низкая, клиенты — серверные
  интеграции); от повторного создания мерчанта защищает `external_id` — повтор отвечает 409 с id
  созданного.
- **Лимиты**: на учётные данные (клиент или ключ) — `access.management_rate_per_minute`, на точку выдачи
  токенов — 60 в минуту с адреса. Порядок middleware: аудит → `management.auth` (только аутентификация) →
  `throttle:management` → `management.scope:<скоуп>` → `management.merchant`; отказы по скоупу и мерчанту
  расходуют лимит, как любой запрос.
- **Аудит** (ADR-0010): каждое изменение, отказ 403, выдача токена и чтение данных участников записываются в
  неизменяемый журнал; его отдаёт `GET /api/management/v1/audit-entries` (скоуп `audit`).
- **Каталог** (этап 6h-3a, скоуп `programs`): категории и товары мерчанта для лояльности — `PUT /catalog/categories`
  и `PUT /catalog/products` пишут пачкой до 1000 штук по коду и артикулу, все или ни одной (одна транзакция, строки
  в порядке кодов, чтобы две записи одних кодов ждали друг друга, а не блокировали). Каждая заменяет строку целиком:
  поле, которого нет, — `false` или пусто; повтор в запросе — последний вариант; ответ — сколько строк записано.
  Элементы проверяются одним проходом и строго по типам спецификации (неизвестное поле, `"1"` вместо числа или
  `1` вместо `true` — отказ), а не правилами со `*`: Laravel разворачивает такое правило на каждое поле каждого
  элемента, и тело из мусора стоило бы ему десятков секунд; отказ называет первые 20 ошибок. `GET` того же пути
  отдаёт страницы по коду и артикулу с собственными ограничениями строки (ограничения категорий-родителей, до 16
  уровней, применяет платформа при расчёте чека — `Catalog::resolve`). Товары фильтруются по категории (без
  подкатегорий) и поиску до 64 символов: артикул с этого текста или название с ним внутри, без учёта регистра в
  обоих; поиск идёт по товарам мерчанта без отдельного индекса — условие мерчанта доходит до индекса и при RLS, — а
  текст, которым не может быть ни код, ни название (не UTF-8, управляющий символ), ничего не находит. Чтение каталога
  не пишется в журнал (в нём нет персональных данных); тело записи больше 32 КБ журнал хранит только размером, как
  любое. Отказ домена — `invalid_catalog_data` (категория — родитель самой себе, порог цены выше предела строки
  чека, управляющий символ в коде), формы запроса — `validation_failed`.

## Плоскость участника и браузеры (этап 6j)

- **Плоскость участника** (ADR-0018) — `docs/api/member-v1.yaml`, тесты проверяют ответы так же, архитектурные тесты
  сверяют маршруты, скоупы и каталог. Доступ — сеанс одного участника `lms_…`, который открывает бэкенд сайта через
  Management API; запрос должен прийти со страницы сайта сеанса (`Origin`).
- **CORS** (`config/cors.php`): Runtime API и плоскость участника отвечают страницам любых сайтов без cookie и
  открывают им `X-Request-Id`, `Retry-After`, `RateLimit-*`, `Idempotent-Replayed`, `Loyal-Environment`; preflight
  кэшируется 10 минут. Management API браузерам других сайтов CORS-заголовками не отвечает: оно для серверов.

## Каталог ошибок и повторы (этап 5.6)

- **Каталог кодов.** У каждой спецификации есть корневой `x-problem-codes`: каждый стабильный `code` ответа
  problem+json со статусом, русским названием и дополнительными полями (`merchant_id`, `available`, …). Тесты сверяют с
  ним каждый ответ об ошибке, архитектурный тест — коды в исходниках; SDK генерирует из него константы кодов. Коды
  `http_<статус>` ошибок фреймворка подразумеваются.
- **Полнота ответов.** Каждая операция с аутентификацией описывает 401, 403 и 429.
- **Безопасные повторы.** POST без `Idempotency-Key`, который ничего не меняет (расчёт чека, поиск участника),
  помечен `x-safe-to-retry: true`: SDK повторяет его после потерянного ответа. Остальные POST повторяются только с
  ключом идемпотентности.
