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

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

Менеджер з продажів відкриває картку угоди в Бітрікс24 і бачить лише ту інформацію, яку вніс вручну. А в обліковій системі у цього клієнта — 3 роки історії покупок, кредитний ліміт, відкриті рекламації. Перемикатися між двома вкладками стомлює, дані розходяться. REST-додаток вбудовує потрібну інформацію безпосередньо в інтерфейс Бітрікс24 без необхідності відкривати сторонню систему.

Що таке REST-додаток в екосистемі Бітрікс24

REST-додаток — це зовнішній веб-сервіс, який взаємодіє з Бітрікс24 через OAuth 2.0 та REST API (https://domain.bitrix24.ru/rest/). Додаток може:

• вбудовувати віджети в інтерфейс Бітрікс24 (через placement)
• читати та записувати дані CRM, завдання, дзвінки через REST-методи
• підписуватися на події (вебхуки) та реагувати на зміни
• додавати власні кнопки в картки угод, контактів, компаній

Додатки поділяються на тиражні (публікуються в Маркетплейс Бітрікс24) та вбудовані (розробляються для конкретного порталу). Більшість корпоративних завдань — вбудовані.

OAuth та авторизація

Перший крок — налаштування OAuth 2.0. Додаток отримує client_id та client_secret при реєстрації на порталі. Користувач авторизує додаток, він отримує access_token (TTL 1 година) та refresh_token (TTL 30 днів).

class Bitrix24OAuth {
    public function refreshToken(string $refreshToken): array {
        $response = Http::post('https://domain.bitrix24.ru/oauth/token/', [
            'grant_type'    => 'refresh_token',
            'client_id'     => config('b24.client_id'),
            'client_secret' => config('b24.client_secret'),
            'refresh_token' => $refreshToken,
        ]);
        // Зберегти нові токени у сховище
        TokenStorage::save($response['access_token'], $response['refresh_token']);
        return $response;
    }
}

Токени зберігаються у зашифрованому вигляді (AES-256). При кожному API-виклику перевіряється TTL токена та за потреби виконується рефреш до відправлення запиту.

Детально: віджет у картці угоди

Найпоширеніший сценарій — вбудувати зовнішні дані в картку CRM. Реєстрація placement:

// Виклик через REST API при встановленні додатку
$client->call('placement.bind', [
    'PLACEMENT' => 'CRM_DEAL_DETAIL_TAB',
    'HANDLER'   => 'https://myapp.example.com/widget/deal/',
    'TITLE'     => 'Історія клієнта',
    'OPTIONS'   => ['extraData' => 'ENTITY_ID'],
]);

Коли менеджер відкриває угоду, Бітрікс24 завантажує iframe з URL вашого додатку, передаючи ENTITY_ID (ID угоди). Додаток:

1. Отримує ENTITY_ID з placement.info()
2. Робить REST-запит crm.deal.get для отримання даних угоди (ID контакту/компанії)
3. За ID контакту звертається до внутрішньої облікової системи
4. Відображає історію покупок, кредитний ліміт, відкриті завдання

Весь цикл займає 1–2 секунди при правильному кешуванні даних з облікової системи.

Взаємодія з REST API Бітрікс24

REST API Бітрікс24 містить понад 700 методів. Найбільш вживані в корпоративних додатках:

• crm.deal.*, crm.contact.*, crm.company.* — робота з CRM
• tasks.task.* — завдання
• im.message.add — надсилання повідомлень у чат
• bizproc.workflow.start — запуск бізнес-процесів
• user.get — дані користувачів

Batch-запити. При необхідності отримати дані з кількох методів одночасно використовується batch:

$result = $client->call('batch', [
    'halt'  => 0,
    'cmd'   => [
        'deal'    => 'crm.deal.get?id=123',
        'contact' => 'crm.contact.get?id=$result[deal][CONTACT_ID]',
    ]
]);

Це скорочує кількість HTTP-запитів та пришвидшує завантаження віджета.

Ліміти та квоти

Бітрікс24 обмежує API: 2 запити на секунду для одного додатку, не більше 50 запитів у batch. При перевищенні — помилка QUERY_LIMIT_EXCEEDED. Модуль реалізує чергу запитів з обмеженням швидкості (rate limiter на основі Redis або таблиці БД) та автоматичним повтором при отриманні помилки ліміту.

Терміни розробки

Перед розробкою потрібно визначити, чи буде додаток тиражним (публікація в Маркетплейс) або вбудованим — це впливає на архітектуру OAuth-потоку та вимоги до мультиорендності.