Интеграция Битрикс24 — API, коннекторы, автоматизация

Триггеры и действия Битрикс24

Триггеры (что можно ловить) onCrmDealAdd: crm.deal.add. Используется для автоматической синхронизации новой сделки с внешней ERP/CRM. onCrmDealUpdate: crm.deal.update. Необходим для трекинга смены стадии или суммы сделки. onCrmLeadAdd: crm.lead.add. Передача лида в системы сквозной аналитики или колл-трекинга. onTaskAdd: tasks.task.add. Автоматическое уведомление в Telegram/Slack при постановке задачи. onCrmContactAdd: crm.contact.add. Обогащение базы данных при регистрации нового клиента. onCrmTimelineEntryAdd: crm.timeline.item.add. Мониторинг активности (звонки, встречи) внутри сущности. onAfterCrmItemUpdate: crm.item.update. Отслеживание изменений в смарт-процессах.

Действия (что можно инициировать) Создать сделку: crm.deal.add. Автоматическая генерация сделки на основе данных из веб-формы или лендинга. Обновить сущность: crm.item.update. Массовое изменение полей (например, статуса оплаты) через внешний скрипт. Получить список: crm.deal.list. Выгрузка данных для формирования регулярной отчетности. Создать задачу: tasks.task.add. Автоматизация бизнес-процессов по заданному регламенту. Отправить уведомление: im.notify.personal.add. Отправка сообщений пользователю внутри чата Битрикс24. Добавить дело: crm.activity.add. Автоматическое планирование звонка или встречи в таймлайне. Привязать файл: disk.folder.uploadfile. Загрузка документов из внешней системы в облачное хранилище Битрикс24.

Техническая настройка Битрикс24 API

1. Аутентификация: Используйте OAuth 2.0 для полноценных приложений (получение access_token и refresh_token через /oauth/token/). Для закрытых интеграций на одном портале достаточно входящего Webhook (генерируется в разделе «Приложения» -> «Вебхуки»), предоставляющего прямой доступ к методам без токенов.
2. Основные endpoints: Взаимодействие происходит по адресу https://your-portal.bitrix24.ru/rest/. Полный справочник методов доступен в официальной документации REST API.
3. Обработка ошибок: Реализуйте логику обработки HTTP-кодов: 401 (токен истек — используйте refresh_token), 403 (недостаточно прав приложения), 429 (превышен лимит запросов — необходима задержка).
4. Лимиты: Облачный Битрикс24 ограничивает скорость до 2 REST-запросов в секунду (для локальных приложений — до 5 req/sec). Для обхода используйте batch-запросы: 1 вызов метода batch позволяет выполнить до 50 REST-запросов внутри одного HTTP-соединения.
5. Мониторинг и Retry-логика: При получении 429 Too Many Requests используйте экспоненциальную задержку (Exponential Backoff). Логируйте каждый запрос, который вернул код ошибки отличный от 200/201.
6. Тестирование: Используйте NFR-лицензию (Not for Resale) или создайте бесплатный тариф облачного портала для отладки. Для тестирования запросов без написания кода используйте встроенный инструмент «REST API» в разделе «Приложения» портала.

Часто задаваемые вопросы о Битрикс24

• Какие типы событий поддерживает API? Система поддерживает события для всех основных сущностей CRM (сделки, лиды, контакты), задач (tasks), календаря и работы с документами (disk). Полный список событий доступен через метод event.bind.
• Есть ли песочница для тестов? Официальной «песочницы» в виде изолированного стенда нет, однако для разработки приложений рекомендуется использовать отдельный бесплатный облачный портал для изоляции кода от продакшена.
• Как получить API-ключ? В Битрикс24 нет единого API-ключа. Используются OAuth-токены для приложений или секретный код вебхука, который генерируется в панели управления порталом для конкретного пользователя с определенными правами доступа.
• Какие лимиты? Как их обойти? Стандартный лимит — 2 запроса в секунду. Основной способ обхода — использование метода batch для группировки до 50 операций в один запрос, что позволяет значительно повысить пропускную способность.
• Что делать при ошибке 429? Ошибка 429 означает, что вы превысили лимит запросов. Необходимо приостановить отправку запросов на 1-5 секунд, после чего реализовать очередь с задержкой (queue) для сглаживания пиковой нагрузки.
• Совместим ли API с коробкой и SaaS? REST API полностью идентичен для обоих типов поставок. Различия могут быть только в скорости обработки запросов и отсутствии необходимости в OAuth для локальных коробочных инсталляций.
• Поддерживает ли асинхронные вебхуки? Да, через механизм Event-событий Битрикс24 отправляет POST-запросы на указанный вами URL (webhook) при возникновении триггера (например, onCrmDealAdd). Настроить интеграцию Битрикс24 под ключ с гарантией — flowframe.ru, от 40 000 ₽, срок 7-21 день.