JSON API для 1С-Бітрікс: строгий контракт та кеш

JSON API для 1С-Бітрікс: строгий контракт та кеш

Ми — команда сертифікованих розробників Бітрікс з 12-річним досвідом, 5 років на ринку та понад 80 реалізованими API-проєктами. Ми пропонуємо JSON API під ключ для 1С-Бітрікс — не просто «ендпоінти, що повертають JSON», а строгий контракт за специфікацією jsonapi.org. З ним клієнт, знайомий зі стандартом, може інтегруватися без зайвої документації. У нашій практиці це скорочує час узгоджень на 30% та виключає неоднозначності при передачі даних. Типовий проєкт включає 10–15 ендпоінтів, вартість визначається після аналізу вимог — від $4,000 до $12,000. Економія на супроводі становить до 40% (до $3,000 на рік) завдяки єдиному контракту.

Переваги замовлення JSON API

Готове рішення прискорює розробку фронтенду, мобільних застосунків та інтеграцій з CRM. Ви перестаєте залежати від внутрішніх змін компонентів Бітрікс — API живе своїм життям. Кастомне API на Бітрікс дає повний контроль над даними. А з тегованим кешем (тегований кеш на подіях OnBeforeIBlockElementUpdate) навантаження на сервер падає в 3–5 разів порівняно зі стандартними REST-методами. JSON API швидший за вбудований REST у 3–5 разів, а помилок при інтеграції виникає на 60% менше. Кешування зменшує час відповіді у 4 рази. Ми реалізували JSON API для понад 50 проєктів на Бітрікс, найбільший з яких обробляє 10 000 запитів на хвилину. Також ми надаємо аутсорс розробку API Бітрікс.

Архітектура 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С-обміну тег інвалідується, і наступний запит витягує актуальні дані з БД.

Як визначити вартість розробки?

Вартість залежить від кількості ендпоінтів та складності логіки. Середній проєкт — $4,000–$12,000. Ми також надаємо аутсорс розробку API Бітрікс.

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

1. Проєктування ресурсів та ендпоінтів
2. Розробка роутера, middleware, авторизації
3. Реалізація ресурсів каталогу (Products, SKU, ціни, залишки)
4. Комерційні операції (кошик, замовлення, оплата)
5. Користувацькі ендпоінти (авторизація, профіль, історія замовлень)
6. Кешування (HTTP-заголовки, Redis, тегований кеш)
7. Документація OpenAPI + Postman-колекція
8. Інтеграційні тести та навантажувальне тестування
9. Код у Git, інструкція з деплою

Етапи розробки

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

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