# Запросы и ответы

Правила, общие для Runtime API, Management API и Member API: адрес и версия, учётные данные, формат данных, повторы,
ошибки, страницы и лимиты.

## Адрес и версия

- Все запросы — по HTTPS. Песочница — `https://sandbox.rebonus.ru`, адрес рабочего окружения сообщаем при
  подключении. В примерах SDK рабочий адрес записан как `https://api.example.com`.
- Версия — в пути: `/api/v1`, `/api/management/v1`, `/api/member/v1`. Внутри версии API меняется только совместимо:
  появляются новые операции, необязательные поля запросов, новые поля ответов, новые значения перечислений и новые
  коды ошибок. Код интеграции должен пропускать поля, которых не знает, и разбирать незнакомое значение как «другое».
- Действие над ресурсом — через двоеточие: `POST /api/v1/receipts:calculate`, `POST /api/v1/receipts/{receipt}:confirm`.
- В протоколе платформа называется Loyal: заголовки `Loyal-Merchant` и `Loyal-Environment`, тип ошибок
  `urn:loyal:problem:…`, пакеты SDK `loyal/sdk` и `@loyal/sdk`. Это то же самое, что Rebonus.

## Учётные данные

| Что | Вид | Где работает | Как передаётся |
|---|---|---|---|
| Ключ кассы | `lk_<префикс>.<секрет>` | Runtime API | `Authorization: Bearer …` |
| Клиент партнёра | `lc_…` и секрет `lcs_…` | выдача токена Management API | HTTP Basic или поля формы в `POST /api/management/v1/oauth/token` |
| Токен партнёра | `lat_…`, живёт час | Management API | `Authorization: Bearer …` и мерчант в заголовке `Loyal-Merchant` |
| Ключ мерчанта | `lm_<префикс>.<секрет>` | Management API, данные своего мерчанта | `Authorization: Bearer …` |
| Сеанс участника | `lms_<префикс>.<секрет>` | Member API, только со страниц своего сайта | `Authorization: Bearer …` |

- В песочнице у каждого вида метка `test_`: `lk_test_…`, `lat_test_…`. Учётные данные другого окружения получают
  401 `environment_mismatch`.
- Ключ — секрет сервера: не кладите его в код страниц, в мобильное приложение и в репозиторий. Отозванный ключ перестаёт
  работать в течение минуты.
- **Скоупы** ограничивают, что может ключ. Ключ кассы — `receipts`, `members`, `balances`. Ключам серверов сайтов,
  приложений и интеграций можно дать ещё `activities` и `presentation_codes`, причём `presentation_codes` — только
  без `receipts`: ключ, который сам выпускает коды участника и проводит чеки, тратил бы баллы любого участника.
  Скоупы Management API — в
  [его справочнике](/docs/api/management/#scopes), сеанса участника — `profile`, `history`, `presentation_code`,
  `consents` и `details`. Без нужного скоупа — 403 `scope_missing`.

## Формат данных

- JSON в UTF-8. Поля — `snake_case`, идентификаторы — UUID, перечисления — строки.
- **Деньги** — целые копейки: 1 250,00 ₽ — это `125000`.
- **Баллы** — целые минимальные единицы типа баллов; сколько у них знаков после запятой, говорит `precision` (у обычных
  баллов — 0).
- **Количество** — тысячные доли: 1 шт. — `1000`, 0,5 кг — `500`.
- **Время** — ISO 8601. API принимают время со смещением (`2026-11-17T09:41:00+03:00`) или в UTC (`…Z`) и отвечают в
  UTC, бывает — с долями секунды (`2026-11-17T06:41:00.000000Z`). Даты — `2026-11-17`.

Дробных чисел в деньгах и баллах нет нигде: так суммы сходятся до копейки.

## Повторы без двойных списаний

Связь рвётся, и касса не всегда знает, дошёл ли запрос. Поэтому изменяющие запросы Runtime API идут с ключом
идемпотентности:

- заголовок `Idempotency-Key` — от 1 до 255 видимых символов ASCII; без него — 400 `idempotency_key_required`;
- повтор с тем же ключом и тем же телом возвращает сохранённый ответ с заголовком `Idempotent-Replayed: true` — баллы
  не спишутся и не начислятся второй раз. Успешные ответы хранятся 48 часов; после ответа с ошибкой повтор с тем же
  ключом выполняет запрос заново;
- тот же ключ с другим телом — 422 `idempotency_key_reused`;
- ключ стройте из того, что однозначно называет действие, — кассы, бизнес-даты и номера чека. Тогда повтор найдёт тот
  же чек, даже если касса перезапустилась между попытками. Для действий без номера подойдёт UUID. Телефон и другие
  данные покупателя в ключ не кладите: ключ хранится как есть.

Операции, которые ничего не меняют (расчёт чека, поиск участника), в справочнике помечены «Ничего не меняет — можно
повторять». Management API ключа идемпотентности не требует: от повторного создания мерчанта защищает `external_id` —
повтор отвечает 409 с id уже созданного.

SDK делают это сами: один ключ на все попытки вызова, повтор только того, что повторять безопасно, и пауза перед
повтором.

## Ошибки

Ошибка — ответ `application/problem+json` (RFC 9457) со стабильным полем `code`. Решайте по `code`: он не меняется.
`title` и `detail` — по-английски, для журнала, а не для покупателя.

```json
{
  "type": "urn:loyal:problem:receipt_exists",
  "title": "The terminal already registered a receipt with this number on this business date.",
  "status": 409,
  "code": "receipt_exists",
  "request_id": "…",
  "receipt_id": "…"
}
```

- У `validation_failed` есть `errors` — сообщения по полям.
- Некоторые коды несут свои поля: здесь `receipt_id` — уже зарегистрированный чек. Они перечислены в
  [каталоге кодов](/docs/errors/).
- Только выдача токена `POST /api/management/v1/oauth/token` отвечает по RFC 6749 (`error`, `error_description`), как
  ждут библиотеки OAuth.

## Страницы

Списки отдаются страницами: параметры `limit` и `cursor`, ответ — `{"data": [...], "next_cursor": "…"}`.

- `next_cursor` передайте в `cursor` следующего запроса как есть: это непрозрачная строка.
- `next_cursor: null` — страниц больше нет.
- Испорченный курсор — 400 `invalid_cursor`. Передавайте курсор только в тот запрос, из которого он взят.
- Сколько записей на странице и по умолчанию — у каждой операции в справочнике (обычно до 100).

В SDK у таких операций есть парный метод `…All()`: он перебирает все записи всех страниц.

## Лимиты

| API | Сейчас |
|---|---|
| Runtime API | 600 запросов в минуту на ключ кассы, 6000 на мерчанта |
| Management API | 600 запросов в минуту на клиента или ключ мерчанта, выдача токенов — 60 в минуту с адреса |
| Member API | 60 запросов в минуту на участника, 6000 на мерчанта |

Сверх лимита — 429 `too_many_requests` с заголовком `Retry-After` (через сколько секунд повторить) и `RateLimit-*`.
У кодов подтверждения свои лимиты — на номер, на кассу и на мерчанта, они описаны у операций. В песочнице лимиты ниже —
[«Песочница»](/docs/sandbox/).

## Заголовки ответа

- `X-Request-Id` — в каждом ответе. Назовите его, когда пишете нам на hello@rebonus.ru: по нему находится запрос.
- `Loyal-Environment` — `live` или `sandbox`. Когда пришло `sandbox`, покажите на экране плашку «ТЕСТОВЫЙ РЕЖИМ».

## Браузеры

Runtime API и Member API отвечают на CORS-запросы страниц любых сайтов без cookie. Но ключ кассы — секрет, и на
страницах для покупателей его быть не должно: им служит Member API с коротким сеансом участника, который открывает
бэкенд сайта ([«Виджеты участника»](/docs/widgets/)). Management API — только для серверов: браузеру других сайтов он
не отвечает.
