Как получить код приложения битрикс24

Обновлено: 22.01.2025

Aimylogic предоставляет возможность интеграции с Битрикс24. Боты могут самостоятельно:

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

Вы можете посмотреть видеоинструкцию по использованию Битрикс24.

Особенности Битрикс24

Индивидуальные и групповые чаты — это часть экосистемы Битрикс24 и один из основных каналов коммуникации с клиентами. Чаты полностью интегрированы с другими бизнес-инструментами.

Если вы подключаете канал Битрикс24, то любые другие интеграции необходимо создавать на стороне Битрикс24, а не в Aimylogic.

Роботы

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

Вы можете использовать чат-ботов Aimylogic с роботами Битрикс24 на любом этапе и статусе сделки.

Если вы не подключили робота к лиду или сделке, то автоматически будет активирован основной сценарий, который вы указали в настройках Открытых линий.

Открытые линии

В Открытых линиях доступны разные каналы — например, Яндекс.Чат, Viber, Telegram, ВКонтакте, Facebook.

Ограничения канала

При работе с Битрикс24 есть несколько ограничений:

Битрикс24 не поддерживает кнопки.
- Если в сценарии, который вы опубликовали в Битрикс24, есть кнопки, клиенты их не увидят.
- Если вы хотите обрабатывать реакции клиентов, используйте в сценарии интенты.
Подключение бота к Битрикс24

Для подключения чат-бота Aimylogic к Битрикс24:

Создайте сценарий

Создайте сценарий с учетом ограничений канала Битрикс24.

Старт диалога
1. В любом месте сценария нажмите Добавить экран > Сделать свой интент.
2. В качестве шаблона фразы добавьте $TEXT .
3. Включите опцию Сделать доступным из любой точки сценария.
4. Соедините интент $TEXT с экраном приветствия в сценарии.
Опция Любая другая фраза не должна быть связана с другими блоками.

Обработка непредсказуемых фраз клиента

От опции Любая другая фраза создайте экран и поместите на него реплику бота на случай, если клиент напишет что-то непредсказуемое.

На этот раз не нужно делать интент доступным из любой точки сценария. В противном случае глобальный интент $TEXT , настроенный для старта диалога, не будет отлавливать реплики из других экранов и не будет переводить диалог на экран приветствия.

Системные переменные

При работе с Открытыми линиями Битрикс24 вы можете использовать системные переменные.

Перевод на оператора

Вы можете использовать Битрикс24 как операторский канал.

Для начала подключите Битрикс24, а потом добавьте в ваш сценарий блок Перевод на оператора. В качестве операторского канала будет автоматически указан Битрикс24.

Вы также можете переводить диалог на конкретного оператора.

Если у вас еще нет аккаунта нужного сотрудника в Битрикс24, создайте его:

Чтобы получить идентификатор сотрудника, найдите его на странице Сотрудники и перейдите в его профиль. В адресной строке браузера вы увидите ссылку вида:

Последнее число в ссылке является идентификатором вашего сотрудника — в данном случае это 12 . Укажите этот идентификатор в поле Идентификатор сотрудника (user_id) при настройке блока Перевод на оператора в Aimylogic.

Если ваш чат-бот подключен к Битрикс24, то после перевода на оператора клиент не сможет вернуться на то же место в диалоге с ботом. Битрикс24 не предусматривает такой возможности. В Webim (Custom Channel API) и LiveTex такая опция доступна.

Закрытие чата

Чтобы обработать завершение диалога с клиентом, добавьте в сценарий блок Завершение сценария.

Как только бот дойдет до этой части сценария, текущий чат будет закрыт в Битрикс24.

Добавьте приложение Aimylogic в Битрикс24
1. Перейдите в личный кабинет Битрикс24.
2. В боковом меню выберите Еще > Маркет.
3. В списке приложений найдите и установите приложение Aimylogic. В процессе установки вам нужно будет авторизоваться в вашем аккаунте Aimylogic.
После того как приложение будет установлено, в списке ваших чат-ботов Aimylogic появится шаблонный чат-бот Сбор информации о доставке. Шаблон будет сразу доступен в чатах и для Открытых линий Битрикс24.

Опубликуйте сценарий в канал Битрикс24

После успешной публикации чат-бот будет доступен в вашем аккаунте Битрикс24.

Общий порядок работы с OAuth при создании приложений для Битрикс24

C 25 мая 2015г. для того чтобы добавлять свои приложения на портал больше не требуется становиться технологическим партнером.

Если у вас права администратора на вашем портале, зайдите в раздел Приложения — Добавить приложение. Выбрать для личного пользования (в этом случае, никто кроме вас и вашего портала не сможет использовать это приложение)

Откроется форма добавления приложения

В форме заполняем:
1. Название приложения — произвольное.
2. Приложение использует только API – обязательно
3. Права доступа — указываем к каким разделам будет доступ у данного приложения
4. Укажите ссылку — указываем произвольный ваш сайт (или любую произвольную страницу).
После этого нажимаем «Сохранить»

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

OAuth-авторизация для desktop-приложения
1. При помощи client_id получаем параметр code, требуемый для получения авторизационного токена.
2. При помощи clent_id, client_secret и code приложение получает параметры access_code и refresh_token.
3. При помощи access_code приложение совершает запросы к REST-сервису до его истечения.
4. Через час access_code истекает, и приложение может использовать полученный refresh_token для получения нового.
5. Если refresh_token еще не истек (с момента его получения не прошел месяц), то приложение получает свежий access_code и свежий refresh_token, после чего, можно перейти к шагу 3.
6. Если refresh_token уже истек, то требуется повторная авторизация с участием пользователя.
По сути, физическая авторизация пользователя требуется только на шаге 1. В итоге получаем, что если приложение используется постоянно (шаг 4 используется чаще раза в месяц), то приложение имеет возможность продлевать авторизацию не трогая пользователя сколь угодно долго.Рассмотрим данный алгоритм более подробно.

Desktop приложение должно слушать какой-либо порт на localhost (Oktell как правило слушает порт 4055).

1)Для авторизации необходимо открыть браузер и перейти на адрес вида:

2)Далее произойдет редирект на адрес вида:

После получения этих данных браузер больше не нужен. Данные которые были получены в результате создания приложения и полученный code необходимо внести в таблицу oktell.dbo.bitrix_oauth в соответствующие поля. Скрипт для создания таблицы приведен в конце статьи

В ответ сервер вернет json-структуру со всеми необходимыми для совершения запросов к серверу данными.
- access_token – ключ для отправки запросов к REST-сервису
- expires_in – период действия данного at (access_token)
- scope – объекты к которым предоставлен доступ
- user_id – id пользователя от имени которого произошла авторизация
- refresh_token - маркер обновления, для получения нового access_token
- domain – домен к которому был получен доступ
- member_id - уникальный идентификатор портала
Все, приложение может совершать запросы к REST-сервису.

В результате выполнения данного запроса будет возвращена json-структура вида:

access_token, который хранится в БД обновляется каждый час, для того чтобы была возможность непрерывно выполнять любые запросы к Bitrix24.

Пример сценария, который отправляет запрос на получение access_token, после получения code и обновляет access_token по существующему refresh_token:

Пример использования REST API

Рассмотрим пример получения списка всех лидов. Для этого нам понадобятся 2 метода:
- crm.lead.list - Возвращает список лидов по фильтру, при этом фильтры использоваться не будут это означает, что будет получаться весь список лидов (в дальнейшем имеет смысл рассмотреть применение фильтра и получать только тех, кто был изменен после последней синхронизации).
- crm.lead.get - Возвращает лид по идентификатору, с помощью данного метода мы получим контактные данные по лиду – телефон, e-mail, web-сайт.
Сценарий «bitrix_crm_lead_list»

0)Выводим уведомление о Запуске сценария и Получаем текущую дату и время для того чтобы отобразить время выполнения сценария. Дату и время получаем из функции «Текущие дата и время».
1)В данном сценарии как и в любом другом удобно использовать существующий, автоматически обновляемый access_token, который мы получили в предыдущей главе. Получаем данные из таблицы oktell.dbo.bitrix_oauth для выполнения REST запроса. Текст выполняемого запроса -

2)Устанавливаем счетчик для получения списка лидов = 0 и счетчик последней итерации = 0 и счетчик итераций получения лидов=0

4)Получаем сколько всего лидов. Используется компонент Парсер с алгоритмом «Парсер JSON». В примере: поисковый запрос - total

Важно! Все компоненты парсер в данном сценарии используют алгоритм «Парсер JSON».

5)Записываем в счетчик получения лидов начальный номер для следующей итерации. В примере: поисковый запрос - next

5.1)Если парсер JSON выполнился с ошибкой, это означает что счетчик для следующей итерации отсутствует, что свидетельствует о последней итерации, тогда дополнительно определяем счетчик последней итерации и устанавливаем для последней итерации счетчик получения лидов = сколько всего лидов (total)

6)Устанавливаем счетчик для получения N-го лида парсером (как правило счетчик будет бегать от 0 до 49).

7)Получаем N-ый лид для дальнейшего парсинга (Парсер JSON). В примере: поисковый запрос- выражение - '"result"/'+[counter_lead_parse]

7.1)Далее идет серия JSON парсеров по тегам которые необходимы для сохранения (количество тегов можно менять в зависимости от условий, главное всегда получать как минимум тег “ID”, который соответствует № лида).
Важно! У компонентов парсер всегда должны быть назначены переходы по ветке «Ошибка», т.к. в случае если данных в этом поле не будет парсер отработает именно по этому переходу и если он не указан, то сценарий завершится.

8)Обновляем лид в таблице - [oktell].[dbo].[bitrix_leads] если он там есть и добавляем если нет, определение происходит по sql_ID (по № лида). Текст выполняемого запроса -

8.1)Если sql запрос по добавлению\обновлению лида выполнился с ошибкой, то Записываем информацию об ошибке в таблицу [oktell].[dbo].[bitrix_import_lead_error]

Текст выполняемого запроса -

9) Увеличиваем счетчик для получения N-го лида на 1 (+1)

10) После этого происходит проверка Счетчик получения N-го лида меньше чем Счетчик количества полученных лидов в веб-запросе? Текст выражения - [Счетчик итераций получения списка лидов]*50+num([counter_lead_parse]) В выражении используем коэффициент в виде счетчика итераций получения списка лидов, для того чтобы корректно проходить по всем лидам которые получили в результате web-запроса. Например при первой итерации пройдем по 0*50+[0..49] лидам, при второй по 1*50+[0..49], т.е. с 50 по 99 лид и т.д.

10.1)Если да, то переходим на шаг 7) 10.2)Если нет, то переходим на шаг 11)
11) Увеличиваем Счетчик итерации получения списка лидов +1

12)Проверяем Счетчик последней итерации=1?

12.1)Если да, то переходим на шаг 13) 12.2)Если нет, то переходим на шаг 3)
13)Отображаем уведомление о Завершении сценария со временем выполнения. Текст уведомления — выражение -

14) Обновляем данные по завершению сценария в таблице oktell.dbo.bitrix_lead_runtime Текст выполняемого запроса -

15) Производим Запуск сценария bitrix_crm_lead_get_by_id, в котором мы обновим контакты лидов, при первом запуске будут получены все контакты, при дальнейших запусках только контакты у лидов которые были обновлены после выполнения данного сценария.

Сценарий «bitrix_crm_lead_get_by_id»

В данном сценарии будет последовательно обрабатываться каждый № лида, т.к. это могло бы занять достаточно много времени, проверять будем только те лиды, которые были изменены после предыдущего запуска данного сценария (если он запускается в первый раз, то получим данные по всем лидам). Дату запуска получаем из таблицы [oktell]. [dbo].[bitrix_lead_runtime]

0) Выводим уведомление о Запуске сценария и Получаем текущую дату и время для того чтобы отобразить время выполнения сценария. Дату и время получаем из функции «Текущие дата и время».

1) Получаем данные из таблицы oktell.dbo.bitrix_oauth для выполнения REST запроса Текст запроса -
- client_id - id приложения, который был получен ранее, в данном запросе указывается в виде строки.
2) Присваиваем счетчику для перебора лидов отрицательное значение, это необходимо для получение первого лида.

3) SQL-запрос. Получение N-го лида. Получаем № лида (ID)

4)sql_result>0? – в результате выполнения запроса нашелся хотя бы один лид?

4.1)Если да, то идем на шаг 5) 4.2)Если нет, то Обновляем данные о времени выполнения в таблице [oktell].[dbo].[bitrix_lead_runtime] и выводим уведомление с временем завершения сценария.
5)Выполняем web-запрос и получаем информацию по N-му лиду передавая его ID

6)Получаем «Выбранное решение» лидом (опционально, можно убрать данный компонент)

Текст запроса — выражение вида - '"result"/"UF_CRM_1387525788"/'+str([i])

7)Добавляем выбранное клиентом решение в таблицу - oktell.dbo.bitrix_lead_solution (опционально, можно убрать данный компонент) Текст запроса -

8)Устанавливаем Счетчик i =0, он необходим для того, чтобы из JSON структуры мы могли получить произвольное количество e-mail на следующей цепочке шагов.

9)Подсчитываем количество e-mail у лида. Компонент Парсер. Текст запроса — выражение вида - "result"/"EMAIL"

10)Получаем i-ый e-mail и выполняем серию компонентов Парсер JSON, для получения каждого из них. Получаем структуру вида:

11)Каждый из них добавляем в таблицу oktell.dbo.bitrix_lead_contacts Текст запроса -

12)Увеличиваем счетчик i=i+1

13)Проверяем i<cnt_EMAIL? Т.е. еще остались e-mail которые необходимо добавить в БД?

13.1)Если да, то идем на шаг 10) 13.2)Если нет, то идем на шаг 14)

14)Устанавливаем Счетчик i=0 (для получения телефонов) и повторяем точно такой же цикл как и для e-mail, т.к. JSON структура ответа у них совпадает.

15)Подсчитываем количество телефонов у лида Текст запроса — выражение вида - "result"/"PHONE"

16)Получаем i-ый телефон и выполняем серию компонентов Парсер JSON, для получения каждого из них. Получаем структуру вида:

17)Каждый из них добавляем в таблицу oktell.dbo.bitrix_lead_contacts Текст запроса -

18)Увеличиваем счетчик i=i+1

19)Проверяем i<cnt_PHONE? Т.е. еще остались телефоны которые необходимо добавить в БД?

19.1)Если да, то идем на шаг 16) 19.2)Если нет, то идем на шаг 20)

20)Присваиваем счетчик перебора лидов = текущему ID лида, для поиска построчно и переходим на шаг 3) и так до тех пор пока не отработает условие 4.2)

Создание служебных задач

После того, как все сценарии были настроены можно создать служебные задачи для автоматизации процесса получения новых refresh_token, access_token, и информации из Bitrix24. Исходя из описания REST API следует что access_token необходимо получать каждые 3600с, в то время как refresh_token активен в течении 1 месяца. В данном примере была создана служебная задача с периодом запуска — раз в 50 минут. Что позволяет всегда хранить действующий access_token, следует учитывать что после выполнения запроса refresh_token так же обновляется.

Таким образом были созданы 2 служебные задачи:

Заключение

В результате мы можем совершать запросы используя REST API и получать и записывать практически любую информацию из облачной версии Bitrix24. В данной статье был рассмотрен пример получения всех лидов и сохранения информации в БД.

Эти данные мы можем использовать:

1)Для определения номера при входящем звонке и отображении web-формы в Call-центре сразу со страницей лида.

2)Для отображение названии компании в различных отчетах, например пропущенные вызовы, что упростит поиск и скорость принятия решения на отработку вызова.

3)Для использования данной базы в различных исходящих обзвонах, отправки почты на e-mail.

Приведены только несколько примеров. Применение может быть различным.

Файлы

Исходный код

Скрипт создания таблиц в БД OKTELL

/*[bitrix_oauth] – Таблица с данными по Bitrix OAuth*/

/*[bitrix_leads] – Таблица которая содержит всю информацию по лидам*/

/* [bitrix_lead_contacts] – Список контактов лидов*/

/*[bitrix_import_lead_error] – таблица ошибок при выполнении sql запроса на добавление\обновление лида*/

/*[bitrix_lead_runtime] – Таблица с данными по дате запуска сценариев импорта лидов и импорта контактов лидов*/

/*[bitrix_lead_solution] – Таблица содержащая решение клиентов по проектам (распологается в самом низу карточки лида)*/

Если вдруг вам не хватает стандартных возможностей «Битрикс24», добавьте новые функции с помощью мини-программ. Сделайте хорошую платформу еще лучше.

Что такое приложения Битрикс24

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

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

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

В Битрикс24 есть встроенный каталог приложений — «Маркет». В нем можно найти и установить сотни самых разных мини-программ. В основном эти приложения позволяют автоматизировать однотипные действия, добавляют в интерфейс новые инструменты или открывают возможность для интеграций Bitrix24 с другими сервисами. Большинство таких модулей работает только в полной версии Битрикс24, но некоторые совместимы и с мобильной.

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

Цены на приложения Битрикс24

Если вы используете бесплатный план Битрикс24, но хотите попробовать приложения, можете оформить пробную подписку на «Маркет». Она бесплатно открывает полный доступ к приложением на 30 дней.

Примеры приложений Bitrix24

Mind Map. После установки этого приложения в разделе «Группы» появится новая вкладка, которая позволяет создавать ментальные карты. Так называют графические схемы, в виде которых удобно представлять сложные идеи, проекты или рабочие процессы — чтобы они стали понятнее. На изображения можно быстро добавлять значки сотрудников и задач, которые уже есть в системе, а также новые объекты и связи между ними. Ментальные карты заметно упрощают работу с информацией.

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

«Проверка телефонов». При работе с клиентами из разных часовых поясов можно случайно позвонить в нерабочее время и доставить тем самым неудобства. Эта программа избавит от множества подобных ситуаций. Она поможет быстро проверять часовые пояса собеседников по номерам телефонов. Ввели номер перед звонком — узнали текущее время абонента. По очевидным причинам, приложение работает только со стационарными федеральными номерами. Да, мобильные отследить не выйдет.

«Дни рождения сотрудников». Если вы заботитесь о корпоративной культуре, а также лояльности клиентов и сотрудников, вам пригодится эта программа. С ней вы перестанете забывать о днях рождения тех и других. Приложение отображает памятные даты на календаре и уведомляет о наступающих праздниках. Правда, даты рождения обязательно должны быть указаны в карточках соответствующих людей. Иначе они не появятся в календаре.

ApiX-Drive. С помощью этой программы вы сможете создавать интеграции Битрикс24 c сотнями других сервисов. Быстро и без единой строчки кода.

Приведем несколько примеров интеграций, которые можно создавать после установки ApiX-Drive.
- Социальные сети: подключайте лид-формы «ВКонтакте» и Facebook к Битрикс24, чтобы заявки автоматически попадали из соцсетей в воронку продаж.
- Конструкторы сайтов: благодаря интеграции с сайтами заказы и другие данные будут автоматически попадать из форм в CRM. ApiX-Drive поддерживает сайты, созданные на платформах вроде Tilda, Landingi, Wix, LPGenerator и Bloxy.
- Конструкторы квизов: после подключения опросов к Битрикс лиды и прочие ответы клиентов также будут попадать прямиком в CRM. С помощью ApiX-Drive можно интегрировать квизы, созданные в Marquiz, Typeform, Enquiz, QuizGO и других конструкторах.
- Электронные таблицы: подключите Google Sheets к Битрикс24 — и ApiX-Drive будет выгружать суммы сделок или другие выбранные данные в таблицу. Пригодится, если нужно будет визуализировать цифры в графиках или посчитать прибыль.
- Мессенджеры: после интеграции Битрикс24 с Viber, Telegram или Slack вы сможете получать уведомления о смене статусов и других событиях в CRM в любимом мессенджере.
Чтобы создать интеграцию, сначала нужно обязательно установить приложение. После этого остается зарегистрироваться на сайте одноименного сервиса ApiX-Drive и настроить связи между Битрикс24 и выбранными системами. Пользователю помогают встроенные подсказки, а при необходимости можно почитать подробные инструкции в справке ApiX-Drive. Создание интеграции занимает около 15 минут.

Как устанавливать приложения Битрикс24

Установка приложения занимает пару минут и не требует каких-либо технических знаний. Но эта возможность доступна только пользователю с правами администратора.

Чтобы попасть в каталог, нужно открыть личный кабинет Bitrix24 и нажать на боковой панели «Еще» — «Маркет». По умолчанию откроется вкладка «Все приложения». На ней можно найти все программы, доступные для установки.

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

Чтобы установить выбранное приложение, нужно кликнуть рядом с ним «Посмотреть», а затем «Установить».

Если программа потребует разрешения для доступа к тем или иным данным, надо будет отметить все запросы и повторно нажать «Установить».

Кроме того, на странице каждого приложения есть вкладка «Установка». Здесь могут быть перечислены дополнительные инструкции, необходимые для инсталляции или запуска программы.

Как удалять приложения Битрикс24

Если установленное приложение станет ненужным, вы сможете в любой момент его удалить.

Для этого сначала необходимо нажать на боковой панели «Еще» — «Маркет». Когда появится каталог, надо перейти на вкладку «Установленные». Здесь отображаются ранее загруженные программы.

Чтобы удалить выбранное приложение, нужно нажать рядом с ним «Удалить». После этого может понадобиться подтвердить удаление настроек и данных программы.

После удаления программа останется в списке «Установленные», чтобы при необходимости вы могли быстро найти и установить ее повторно. Для этого нужно снова нажать на кнопку «Установить».

Разработка приложений Битрикс24

Разработать приложение может любой желающий. Если программа пройдет модерацию, она появится в каталоге.

Есть несколько причин, которые могут подтолкнуть вас на создание своей программы для «Маркета». Если ваша компания использует Битрикс24, но сотрудникам не хватает какой-то важной функции в основном интерфейсе и уже готовых приложениях, можете добавить ее с помощью собственной разработки.

Кроме того, «Маркет» дает возможность заработать. Создав приложение, вы можете продавать к нему доступ другим пользователям. Разработчики сами выбирают формат монетизации: продавайте пожизненные лицензии на программы, сдавайте их в аренду по подписке, или зарабатывайте на встроенных покупках. Можете также создавать приложения для других компаний, которые хотят расширить функциональность Битрикс24, под заказ.

Для разработки разрешено использовать любые технологии и языки программирования, совместимые с Bitrix24 API (RESTful API). Вся необходимая документация и обучающие материалы доступны на сайте Битрикс.

Мы уже больше года рассказываем о приложениях для Битрикс24. Наши эксперты изучили и подготовили обзоры более 130 приложений! Если вы еще не видели эти обзоры, крайне рекомендуем ознакомиться, наверняка вы найдете для себя что-то интересное. Все обзоры приложений собраны тут. Сегодня мы решили копнуть глубже и рассказать не просто про готовые приложения, а про процесс разработки приложений для Битрикс24. Наша команда регулярно создает приложения, которые помогают решать различные задачи клиентов, так что нам есть, что рассказать.

Руководитель отдела веб-разработки - Вадим Солуянов согласился поделиться своим бесценным опытом разработки приложений для интеграции сторонних сервисов с Битрикс24. Так как материал получился очень объемным, мы разделим его на 4 части, поэтому рекомендуем подписаться на нас в социальных сетях, чтобы ничего не пропустить. Описание работы над приложением будет вестись от лица Вадима. Итак, поехали!

С чего начинается приложение?

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

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

Еще немного о приложении. Существует несколько способов работы с порталом Битрикс24. Здесь речь пойдет о приложении с пользовательским интерфейсом и размещаемом на стороннем сервере. Таким образом, в интеграции будет участвовать как минимум три сервера: портала, нашего приложения и СМС-провайдера.

Итак, поставлю задачу.

Выделим подзадачи из этой общей. В итоге получим такие точки входа в приложение:
- install - установка приложения,
- settings - настройка его параметров,
- handler - обработка команд на отправку СМС,
- task - периодическая проверка статуса СМС,
- statistic - сбор статистики по работе и ошибкам приложения.
Во-первых, установка. В принципе, Битрикс24 не требует подобной точки входа, приложение будет установлено и без нее, но было бы неплохо регистрировать где-то у себя сам факт установки. В дальнейшем появится и еще одна тому причина, но пока довольно и одной. При установке необходимо где-то зафиксировать, что на таком-то портале было установлено наше приложение в такой-то день и т.п. Сразу следует отметить одну особенность Битрикс24: на данную точку входа портал постучит не только при установке приложения, но и при обновлении с версии на версию. Поэтому, регистрируя факт установки, нам потребуется отличить первую установку от обновлений. Сделать это элементарно по наличию у нас записи об установке: если она есть, значит произошло обновление, если нет - установка. Отмечу также, что установка - это страница с пользовательским интерфейсом. Она может содержать какую-то информацию, а может лишь вызывать метод js-библиотеки, предоставляемой Битрикс24, который фиксирует факт установки. Допустим, что у нас будет лишь этот вызов: BX24.installFinish(). После чего портал перенаправит пользователя на основную страницу приложения, т.е в настройки.

Статистика. Если мы хотим не просто написать приложуху, выложить в открытый доступ и забыть о ее существовании, то нам потребуется собирать статистику. Во-первых, для того, чтобы видеть насколько востребовано приложение, во-вторых, для технической поддержки. Под статистикой я подразумеваю два хранилища данных: лог приложения, в котором фиксируются действия и данные в ключевых точках программы, фиксируются факты установки, удаления, успешной/неудачной отправки/доставки, ошибки и собственно статистика - собранные за день и сложенные в одну цифру интересующие нас факты. Упс. Удаление. Придется внести правки в изначальный список точек входа. Теперь он будет выглядеть так:
- install,
- settings,
- handler,
- event_handler - обработка событий портала,
- task,
- statistic.
Появилась еще одна - обработчик событий. Факт удаления нашего приложения мы можем узнать лишь подписавшись в портале на событие OnAppUninstall. Когда оно произойдет, портал стукнется на тот URL, что мы указали при подписке. Помимо того, что мы зафиксируем факт удаления, мы еще и почистим все хранилища (за исключением логов и статистики) от записей, привязанных к данному порталу, поскольку от них больше никакого проку.

Ну, вот теперь все точки входа в наше приложение вкратце описаны, выяснены действия, какие необходимо выполнить, и данные, которые необходимо где-то у себя хранить. Было бы неплохо их еще раз перечислить отдельно от описания точек входа. Итак:
Логирование.
DOMAIN - домен портала (все-таки при техподдержке с ним работать удобнее)
MEMBER_ID - идентификатор портала (домен может быть переименован, но id - нет)
EVENT_TYPE - тип события (напр., факт установки - INSTALL)
EVENT_DATA - любые интересующие данные в виде текста
DATE_CREATE - дата и время события в понятном человеку написании
DATE_POINT - дата, время и миллисекунды для сортировки и получения точной последовательности событий (просто DATE_CREATE для этого не хватит, поскольку за одну секунду может произойти несколько событий)

Хранение авторизации СМС-провайдера
Для простоты добавим поля к п.1 в те самые другие поля
API_LOGIN - логин у СМС-провайдера
API_KEY - АПИ ключ

Авторизация пользователя портала
DOMAIN
MEMBER_ID
BX_USER_ID - униальный в рамках портала id пользователя
ACCESS_TOKEN - собственно, тот токен, с которым будем стучаться на портал
REFRESH_TOKEN - токен для обновления access_token
REFRESH_DATE_END - последняя дата-время валидности refresh_token
VERSION - версия приложения

Статистика
DOMAIN
MEMBER_ID
EVENT_TYPE - тип события
DAY_VALUE - количество событий за день
DATE_CREATE - дата, на которую собрана статистика

Хранилище данных требует пояснений. Например, почему всюду дублируется домен и id портала. Ну. домен, потому что так удобнее просматривать и фильтровать записи при осуществлении технической поддержки, а MEMBER_ID. можно, конечно, привязку сделать по первичному ключу с данными из п.1 (Сведения о портале). Но и выборки придется делать всегда с джойном двух таблиц. Короче, я выбираю именно вариант с id портала в каждой таблице. Когда мы работаем с порталом, то у нас в наличии всегда именно member_id, он приходит с портала, и его же мы посылаем самим себе при обращении с фронта в бэк.

И еще одно важное замечание по поводу версий. Во всех местах программы, где вы указываете путь к приложению, а это URL обработчика событий, это URL для атрибута action формы настроек, это URL отправки тестового СМС из фронта в бэк, всюду URL должен формироваться динамически, исходя из текущего расположения приложения. Иначе при выпуске новой версии вам придется лазить по всему коду и заменять. Даже, если вынесете эти URL-ы в конфигурационный файл, всегда можно что-то пропустить. Динамическое формирование URL-ов самое правильное.

Теперь REFRESH_DATE_END в таблице пользователей. Токен, с которым мы стучимся на портал, живет лишь один час, а затем требует обновления через refresh_token, но у того самого (пока еще) есть собственный lifetime размером в 30 дней. Чтобы не потерять возможность делать запросы от лица каждого пользователя, мы обязаны отслеживать момент окончания валидности и делать обновление. По данному полю мы определяем такую необходимость. Вот поэтому я и вынес авторизацию пользователей в отдельное хранилище, поскольку по нему придется периодически пробегать, обновляя токены. Ну и с точки зрения построения баз данных это правильнее. И еще замечание по токенам. Если приложение размещается не на вашем сервере, а может, даже и в этом случае, токены следует хранить в зашифрованном виде.

Итак, после перечисления всех данных мы обнаруживаем, что список наших действий необходимо дополнить пунктом 16.

16. Обновление refresh_token-ов, у которых срок жизни приближается к 30 дням, раз в сутки.

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

Читайте также: