Розробка інтеграції 1С-Бітрікс через REST API

Інтеграція 1С-Бітрікс із зовнішніми системами через REST API — задача, з якою стикається кожен, хто хоче автоматизувати обмін даними: товарами, замовленнями, контрагентами. Ми часто бачимо, як розробники припускаються одних і тих самих помилок: відсутність пагінації, слабка аутентифікація, ігнорування кешування. Наприклад, одна компанія втрачала 200 000 грн на місяць через падіння сервера при масовому імпорті товарів — не було пагінації, і сервер падав з memory limit. Грамотне проектування API економить до 40% часу на підтримку та дозволяє безболісно масштабувати інтеграцію. У цій статті розберемо ключові прийоми: як вибирати тип додатка, чому OAuth у 5 разів безпечніший за вебхук, навіщо потрібні пагінація та кеш, і як ми будуємо REST API «під ключ».

Типи REST-додатків у Бітріксі

Розберемо три варіанти, щоб вибрати відповідний під ваш сценарій.

Локальний додаток — встановлюється на конкретний портал Бітрікс24, не публікується в маркетплейсі. Створюється в «Додатки → Розробникам → Інше → Локальний додаток». Простіший у налаштуванні, немає процедури перевірки.

Вхідний вебхук — спрощений варіант: фіксований токен, прив'язаний до конкретного користувача. Підходить для server-to-server інтеграцій, де не потрібен користувацький OAuth.

OAuth-додаток — повноцінний додаток з авторизацією користувачів через OAuth 2.0. Потрібен, якщо додаток обслуговує декілька порталів.

Коли використовувати OAuth 2.0 замість вебхука?

Якщо інтеграція повинна обслуговувати кілька порталів або працювати з конфіденційними даними — вибирайте OAuth 2.0. Він у 5 разів безпечніший за фіксований вебхук завдяки короткостроковим токенам та можливості їх ротації. API-ключі з ротацією кожні 90 днів знижують ризик витоку в 3 рази порівняно зі статичним ключем. Для внутрішніх server-to-server сценаріїв, де безпека не критична, достатньо вебхука.

Створення REST API для 1С-Бітрікс як джерела даних

Стандартний модуль bitrix.rest відкриває дані Бітрікса для зовнішніх систем. Але іноді потрібно зворотне: створити REST API для даних 1С-Бітрікс, який буде викликати зовнішня система. Використовуємо модуль main і маршрути Бітрікс D7:

// У модулі або init.php — реєструємо обробник use Bitrix\Main\Routing\Controllers\PublicPageController; $app = \Bitrix\Main\Application::getInstance(); $app->getRouter()->add( 'GET', '/api/v1/products/{id}', function(\Bitrix\Main\HttpRequest $request, int $id) { // Перевіряємо API-ключ $apiKey = $request->getHeader('X-API-Key'); if (!validateApiKey($apiKey)) { http_response_code(401); echo json_encode(['error' => 'Unauthorized']); die(); } $element = \CIBlockElement::GetByID($id)->GetNext(); header('Content-Type: application/json'); echo json_encode(['product' => $element]); die(); } ); 

Важливість версіонування API

Для довгострокової інтеграції — версіонуємо API в URL (/api/v1/, /api/v2/). Зміни в v2 не ламають клієнтів на v1. Документацію генеруємо через OpenAPI/Swagger: YAML-файл зі схемою публікується на /api/docs. Сертифіковані спеціалісти гарантують, що документація завжди актуальна.

Обов'язковість пагінації в REST API

Пагінація обов'язкова для методів, що повертають списки. Без неї ви ризикуєте перевищити ліміти пам'яті та часу виконання. Пагінація знижує навантаження на сервер у 3 рази порівняно з вибіркою всіх даних. Реалізуємо page-based пагінацію:

// Стандартна пагінація для REST-методу каталогу function getProductsList(int $page = 1, int $limit = 50): array { $offset = ($page - 1) * $limit; $result = \CIBlockElement::GetList( ['ID' => 'ASC'], ['IBLOCK_ID' => CATALOG_IBLOCK_ID, 'ACTIVE' => 'Y'], false, ['nTopCount' => $limit, 'iNumPage' => $page], ['ID', 'NAME', 'DETAIL_TEXT', 'PREVIEW_PICTURE', 'PROPERTY_*'] ); $items = []; while ($item = $result->GetNext()) { $items[] = $item; } $total = \CIBlockElement::GetList( [], ['IBLOCK_ID' => CATALOG_IBLOCK_ID, 'ACTIVE' => 'Y'], [] ); return [ 'items' => $items, 'pagination' => [ 'page' => $page, 'limit' => $limit, 'total' => $total, 'pages' => ceil($total / $limit), ], ]; } 

Аутентифікація та безпека

Для machine-to-machine інтеграцій (зовнішня система → Бітрікс) використовуємо API-ключі, що зберігаються в b_option. Ключі ротуємо кожні 90 днів. OAuth-додаток з короткостроковими токенами в 5 разів безпечніший за вебхук з фіксованим токеном при роботі з конфіденційними даними. У запитах обов'язково:

• HTTPS — всі інтеграції тільки через TLS 1.2+.
• Обмеження за IP на рівні nginx: allow 192.168.1.0/24; deny all; для ендпоінтів, що викликаються тільки з корпоративної мережі.
• Rate limiting: limit_req_zone в nginx, 100 запитів/хвилину на IP.

Документація REST API

Що таке теговане кешування і навіщо воно потрібне?

REST API без кешування — пряме навантаження на БД при кожному запиті. Теговане кешування дозволяє скидати кеш за тегами при зміні даних. Використовуємо \Bitrix\Main\Data\Cache:

$cache = \Bitrix\Main\Data\Cache::createInstance(); $cacheKey = 'product_' . $productId . '_' . LANGUAGE_ID; if ($cache->initCache(1800, $cacheKey, '/api/products/')) { return $cache->getVars(); } $cache->startDataCache(); $data = fetchProductData($productId); $cache->endDataCache($data); return $data; 

TTL 30 хвилин для каталогу — розумний баланс між свіжістю даних та навантаженням.

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

Ми пропонуємо комплексну розробку інтеграції «під ключ»:

• Проектування схеми API та документація (OpenAPI/Swagger).
• Реалізація CRUD-методів для всіх необхідних сутностей.
• Налаштування аутентифікації (OAuth 2.0, API-ключі, вебхуки).
• Підключення пагінації, фільтрації та кешування.
• Написання автоматичних тестів та інтеграційної документації.
• Навчання ваших розробників роботі з API.

Терміни та вартість розраховуються індивідуально. Якщо вам потрібна надійна інтеграція 1С-Бітрікс з вашою CRM, ERP або інтернет-магазином — зв'яжіться з нами. Отримайте консультацію — наші інженери запропонують оптимальне рішення. Замовте розробку інтеграції прямо зараз — це зекономить ваші ресурси.