Редактирование: guest-api

Путь: 09_Справочник_API/guest-api.md

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

# 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`).

**Запрос:**
```json
{ "card_number": "10008", "phone": null }
```

**Ответ:**
```json
{
  "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 — ответ:**
```json
[
  { "id": 489000, "name": "SILVER" },
  { "id": 489001, "name": "GOLD" },
  { "id": 489002, "name": "PLATINA" }
]
```

**GuestCategories.Get — запрос:**
```json
{ "id": 40404100 }
```

**GuestCategories.Add / Del — запрос:**
```json
{ "guest_id": 40404100, "category_id": 489000 }
```

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

**Ответ (Add/Del):**
```json
{ "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 — запрос/ответ:**
```json
// запрос
{ "guest_id": 40404100 }

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

**Wallets.Refill / Withdraw — запрос:**
```json
{ "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` |

Отмена