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

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

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

# Обзор API ReMarked

API ReMarked предназначено для доступа к процессингу программ лояльности (ПЛ) на базе ReMarked. Через него кассовые системы (iiko, R-Keeper) и внешние сервисы взаимодействуют с процессингом: получают данные о госте, считают скидки и бонусы, проводят и подтверждают транзакции, синхронизируют меню.

## Версии API

| Версия | Назначение | Базовый адрес |
|---|---|---|
| **API v1** | Исторические методы по протоколу JSON-RPC: отзывы, депозиты/сертификаты, вебхуки продаж, информация о гостях | `https://app.remarked.ru/api/v1/api` |
| **API v2 (Loyalty API)** | Актуальное API процессинга лояльности: гость, заказ, транзакции, сертификаты, синхронизация данных лояльности | `https://app.remarked.ru/api/v2/...` |

> Текущая версия Loyalty API v2 — **2.12** (по спецификации OpenAPI `ReMarked Loyalty API v2`).

## Базовые принципы

- **Транспорт:** HTTP(S). Большинство методов v2 — `POST`, тело в формате JSON. Часть методов v1 работают по протоколу **JSON-RPC** (`method`, `params`, `id`).
- **Авторизация:** Bearer Token в заголовке `Authorization: Bearer <token>`. В v1 токен можно передать также как параметр в теле запроса.
  - *Токены и ключи доступа в документацию не выносятся (доступы хранятся во внутренней базе знаний, раздел 18).*
- **Идентификатор запроса:** заголовок `X-Request-Id` — уникальный идентификатор обращения. Используется для трассировки запроса в логах и при обращении к разработчикам.
- **Идентификация поинта:** числовой код заведения (`point`). Для сетевых клиентов часто используется общий поинт сети.
- **Формат статусов:** код `200 OK` означает, что запрос принят, но внутри JSON может присутствовать `"status":"error"` с полями `code`/`message`/`mes`. Всегда проверять тело ответа, а не только HTTP-код.

## Структура раздела «Справочник API»

| Файл | Содержание |
|---|---|
| `обзор-api.md` | Версии, базовые принципы (этот документ) |
| `эндпоинты-loyalty-api-v2.md` | Все 14 эндпоинтов Loyalty API v2 |
| `guest-api.md` | Guest.Add / Guest.Get и дополнительное API работы с гостем (категории, кошельки) |
| `плейсхолдеры-и-выгрузка-меню.md` | Плейсхолдеры печати и модуль выгрузки меню |
| `loyaltyscripts-и-php.md` | LoyaltyScripts и PHP-скрипты-примеры |

## Документация (внешние ссылки)

| Раздел | Ссылка |
|---|---|
| API v2 (полная) | `https://api.remarked.ru/docs/RM.Loyalty.html` |
| Гости и дополнительное API | `https://api.remarked.ru/docs/RM.guests-and-additional.html` |
| API v1 — CashboxConfig, IIKOData, LoyalityAPI, Сертификаты | внутренние документы (раздел 14 базы знаний) |

Отмена