Розробка headless-архітектури на 1С-Бітрікс

Розробка headless-архітектури на 1С-Бітрікс

Монолітна архітектура 1С-Бітрікс із шаблонами і компонентами чудово працювала, коли сайт був єдиною точкою контакту з клієнтом. Сьогодні той самий каталог має віддаватися в мобільний застосунок, у PWA, у голосові асистенти, у зовнішні сервіси агрегаторів. Компонентний підхід Бітрікса для цього не підходить — він генерує HTML, а не JSON.

Headless-архітектура розділяє Бітрікс на бекенд (бізнес-логіка, дані, API) і незалежний фронтенд. Бітрікс стає headless CMS — керує контентом і даними, не генеруючи HTML.

Архітектурна схема

[1С-Бітрікс Backend]
  ├── Інфоблоки (каталог, контент)
  ├── Торговий каталог (ціни, залишки)
  ├── CRM / Замовлення
  └── REST API Layer
         |
    [API Gateway / nginx]
         |
    ┌────┴─────────────┐
[React SPA]    [Mobile App]    [Зовнішні сервіси]

Бітрікс зберігає всю бізнес-логіку: обробка замовлень, сесії, кошик, авторизація, інтеграція з 1С. Фронтенд — незалежно розроблюваний і розгортуваний React/Next.js застосунок.

REST API у 1С-Бітрікс

Бітрікс не має вбудованого REST API рівня Next.js або Laravel. API будується двома способами:

1. Контролери через addAjaxAction (старий, але робочий спосіб):

// /local/ajax/catalog.php
define('STOP_STATISTICS', true);
define('NO_KEEP_STATISTIC', 'Y');
define('BX_SECURITY_SHOW_MESSAGE', true);

require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php';

header('Content-Type: application/json; charset=UTF-8');
header('Access-Control-Allow-Origin: https://your-frontend.com');

CModule::IncludeModule('iblock');

$action = $_GET['action'] ?? '';

if ($action === 'catalog') {
    $items = getCatalogItems($_GET);
    echo json_encode(['status' => 'ok', 'data' => $items]);
}

2. Роутер через bitrix/routing (Бітрікс 20+, рекомендований підхід):

// local/routes/api.php
use Bitrix\Main\Routing\RoutingConfigurator;

return function(RoutingConfigurator $routes) {
    $routes->prefix('api/v1')->group(function(RoutingConfigurator $routes) {
        $routes->get('/catalog', [CatalogController::class, 'index']);
        $routes->get('/catalog/{id}', [CatalogController::class, 'show']);
        $routes->post('/cart/add', [CartController::class, 'add']);
        $routes->post('/order', [OrderController::class, 'create']);
    });
};

// local/controllers/CatalogController.php
class CatalogController extends \Bitrix\Main\Engine\Controller {
    public function indexAction(int $page = 1, int $limit = 20): array {
        $items = \Bitrix\Iblock\Elements\ElementCatalogTable::getList([
            'filter' => ['ACTIVE' => 'Y', 'IBLOCK_ID' => CATALOG_IBLOCK_ID],
            'limit'  => $limit,
            'offset' => ($page - 1) * $limit,
        ]);

        return ['items' => $items->fetchAll(), 'page' => $page];
    }
}

Аутентифікація і сесії

Headless-архітектура руйнує стандартну сесійну авторизацію Бітрікса. Два підходи:

JWT-токени. Користувач авторизується через API, отримує JWT, прикладає до кожного запиту. Бітрікс валідує токен і визначає користувача:

// Middleware для валідації JWT
function validateJwtToken(string $token): ?int {
    $payload = JWT::decode($token, new Key(JWT_SECRET, 'HS256'));
    return $payload->userId ?? null;
}

Cookie + CORS. Зберігаєте стандартну сесію Бітрікса, але налаштовуєте CORS для фронтенд-домену. Простіше в реалізації, складніше з точки зору безпеки (CSRF-захист обов'язковий).

Кешування API-відповідей

Без кешування headless-Бітрікс повільний — кожен запит до каталогу повністю будує вибірку з БД. Багаторівневе кешування:

// CDN-кеш для статичних даних каталогу (Redis + nginx)
public function indexAction(): array {
    $cacheKey = 'catalog_page_' . $this->getCurrentPage();
    $cache = Cache::createInstance();

    if ($cache->initCache(3600, $cacheKey, '/catalog/')) {
        return $cache->getVars()['data'];
    }

    $data = $this->buildCatalogData();

    $cache->startDataCache();
    $cache->endDataCache(['data' => $data]);

    return $data;
}

Кеш інвалідується при зміні даних інфоблоку через BXClearCache(true, '/catalog/') в обробнику події OnAfterIBlockElementUpdate.

Деплой і CORS

Headless вимагає правильного розділення доменів: api.yoursite.ua (Бітрікс) і yoursite.ua (фронтенд Next.js на Vercel/nginx). Налаштування CORS у nginx для API-сервера:

location /api/ {
    add_header 'Access-Control-Allow-Origin' 'https://yoursite.ua';
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
    add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type';
    add_header 'Access-Control-Allow-Credentials' 'true';

    if ($request_method = 'OPTIONS') {
        return 204;
    }

    fastcgi_pass php-fpm;
}

Headless на Бітріксі — це архітектурне рішення з відчутними перевагами (незалежний фронтенд, швидкість, мультиканальність) і реальними витратами (розробка API, кешування, CORS, інфраструктура). Ухвалюйте це рішення усвідомлено, коли моноліт справді став обмеженням, а не через моду на headless.