REST API Битрикс24: как работает интеграция CRM

Система Битрикс24 может интегрироваться с внешними сервисами, имеющими отношение и значение для бизнеса. Это существенно расширяет возможности CRM и ее пользователей. Взаимодействие может осуществляться как с помощью готовых решений, так и с нуля – с помощью интерфейса программирования REST. Вместе с техническими специалистами CRM Академии попробуем разобраться, как такая интеграция работает, что дает, и для каких сценариев годится.

Зачем бизнесу REST API Битрикс24

За счет своих широчайших возможностей механизм REST API Битрикс24 будет весьма полезен для бизнеса. Интерфейс позволяет создавать задачи и запускать бизнес-процессы, а также создавать сделки и обновлять каталоги товаров. В распоряжении руководителя и программиста имеются сотни методов, покрывающие все основные модули портала.

Когда стоит использовать API вместо готовых решений

Сложные интеграции на основе REST API вместо готовых решений следует использовать бизнесу, например, когда нужно сложное взаимодействие с самостоятельно написанным сайтом. Встроенных в Битрикс24 средств интеграции в этом случае окажется недостаточно.

Как устроено взаимодействие с REST API

Чтобы лучше понять, как устроено взаимодействие с REST API, следует вкратце рассказать, что собой представляет данное понятие. Это – интерфейс прикладного программирования, который определяет порядок «общения» веб-приложений.

Для выполнения взаимодействия по заданному сценарию и набору данных используются приложения, которые пишутся на PHP и Javascript. А для авторизации могут использоваться входящие вебхуки (точки входа для API-вызовов) и исходящие вебхуки (event handlers – подписки на события портала типа задача изменена, сделка создана и т.д.) или сервер OAuth 2.0 (открытый протокол, не требующий передачи логина/пароля пользователя).

Обмен данными происходит следующим образом:

1. Вначале происходит соединение с расположенным в каталоге /rest специальным разделом портала Битрикс24 API.

2. C помощью запросов GET (чтение данных) и POST (создание или изменение) нужные данные в формате JSON передаются на портал.

3. В свою очередь, система в ответ возвращает выходные данные в том же формате или же код ошибки.

Какие задачи решает REST API в Битрикс24

Благодаря разнообразию программных методов и запросов REST API может решать самые разнообразные задачи. Рассмотрим самые ходовые и полезные.

Работа с CRM-данными

Самый банальный пример взаимодействия через REST API – это работа с CRM-данными. В качестве одного из способов реализации можно привести веб-форму на сайте интернет-магазина. Когда пользователь выберет товар или услугу и оставит данные для обратной связи, по щелчку на кнопке «Отправить» запустится веб-приложение, которое тут же передаст все данные в нужные поля Битрикс24 и автоматически создаст сделку. Это даст контроль над ее выполнением.

Автоматизация процессов и сценариев

Еще одна задача, решаемая с помощью REST API Битрикс, – это автоматизация процессов. Благодаря прямому взаимодействию можно сделать так, чтобы каталог товаров в 1С обновлялся автоматически по мере реализации или поступления.

Интеграция с внешними сервисами

Важным преимуществом REST API является возможность интеграции с разнообразными сервисами для глубокого взаимодействия. Когда в какой-нибудь службе возникает существенное событие, например, добавление задачи в планировщике или смена стадии на сторонней канбан-доске, то происходит отправка запроса или инициируется вебхук в Битрикс24.

Основные сценарии интеграции

Применение REST API для интеграции Битрикс24 с внешними сервисами улучшает управляемость и производительность, сокращает ошибки, а также дает возможность построить идеальный программный комплекс для бизнеса согласно потребностям компании. 

Связка с сайтами и интернет-магазинами

Интерфейс REST позволяет связывать Битрикс24 с любыми сайтами и интернет-магазинами, независимо от конструктора и платформы. Такой подход позволит не ограничиваться одним сбором клиентских заявок. Благодаря REST API также можно оперативно обновлять список товаров, распределяя их по категориям.

Интеграция с телефонией и чатами

Еще один сценарий интеграции – это подключение телефонии и чатов. Благодаря этому можно, например, подключать к Битрикс24 не только «Телеграм» и «МАКС», но также и менее банальные альтернативные средства связи (такие, как IMO и Bip). Широта возможностей REST API Битрикс24 позволит в ответ на сообщение создать вебхук, по которому будет направлена задача для менеджера, а сотрудники получат оповещение.

Обмен данными с учетными системами

Также REST API дает возможность обмена данными с отечественными и зарубежными учетными системами (1С, Microsoft Dynamics, SAP и другими). Это дает такие возможности, как:

• двухсторонняя синхронизация контрагентов;

• выгрузка заказов или сделок;

• связь конкретных этапов бизнес-процесса в учетной системе с задачами по отгрузке.

Разумеется, перечень возможных интеграций не ограничивается описанными вариантами.

Как подключить REST API Битрикс24

Когда рассмотрены все возможности REST API в Битрикс24, можно рассказать о способах подключения, а также напомнить об ограничениях. Стоит учесть, что для выполнения всех описываемых действий нужна подписка на Битрикс24 Маркетплейс и статус администратора.

Выбор способа подключения

Зависит от требований к безопасности и масштабируемости:

1. Вебхук. Самый простой способ подключиться к порталу в Битрикс24, чтобы загрузить туда или получить оттуда данные. Идеален для автоматизированной обработки.

2. OAuth. Более сложный, но гораздо более безопасный способ авторизации для подключения сторонней службы. Поэтому подходит для масштабных обменов данными, а также для задач, требующих создания пользовательского интерфейса.

Настройка доступа

При использовании коробочной версии Битрикс24 важно разрешить веб-запросы к нескольким важным страницам и типам данных:

1. К своему серверу, а также на oauth.bitrix24.com – исходящие HTTPS-запросы.

2. Для MIME-типа application/x-www-form-urlencoded, а также для серверов, адреса которых начинаются на mp-actions- – входящие запросы как по HTTP, так и по HTTPS.

Также надо разрешить запросы от серверов выбранного приложения и открыть доступ к порталу 1c-bitrix.ru с поддоменами третьего уровня. Без этого не получится создавать вебхуки и интеграции.

Первый запрос к API

Для начала работы с REST API в Битрикс24 нужно запустить работу с данным, создав входящий вебхук (webhook). Вот, как это сделать:

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

2. Выбрать пункты «Другое → Входящий вебхук».

3. Если необходимо, активировать пробный период или же оплатить подписку на Битрикс24.Маркетплейс.

4. Если все прошло успешно, появится слайдер с генератором запросов, где следует указать метод, добавить параметры с конкретными значениями.

В результате будет сгенерирована ссылка, содержащая вебхук. При переходе по ней будет передан запрос к API Битрикс24, в результате выполнения в том же окне-слайдере придет ответ. В верхней части будет приведен результат в одну или пару строк, а под ним – то же самое, только в более удобном для восприятия формате JSON.

Ограничения REST API Битрикс24

Чтобы обеспечить оптимальную производительность и защищенность системы Битрикс24, REST API накладывает определенные ограничения. Рассмотрим, в каких областях программного интерфейса имеются лимиты.

Лимиты запросов

Ограничения запросов к REST API в Битрикс24 установлены по так называемому принципу «протекающего ведра». Как это действует:

1. В систему поступает некоторое количество запросов из внешнего источника, что увеличивает значение соответствующего счетчика.

2. Как только он достигает 250 запросов на тарифе «Энтерпрайз» (или 50 – на остальных), все входящие запросы блокируются.

3. В то же время, значение счетчика запросов уменьшается на 5 и 2 запроса в секунду соответственно. Это дает возможность подготовиться к отправке следующего потока.

Такая политика ограничений позволяет без проблем отсылать запросы время от времени в небольших объемах, в то же время, допускаются кратковременные всплески запросов (например, когда в прикрепленную телефонию поступает сразу несколько звонков). Главное, чтобы такие выбросы в API не происходили постоянно.

Ограничения логики и структуры данных

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

Что касается списков сделок, комментариев, задач и т.п., то Битрикс24 разбивает их на пакеты по 50 элементов. Такой лимит тоже положительно сказывается на производительности всей системы.

Особенности работы с правами доступа

В REST API права на выполнение методов регулируются при помощи скоупов (scope). Так называются идентификаторы функций Битрикс24, с помощью которых можно обращаться к конкретному средству.

Например, скоуп для телефонии включает в себя несколько методов, один из которых call для совершения звонков и пару методов от VoxImplant для аналогичного действия с проигрыванием голосового обращения. Разумеется, есть также и другие скоупы, дающие право доступа к чатам, бизнес-процессам, календарю и так далее.

Типичные ошибки при работе с API

Одна из типичных ошибок при работе с REST API – это выполнение слишком большого числа запросов из нескольких источников. В результате действия уже описанных ограничений будет выдаваться код 503, означающий превышение лимитов. О снижении нагрузки на систему мы поговорим чуть ниже.

Рекомендации по работе с REST API

Официальная документация по Битрикс24 REST API хранится в открытом репозитории на GitHub, а коды ошибок можно посмотреть на официальном сайте вендора. Здесь же мы рассмотрим основные моменты для лучшей производительности.

Как снизить нагрузку на систему

Чтобы снизить нагрузку во время работы с огромным количеством сущностей (например, импорт с портала), нужно отключать подсчет числа элементов, вставив в код POST-запроса директиву start = -1.

Как обеспечить стабильность интеграции

Чтобы передать большое количество запросов в Битрикс24 по API и в то же время не выйти за ограничения, рекомендуется использовать пакетный метод – batch. Он также хорош тем, что не позволяет внутри себя вызвать еще один такой же метод. Это и частичное кэширование в разы повышает стабильность интеграции.

Когда REST API — лучшее решение, а когда нет

Выбор между REST API и иными коннекторами зависит, прежде всего, от масштабности интеграции и требований. Первый способ подойдет для масштабных подключений к внешним системам с целью существенного расширения возможностей Битрикс24 как в облаке, так и в коробке. Но нужно учитывать, что такой подход требует больших затрат времени и ресурсов, также требуется знание и понимание cURL, PHP, JavaScript и JSON.

Именно поэтому REST API – это не лучшее решение для разовых и простых интеграций без излишеств. В таком случае проще будет использовать готовые решения для поддерживаемых сервисов. Например, для 1С в разных конфигурациях предлагается коннектор и модуль обслуживания для обеих сторон. Аналоги, не требующие навыков программирования, есть для подключения Битрикс24 к другим полезным сервисам.