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