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 Бітрікс.
Що входить у роботу
- Проєктування ресурсів та ендпоінтів
- Розробка роутера, middleware, авторизації
- Реалізація ресурсів каталогу (Products, SKU, ціни, залишки)
- Комерційні операції (кошик, замовлення, оплата)
- Користувацькі ендпоінти (авторизація, профіль, історія замовлень)
- Кешування (HTTP-заголовки, Redis, тегований кеш)
- Документація OpenAPI + Postman-колекція
- Інтеграційні тести та навантажувальне тестування
- Код у Git, інструкція з деплою
Етапи розробки
| Етап | Зміст | Строк |
|---|---|---|
| Проєктування | Ресурси, ендпоінти, формат даних | 1 тиждень |
| Інфраструктура | Роутер, middleware, авторизація | 1 тиждень |
| Ресурси каталогу | Products, SKU, ціни, залишки, секції | 1–2 тижні |
| Комерційні операції | Кошик, замовлення, оплата | 1–2 тижні |
| Користувацькі ендпоінти | Авторизація, профіль, історія замовлень | 1 тиждень |
| Кешування | HTTP-заголовки, Redis, тегований кеш | 1 тиждень |
| Документація | OpenAPI, Postman-колекція | 3–5 днів |
| Тестування | Інтеграційні тести, навантаження | 1 тиждень |
Деталі архітектури кешу
Використовуємо тегований кеш Бітрікс: при збереженні елемента інфоблоку викликається подія `OnAfterIBlockElementAdd`, яка інвалідує кеш за тегом `iblock_id_XXX`. Це гарантує актуальність даних без ручного скидання.JSON API на Бітрікс — це строгий, передбачуваний контракт, який живе незалежно від версій компонентів та шаблонів. При правильній реалізації фронтенд-команда працює з API як з незалежним сервісом. Усі запити логуються, помилки повертаються в стандартному форматі, а версіонування захищає клієнтів від несподіваних змін схеми даних.
Оцініть свій проєкт безкоштовно. Напишіть нам — ми проаналізуємо вимоги та запропонуємо архітектуру зі строками. Отримайте консультацію інженера з досвідом понад 10 років у Бітрікс.