87 lines
7.0 KiB
Markdown
87 lines
7.0 KiB
Markdown
# 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)]]
|