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

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

1С-Бітрікс надає власний REST API через модуль bitrix.rest (починаючи з версії 14.0). Це не просто набір ендпоінтів — повноцінний фреймворк для створення застосунків та інтеграцій з автентифікацією OAuth 2.0, системою подій і вебхуків.

Типи REST-застосунків у 1С-Бітрікс

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

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

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

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

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

Використовуємо модуль main та маршрути Bitrix 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-методу каталогу
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 інтеграцій (зовнішня система → 1С-Бітрікс) використовуємо API-ключі, що зберігаються в b_option. Ключі ротуємо кожні 90 днів. У запитах обов'язково:

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

Кешування відповідей

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 хвилин для каталогу — розумний баланс між актуальністю даних та навантаженням.