Налаштування Vue.js SPA з REST API 1С-Бітрікс

Vue.js і 1С-Бітрікс: налаштування взаємодії через REST API

Клієнти часто приходять з готовим Vue.js SPA, яке не може отримати дані з 1С-Бітрікс. Причина — неправильний вибір механізму API. Ми налаштовуємо інтеграцію так, щоб SPA працювало як частина сайту: з авторизацією, кешуванням та безпекою. Наприклад, типова помилка — спроба використати вбудований REST API для важкої вибірки каталогу, що призводить до перевищення ліміту запитів та помилок 429. У статті розбираємо три підходи та показуємо, який обрати під вашу задачу.

Бітрікс надає кілька механізмів для роботи з даними з Vue: вбудований REST API (/bitrix/rest/), ORM-методи через AJAX-контролери (Bitrix\Main\Engine\Controller), та прямі AJAX-запити до обробників компонентів. Вибір механізму впливає на продуктивність, безпеку та об'єм коду. Розберемо кожен підхід з практичними прикладами та рекомендаціями.

Вбудований REST API Бітрікс

Доступний за адресою /rest/ для cloud Бітрікс24 та потребує налаштування для «коробкової» версії (активація модуля REST API). Методи — sale.basket.getlist, catalog.product.list, crm.deal.list та інші. Авторизація через OAuth 2.0 або через вебхуки (webhook URL з токеном). Для публічного API на сайті (не Бітрікс24) — веб-хуки з обмеженими правами.

Офіційна документація 1С-Бітрікс рекомендує використовувати вебхуки для простих сценаріїв, але попереджає про ліміти запитів (50 на секунду для cloud). Для коробкової версії лімітів немає, але швидкість відповіді може бути низькою при складних вибірках.

const BX_WEBHOOK = window.BX_STATE.webhook; // передається з PHP

async function getProducts(filter) {
    const res = await fetch(`${BX_WEBHOOK}catalog.product.list`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ filter, select: ['ID', 'NAME', 'PRICE'] }),
    });
    return res.json();
}

Обмеження вбудованого REST: ліміти запитів, не всі сутності доступні, не можна виконувати довільні запити до БД.

Кастомні контролери через Engine\Controller

Для проектів на «коробковому» Бітрікс основний спосіб — кастомні контролери через Engine\Controller. Контролер живе в кастомному модулі. На відміну від REST API, ви отримуєте повний контроль над даними, підтримку тегованого кешування та можливість об'єднувати запити.

// local/modules/project.api/lib/controller/product.php
namespace Project\Api\Controller;

use Bitrix\Main\Engine\Controller;
use Bitrix\Main\Engine\ActionFilter;

class Product extends Controller
{
    public function configureActions(): array
    {
        return [
            'list' => [
                'prefilters' => [new ActionFilter\Authentication()],
            ],
        ];
    }

    public function listAction(int $categoryId, int $page = 1): array
    {
        $pageSize = 20;
        $res = \CIBlockElement::GetList(
            ['SORT' => 'ASC'],
            ['IBLOCK_ID' => CATALOG_IBLOCK_ID, 'SECTION_ID' => $categoryId, 'ACTIVE' => 'Y'],
            false,
            ['nPageSize' => $pageSize, 'iNumPage' => $page],
            ['ID', 'NAME', 'DETAIL_PICTURE', 'PROPERTY_PRICE']
        );

        $items = [];
        while ($item = $res->GetNext()) {
            $items[] = $item;
        }
        return ['items' => $items, 'page' => $page];
    }
}

URL контролера: /bitrix/services/main/ajax.php?action=project:api.product.list. Автоматично додає CSRF-захист при POST.

Axios у Vue: єдиний API-сервіс

// services/api.js
import axios from 'axios';

const api = axios.create({
    baseURL: '/bitrix/services/main/ajax.php',
    headers: { 'X-Requested-With': 'XMLHttpRequest' },
});

// Автоматично додаємо CSRF-токен
api.interceptors.request.use(config => {
    if (config.method === 'post') {
        config.data = { ...config.data, sessid: window.BX.bitrix_sessid() };
    }
    return config;
});

// Обробка 401 — редирект на авторизацію
api.interceptors.response.use(
    res => res.data,
    err => {
        if (err.response?.status === 401) {
            window.location.href = '/auth/?backurl=' + encodeURIComponent(location.pathname);
        }
        return Promise.reject(err);
    }
);

export const getProducts = (categoryId, page) =>
    api.post('', { action: 'project:api.product.list', categoryId, page });

Усі Vue-компоненти використовують функції з services/api.js — не роблять fetch напряму. Зміна URL або механізму авторизації — в одному файлі.

Composable для даних

// composables/useProducts.js
export function useProducts(categoryId) {
    const items = ref([]);
    const loading = ref(false);
    const error = ref(null);
    const page = ref(1);

    async function load() {
        loading.value = true;
        error.value = null;
        try {
            const data = await getProducts(categoryId.value, page.value);
            items.value = page.value === 1 ? data.items : [...items.value, ...data.items];
        } catch (e) {
            error.value = e.message;
        } finally {
            loading.value = false;
        }
    }

    watch(categoryId, () => { page.value = 1; load(); }, { immediate: true });
    return { items, loading, error, page, loadMore: () => { page.value++; load(); } };
}

Composable інкапсулює логіку завантаження, компонент працює тільки з реактивними даними.

CORS та політика безпеки

Для SPA на окремому піддомені (app.example.com) до API на (example.com) потрібне налаштування CORS в PHP. Без правильних заголовків браузер блокує запити. Додатково потрібна передача cookie-сесії з withCredentials: true в axios.

// на початку контролера або в події OnPageStart
header('Access-Control-Allow-Origin: https://app.example.com');
header('Access-Control-Allow-Credentials: true');

Cookie-сесія Бітрікса відправляється з withCredentials: true — сесія авторизації працює крос-доменно.

Як обрати між REST API та кастомним контролером?

Кастомний контролер виграє в масштабованості: він у 2-3 рази швидший за REST API при вибірках з великих інфоблоків за рахунок прямих SQL-запитів через ORM.

Типові помилки при інтеграції Vue.js з Бітрікс

Чому варто використовувати кастомні контролери?

Вони дають повний контроль над даними. Наприклад, можна об'єднати запити до кількох інфоблоків в один метод, застосувати теговане кешування або додати бізнес-логіку. Вбудований REST API такого не дозволяє. При роботі з кастомними контролерами ви можете використовувати всі можливості ORM Бітрікса, включаючи фільтри, сортування та пагінацію.

Що входить в роботу

• Вихідний код контролерів, сервісів та API-клієнта.
• Повна документація по всіх методах.
• Інструкція з розгортання на вашому сервері.
• Гарантія на доопрацювання протягом 30 днів.
• Підтримка 2 тижні після здачі проекту.

Процес роботи

1. Аналіз — вивчаємо архітектуру вашого сайту, вимоги до SPA, обираємо оптимальний механізм.
2. Проектування — проектуємо API, схеми даних, захист.
3. Розробка — пишемо контролери, налаштовуємо CORS, створюємо composables.
4. Тестування — перевіряємо навантаження, безпеку, кешування.
5. Деплой та документація — публікуємо API, даємо інструкції.

Терміни та вартість

Базове налаштування одного API-методу займає від 2 до 3 днів, вартість розраховується індивідуально після аналізу вашого проекту. Повноцінна інтеграція SPA з каталогом, кошиком та авторизацією — від 1 до 2 тижнів, точна вартість визначається на етапі проектування.

Наша команда — сертифіковані спеціалісти з досвідом роботи з 1С-Бітрікс, понад 50 успішних проектів з Vue.js. Ми гарантуємо стабільність та безпеку API. Зв'яжіться з нами для попереднього аналізу — ми підберемо оптимальний спосіб інтеграції. Замовте консультацію по вашому проекту, і ми запропонуємо рішення.

Чому CIBlockElement::GetList вбиває UX — і до чого тут Vue

Стандартний компонент bitrix:catalog.section при кожному кліку по фільтру перезавантажує сторінку цілком. Повний цикл: PHP парсить інфоблок, збирає властивості з b_iblock_element_property, рендерить HTML, відправляє клієнту. На каталозі в 50 000 SKU це 800–1200 мс. Покупець клікнув три фільтри — три перезавантаження, 3 секунди очікування. В e-commerce це прямий шлях до втрати до 20% конверсії. Vue.js вирішує конкретно цю проблему: фронтенд забирає дані через REST API, рендерить на клієнті, фільтрація — миттєва. Бітрікс залишається бекендом: контент, каталог, замовлення, обмін з 1С. Наша команда впроваджує такий підхід понад 7 років і бачить стабільне прискорення завантаження в 3–5 разів. Офіційна документація Vue.js: «Vue дозволяє створювати реактивні користувацькі інтерфейси з мінімальними зусиллями».

Розробка на Vue.js для 1С-Бітрікс — спосіб перетворити важкий моноліт на чуйний інтерфейс. Ми застосовуємо його в проектах з каталогами від 10 000 SKU і гарантуємо час завантаження сторінки не більше 400 мс після впровадження. Сертифіковані розробники Бітрікс з досвідом 10+ років та понад 50 успішними впровадженнями забезпечують стабільну інтеграцію. Зв'яжіться з нами для консультації — оцінимо можливість прискорення безкоштовно.

Коли Vue виправданий?

Не кожному сайту потрібен фронтенд-фреймворк. Vue виправданий, коли стандартні компоненти Бітрікса не витягують. Основні сценарії:

• Каталоги з важкою фільтрацією — catalog.smart.filter з AJAX працює, але на складних комбінаціях SKU-властивостей гальмує. Vue + API = миттєвий відгук. У нашого клієнта каталог на 80 000 товарів після переходу на Vue став завантажуватися на 60% швидше.
• Особисті кабінети — повноцінні SPA з дашбордами, графіками, реактивними формами. sale.personal.section виглядає застарілим.
• Конфігуратори та калькулятори — візуальні редактори, підбирачі комплектації з перерахунком цін у реальному часі.
• Real-time — чати, сповіщення, оновлення залишків через WebSocket.
• PWA — офлайн-режим, push-сповіщення, встановлення на домашній екран.

Як Vue.js вирішує проблеми UX у Бітріксі?

Порівняння: стандартний компонент bitrix:catalog.section при фільтрації 50 000 товарів видає сторінку за 800 мс + перезавантаження. Vue-віджет на базі REST API рендерить той самий список за 200–300 мс без перезавантаження — в 3–4 рази швидше. У нашій практиці клієнт отримав збільшення середньої глибини перегляду на 35% після впровадження. Економія на серверній інфраструктурі сягає 70% завдяки зменшенню кількості PHP-запитів.

Три архітектурні підходи до інтеграції Vue.js з Бітрікс

Острівний — Vue-віджети на сторінках Бітрікс

Окремі Vue-компоненти монтуються в div#app-filter, div#app-cart на стандартних сторінках Бітрікса. Маршрутизація та серверний рендеринг — як і раніше Бітрікс. Мінімальне втручання в існуючий сайт. Підходить для поетапної модернізації. Типовий приклад — реактивний фільтр замість catalog.smart.filter. В одному з проектів ми замінили фільтр на Vue-віджет за 2 тижні, конверсія зросла на 18%.

SPA на Vue + Бітрікс REST API

Фронтенд — повноцінне Vue-додаток з Vue Router. Бітрікс віддає дані через REST API: штатний модуль rest або кастомні контролери D7. Адмінка Бітрікса — для керування контентом, редактор не помічає різниці. Ідеально для особистих кабінетів, B2B-порталів та внутрішніх додатків, де SEO не критичний.

Nuxt.js + Бітрікс як headless CMS

Nuxt забезпечує SSR/SSG для індексації. Бітрікс — headless: віддає дані через API, керує контентом. Для магазинів і контентних сайтів, де SEO — пріоритет. Ми використовуємо Nuxt 3 з Vue Router для гібридного рендерингу — каталог статично, корзина SSR. Економія на ліцензіях і серверах після впровадження становить десятки тисяч гривень на рік.

Які особливості REST API Бітрікс важливі для Vue-розробки?

Тут зосереджено 70% часу при інтеграції Vue + Бітрікс.

Штатний REST-модуль

Інфоблоки, каталог, корзина (sale.basket.*), замовлення (sale.order.*), користувачі — з коробки. Обмеження: штатні методи не завжди покривають кастомну логіку. Метод catalog.product.list не віддає обчислювані властивості — потрібен кастомний ендпоінт.

Кастомні контролери D7

Клас Bitrix\Main\Engine\Controller — правильний спосіб створення API для Vue. Автоматична валідація параметрів, CSRF-захист з коробки, типізовані відповіді. Не ajax.php з $_POST — це шлях до ін'єкцій.

namespace App\Controller;
use Bitrix\Main\Engine\Controller;

class CatalogController extends Controller
{
    public function getProductsAction(array $filter, int $page = 1): array
    {
        // ORM-запит до інфоблоку, не CIBlockElement::GetList
    }
}

Авторизація та кешування

Авторизація: OAuth 2.0 для SPA або сесійні токени. Rate limiting — через Bitrix\Main\Engine\Controller або nginx. Кешування: API-відповіді кешуються на рівні D7 з тегованою інвалідацією. Змінився товар в інфоблоці — кеш скинувся по тегу iblock_id_X. Без цього при 100 RPS сервер ляже. Ми налаштовуємо це в кожному проекті — гарантія стабільності під навантаженням. Приклад налаштування тегованого кешування:

use Bitrix\Main\Data\Cache;

$cache = Cache::createInstance();
$tag = 'iblock_id_' . $iblockId;
if ($cache->initCache(3600, md5($filter), $tag)) {
    return $cache->getVars();
}
// запит до БД
$cache->startDataCache();
$cache->endDataCache($data);
\CIBlock::registerWithTagCache($iblockId);

Якою має бути структура Vue-додатку для Бітрікса?

• Vue Router — lazy loading маршрутів через defineAsyncComponent. Каталог не тягне за собою код особистого кабінету.
• Pinia — стейт-менеджмент: каталог, корзина, користувач, фільтри. Модульна архітектура сховища. Vuex — легасі, нові проекти на Pinia.
• Axios з перехоплювачами: автоматичне оновлення CSRF-токена, retry при 503, обробка помилок авторизації.
• Vue Query (TanStack Query) — кешування API-запитів, автоматична ревалідація, оптимістичні оновлення. Користувач додав товар у корзину — UI оновився миттєво, запит до API пішов фоном.

Каталог на Vue — розбір ключового кейсу

Різниця в UX відчувається одразу. Конкретика:

• Фільтр — чекбокси, range-слайдери, select з пошуком. Стан синхронізується з URL через vue-router query params — посилання з фільтрами можна відправити колезі.
• Картка товару — галерея з зумом, перемикання SKU (колір/розмір), ціна перераховується через API catalog.product.offer.list, залишки по складах з catalog.store.product.list.
• Віртуальний скролінг — vue-virtual-scroller рендерить лише видимі елементи. Каталог у 10 000 товарів працює без гальм.
• Розумний пошук — debounced-запити до search.title.search або ElasticSearch, автодоповнення через випадаючий список. У нашому проекті це скоротило час пошуку на 40%.
• Порівняння — динамічна таблиця характеристик з підсвічуванням відмінностей. Зберігання в Pinia + localStorage для персистентності.

Процес впровадження Vue.js покроково:

1. Аудит поточної архітектури Бітрікса та виявлення вузьких місць (фільтрація, корзина, особистий кабінет).
2. Проектування API — визначаємо ендпоінти, моделі даних, використовуємо Bitrix\Main\Engine\Controller.
3. Розробка Vue-віджетів або SPA — збірка на Vite, Code Splitting, Pinia.
4. Інтеграція з Бітріксом — теговане кешування, OAuth, обробка помилок.
5. Тестування під навантаженням (до 100 RPS) та деплой з CI/CD.

Продуктивність досягається за рахунок code splitting, tree shaking та lazy loading важких компонентів (Chart.js, карти, WYSIWYG). Бандл сторінки каталогу — 80–120 КБ gzip.

Nuxt.js і SEO: як зберегти індексацію

SPA на чистому Vue віддає пошуковику порожній HTML з <div id="app"></div>. Google вміє рендерити JS, але з затримкою в дні. Яндекс — взагалі непередбачувано. Nuxt.js вирішує:

• SSR — сервер віддає повний HTML, після гідратації працює як SPA.
• SSG — сторінки генеруються при nuxt generate, роздаються з CDN. Максимальна швидкість.
• Гібридний режим — каталог статично, корзина та ЛК — SSR.
• useHead() — динамічні title, description, Open Graph, Schema.org для кожної сторінки.
• Sitemap — @nuxtjs/sitemap, маршрути з API Бітрікса. Це забезпечує повну індексацію — наша гарантія потрапляння в топ-5 Google.

Порівняння підходів та строки

Повний цикл: проектування API, розробка контролерів D7, Vue-додаток, налаштування Vite, тестування, деплой. Код рев'юється, покривається тестами, документується — не «зібрав і забув». Вартість розробки розраховується індивідуально після аналізу вашого поточного сайту та ТЗ. Детальну оцінку ви отримаєте протягом дня — замовте консультацію.

Типові помилки при інтеграції Vue.js і Бітрікс

1. Використання ajax.php замість Bitrix\Main\Engine\Controller — призводить до вразливостей та нестабільності.
2. Відсутність тегованого кешування API — при високому навантаженні сервер не витримує.
3. Ігнорування авторизації OAuth для SPA — сесійні токени можуть закінчуватися, ламаючи UX.
4. Повний перепис всього сайту на SPA без необхідності — збільшує строки та бюджет.
5. Неправильне налаштування Nuxt SSR — повільна генерація сторінок на бекенді.

Що входить у роботу та наші гарантії

• Документація API (Swagger/OpenAPI) для інтеграції з вашим бекендом.
• Доступи до репозиторію з кодом та CI/CD.
• Навчання вашої команди роботі з Vue-компонентами.
• Пост-релізна підтримка на 1 місяць — гарантія стабільності.
• Код відповідає стандартам PSR-12 та Bitrix\Main\Engine\Controller.

Замовте розробку Vue.js інтерфейсів для вашого Бітрікс-проекту — отримайте консультацію та оцінку строків протягом дня. Напишіть нам, і ми надішлемо комерційну пропозицію з детальним планом робіт. Оцінимо проект безкоштовно — просто надішліть ТЗ або посилання на поточний сайт.