Initial commit

2026-07-06 13:05:56 +03:00
commit 831c72dc60
28 changed files with 2527 additions and 0 deletions
@@ -0,0 +1,86 @@
+# 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)]]