Создание локального (serverless) приложения для Bitrix24 с нуля

Ниже представлена подробная статья о том, как создать «локальное» (serverless) приложение для Bitrix24 практически с нуля. Мы разберёмся, что подразумевается под «локальным» приложением в контексте Bitrix24, как настроить окружение, как протестировать взаимодействие с Bitrix24 и, наконец, как развёртывать и поддерживать такое приложение.

1. Что такое локальное (serverless) приложение для Bitrix24

Локальное приложение в Bitrix24 – это приложение, которое вы размещаете не на стороннем сервере, а фактически «у себя»: оно не требует постоянного собственного сервера, а взаимодействует с порталом Bitrix24 через REST API. Для этого можно:

либо использовать инфраструктуру (например, AWS Lambda, Яндекс Функции, Cloud Functions и др.) – то есть фактически «serverless»-подход: платить только за время выполнения кода;
либо запустить приложение на локальном компьютере/локальной сети, используя прокси или временный туннель, когда приложение доступно Bitrix24 только в момент его реального использования (подходит для тестовых окружений, демонстраций и прототипирования).

Что даёт локальное приложение:

Автономность. Код не нужно хостить на постоянном сервере.
Гибкость. Вы можете быстро вносить изменения и проверять их в работе.
Оптимизация затрат. Платите за серверные ресурсы (или за функции serverless), когда действительно используете приложение.

2. Подготовка к созданию приложения

2.1. Регистрация на Bitrix24 и доступ к REST API

Для начала убедитесь, что у вас есть портал Bitrix24 (например, в формате company.bitrix24.ru или .by и т.д.) и у вас есть права администратора на этом портале – без них вы не сможете создавать приложения.

Чтобы работать с REST API, не нужно никаких дополнительных лицензий или модулей: достаточно стандартной «коробочной» версии или облачного портала (включая бесплатный тариф, у которого есть базовые ограничения, но для учебных целей подходит).

2.2. Создание приложения через «Мои приложения»

Переходим в Разработчикам → Мои приложения → Добавить новое приложение.

Тип приложения: «Локальное».
Название: введите любое удобное, например «TestApp Serverless».
Описание: укажите назначение приложения (пример: «Тестовое серверлесс-приложение для демонстрации интеграции»).
Настройки OAuth: при создании приложения Bitrix24 автоматически сгенерирует для вас пару ключей: client_id и client_secret. Их нужно будет использовать, чтобы ваше приложение могло выполнять запросы к Bitrix24.

2.3. Определение конечных точек (endpoint) для REST

Приложению понадобятся URL-адреса, по которым Bitrix24 будет направлять запросы (для входящей интеграции) и где вы будете обрабатывать события. В случае serverless-приложений эти адреса указывают на входные точки (Endpoints) в ваших «Функциях» (например, AWS Lambda), либо на публичный tunneling-URL (например, ngrok), если вы разворачиваете код локально на своём компьютере.

Основные endpoint-ы:

Endpoint для авторизации (OAuth) – туда Bitrix24 будет направлять код авторизации, когда вы запускаете приложение в портале.
Endpoint для обработки событий (Event Handler) – если приложение подписывается на события (например, «добавлен лид»).
Endpoint для взаимодействия (REST) – обычный адрес, на который посылаются запросы.

Важно: даже для «локальных» приложений Bitrix24 требует, чтобы URL в настройках были публично доступны хотя бы на время тестирования, иначе портал не сможет отправить на них запросы.

3. Настройка инфраструктуры serverless

Рассмотрим один из самых распространённых способов «безсерверного» запуска кода – AWS Lambda. Важно понимать, что вы можете использовать любую другую платформу с аналогичным функционалом (Azure Functions, Google Cloud Functions, Яндекс Функции, Cloudflare Workers и др.) или вообще поднять локальный сервер с публичным адресом через ngrok.

3.1. Создаём AWS Lambda-функцию

Шаг 1. Зарегистрируйтесь в AWS, если у вас ещё нет аккаунта.
Шаг 2. В AWS Console перейдите к сервису Lambda.
Шаг 3. Нажмите «Create function».
- Function name: например, Bitrix24ServerlessApp.
- Runtime: выберите нужный язык (Node.js, Python и т.д.).
- Permissions (Роли): AWS предложит создать или выбрать роль IAM. Для начала можно создать базовую роль с правами на логирование в CloudWatch.

После создания в списке появится ваша функция. Откройте её и обратите внимание на API Gateway или Function URL – именно через эти инструменты Lambda сможет «принимать» HTTP-запросы от Bitrix24.

3.2. Подключаем API Gateway (или Function URL)

Способ 1: Function URL

Нажмите Configuration → Function URL.
Создайте новый Function URL.
Установите «Auth type» = «NONE» (для теста) или используйте авторизацию AWS IAM.

Способ 2: API Gateway

Создайте новый API (REST или HTTP).
Привяжите его к своей Lambda-функции.
Запомните URL-адрес (Endpoint) – это и будет ваш публичный адрес, который вы укажете в настройках приложения Bitrix24.

Важно: если вы планируете работать с OAuth-авторизацией и подпиской на события, подготовьте несколько эндпоинтов (или один универсальный) – Bitrix24 будет отправлять запросы на разные URL по отдельным событиям.

4. Пример кода Lambda-функции (Node.js)

Ниже приведён упрощённый пример на Node.js, показывающий логику приёма запросов и отправки ответов через serverless. Предположим, что у нас всего один URL-эндпоинт, обрабатывающий базовую авторизацию и простые запросы.

exports.handler = async (event) => {
    // event: объект с информацией о запросе
    const { httpMethod, body, queryStringParameters } = event;
    let responseBody = {};

    try {
        // Преобразуем тело запроса
        let data = {};
        if (body) {
            data = JSON.parse(body);
        }

        // Пример: проверяем метод
        if (httpMethod === 'GET') {
            // Обработка при открытии приложения (например, OAuth-код)
            const code = queryStringParameters && queryStringParameters.code;
            if (code) {
                // Получаем access_token у Bitrix24
                // 1. Обмениваем code на access_token
                // 2. Сохраняем access_token в базу или выдаём пользователю
                responseBody = { message: "Приложение установлено. Code получен.", code };
            } else {
                responseBody = { message: "GET запрос без кода авторизации" };
            }
        } else if (httpMethod === 'POST') {
            // Обработка различных событий от Bitrix24
            if (data.event) {
                // Например, обрабатываем событие создания лида
                if (data.event === 'onCrmLeadAdd') {
                    // Здесь логика: вы можете вызвать методы REST Bitrix24
                    // с помощью полученного ранее access_token
                    // Например, сделать запрос к CRM и дополнить лид данными
                    responseBody = { message: "Событие onCrmLeadAdd получено и обработано" };
                } else {
                    responseBody = { message: `Неизвестное событие: ${data.event}` };
                }
            } else {
                responseBody = { message: "Нет поля 'event' в теле запроса" };
            }
        }
    } catch (err) {
        console.error("Ошибка:", err);
        return {
            statusCode: 500,
            body: JSON.stringify({ error: err.message })
        };
    }

    return {
        statusCode: 200,
        body: JSON.stringify(responseBody)
    };
};

Что здесь важно отметить:

При GET-запросе мы проверяем, передан ли в query-параметрах code – это код, который Bitrix24 выдаёт при установке приложения (OAuth). С помощью него мы получаем access_token.
При POST-запросе (например, уведомления о событиях) мы проверяем поле data.event, чтобы понять, какое событие пришло из Bitrix24.

5. Настройка приложения в Bitrix24 для интеграции

Возвращаемся в настройки нашего приложения в Мои приложения → Настройки:

OAuth redirect URL: здесь указываем endpoint, который будет обрабатывать авторизацию. Например, https://<your-api-endpoint>/auth.
Event Handler URL (если используем подписку на события): можно указать тот же endpoint или отдельный, например, https://<your-api-endpoint>/events.
Scope (права): отметьте нужные вам права (CRM, списки, диск, пользователи и т.д.), чтобы приложение могло обращаться к соответствующим методам.

Сохраните изменения и обратите внимание на сгенерированные параметры:

client_id
client_secret

Эти значения будут нужны, чтобы получать access_token. Bitrix24 формирует запрос примерно следующего вида:

POST https://oauth.bitrix.info/oauth/token/
?grant_type=authorization_code
&client_id=<ваш client_id>
&client_secret=<ваш client_secret>
&code=<выданный при авторизации code>

В ответ вы получите JSON, в котором будет access_token (действителен ограниченное время) и refresh_token (для продления).

6. Подписка на события (Event Subscriptions)

Если ваше приложение должно реагировать на события в портале (например, при создании лида, задачи или изменения статуса сделки), необходимо подписаться на соответствующее событие. Это можно сделать двумя способами:

Вручную в настройках приложения (указать события).
Через REST-метод event.bind.

6.1. Пример использования `event.bind`

POST https://<your-portal>.bitrix24.ru/rest/<user_id>/<access_token>/event.bind
{
   "event": "onCrmLeadAdd",
   "handler": "https://<your-api-endpoint>/events"
}

event – название события, на которое подписываемся.
handler – наш serverless-URL, принимающий запрос.

Bitrix24 будет отправлять POST-запросы на этот handler при каждом создании нового лида. Формат JSON, который вы получите в теле запроса, будет содержать event, data и другую служебную информацию.

7. Тестирование приложения

7.1. Установка приложения в портал

Переходим в раздел Приложения → Мои приложения.
Находим наше локальное приложение (например, «TestApp Serverless»).
Нажимаем Установить. Происходит перенаправление на ваш OAuth redirect URL, где вы получите code.
Приложение запрашивает access_token, сохраняя его у себя (в коде Lambda или внешней базе).

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

7.2. Проверка события (`onCrmLeadAdd`)

Создайте тестовый лид. Проверьте логи Lambda (либо лог вашей serverless-платформы), чтобы убедиться, что туда пришёл запрос от Bitrix24. Увидите тело запроса, содержащее поле event: "onCrmLeadAdd" и идентификатор созданного лида.

8. Лучшие практики и советы

Используйте безопасные соединения (HTTPS). Все запросы Bitrix24 к вашему приложению будут идти только по HTTPS.
Хранение токенов. access_token и refresh_token нужно надёжно хранить. При использовании serverless-подхода можно хранить их в каком-либо безопасном хранилище (например, AWS Secrets Manager, DynamoDB с шифрованием).
Обновление токена. Не забывайте, что access_token действует ограниченное время (обычно 3600 секунд). Вам понадобится использовать refresh_token для обновления. Это можно автоматизировать.
Обработка ошибок. Всегда обрабатывайте исключения (try…catch), чтобы Bitrix24 получал корректный HTTP-статус. Иначе подписки могут быть отключены.
Версионирование. Удобнее вести код приложения в системе контроля версий (Git), чтобы в любой момент можно было откатиться к стабильной версии.
Лимиты. Bitrix24 и serverless-платформы имеют лимиты (на время выполнения, объём данных в одном запросе и т.д.). Учитывайте это при проектировании.

9. Развёртывание и дальнейшая поддержка

Развёртывание:
- При использовании AWS Lambda: обновляйте код в консоли или через автоматизированные инструменты (SAM, Serverless Framework, Terraform).
- Если используете ngrok или другой туннель, каждый раз при запуске может меняться URL. Придётся обновлять настройки приложения в Bitrix24, что не всегда удобно. Поэтому для постоянной работы лучше иметь стабильный публичный URL.
Мониторинг:
- В AWS Lambda – используйте CloudWatch для логирования и метрик.
- В других платформах – используйте встроенные механизмы логирования и мониторинга.
Обновление приложения:
- Если вам нужно изменить набор прав (scope), необходимо обновить их в настройках Bitrix24 и переустановить приложение.
- Если модифицируете код, важно учесть, что пользователям, уже установившим приложение, возможно, потребуется повторная установка (если изменения критичны к логике OAuth).

10. Вывод

Создание локального serverless-приложения для Bitrix24 даёт вам гибкость и экономию ресурсов: код исполняется ровно тогда, когда в этом есть необходимость, а вы не тратите средства на аренду выделенного сервера. При этом сам процесс не очень сложен, если понимать основные шаги:

Зарегистрировать приложение в Bitrix24 и получить client_id / client_secret.
Организовать «точку входа» (Endpoint) – это может быть AWS Lambda, Google Cloud Functions или другой serverless-сервис.
Настроить получение и хранение access_token, регулярно обновлять его с помощью refresh_token.
Подписаться на нужные события через REST или вручную указать их при настройке приложения.
Подключить логи и отладку, чтобы следить за корректной работой приложения.

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

Надеемся, что данная инструкция поможет вам быстро освоить базовый процесс создания локального (serverless) приложения для Bitrix24 и вдохновит на новые эксперименты с интеграциями!

Теги: Битрикс24