Разработка серверных приложений Битрикс24 под ключ

Разработка серверных приложений Битрикс24

Представьте: интернет-магазин на Magento, 5000+ заказов в день. Каждый нужно превратить в сделку Битрикс24, назначить ответственного, отправить уведомление в Telegram. Без серверного приложения — ручная работа или вебхуки с ограничениями: привязаны к сессии, не масштабируются. Серверное приложение решает это полностью автоматически: работает в фоне, использует OAuth 2.0, подписывается на события. Мы реализовали 50+ таких интеграций для ритейла, логистики и финтеха. За более чем 5 лет выработали архитектуру, выдерживающую миллионы запросов в сутки. Но есть нюансы: токены могут истечь, события могут приходить валом, а батч-запросы требуют грамотной паузы. Разберём ключевые моменты, которые превращают простую интеграцию в отказоустойчивый production.

Чем серверное приложение отличается от webhook?

Вебхуки в Битрикс24 — входящие URL, куда Битрикс24 шлёт события. Они удобны для простых сценариев, но имеют ограничения: привязаны к конкретному пользователю, не поддерживают OAuth, не могут быть тиражными. Серверное приложение (тип server) — полноценный OAuth-клиент:

• Авторизуется от имени установившего пользователя с сохранением токенов.
• Работает в фоне (демон, очередь задач, cron).
• Поддерживает многопортальность (одно приложение — много клиентов).
• Имеет собственный обработчик событий через event.bind.

Серверное приложение в 10 раз надёжнее вебхуков при высокой нагрузке и не зависит от сессии. Для сложных сценариев — единственный рабочий вариант.

Как работает OAuth в серверном приложении?

Битрикс24 использует Authorization Code Flow. Приложение перенаправляет пользователя на страницу авторизации с client_id, response_type=code, state. После подтверждения код обменивается на токены через POST к oauth.bitrix.info. Токены содержат access_token, refresh_token, expires_at и member_id. Согласно документации Битрикс24, refresh_token живёт 1 месяц, после чего требуется повторная авторизация. Важно хранить токены в защищённом хранилище (база данных, AWS Secrets Manager, Vault). member_id — уникальный идентификатор портала, служит ключом в multi-tenant архитектуре.

Member_id: идентификация портала

member_id — хеш, однозначно идентифицирующий портал. Возвращается вместе с токенами и не меняется. В многопортальном приложении служит ключом для хранения токенов и конфигурации каждого клиента.

Как обеспечить надёжное хранение токенов?

В 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-минутный буфер — иначе токен может истечь между проверкой и запросом. Альтернативно используйте Vault.

vault kv put secret/bitrix/member_abc123 \
    access_token=xxx \
    refresh_token=yyy \
    expires_at=2025-01-01T00:00:00Z

Подписка на события портала

Подписка через REST: POST /rest/event.bind с параметрами event, handler, auth_type. При срабатывании Битрикс24 шлёт POST на handler. Поддерживаются все события CRM: добавление, обновление, удаление сделок, лидов, контактов.

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)
    return jsonify({'status': 'accepted'}), 200

Работа с батч-запросами

REST API лимит: 2 запроса в секунду (50 для платных). При массовых операциях используйте батч:

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"
  }
}

В одном батче до 50 команд. halt=1 останавливает при ошибке.

Как настроить OAuth за 4 шага

1. Зарегистрируйте приложение в Битрикс24 (тип server).
2. Укажите redirect_uri — эндпоинт, принимающий код авторизации.
3. Реализуйте обмен кода на токены через POST к oauth.bitrix.info.
4. Сохраните токены вместе с member_id в защищённом хранилище.

Каждый шаг требует тестирования: сбои на этапе авторизации — частая ошибка.

Многопортальная архитектура

Если приложение обслуживает несколько порталов, структура должна изолировать данные:

• /api/v1/{member_id}/sync — синхронизация.
• /webhooks/{member_id}/event — приём событий.

Использование member_id в URL удобно, но проверяйте подпись запроса — избегайте IDOR.

Какие этапы включает разработка серверного приложения?

• Анализ требований и проектирование.
• Реализация на PHP/Python с REST API.
• Интеграция с внешними системами (1С, CRM, платежные шлюзы).
• Деплой (Docker, CI/CD).
• Документация и обучение.
• Поддержка месяц после запуска.

Сроки разработки

Основная сложность — не REST API, а надёжность: идемпотентность, retry-логика, мониторинг токенов. На это уходит 40–60% времени. Мы гарантируем стабильное решение. Если вам нужна разработка серверного приложения, свяжитесь с нами — обсудим вашу задачу и предложим оптимальный срок. Получите консультацию, чтобы убедиться, что мы подходим под ваш проект.

Почему стоит выбрать серверное приложение? Потому что это единственный способ сделать интеграцию, которая не требует ручного вмешательства и выдерживает нагрузку. Доверьте автоматизацию экспертам.