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

Розробка API-шлюзу для Bitrix24

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

Для чого потрібен API-шлюз

Приховування складності Bitrix24 API. Отримання угоди з усіма пов'язаними даними (контакт, компанія, товари, завдання, справи) — це 5–7 окремих REST-запитів до різних методів. Шлюз робить один виклик /deals/123, збирає всі дані паралельно та отримує клієнту єдиний JSON.

Управління токенами. Клієнтські додатки не зберігають токени Bitrix24. Шлюз — єдине місце, де зберігаються OAuth-токени, оновлюються access_token через refresh_token та контролюється їх ротація.

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

Кешування. Довідкові дані (типи цін, стадії лійки, список користувачів) змінюються рідко — кешуємо на рівні шлюзу. Запити одних і тих же даних не йдуть у Bitrix24.

Єдина точка моніторингу. Усі виклики логуються, метрики (latency, error rate) збираються в одному місці, сповіщення при деградації Bitrix24 API.

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

Шлюз — окремий HTTP-сервіс, як правило PHP (Laravel/Slim) або Node.js. Розташовується між клієнтами та Bitrix24.

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

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

Клієнти шлюзу аутентифікуються окремо від Bitrix24. Варіанти:

API Key. Найпростіший варіант для server-to-server. Клієнт передає ключ у заголовку X-API-Key. Шлюз перевіряє ключ у своїй БД, визначає прив'язаний Bitrix24-аккаунт та права.

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

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

Batch-запити та паралелізація

Bitrix24 підтримує batch: до 50 методів в одному HTTP-запиті. Шлюз агрегує паралельні виклики клієнта у batch:

// Клієнт викликає 3 ресурси шлюзу "одночасно"
// Шлюз збирає їх в один batch до Bitrix24:
$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-запит до Bitrix24 та збирає результат.

Кешування у Redis

Два рівні кеша:

Довідники (TTL 1 година): стадії лійок (crm.status.list), користувачі (user.get), типи цін, джерела лідів. Ці дані змінюються рідко й запитуються при кожному зверненні до угод.

Сутності (TTL 5 хвилин): дані конкретних угод, контактів, компаній. Інвалідуються при отриманні webhook від Bitrix24 про зміну об'єкту.

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

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

Шлюз нормалізує відповіді Bitrix24. З об'єкту з рядковими полями типу 'OPPORTUNITY' => '50000.00' отримуємо типізовану відповідь:

{
  "id": 123,
  "title": "Угода з компанією Роги та Копита",
  "amount": 50000.00,
  "stage": "negotiation",
  "contact": {
    "id": 456,
    "name": "Іван Петров",
    "phone": "+79001234567"
  }
}

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

Обробка помилок та circuit breaker

Якщо Bitrix24 недоступний або відповідає з помилкою 503 Too Many Requests, шлюз не має сліпо повертати цю помилку клієнтам. Реалізуємо circuit breaker:

• Closed (нормальна робота): запити проходять через шлюз до Bitrix24
• Open (Bitrix24 недоступний): шлюз одразу повертає кешовані дані або помилку з зрозумілим повідомленням, не створюючи чергу очікуючих запитів
• Half-Open (перевірка відновлення): періодично пробуємо тестовий запит до Bitrix24

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

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

• Latency за методами (p50, p95, p99)
• Error rate за кодом
• Розмір черги запитів
• Hit rate кеша
• Поточне обмеження Bitrix24 (із заголовка X-RateLimit-Remaining)

Етапи розробки

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