obsidian/Магазин обуви (apelsincom)/REST API (richcode.api).md

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. Удобно для отладки интеграций; помните, что в лог попадает тело запроса — не логируйте лишнего (ПДн).

Поток запроса

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)