Разработка API-шлюза для Битрикс24

Разработка API-шлюза для Битрикс24

REST API Битрикс24 мощный, но работать с ним напрямую из множества клиентских приложений — неудобно и небезопасно. Каждый клиент должен знать токены, понимать специфику методов, обходить лимиты. API-шлюз (gateway) — это промежуточный слой, который стандартизирует взаимодействие: клиентские приложения обращаются к шлюзу с понятным интерфейсом, шлюз транслирует вызовы в Битрикс24, агрегирует данные и возвращает нормализованный ответ.

Зачем нужен API-шлюз

Сокрытие сложности Битрикс24 API. Получение сделки со всеми связанными данными (контакт, компания, товары, задачи, дела) — это 5–7 отдельных REST-запросов к разным методам. Шлюз делает один вызов /deals/123, собирает все данные параллельно и отдаёт клиенту единый JSON.

Управление токенами. Клиентские приложения не хранят токены Битрикс24. Шлюз — единственное место, где хранятся OAuth-токены, обновляются access_token через refresh_token и контролируется их ротация.

Обход лимитов. Облачный Битрикс24 ограничивает: 2 запроса в секунду, 50 операций в batch. Шлюз реализует очередь и rate limiting — клиенты отправляют запросы сколько угодно быстро, шлюз сглаживает нагрузку.

Кеширование. Справочные данные (типы цен, стадии воронки, список пользователей) меняются редко — кешируем на уровне шлюза. Запросы одних и тех же данных не уходят в Битрикс24.

Единая точка мониторинга. Все вызовы логируются, метрики (latency, error rate) собираются в одном месте, алерты при деградации Битрикс24 API.

Архитектура шлюза

Шлюз — отдельный HTTP-сервис, как правило PHP (Laravel/Slim) или Node.js. Располагается между клиентами и Битрикс24.

Клиенты (мобильное приложение, внешний сайт, ERP)
        ↓  HTTP/JSON (собственный API шлюза)
  API-шлюз
    ├── Аутентификация клиента (JWT / API Key)
    ├── Валидация входных данных
    ├── Rate limiter
    ├── Кеш (Redis)
    ├── Маппер запросов → Битрикс24 REST
    └── Batch-агрегатор
        ↓  OAuth2 Token
  Битрикс24 REST API

Аутентификация клиентов шлюза

Клиенты шлюза аутентифицируются отдельно от Битрикс24. Варианты:

API Key. Простейший вариант для server-to-server. Клиент передаёт ключ в заголовке X-API-Key. Шлюз проверяет ключ в своей БД, определяет привязанный Битрикс24-аккаунт и права.

JWT. Для клиентов с пользователями. Пользователь логинится (через Битрикс24 OAuth или собственную систему), шлюз выдаёт JWT-токен. Каждый запрос к шлюзу содержит JWT в заголовке Authorization: Bearer. Шлюз декодирует токен, определяет пользователя и действует от его имени в Битрикс24.

OAuth 2.0 поверх шлюза. Если шлюз обслуживает несколько клиентских приложений от разных организаций, строим полноценный OAuth-сервер (Authorization Code Flow). Каждый клиент-приложение — отдельный OAuth-клиент шлюза.

Batch-запросы и параллелизация

Битрикс24 поддерживает batch: до 50 методов в одном HTTP-запросе. Шлюз агрегирует параллельные вызовы клиента в batch:

// Клиент вызывает 3 ресурса шлюза "одновременно"
// Шлюз собирает их в один batch к Битрикс24:
$batch = [
    'deal' => 'crm.deal.get?id=123',
    'contact' => 'crm.contact.get?id=456',
    'products' => 'crm.deal.productrows.get?id=123',
];
$result = $b24->batch($batch);

Для получения сделки со всеми данными шлюз формирует batch из 4–5 методов, выполняет один HTTP-запрос к Битрикс24 и собирает результат.

Кеширование в Redis

Два уровня кеша:

Справочники (TTL 1 час): стадии воронок (crm.status.list), пользователи (user.get), типы цен, источники лидов. Эти данные меняются редко и запрашиваются при каждом обращении к сделкам.

Сущности (TTL 5 минут): данные конкретных сделок, контактов, компаний. Инвалидируются при получении webhook от Битрикс24 об изменении объекта.

Ключ кеша: b24:{portal_id}:{method}:{hash(params)}. При webhook-событии ONCRMDEALUPDATE с ID=123 — инвалидируем b24:portal1:crm.deal.get:hash({id:123}).

Трансформация данных

Шлюз нормализует ответы Битрикс24. Из объекта со строковыми полями типа 'OPPORTUNITY' => '50000.00' получаем типизированный ответ:

{
  "id": 123,
  "title": "Сделка с компанией Рога и Копыта",
  "amount": 50000.00,
  "stage": "negotiation",
  "contact": {
    "id": 456,
    "name": "Иван Петров",
    "phone": "+79001234567"
  }
}

Маппинг задаётся в конфигурации шлюза — это позволяет менять структуру ответа без изменения клиентов.

Обработка ошибок и circuit breaker

Если Битрикс24 недоступен или отвечает с ошибкой 503 Too Many Requests, шлюз не должен слепо возвращать эту ошибку клиентам. Реализуем circuit breaker:

• Closed (нормальная работа): запросы проходят через шлюз к Битрикс24
• Open (Битрикс24 недоступен): шлюз сразу возвращает кешированные данные или ошибку с понятным сообщением, не создавая очередь из ожидающих запросов
• Half-Open (проверка восстановления): периодически пробуем тестовый запрос к Битрикс24

Мониторинг и метрики

Шлюз экспортирует метрики в Prometheus/Grafana или пишет в ELK:

• Latency по методам (p50, p95, p99)
• Error rate по коду ошибки
• Размер очереди запросов
• Hit rate кеша
• Текущий лимит Битрикс24 (из заголовка X-RateLimit-Remaining)

Этапы разработки

API-шлюз особенно оправдан, когда с Битрикс24 работают несколько приложений одновременно, или когда клиентские разработчики не должны знать специфику Битрикс24 API. Для одного небольшого интеграционного сценария — избыточно.