Розробка серверних програм Бітрікс24

Розробка серверних застосунків Bitrix24

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

Чим серверний застосунок відрізняється від webhook

Вебхуки в Bitrix24 — це вхідні URL, куди Bitrix24 надсилає події. Вони зручні для простих сценаріїв, але мають обмеження: прив'язані до конкретного користувача, не підтримують OAuth, не можуть бути тиражними. Серверний застосунок (тип server) — повноцінний OAuth-клієнт, який:

• Авторизується від імені користувача, що встановив, зі збереженням токенів
• Може працювати у фоні (демон, черга завдань, cron)
• Підтримує мультипорталовість (один застосунок — багато клієнтів)
• Має власний обробник подій через event.bind

OAuth 2.0 у контексті Bitrix24

Bitrix24 використовує стандартний Authorization Code Flow:

1. Перенаправлення користувача на:
   https://company.bitrix24.ru/oauth/authorize/
     ?client_id=YOUR_CLIENT_ID
     &response_type=code
     &state=RANDOM_STRING

2. Після дозволу — перенаправлення на redirect_uri з `code`

3. Обмін коду на токени:
   POST https://oauth.bitrix.info/oauth/token/
     grant_type=authorization_code
     &client_id=YOUR_CLIENT_ID
     &client_secret=YOUR_SECRET
     &code=RECEIVED_CODE
     &redirect_uri=https://your-app.com/oauth/callback

4. Відповідь:
{
  "access_token": "...",
  "expires_in": 3600,
  "token_type": "bearer",
  "scope": "crm,task,user",
  "refresh_token": "...",
  "member_id": "portal_hash"
}

Критично: токени зберігайте в захищеному сховищі (база даних, AWS Secrets Manager, Vault). member_id — унікальний ідентифікатор порталу, використовуйте його як ключ у multi-tenant архітектурі.

Зберігання токенів та refresh-логіка

У production-системі токени зберігаються приблизно так:

CREATE TABLE bitrix_tokens (
    id          SERIAL PRIMARY KEY,
    member_id   VARCHAR(64) UNIQUE NOT NULL,
    domain      VARCHAR(255) NOT NULL,
    access_token TEXT NOT NULL,
    refresh_token TEXT NOT NULL,
    expires_at  TIMESTAMPTZ NOT NULL,
    scope       TEXT,
    created_at  TIMESTAMPTZ DEFAULT NOW(),
    updated_at  TIMESTAMPTZ DEFAULT NOW()
);

Refresh при закінченні токена:

def get_valid_token(member_id: str) -> str:
    token = db.get_token(member_id)
    if token.expires_at < datetime.now() + timedelta(minutes=5):
        response = requests.post(
            'https://oauth.bitrix.info/oauth/token/',
            data={
                'grant_type': 'refresh_token',
                'client_id': CLIENT_ID,
                'client_secret': CLIENT_SECRET,
                'refresh_token': token.refresh_token,
            }
        )
        new_token = response.json()
        db.update_token(member_id, new_token)
        return new_token['access_token']
    return token.access_token

Додавайте 5-хвилинний буфер (timedelta(minutes=5)) — інакше токен може закінчитися між перевіркою і фактичним запитом.

Підписка на події порталу

Серверний застосунок може підписуватися на події Bitrix24 через REST:

POST /rest/event.bind
{
  "event": "ONCRMDEALADD",
  "handler": "https://your-app.com/webhooks/bitrix/deal-add",
  "auth_type": 0
}

При спрацюванні події Bitrix24 надішле POST на handler з даними про подію та токеном. Підтримувані події для CRM: ONCRMDEALADD, ONCRMDEALUPDATE, ONCRMDEAIDELETED, ONCRM* — аналогічно для лідів, контактів, компаній.

Важливий нюанс: handler повинен відповідати 200 OK протягом 3 секунд. Якщо ваша обробка займає більше — негайно повертайте 200 і кладіть завдання в чергу (RabbitMQ, Redis Streams, SQS):

@app.route('/webhooks/bitrix/deal-add', methods=['POST'])
def handle_deal_add():
    data = request.json
    task_queue.enqueue(process_new_deal, data)  # Async processing
    return jsonify({'status': 'accepted'}), 200

Робота з batch-запитами

REST API Bitrix24 має ліміт 2 запити на секунду на портал (50 запитів на секунду для платних тарифів). При масових операціях використовуйте batch:

POST /rest/batch
{
  "halt": 0,
  "cmd": {
    "get_deal": "crm.deal.get?id=42",
    "get_contact": "crm.contact.get?id=17",
    "get_company": "crm.company.get?id=5"
  }
}

В одному batch-запиті — до 50 команд. При halt=1 виконання зупиняється на першій помилці.

Мультипорталова архітектура

Якщо застосунок обслуговує кілька порталів, структура повинна підтримувати ізоляцію даних:

/api/v1/{member_id}/sync   — синхронізація даних порталу
/webhooks/{member_id}/event — приймання подій від конкретного порталу

Використання member_id в URL — зручний патерн, але переконайтесь, що немає IDOR-вразливостей: перевіряйте підпис запиту або авторизацію перед обробкою.

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

Основна складність серверних застосунків — не сам REST API, а надійність: правильна обробка повторних запитів (idempotency), retry-логіка при тимчасовій недоступності порталу, моніторинг токенів, що закінчилися. Ці аспекти займають 40–60% часу розробки.