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

Розробка API для мобільного застосунку на базі 1С-Бітрікс

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

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

Оптимальна точка входу — єдиний файл /api/v1/index.php, який маршрутизує запити через роутер. Використовуємо компонент маршрутизації 1С-Бітрікс або реалізуємо мінімальний роутер самостійно.

Структура 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

Сесійна авторизація 1С-Бітрікс не підходить для мобільного застосунку — потрібні токени. Реалізуємо 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