# REST API (richcode.api)

Главная техническая особенность проекта. Сторонний модуль **`richcode.api` версии 3.1.5** (2024-08-02) отдаёт наружу REST-интерфейс к сущностям сайта: товарам, заказам, складам, пользователям, сделкам. Через него данными можно управлять **без админки** — вероятно, ради этого он и стоит.

Проверено по коду модуля: `bitrix/modules/richcode.api/` (`include.php`, `options.php`, `lib/core/Route.php`).

## Точка входа и формат URL
Запрос перехватывается обработчиком модуля на старте страницы (не через `urlrewrite.php`). Базовый путь задаётся в настройках модуля, по умолчанию `/api/`.

Структура адреса (из `lib/core/Route.php`):
```
/{apiPath}/{module}/{token}/{controller}/{action}
```
- `apiPath` — базовый путь (например `api`).
- `module` — область: `iblock`, `sale`, `main`, `crm`.
- `token` — токен авторизации (если включена авторизация по токену).
- `controller` / `action` — что вызываем. Действие — это оставшиеся сегменты пути после контроллера, склеенные точкой (`…/order/status/set` → `status.set`).
- Параметры: для GET — query-строка; для POST/PUT/DELETE — тело JSON (`Content-Type: application/json`).

Ответы — JSON (`lib/core/Response.php`).

## Что доступно (контроллеры)
Из карты автозагрузки в `include.php`:

| Модуль | Контроллер | Назначение |
|---|---|---|
| `iblock` | `Element` | CRUD элементов инфоблока: свойства (в т.ч. UF), разделы, файлы, единицы измерения |
| `sale` | `Order` | заказы: корзина, свойства заказа, оплаты, отгрузки |
| `sale` | `Product` | товары каталога и остатки на складах |
| `sale` | `Store` | склады и их остатки |
| `sale` | `Measure` | единицы измерения |
| `sale` | `Discount` | скидки |
| `main` | `User` | создание/обновление пользователей |
| `crm` | `Deal` | сделки (CRM) |

Важно: **каталог (инфоблок 2) обслуживает `sale/product`**, а `iblock/element` — только не-каталожные инфоблоки. Действия у них одинаковые.

> [!info] Полный список действий и примеры
> Все действия каждого контроллера, их параметры и готовые примеры запросов `curl` вынесены в отдельный справочник — [[REST API — методы и примеры (richcode.api)]]. Он составлен по исходникам контроллеров, а не по догадкам.

## Авторизация
- Включается опцией **«Авторизация по токену»** (`USE_AUTH_TOKEN`).
- Токен хранится в поле пользователя **`UF_API_TOKEN`** (по коду `lib/core/Tokens.php`; в подсказке настроек оно ошибочно названо `UF_RESTFUL_API_TOKEN`). Токены генерируются в настройках модуля («Сгенерировать» / «Пересоздать»).
- Токен передаётся **сегментом URL** (`…/{module}/{token}/{controller}/…`), а не заголовком — рабочий код читает его из пути. Пользователь-владелец токена должен состоять в заданной группе.
- Каждый вызов идёт **от имени пользователя-владельца токена** — права API = права этого пользователя. Это важно для безопасности: см. [[Информационная безопасность (apelsincom)]].
- Полная схема адресов, все действия и примеры `curl` — в [[REST API — методы и примеры (richcode.api)]].

## Настройки модуля (что где крутится)
Опции (админка → Настройки → Список модулей → richcode.api, или в БД):

| Опция | Смысл |
|---|---|
| `USE_API` | включить/выключить API |
| `API_PATH` | базовый путь (пример `/api/`) |
| `USE_AUTH_TOKEN` | авторизация по токену |
| `ONLY_HTTPS_EXCHANGE` | принимать только https |
| `USE_BLACK_LIST_ADDRESS_FILTER` / `BLACK_LIST_ADDRESS` | чёрный список IP |
| `USE_WHITE_LIST_ADDRESS_FILTER` / `WHITE_LIST_ADDRESS` | белый список IP |
| `USE_ACCESS_CONTROL_ALLOW_ORIGIN_FILTER` | CORS-фильтр по домену |
| `LOGGING` / `hl_logging` | лог запросов в highload-блок «Лог запросов» |

## Логирование
При включённом `LOGGING` каждый запрос пишется в highload-блок (его ID — в опции `hl_logging`) с полями `UF_API_LOG_TIME`, `UF_API_LOG_URL`, `UF_API_LOG_METHOD`, `UF_API_LOG_DATA`. Удобно для отладки интеграций; помните, что в лог попадает тело запроса — не логируйте лишнего (ПДн).

## Поток запроса
```mermaid
sequenceDiagram
    participant C as Клиент
    participant R as richcode.api (Route)
    participant B as Bitrix (iblock/sale/main/crm)
    C->>R: HTTP /api/{module}/{token}/{controller}/{action} (+JSON)
    R->>R: проверка HTTPS / IP / CORS / токена
    R->>B: вызов контроллера от имени пользователя токена
    B-->>R: результат
    R-->>C: JSON-ответ (+ запись в лог, если включён)
```

> [!warning] Что проверить и обезопасить
> - Точный `API_PATH` и какие пользователи-токены заведены — по файлам не видно, смотрите настройки модуля.
> - Включены ли `ONLY_HTTPS_EXCHANGE`, белый список IP и CORS — это ключевые меры защиты API.
> - Токены = ключи от данных. Их хранение, ротация и права пользователей-владельцев — в [[Информационная безопасность (apelsincom)]].

## См. также
- [[Информационная безопасность (apelsincom)]]
- [[Интеграции (apelsincom)]]
- [[Инфоблоки и каталог (apelsincom)]]