Битрикс как headless API: что отдаёт, что нет

Что Битрикс даёт «из коробки»

Когда мы говорим о Битрикс как headless-бэкенде, важно сразу разграничить: речь идёт не о Bitrix REST API (Marketplace), а о прямом доступе к ядру через PHP-эндпоинты. Именно в этом режиме Битрикс работает хорошо и стабильно.

Что работает без существенной кастомизации:

• Инфоблоки (iblock) как источник данных каталога. CIBlockElement::GetList с нужными параметрами покрывает большинство сценариев получения товаров, категорий и свойств. Нужна аккуратная обёртка — но сама система надёжна.
• Авторизация пользователей. Стандартный механизм сессий работает, хотя с оговорками (о них ниже). Регистрация, вход, восстановление пароля — всё это можно вызвать через PHP без переписывания.
• Управление заказами. Модуль «Интернет-магазин» Битрикс имеет зрелое API для создания и получения заказов, работы с корзиной, применения скидок. Для большинства B2B-сценариев этого достаточно.
• Синхронизация с 1С. Это одна из главных причин, по которой клиенты из сегмента B2B выбирают Битрикс и не хотят его менять. Синхронизация товаров, цен, остатков и контрагентов через CommerceML работает стабильно и не требует доработки со стороны фронтенда.

Что требует кастомной PHP-разработки

Здесь начинается реальная работа. Стандартных компонентов Битрикс для headless недостаточно — нужно писать собственные тонкие JSON-эндпоинты.

• Фильтрация каталога по множеству свойств. CIBlockElement::GetList с фильтром по свойствам работает, но медленно при большом каталоге и сложных комбинациях. Нужна обёртка с кешированием и, при каталоге от 1 000 SKU, — вынос поиска и фильтрации на Elasticsearch.
• Поиск. Встроенный поиск Битрикс не подходит для серьёзного e-commerce. Пишем отдельный эндпоинт, который проксирует запросы в ES.
• Сложные правила ценообразования. Индивидуальные цены для контрагентов, накопительные скидки, прайс-листы — всё это требует кастомного PHP-слоя поверх стандартного модуля цен.
• Персонализированные рекомендации. Битрикс не имеет нативного движка рекомендаций. Либо кастомная логика («купили вместе» на основе истории заказов), либо внешний сервис.

Что не стоит делать

Не пытайтесь использовать Bitrix REST API (тот, что в разделе «Приложения» и Marketplace) для рендеринга страниц фронтенда. Этот API спроектирован для интеграций CRM, телефонии и внешних систем — у него другая модель авторизации (OAuth), другая структура ответов, и он не предназначен для высокочастотных запросов от пользовательского интерфейса.

Правильный подход — писать собственные PHP-эндпоинты, которые используют ядро Битрикс напрямую. Они просты, стабильны и не зависят от обновлений Marketplace.

Реальная практика: как это устроено у нас

На каждом headless-проекте мы пишем в среднем 5–8 тонких PHP-эндпоинтов. Типичный набор:

Эндпоинт	Что делает
/api/catalog/list	Листинг товаров с фильтрацией и пагинацией
/api/catalog/detail	Полные данные товара по slug или ID
/api/search	Проксирует запрос в Elasticsearch
/api/categories	Дерево категорий с количеством товаров
/api/cart	Состояние корзины (GET), добавление/удаление (POST)
/api/user/profile	Данные авторизованного пользователя
/api/orders	История заказов контрагента

Каждый эндпоинт — это 60–150 строк PHP, которые используют стандартное ядро Битрикс и возвращают чистый JSON. Они не зависят от шаблонов и компонентов, обновления Битрикс их не ломают.

Типичная ловушка: сессии против ISR

Стандартная авторизация Битрикс работает через сессии PHP. Next.js с ISR (Incremental Static Regeneration) кешируют ответы на CDN — сессионный механизм в этой схеме не работает: CDN отдаёт одну версию страницы всем пользователям.

Решение: разделить публичную часть (каталог, категории, статические страницы) и приватную (корзина, профиль, заказы). Публичные страницы — ISR без авторизации. Приватные запросы — через токен-авторизацию: при логине Битрикс генерирует JWT-токен, Next.js хранит его в httpOnly-cookie и передаёт в каждый API-запрос.

Итог: что работает и что нет

Битрикс как headless API закрывает около 80% типичных e-commerce сценариев без больших сюрпризов. Остальные 20% — это поиск (нужен Elasticsearch) и сложные рекомендации (кастом или внешний сервис). Синхронизация с 1С, управление заказами и ценообразование — его сильные стороны, которые не стоит заменять без веской причины.

Хотите понять, как будет выглядеть API-слой вашего Битрикс-проекта? В рамках Catalog Probe мы анализируем вашу инсталляцию и показываем конкретную схему эндпоинтов под ваши задачи.