API работы с гостем

Документ описывает основные методы работы с гостем в Loyalty API v2 (Guest.Add / Guest.Get) и дополнительное API управления категориями и кошельками гостя.

Авторизация: Bearer Token + заголовок X-Request-Id. Токены в документацию не выносятся (доступы хранятся во внутренней базе знаний, раздел 18).

1. Guest.Get / Guest.Add (Loyalty API v2)

Метод	URL
guest/get	https://app.remarked.ru/api/v2/loyalty/guest/get
guest/add	https://app.remarked.ru/api/v2/loyalty/guest/add

Guest.Get — получение данных гостя

Поиск по одному из идентификаторов: внутренний id, phone или номер карты (card_number / card).

Запрос:

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

Ответ:

{
  "id": 51551023,
  "phone": "+79776172199",
  "email": "t@t.ru",
  "surname": "Иванов",
  "name": "Иван",
  "cards": ["18531"],
  "total_balance": 0
}

Поле	Тип	Описание
id	int	Внутренний идентификатор гостя
phone, email, surname, name	string	Контактные данные
cards	array	Номера карт гостя
total_balance	int	Суммарный баланс бонусов
delivery_addresses	array	Адреса доставки (в ответе get)

Guest.Add — создание гостя

Запрос (основные поля): surname, name, patronymic, phone, email, gender и др. Ответ: id, phone, email, surname, name, cards, total_balance, gender.

2. Дополнительное API работы с гостем

Адрес: https://app.remarked.ru/api/v2/.... Все методы (кроме category/get) — POST с JSON-телом. Статус операции возвращается в поле status (success / error), текст ошибки — в mes.

Категории

Метод	Путь	Назначение
Category.Get	GET /api/v2/category/get	Список всех категорий поинта, доступных для дистанционного присвоения (api_add=true)
GuestCategories.Get	POST /api/v2/guest/categories/get	Категории, назначенные гостю
GuestCategories.Add	POST /api/v2/guest/categories/add	Добавить категорию гостю
GuestCategories.Del	POST /api/v2/guest/categories/del	Удалить категорию у гостя

Category.Get — ответ:

[
  { "id": 489000, "name": "SILVER" },
  { "id": 489001, "name": "GOLD" },
  { "id": 489002, "name": "PLATINA" }
]

GuestCategories.Get — запрос:

{ "id": 40404100 }

GuestCategories.Add / Del — запрос:

{ "guest_id": 40404100, "category_id": 489000 }

Поле	Тип	Обяз.	Описание
guest_id	int	да	Идентификатор гостя
category / category_id	int	да	Идентификатор категории

Ответ (Add/Del):

{ "status": "error", "mes": "category not found" }

Кошельки (балансы)

Метод	Путь	Назначение
Wallets.Get	POST /api/v2/guest/wallets/get	Данные о кошельках гостя
Wallets.Refill	POST /api/v2/guest/wallets/refill	Начисление бонусов внешними системами
Wallets.Withdraw	POST /api/v2/guest/wallets/withdraw	Списание бонусов внешними системами

Wallets.Get — запрос/ответ:

// запрос
{ "guest_id": 40404100 }

// ответ
[ { "id": 489000, "name": "Тест", "balance": 50 } ]

Wallets.Refill / Withdraw — запрос:

{ "guest_id": 40404100, "wallet_id": 489000, "sum": 500, "comment": "Важный комментарий" }

Поле	Тип	Обяз.	Описание
guest_id	int	да	Идентификатор гостя
wallet_id	int	да	Идентификатор кошелька
sum	int	да	Сумма операции
comment	string	нет	Комментарий (добавлен в версии 1.2)

Ответ: status (success / error), mes (текст ошибки).

3. API информации о гостях (v1, JSON-RPC)

Адрес: https://app.remarked.ru/api/v1/api, метод POST, протокол JSON-RPC. Общая структура: id (REQUEST_ID, возвращается в ответе), method, params.

Метод	Назначение	Ключевые параметры
GuestsApi.GetGuestsData	Поиск информации о госте	token; один из phone / id / ext_uuid; опц. point
GuestsApi.UpdateGuest	Обновление данных гостя	token, id (или ext_uuid), fields (любые поля, кроме id, phone, cards, registration_date, bonuses)
GuestsApi.CreateGuest	Создание гостя	token, fields (обязателен phone; опц. surname, name, patronymic, fio, photo, birthday, gender, email, comment, is_subscriber, ext_uuid)

Форматы полей CreateGuest: phone — +7XXXXXXXXXX; birthday — YYYY-mm-dd; gender — male / female / пусто; is_subscriber — 0 / 1; photo — URL.

Теги гостя (v2)

Метод	Путь	Назначение
Получить теги заведения	POST /api/v2/guest/tags/get	Список тегов поинта (id, name, color)
Назначить теги гостю	POST /api/v2/guest/tags/set	Присвоить теги гостю по guest_id