Инструменты для локальных интеграций

Локальные интеграции — это программные решения, которые создаются и настраиваются на конкретном Битрикс24. Локальную интеграцию нельзя установить на другой Битрикс24: ее права доступа, обработчики событий и виджеты настраивает сотрудник той же компании. Если интеграцию нужно устанавливать на разные Битрикс24, выбирайте тиражное приложение.

Локальную интеграцию строят на двух инструментах — вебхуках и локальных приложениях. Они различаются способом авторизации, местом выполнения кода и набором доступных возможностей. Параметры, ответы и ошибки отдельных методов описаны в Справочнике REST API.

Типовые задачи для локальных интеграцийТиповые задачи для локальных интеграций

Локальные интеграции решают задачи, которые ограничены одним Битрикс24:

• импорт данных в CRM или другие инструменты Битрикс24
• обмен данными с внутренними системами компании
• автоматизация, связанная с массовой обработкой данных клиентов
• встраивание своих элементов в интерфейс Битрикс24

Готовые последовательности методов для таких задач собраны в статье Локальные интеграции: сценарии использования.

Как начать работуКак начать работу

1. Определите задачу интеграции и выберите инструмент в таблице.
2. Проверьте права доступа: нужный scope и права сотрудника, от имени которого интеграция будет обращаться к Битрикс24.
3. Создайте интеграцию в разделе Разработчикам — Приложения > Разработчикам. Для серверного приложения заранее разместите обработчик на своем сервере и откройте его по HTTPS.
4. Проверьте первый запрос в генераторе запросов или по инструкции Как выполнить свой первый запрос к API.
5. Разберите готовый сценарий из статьи Локальные интеграции: сценарии использования и соберите свою последовательность методов.

Как выбрать инструментКак выбрать инструмент

Входящие и исходящие вебхукиВходящие и исходящие вебхуки

Вебхуки подходят для быстрых интеграций, когда не требуется сложная логика авторизации.

Входящий вебхук — это секретный код, который сотрудник получает в интерфейсе Битрикс24 и подставляет в URL запроса. Входящий вебхук может быть ограничен датой окончания. Исходящий вебхук работает в обратную сторону: при наступлении события Битрикс24 сам отправляет данные на URL вашего обработчика.

Часть методов через вебхуки недоступна, потому что их логика требует контекста приложения. Это методы встраивания приложений в интерфейс Битрикс24, события телефонии и часть событий чат-ботов. Для таких сценариев нужно локальное приложение.

Локальные приложенияЛокальные приложения

Локальные приложения позволяют:

• создавать пользовательский интерфейс
• выполнять серверную обработку
• подписываться на события
• настраивать права доступа

Приложения делятся на статичные и серверные. Статичное приложение работает в браузере на HTML и JS, серверное выполняет код на вашем сервере. Серверные приложения различаются наличием интерфейса, поэтому вариантов три:

• Статичное приложение — работает в браузере, не требует своего сервера, отображается как отдельная страница в интерфейсе Битрикс24
• Серверное приложение с интерфейсом — код выполняется на вашем сервере, отображается как страница или встраиваемый виджет внутри Битрикс24
• Серверное приложение без интерфейса — работает в фоне на вашем сервере, не отображается в интерфейсе, подходит для автоматических задач и синхронизации

Права доступа и безопасностьПрава доступа и безопасность

• Права. Интеграция работает в рамках прав того сотрудника, который ее создал, и списка scope, выбранного при создании. Метод вернет ошибку, если нужного scope нет или у сотрудника нет прав на объект.
• Доступ к REST API. Локальная интеграция работает, только если у Битрикс24 есть доступ к REST API — по подписке Маркетплейс или в пробном режиме.
• Протокол. Запросы вебхука выполняются только по HTTPS. Обработчик серверного приложения тоже должен быть доступен по HTTPS до того, как вы добавите приложение в Битрикс24.
• Секретный код. Утечка URL дает доступ к Битрикс24 в рамках прав вебхука до удаления вебхука или окончания срока действия. Не передавайте URL вебхука во внешние системы и не публикуйте его в коде клиентской части.
• Удаление. Удалить интеграцию может администратор Битрикс24 или сотрудник, который ее создал. Секретные коды чужих вебхуков недоступны даже администратору.

Раздел РазработчикамРаздел Разработчикам

Раздел Разработчикам собирает инструменты для работы с локальными интеграциями. Открыть его можно через левое меню Битрикс24 по пути Приложения > Разработчикам.

Готовые сценарииГотовые сценарии

Шаблоны для типовых задач с примерами кода и предустановленными параметрами на базе вебхуков и локальных приложений. Здесь же находится генератор запросов: он подбирает параметры метода, выполняет запрос и отдает готовый пример кода.

ИнтеграцииИнтеграции

Список всех созданных вебхуков и приложений с информацией о правах доступа, событиях и виджетах. Из списка можно перейти к настройкам интеграции или удалить ее.

СтатистикаСтатистика

График общего количества запросов и детализация по каждой интеграции. Помогает контролировать нагрузку и находить интеграцию, из-за которой REST заблокирован.

Продолжите изучениеПродолжите изучение

• Локальные интеграции: сценарии использования
• Входящие и исходящие вебхуки
• Локальные приложения
• Как выполнить свой первый запрос к API
• Рекомендации по безопасности в приложениях на REST API