Разработка JSON API для 1С-Битрикс под ключ — строгий контракт и кеш

Разработка JSON API для 1С-Битрикс под ключ

Мы разрабатываем JSON API для 1С-Битрикс — не просто «эндпоинты, возвращающие JSON», а строгий контракт по спецификации jsonapi.org. С ним клиент, знакомый со стандартом, может интегрироваться без лишней документации. В нашей практике это сокращает время согласований на 30% и исключает неоднозначности при передаче данных. Типичный проект включает 10–15 эндпоинтов, стоимость разработки варьируется от $1k–3k в зависимости от сложности. При этом экономия на сопровождении составляет до 40% за счёт единого контракта.

Преимущества заказа JSON API

Готовое решение ускоряет разработку фронтенда, мобильных приложений и интеграций с CRM. Вы перестаёте зависеть от внутренних изменений компонентов Битрикс — API живёт своей жизнью. А с тегированным кешем (тегированный кеш на событиях OnBeforeIBlockElementUpdate) нагрузка на сервер падает в 3–5 раз по сравнению со стандартными REST-методами. JSON API быстрее и предсказуемее, чем встроенный REST, особенно при работе с каталогами на 10 000+ товаров.

Архитектура JSON API на Битрикс

Чистая PHP-реализация поверх ядра Битрикс. Точка входа — контроллер вне компонентной системы:

/local/ api/ v1/ router.php — маршрутизация запросов middleware/ AuthMiddleware.php RateLimitMiddleware.php resources/ ProductResource.php — трансформер данных OrderResource.php controllers/ ProductController.php OrderController.php 

В router.php определяются маршруты. Например, для товаров и заказов:

$router->get('/v1/products', [ProductController::class, 'index']); $router->get('/v1/products/{id}', [ProductController::class, 'show']); $router->post('/v1/orders', [OrderController::class, 'create']); $router->patch('/v1/orders/{id}', [OrderController::class, 'update']); 

Трансформация данных в JSON API

Resource-класс преобразует сырые данные из инфоблоков в JSON-структуру, изолируя клиентов от изменений полей. Пример для товаров:

class ProductResource { public static function make(array $product, array $include = []): array { $data = [ 'id' => (int)$product['ID'], 'type' => 'products', 'attributes' => [ 'name' => $product['NAME'], 'code' => $product['CODE'], 'description' => $product['DETAIL_TEXT'], 'active' => $product['ACTIVE'] === 'Y', 'created_at' => $product['DATE_CREATE'], ], 'relationships' => [], ]; if (in_array('prices', $include)) { $data['relationships']['prices'] = PriceResource::collection( PriceRepository::getForProduct((int)$product['ID']) ); } if (in_array('sku', $include)) { $data['relationships']['sku'] = SkuResource::collection( SkuRepository::getForProduct((int)$product['ID']) ); } return $data; } } 

Параметр ?include=prices,sku в запросе управляет включением связанных данных — клиент получает ровно то, что нужно.

Фильтрация, сортировка и пагинация

Все три механизма реализуются через query-параметры. Они работают в одном коде и возвращают метаданные о количестве записей.

// Фильтрация $filter = ['IBLOCK_ID' => CATALOG_IBLOCK_ID, 'ACTIVE' => 'Y']; if (isset($_GET['filter']['section_id'])) { $filter['SECTION_ID'] = (int)$_GET['filter']['section_id']; } // Сортировка $sort = []; foreach (explode(',', $_GET['sort'] ?? 'id') as $field) { $direction = str_starts_with($field, '-') ? 'DESC' : 'ASC'; $sort[ltrim($field, '-')] = $direction; } // Пагинация (offset-based) $limit = (int)($_GET['page']['size'] ?? 20); $offset = ((int)($_GET['page']['number'] ?? 1) - 1) * $limit; 

Ответ включает метаданные:

{ "data": [...], "meta": { "total": 1543, "page": 2, "per_page": 20, "last_page": 78 }, "links": { "self": "/v1/products?page[number]=2", "next": "/v1/products?page[number]=3", "prev": "/v1/products?page[number]=1" } } 

Создание заказа

POST /v1/orders с телом запроса:

{ "data": { "type": "orders", "attributes": { "delivery_address": "Москва, ул. Пушкина, 1", "payment_method": "card" }, "relationships": { "items": { "data": [ { "type": "order-items", "product_id": 123, "quantity": 2 }, { "type": "order-items", "product_id": 456, "quantity": 1 } ] } } } } 

Контроллер валидирует данные и вызывает \Bitrix\Sale\Order::create() через D7-API модуля sale. При ошибке — ответ 422 Unprocessable Entity со структурированным списком ошибок.

Авторизация

• Сессия Битрикс. Для запросов из браузерных приложений, где пользователь залогинен на сайте. Проверяем \CUser::IsAuthorized().
• Bearer-токен (JWT). Для мобильных клиентов и server-to-server. Middleware декодирует JWT, получает user_id, инициализирует сессию Битрикс:

$userId = $jwt->getClaim('sub'); \CUser::SetCurrent($userId); 

После этого все штатные проверки прав работают корректно.

• API Key. Для B2B-партнёров. Ключ в заголовке X-API-Key, привязан к пользователю или группе в Битрикс.

Валидация входных данных

Перед передачей в модули — строгая валидация. Каждый эндпоинт имеет Request-класс с правилами:

class CreateOrderRequest { public function validate(array $data): array { $errors = []; if (empty($data['delivery_address'])) { $errors[] = ['pointer' => '/data/attributes/delivery_address', 'detail' => 'Обязательное поле']; } if (!in_array($data['payment_method'] ?? '', ['card', 'cash', 'invoice'])) { $errors[] = ['pointer' => '/data/attributes/payment_method', 'detail' => 'Недопустимое значение']; } return $errors; } } 

Ошибки возвращаются в формате JSON API Errors:

{ "errors": [ { "status": "422", "source": { "pointer": "/data/attributes/delivery_address" }, "title": "Ошибка валидации", "detail": "Обязательное поле" } ] } 

Кеширование ответов

Для GET-запросов настраиваем HTTP-кеш через заголовки:

header('Cache-Control: public, max-age=600, s-maxage=3600'); header('ETag: "' . md5($cacheKey . $dataHash) . '"'); 

На стороне Битрикс — тегированный кеш для агрегированных данных. При обновлении товара из 1С-обмена тег инвалидируется, и следующий запрос вытягивает актуальные данные из БД.

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

• Проектирование ресурсов и эндпоинтов
• Разработка роутера, middleware, авторизации
• Реализация ресурсов каталога (Products, SKU, цены, остатки)
• Коммерческие операции (корзина, заказы, оплата)
• Пользовательские эндпоинты (авторизация, профиль, история заказов)
• Кеширование (HTTP-заголовки, Redis, тегированный кеш)
• Документация OpenAPI + Postman-коллекция
• Интеграционные тесты и нагрузочное тестирование
• Код в Git, инструкция по деплою

Этапы разработки

JSON API на Битрикс — это строгий, предсказуемый контракт, который живёт независимо от версий компонентов и шаблонов. При правильной реализации фронтенд-команда работает с API как с независимым сервисом. Все запросы логируются, ошибки возвращаются в стандартном формате, а версионирование защищает клиентов от неожиданных изменений схемы данных.

Оцените свой проект бесплатно. Напишите нам — мы проанализируем требования и предложим архитектуру со сроками. Получите консультацию инженера с опытом более 10 лет в Битрикс.