Редактирование: эндпоинты-loyalty-api-v2

Путь: 09_Справочник_API/эндпоинты-loyalty-api-v2.md

Содержимое (Markdown)

# Эндпоинты Loyalty API v2

Спецификация: **ReMarked Loyalty API v2, версия 2.12** (OpenAPI). Все методы, кроме загрузки конфигурации кассы, работают через `POST` с JSON-телом. Авторизация — Bearer Token (*токены в документацию не выносятся, см. раздел 18 внутренней БЗ*). Для трассировки передаётся заголовок `X-Request-Id`.

## Группы методов (теги)

- **CashBox** — конфигурация кассового бокса.
- **LoyaltyData** — синхронизация справочников лояльности (категории, номенклатура, остатки, скидки, типы оплаты).
- **Loyalty** — рабочий процессинг гостя/заказа/транзакций и сертификаты.

## Сводная таблица эндпоинтов

| # | Метод | Путь | Тег | Назначение |
|---|---|---|---|---|
| 1 | GET | `/сashbox/сonfig/load` | CashBox | Загрузка конфигурации кассы (резерв, лояльность, транспорт, страницы, продажа сертификатов) |
| 2 | POST | `/loyaltydata/category/update` | LoyaltyData | Синхронизация категорий (групп) номенклатуры |
| 3 | POST | `/loyaltydata/nomenclature/update` | LoyaltyData | Синхронизация блюд (номенклатуры) |
| 4 | POST | `/loyaltydata/remaining-amounts/change` | LoyaltyData | Изменение доступности товара к продаже (стоп-лист) |
| 5 | POST | `/loyaltydata/discounts/update` | LoyaltyData | Синхронизация скидок |
| 6 | POST | `/loyaltydata/paymenttypes/update` | LoyaltyData | Синхронизация типов оплаты |
| 7 | POST | `/loyalty/guest/get` | Loyalty | Получение данных гостя (по ID / телефону / карте) |
| 8 | POST | `/loyalty/guest/add` | Loyalty | Создание гостя в системе лояльности |
| 9 | POST | `/loyalty/order/update` | Loyalty | Расчёт скидок/бонусов по заказу (предрасчёт) |
| 10 | POST | `/loyalty/order/bill` | Loyalty | Формирование счёта (bill) с учётом списания бонусов |
| 11 | POST | `/loyalty/transaction/makeorupdate` | Loyalty | Создание или обновление транзакции (предтранзакция) |
| 12 | POST | `/loyalty/transaction/confirm` | Loyalty | Подтверждение транзакции (с типами оплаты) |
| 13 | POST | `/loyalty/transaction/rollback` | Loyalty | Откат транзакции |
| 14 | POST | `/loyalty/certificate/get` | Loyalty | Получение данных сертификата |

## Ключевые поля запроса и ответа

### 1. GET `/сashbox/сonfig/load`
- **Ответ:** `reserve`, `loyalty`, `transport_settings`, `show_pages`, `sale_of_certificates`.

### 2. POST `/loyaltydata/category/update`
- **Запрос:** массив объектов категории: `guid` (GUID), `name`, `parent` (GUID родителя, nullable).
- **Ответ:** `status`.

### 3. POST `/loyaltydata/nomenclature/update`
- **Запрос:** массив блюд: `guid` (GUID), `name`, `category` (GUID категории, nullable).
- **Ответ:** `status`.

### 4. POST `/loyaltydata/remaining-amounts/change`
- **Запрос:** массив: `guid` (GUID), `allowedForSale` (bool) — товар доступен к продаже.
- **Ответ:** `status`.

### 5. POST `/loyaltydata/discounts/update`
- **Запрос:** массив скидок: `guid` (GUID), `name`, `deleted` (bool), `isActive` (bool).
- **Ответ:** `status`.

### 6. POST `/loyaltydata/paymenttypes/update`
- **Запрос:** массив типов оплаты: `guid` (GUID), `name`, `CanBeExternalProcessed` (bool) — может обрабатываться внешними системами.
- **Ответ:** `status`.

### 7. POST `/loyalty/guest/get`
- **Запрос:** один из вариантов поиска — по `id`, по `phone` или по `card`.
- **Ответ:** `id`, `phone`, `email`, `surname`, `name`, `cards` (массив карт), `total_balance`, `delivery_addresses`.

```json
{ "card_number": "10008", "phone": null }
```

### 8. POST `/loyalty/guest/add`
- **Запрос:** `surname`, `name`, `patronymic`, `phone`, `email`, и др. данные гостя.
- **Ответ:** `id`, `phone`, `email`, `surname`, `name`, `cards`, `total_balance`, `gender`.

### 9. POST `/loyalty/order/update`
- **Запрос:** `guest_id` (int), `order` — объект заказа: `guid`, `created_at`, `order_sum`, `items[]` (`guid`, `product_guid`, `name`, `count`, `price`, `discount`, `cost`), `gift`.
- **Ответ:** `guest_id`, `order` (с рассчитанными `discount`/`discount_sum`/`promocode`), `withdraw_bonus_limit`, `withdraw_bonus_sum`, `refill_bonus_sum`, `show_info`.

### 10. POST `/loyalty/order/bill`
- **Запрос:** `guest_id`, `withdraw_bonuses` (бонусы к списанию), `order` (объект заказа).
- **Ответ:** `check`, `show_info`.

### 11. POST `/loyalty/transaction/makeorupdate`
- **Запрос:** `transaction_id` (int, при обновлении), `master_order_guid` (GUID, при разделении в режиме 2 ФР), `guest_id`, `withdraw_bonuses`, `order`.
- **Ответ:** `transaction_id`, `check`, `show_info`.

### 12. POST `/loyalty/transaction/confirm`
- **Запрос:** `transaction_id`, `payments[]` — массив типов оплаты заказа (`guid` типа оплаты, сумма и т.п.).
- **Ответ:** `transaction_id`.

### 13. POST `/loyalty/transaction/rollback`
- **Запрос:** `transaction_id`.
- **Ответ:** `transaction_id`.

### 14. POST `/loyalty/certificate/get`
- **Запрос:** `search_data` (строка поиска сертификата), `for_sale` (bool — запрашивается для продажи).
- **Ответ:** `id`, `title`, `type`, `nominal`, `dishes`, `dish_multiselect`, `for_sale`.

## Типовой жизненный цикл заказа на кассе

1. `guest/get` — авторизация гостя по карте/телефону.
2. `order/update` — предрасчёт скидок и доступного лимита списания бонусов.
3. `transaction/makeorupdate` — создание предтранзакции (получаем `transaction_id`).
4. `order/bill` — формирование счёта при списании бонусов (опционально).
5. `transaction/confirm` — подтверждение при закрытии заказа с типами оплаты.
6. `transaction/rollback` — откат при отмене.

> После успешного подтверждения транзакция переходит в статус `success` в таблице `loyalty_transactions` — именно с этого момента ПЛ отрабатывает по гостю.

Отмена