Разработка API для мобильного приложения на базе 1С-Битрикс

Разработка API для мобильного приложения на базе 1С-Битрикс

Битрикс не предоставляет готового REST API для произвольного мобильного приложения. Встроенный REST-модуль (rest) ориентирован на Битрикс24 и вебхуки CRM — он не подходит для публичного API каталога, корзины и заказов. Разработка API под мобилку — это написание кастомных контроллеров поверх ядра Битрикс с правильной авторизацией, версионированием и форматом ответа.

Архитектура API

Оптимальная точка входа — единый файл /api/v1/index.php, который маршрутизирует запросы через роутер. Используем компонент маршрутизации Битрикс или реализуем минимальный роутер самостоятельно.

Структура URL:

GET    /api/v1/catalog/sections         — список разделов
GET    /api/v1/catalog/products         — товары с фильтром и пагинацией
GET    /api/v1/catalog/products/{id}    — карточка товара
POST   /api/v1/cart/add                 — добавить в корзину
GET    /api/v1/cart                     — состояние корзины
POST   /api/v1/order/create             — оформить заказ
POST   /api/v1/auth/login               — авторизация
POST   /api/v1/auth/refresh             — обновление токена

Авторизация через JWT

Сессионная авторизация Битрикс не подходит для мобильного приложения — нужны токены. Реализуем JWT:

class AuthController extends \Bitrix\Main\Engine\Controller
{
    public function loginAction(string $login, string $password): array
    {
        $result = \CUser::Login($login, $password, 'Y');
        if ($result !== true) {
            return ['error' => 'Invalid credentials'];
        }

        $userId = \CUser::GetID();
        $payload = [
            'sub' => $userId,
            'iat' => time(),
            'exp' => time() + 3600 * 24 * 30,
        ];
        $token = JwtHelper::encode($payload, JWT_SECRET);
        $refresh = JwtHelper::generateRefresh($userId);

        return ['access_token' => $token, 'refresh_token' => $refresh];
    }
}

Refresh-токены хранятся в таблице bl_api_tokens с полями user_id, token_hash, expires_at, device_id.

В middleware каждого запроса: декодируем JWT из заголовка Authorization: Bearer ..., получаем user_id, авторизуем пользователя через \CUser::SetOnStartSession() только для текущего запроса.

Каталог и товары

Контроллер каталога с поддержкой фильтра и пагинации:

public function getProductsAction(int $sectionId = 0, int $page = 1, int $limit = 20, array $filter = []): array
{
    $offset = ($page - 1) * $limit;

    $bitrixFilter = [
        'IBLOCK_ID' => CATALOG_IBLOCK_ID,
        'ACTIVE' => 'Y',
        'ACTIVE_DATE' => 'Y',
    ];
    if ($sectionId > 0) {
        $bitrixFilter['SECTION_ID'] = $sectionId;
        $bitrixFilter['INCLUDE_SUBSECTIONS'] = 'Y';
    }
    // применяем пользовательские фильтры

    $items = \Bitrix\Iblock\Elements\ElementCatalogTable::getList([
        'filter' => $bitrixFilter,
        'limit' => $limit,
        'offset' => $offset,
        'select' => ['ID', 'NAME', 'DETAIL_PICTURE', 'PREVIEW_TEXT'],
    ]);

    return ['items' => $this->formatProducts($items), 'page' => $page, 'limit' => $limit];
}

Цены получаем через \Bitrix\Catalog\PriceTable::getList() с учётом группы пользователя.

Корзина и заказы

Корзина хранится в стандартной b_sale_basket через \Bitrix\Sale\Basket. Для неавторизованного пользователя корзина привязывается к FUSER_ID, передаваемому в заголовке запроса (X-Fuser-Id). При авторизации корзина мигрирует к USER_ID.

Оформление заказа — \Bitrix\Sale\Order::create() с передачей адреса доставки, способа оплаты и доставки. API возвращает order_id и ссылку на оплату.

Формат ответа и ошибки

Единообразный JSON-конверт:

{
  "success": true,
  "data": { ... },
  "meta": { "page": 1, "total": 142 }
}

При ошибке:

{
  "success": false,
  "error": { "code": "PRODUCT_NOT_FOUND", "message": "Товар не найден" }
}

HTTP-статусы: 200 OK, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error.

Кейс: мобильное приложение для дилерской сети

Задача: iOS/Android-приложение для 200 дилеров — просмотр каталога, проверка остатков, оформление заказа.

Особенности:

• Индивидуальные цены по группам покупателей (b_catalog_price, группа из b_user)
• Остатки из b_catalog_store_product — несколько складов, нужен агрегированный остаток
• Push-уведомления через FCM при смене статуса заказа
• Кеширование ответов каталога на 5 минут через Bitrix Cache (\Bitrix\Main\Data\Cache)

Результат: 200 активных пользователей, среднее время ответа API 120 мс, нагрузка 50 RPS в пике.

Что входит в разработку

• Роутер и структура контроллеров /api/v1/
• JWT-авторизация с refresh-токенами и поддержкой нескольких устройств
• Эндпоинты каталога с фильтрацией, пагинацией и ценами по группам
• Корзина и оформление заказа через \Bitrix\Sale
• Стандартизированный формат ответа и коды ошибок
• Кеширование ответов каталога, документация в формате OpenAPI