REST API на 1С-Битрикс: проектирование, реализация, документация

Битрикс имеет встроенный REST API для Битрикс24, но для сайта на «1С-Битрикс: Управление сайтом» собственного REST нет — его нужно строить. Задача возникает регулярно: мобильное приложение требует данные каталога, сторонний сервис хочет получать заказы, фронтенд на React или Vue нужно снабжать данными без перезагрузки страницы. Типичная боль: при каждом новом интеграторе приходится писать костыли на COption::GetOptionString и выводить JSON через echo json_encode(), а через месяц код превращается в «лапшу».

У нас за плечами 10+ лет опыта Битрикс-разработки и более 50 реализованных API-интеграций, обрабатывающих до 10 000 RPS. Знаем все подводные камни: от проблем с кэшированием инфоблоков до ошибок сериализации в ORM. Гарантируем стабильную работу под нагрузкой и предоставляем документацию Swagger для каждого эндпоинта. Средняя экономия времени на интеграцию с внешними сервисами составляет 40%.

Как построить REST API на D7?

Основа API — контроллеры на базе \Bitrix\Main\Engine\Controller. Каждый контроллер отвечает за один ресурс. Сравнение с самописными решениями: D7-контроллеры автоматически обрабатывают ошибки, сериализуют ответы в JSON и поддерживают префильтры. Это в 2–3 раза сокращает объём кода по сравнению с ручной обработкой через $APPLICATION->RestartBuffer().

1. Создайте модуль в /local/modules/ с структурой my.api. Определите install/index.php с методами InstallDB() и UnInstallDB() для создания таблиц.
2. Регистрируйте контроллеры в routes.php (начиная с ядра 20.0). Сопоставьте URL с классами, например 'api/v1/products' => 'MyApi\Controllers\ProductController'.
3. Реализуйте action-методы. Каждый метод возвращает массив — ядро сериализует его в JSON. Добавьте префильтры для аутентификации и ограничения HTTP-методов.
4. Подключите сервис-слой — вынесите логику выборки и обработки в отдельные классы ProductService, OrderService и т.д. Это упрощает юнит-тестирование.
5. Документируйте эндпоинты через Swagger (OpenAPI 3.0). Генерируйте спецификацию из аннотаций или вручную. Разместите Swagger UI в /local/swagger/.

/local/modules/my.api/lib/ ├── Controllers/ │ ├── ProductController.php → GET /api/v1/products │ ├── OrderController.php → GET/POST /api/v1/orders │ ├── CategoryController.php → GET /api/v1/categories │ └── AuthController.php → POST /api/v1/auth/token ├── Services/ │ ├── ProductService.php │ └── OrderService.php ├── Transformers/ │ ├── ProductTransformer.php → форматирование ответа │ └── OrderTransformer.php └── Middleware/ ├── AuthMiddleware.php └── RateLimitMiddleware.php 

Пример контроллера: метод listAction принимает параметры пагинации и возвращает данные с мета-информацией. Код короткий, без лишних проверок — всё встроено в D7.

namespace MyApi\Controllers; use Bitrix\Main\Engine\Controller; use Bitrix\Main\Engine\ActionFilter; use MyApi\Services\ProductService; use MyApi\Middleware\AuthMiddleware; class ProductController extends Controller { public function configureActions(): array { return [ 'list' => ['prefilters' => [new AuthMiddleware()]], 'detail' => ['prefilters' => [new AuthMiddleware()]], 'create' => ['prefilters' => [new AuthMiddleware(), new ActionFilter\HttpMethod(['POST'])]], ]; } public function listAction(int $page = 1, int $perPage = 20, string $category = ''): array { $service = new ProductService(); $result = $service->getList($page, $perPage, $category); return [ 'data' => $result['items'], 'meta' => [ 'total' => $result['total'], 'page' => $page, 'per_page' => $perPage, 'pages' => ceil($result['total'] / $perPage), ], ]; } public function detailAction(int $id): array { $service = new ProductService(); $product = $service->getById($id); if (!$product) { $this->addError(new \Bitrix\Main\Error('Товар не найден', 404)); return []; } return ['data' => $product]; } } 

Как обеспечить безопасность REST API?

Аутентификация — частый источник проблем. Для server-to-server используем API-ключи: простой заголовок X-Api-Key. Для пользовательских запросов (mobile app, SPA) — JWT. Библиотека firebase/php-jwt подключается через Composer. Refresh-токены сохраняем в кастомной ORM-таблице с привязкой к пользователю. Это надёжнее, чем хранить сессии в файлах.

Подробнее о JWT: JSON Web Token (Wikipedia).

Формат ответов — консистентность важна. Мы придерживаемся единого шаблона: status, data, meta для успеха, errors для ошибок. D7-контроллер формирует ответ автоматически, но мы переопределяем processAfterAction для полного контроля.

protected function processAfterAction(Action $action, $result) { $response = \Bitrix\Main\Application::getInstance()->getContext()->getResponse(); $response->addHeader('Content-Type', 'application/json; charset=utf-8'); if ($this->getErrors()) { echo json_encode([ 'status' => 'error', 'errors' => array_map(fn($e) => [ 'code' => $e->getCode(), 'message' => $e->getMessage(), ], $this->getErrors()), ], JSON_UNESCAPED_UNICODE); } else { echo json_encode([ 'status' => 'ok', 'data' => $result, ], JSON_UNESCAPED_UNICODE); } exit; } 

CORS — если API вызывается с другого домена, обязательно добавляем заголовки и обрабатываем OPTIONS-запросы. Иначе браузер блокирует запросы.

Rate limiting — защита от перегрузок. Используем Redis или, для малой нагрузки, b_option. Например, 1000 запросов в час на ключ.

Как протестировать API?

Пишите интеграционные тесты на PHPUnit. Для изоляции используйте SQLite вместо MySQL. Проверяйте не только успешные сценарии, но и граничные случаи: неверные параметры, отсутствующие ресурсы, превышение лимитов. Пример теста для listAction:

public function testListReturnsPaginationMeta(): void { $controller = new ProductController(); $result = $controller->listAction(1, 10); $this->assertArrayHasKey('meta', $result); $this->assertArrayHasKey('total', $result['meta']); } 

Что входит в работу

Мы не просто пишем код. Каждый проект включает:

• Техническое задание с прототипом эндпоинтов.
• Архитектурную схему модуля.
• Реализацию контроллеров, сервисов, трансформеров.
• Документацию OpenAPI 3.0 (Swagger).
• Настройку rate limiting и CORS.
• Инструкцию по деплою и поддержку в течение месяца.

Сроки ориентировочно

REST API на Битрикс строится из стандартных блоков — контроллеры, ORM, кеш. Сложность не в технологии, а в проектировании: правильные эндпоинты, консистентные форматы ответов, обработка граничных случаев. Если вам нужен надёжный REST API для вашего сайта на Битрикс, свяжитесь с нами — мы оценим ваш проект за один день. Закажите разработку REST API и получите готовую документацию Swagger в комплекте.

Официальная документация Битрикс D7