📚 RM.Loyalty.docs
➕ Новая статья

эндпоинты loyalty api v2

✏️ Редактировать

Эндпоинты 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.
{ "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 — именно с этого момента ПЛ отрабатывает по гостю.