Разработка серверных приложений Битрикс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% времени. Мы гарантируем стабильное решение. Если вам нужна разработка серверного приложения, свяжитесь с нами — обсудим вашу задачу и предложим оптимальный срок. Получите консультацию, чтобы убедиться, что мы подходим под ваш проект.

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