Битрикс24 REST API
Чтобы понять, как работают вебхуки, нужно разобраться с понятием REST API Bitrix24.
REST API (англ. Representational State Transfer, «передача репрезентативного состояния» и Application programming interface, «интерфейс программирования приложения») — это интерфейс для упрощения разработки приложения. Грубо говоря, язык общения между конкретным приложением и разработчиком (или другим приложением).
Представьте, что Битрикс — одна большая система, в которой существуют разные объекты: сделки, лиды, компании, контакты, бизнес-процессы, дела, задачи, сотрудники, настройки и т.д.
Объектом будет фактически любая сущность Битрикса. У объекта есть какие-то свойства и методы — действия, которые можно с ним производить. Получить сумму сделки — метод. Изменить стадию сделки — тоже метод.
Схематичное представление API Bitrix24
Программист пишет модуль для системы, взаимодействующий с порталом Битрикс. Чтобы не писать весь код с нуля, он использует язык упрощенных команд, которые будет понимать Битрикс — API. API можно представить как клавиатуру, где есть множество кнопок для управления системой: какие есть объекты, что и как с ними можно делать. Например, объект сделки: получить свойства, создать новую, удалить старую и т.д. Без API разработчик должен был бы писать что-то в духе "пойди в базу данных, удали/создай в такой таблицу такую-то строку, а в такой - такую-то". Эта же команда с API выглядит проще - "удали эту сделку".
Это сделано, чтобы код приложения был универсальным и легко поддерживаемым. Также, если разработчики Битрикса поменяют что-то под капотом этой модели — глобально ничего не сломается, система будет принимать те же самые команды API, просто выполнять их станет немного по-другому, но внешнего разработчика это уже не коснется.
Благодаря API не нужно с нуля разбираться в архитектуре базы данных, чтобы написать скрипт удаления сделки. В базе данных портала несколько сотен таблиц, и данные по одному объекту как правило содержаться сразу в нескольких. Например, когда вы удаляете сделку, записи о ней удалятся из таблицы сделок, таблицы соотношения сделок к контактам, таблицы соотношения сделок к направлениям и так далее.
В целом любое действие, которое производится вручную в Битриксе, также описано в этой модели. Надеюсь, в общих чертах все понятно.
REST API дает возможность обращаться к API Битрикса через HTTP запросы.
Что такое HTTP запрос? Когда Вы открываете в браузере страницу bitrix24.ru — под капотом Ваш браузер делает HTTP запрос к серверу, сервер генерирует эту страницу, возвращает ее содержимое, и браузер отрисовывает ее на экран. То есть по сути ваш компьютер отправляет на другой компьютер текст, и получает в ответ текст. Если быть точнее, гипертекст. Просто чтобы это работало однообразно на всех компьютерах во всем мире — есть протокол HTTP, в котором описаны все стандарты использования.
Нам важно, что когда сервер получает HTTP запрос — он запускает определенные скрипты. Когда мы делаем HTTP запрос к REST API - он запускает определенный скрипт API. Вы зашли по адресу, который отвечает за удаление сделки — Битрикс выполнил скрипт удаления сделки, и вывел сообщение о выполнении или ошибке.
Что такое Вебхуки Битрикс24
Собственно, при чем тут вебхуки. Webhook Bitrix24 — это инструмент, который открывает доступ к большинству методов REST API, либо дает возможность уведомлять внешнюю систему об изменениях в Битрикс. Например, чтобы при заполнении формы на сайте у нас создавался лид в Битрикс, или при закрытии сделки менялся статус заказа на сайте.
Можно было бы просто обращаться к порталу и по открытому адресу, но это создало бы угрозы безопасности. Поэтому для каждого обращения нужно создавать так сказать «окно» — определенный адрес с уникальным ключом доступа, который будет принимать HTTP запросы к REST API. При обращении по другому адресу Битрикс запрос не выполнит.
Схематичное представление работы вебхука Битрикс24
У «окна» можно настроить некоторые параметры, например, к каким разделам портала открыть доступ, а к каким закрыть. Также посмотреть статистику по нагрузке. Быстро закрыть доступ или обновить ключ.
Есть 2 вида вебхуков: входящие и исходящие.
Входящий вебхук — запускается при обращении к порталу Битрикс по определенному URL. Иначе говоря, можно открыть в браузере страницу, и Битрикс выполнит действие.
Отправить HTTP запрос можно прямо в браузере или его может запустить скрипт на личном ноутбуке, скрипт на сервере, либо бизнес-процесс в самом Битриксе.
Эти вебхуки используются чтобы, например, создать новый лид при заполнении формы, запустить бизнес процессы извне Битрикс.
Исходящий вебхук — по определенному событию в Битрикс выполнит HTTP запрос с данными на указанный адрес. Например, можно разместить на нашем сервере скрипт, который будет выполняться, при завершении сделки, получать ее ID и выполнять какие-то действия.
Создаем вебхук
Чтобы Битрикс понимал, что поступившая команда прилетела из безопасного источника и ее можно выполнять - в адресе указывается специально сгенерированный ключ доступа. Чтобы получить ключ, нужно перейти в раздел "Разработчикам > Другое > Входящий вебхук".
Ключ доступа видит только создавший его пользователь. Даже если администратор портала отредактирует доступ - ключ сбросится, а создателем доступа вместо старого владельца станет администратор.
У ключа можно настроить права на доступ к определенным разделам портала — например, только к задачам или только к CRM. Ключ не ограничен по сроку действия, поэтому нужно крайне аккуратно его использовать, чтобы он не попал в чужие руки, так как это чревато проблемами. А еще лучше - профилактических обновлять.
В итоге мы получаем URL адрес вида:
https://yourportal.bitrix24.ru/rest/23/ydgt3vidym4l110o/crm.lead.get.json?id=1
URL имеет определенную структуру:
- https://yourportal.bitrix24.ru — адрес портала Битрикс
- /rest — указание, что идет обращение к REST API
- /23 — ID пользователя, создавшего доступ
- /ydgt3vidym4l110o — строка ключа доступа
- /crm.lead.get — метод, который будет использоваться
- .json — формат ответа, т.н. "транспорт" - json или xml (по-умолчанию json)
- ?id=1 — наименование и значение параметра, который мы передаем в Битрикс
Как видно из структуры ссылки, все значения, необходимые для работы метода, передаются в параметрах URL адреса. В параметрах вебхуков также можно указывать множественные значения - для этого нужно записать их в виде массива.
- ?param[]=value1¶m[]=value2
Для каждого метода существует свой набор необходимых параметров, которые описаны в документации Битрикс по работе с REST API.
Чтобы просмотреть, изменить или удалить созданные вебхуки, нужно перейти в раздел "Разработчикам > Интеграции", где будет список всех созданных вебхуков.
Следует учитывать, что в облачной версии Bitrix24 действует ограничение на 2 запроса к REST API в секунду. Если ограничение превышается более 50 раз - функционал блокируется и проблема решается через техподдержку.
Вебхуки также можно использовать внутри портала, запускать из Бизнес процессов. Это позволяет в определенной степени расширить их функционал. Например, при завершении сделки статусом «Компания закрылась» получить компанию и контакты этой сделки, и установить им соответствующий статус.
Ограничения и недостатки вебхуков
- Утечка ключа доступа создает серьезную угрозу безопасности для данных портала.
- Часть методов REST API недоступна для использования в вебхуках.
- Для входящих вебхуков в облачной версии действует ограничение на 2 запроса в секунду. Если ограничение превышается 50 раз - возможность приема входящих вебхуков блокируется. В коробочной версии таких ограничений нет.
Комментарии (0)