Представьте: вы разработали приложение для Битрикс24, прошли модерацию, опубликовали в маркетплейсе. Через неделю приходят жалобы — у половины клиентов не работает синхронизация, приложение выдаёт 403 на crm.deal.list. Оказывается, тариф «Базовый» не даёт прав на CRM, а вы не предусмотрели проверку. Или webhook перестал отвечать — обработчик отвязался, данные потеряны. Такие ситуации — следствие типовых ошибок, которых можно избежать на этапе архитектуры. Проблема в том, что типовые шаблоны и unchecked errors — главная причина отказов при модерации и потери клиентов. Мы за 5 лет реализовали более 50 приложений для маркетплейса Битрикс24 — от простых виджетов до multi-tenant решений. И знаем, как сделать стабильный продукт, который не подведёт клиентов. Мы специализируемся на проектировании устойчивых приложений, которые проходят модерацию с первого раза. Наш опыт позволяет избежать ловушек, связанных с тарифными ограничениями и обработкой ошибок. Стоимость разработки индивидуальна, но инвестиции окупаются за счёт экономии на поддержке и повторных доработках. Закажите консультацию — мы покажем, как снизить затраты на 20% за счёт продуманной архитектуры.
Какие типы приложений существуют?
Встраиваемые приложения (embed) работают в iframe через placement API. Точки: CRM_LEAD_DETAIL_TAB, TASKS_TASK_VIEW_TAB, CALL_LIST и десятки других. Виджеты встраиваются через BX24.placement.call() для небольших действий: кнопка в карточке, панель в чате. Приложения с собственным интерфейсом открываются в отдельной вкладке, больше свободы UX, но пользователь выходит из контекста. Боты и чат-приложения используют imbot.* и imsetting.* методы, имеют собственный обработчик.
Сравнение типов:
| Тип | Точки интеграции | Сложность | Когда выбирать |
|---|---|---|---|
| Встраиваемое (embed) | Placement API | Средняя | Нужна работа в контексте CRM, задач |
| Виджет | BX24.placement.call() | Низкая | Маленькое действие в интерфейсе |
| Приложение с UI | Отдельная вкладка | Высокая | Требуется сложный интерфейс |
| Бот/мессенджер | imbot., imsetting. | Средняя | Автоматизация чатов |
Как работает OAuth 2.0 в приложениях?
Авторизация строится на OAuth 2.0 с кодом авторизации. Флоу:
- Пользователь устанавливает приложение → редирект на redirect_uri с code.
- Приложение обменивает code на access_token и refresh_token через https://oauth.bitrix.info/oauth/token/.
- Access_token живёт 1 час, refresh_token — 180 дней.
- Токены хранятся в вашей БД, привязанные к member_id.
Для server-to-server используйте grant_type=client_credentials — доступно для приложений типа «Приложение». member_id критичен: все данные в БД партиционируются по нему, иначе данные одной компании попадут к другой.
REST API: работа с данными
Битрикс24 REST API — не классический REST. Методы вызываются POST на https://{portal}.bitrix24.ru/rest/{method} с form-data или JSON. Пагинация через start, лимит 50 записей. Для получения всех — цикл с next.
Популярные группы:
- crm.lead., crm.deal., crm.contact., crm.company. — CRM
- tasks.task.*, task.item.list — задачи
- disk.folder., disk.file. — файлы
- im.message.add, imbot.message.add — сообщения
- user.get, user.search — пользователи
- placement.bind — регистрация точек встраивания
Батчинг: отправляйте до 50 запросов через batch. Батчинг в 50 раз быстрее последовательных запросов.
POST /rest/batch
{
"halt": 0,
"cmd": {
"get_deal": "crm.deal.get?id=123",
"get_contact": "crm.contact.get?id=456",
"get_company": "crm.company.get?id=789"
}
}
Как обрабатывать webhook'и без потери данных?
Подпишитесь на события через event.bind. При наступлении события Битрикс24 делает POST на handler URL. Важные детали:
- Handler должен отвечать за
5 секунд. - После 3 неуспешных доставок — обработчик отвязывается.
- Для тяжёлой обработки используйте очередь: примите webhook, положите в очередь, ответьте 200, обработайте асинхронно.
Доступные события: ONCRMLEADADD, ONCRMDEALUPDATE, ONTASKUPDATE, ONIMMESSAGECHAT, ONUSERADD и сотни других.
Размещение (placements)
Регистрация placement производится при установке через placement.bind. Привязывается к точке интерфейса и передаёт контекст: ID сущности, тип, права пользователя.
BX24.placement.getInterface(function(data) {
console.log(data);
});
Подключите //api.bitrix24.com/api/v1/ и вызовите BX24.init() перед обращением к API. В iframe используйте localStorage или postMessage.
Как обойти тарифные ограничения?
REST-методы доступны не на всех тарифах. crm.* — с определённых планов, telephony.* — с телефонией, tasks.* — с модулем «Задачи». При установке проверяйте доступность через app.info и profile. Явно сообщайте пользователю, если функциональность недоступна. Не допускайте необработанных 403.
Хранение данных приложения
Битрикс24 предоставляет key-value хранилище app.option.set/get (лимит ~32KB). Для серьёзных данных нужна собственная БД. Для пользовательских настроек — user.option.set/get на стороне портала.
Сроки разработки
| Тип приложения | Срок |
|---|---|
| Простой виджет / embed с чтением данных CRM | 2–4 недели |
| Полноценное CRM-приложение с двусторонней синхронизацией | 6–10 недель |
| Мессенджер-бот с NLP и контекстом диалогов | 8–12 недель |
| Комплексное приложение с собственным UI, webhooks, multi-tenant БД | 12–20 недель |
Что входит в работу
- Анализ требований и проектирование архитектуры
- Настройка CI/CD и развёртывание на вашем сервере
- Документация REST API и описание интеграции
- Обучение администраторов портала
- Месячная поддержка после релиза
Пример интеграции OAuth
Официальная документация: https://dev.1c-bitrix.ru/rest_help/oauth/Инфраструктура приложения
Приложение должно быть доступно по HTTPS с валидным сертификатом. Для production: отдельный домен, горизонтальное масштабирование (токены в Redis/БД), мониторинг webhook-обработчиков. Логируйте все вызовы REST API, входящие webhook'и и OAuth-обмены. Правильная архитектура экономит до 40% времени на поддержку.
Подробнее о OAuth: Wikipedia.
Свяжитесь с нами для консультации по вашему проекту. Получите предварительную оценку сроков и стоимости.