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

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

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

Типы REST-приложений в Битриксе

Локальное приложение — устанавливается на конкретный портал Битрикс24, не публикуется в маркетплейсе. Создаётся в «Приложения → Разработчикам → Другое → Локальное приложение». Проще в настройке, нет процедуры проверки.

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

OAuth-приложение — полноценное приложение с авторизацией пользователей через OAuth 2.0. Нужно, если приложение обслуживает несколько порталов.

Создание 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-метода каталога
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 дней. В запросах обязательно:

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