Налаштування 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. Зв'яжіться з нами для попереднього аналізу — ми підберемо оптимальний спосіб інтеграції. Замовте консультацію по вашому проекту, і ми запропонуємо рішення.