Как создать дело из приложения
Scope:
crmПрава проверяются для связанного с делом элемента CRM:
- crm.activity.add и crm.activity.update — право на изменение элемента
- crm.activity.delete — право на удаление элемента
Выберите инструмент для разработки с AI-агентом:
- используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
- используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации
Установленное приложение может добавить дело в таймлайн карточки CRM.
Когда сотрудник откроет его, Битрикс24 покажет страницу приложения в боковой панели. Так можно работать с приложением прямо из карточки: смотреть связанные данные, выполнять нужные действия или обращаться к внешнему сервису.
Как работает сценарий
В сценарии участвуют пользователь, Битрикс24 и приложение:
- пользователь — выбирает элемент CRM и работает с созданным делом в таймлайне
- Битрикс24 — сохраняет дело и передает странице приложения параметры его открытия
- приложение — создает, изменяет или удаляет дело через REST API
Сначала пользователь выбирает на странице приложения элемент CRM — в этом сценарии лид. Приложение создает для него дело методом crm.activity.add. Дело появляется в таймлайне лида.
Когда пользователь нажимает на это дело, Битрикс24 открывает страницу приложения и передает идентификатор дела в PLACEMENT_OPTIONS. Так приложение понимает, с каким делом нужно работать, и может изменить или удалить его.
В сценарии будем использовать методы:
- crm.activity.add — создадим дело приложения
- crm.activity.update — изменим или завершим дело
- crm.activity.delete — удалим дело
Дальше соберем страницу приложения по шагам: подготовим файл, определим режим открытия, добавим интерфейс и настроим работу с делом. Для вызова REST-методов и функций интерфейса используем JavaScript-библиотеку BX24.js.
1. Подготовьте приложение
Создайте приложение со scope crm и подготовьте сервер, доступный из внешней сети.
Создайте на сервере файл index.php. В следующих шагах последовательно добавляйте в него блоки кода. После последнего шага получится готовая страница приложения.
2. Определите режим открытия
Одна и та же страница приложения может открываться в двух ситуациях:
- пользователь запускает приложение в Битрикс24 — на странице он выбирает лид и создает для него дело
- пользователь нажимает на созданное дело в таймлайне лида — Битрикс24 открывает ту же страницу с действиями для завершения или удаления дела
Чтобы определить ситуацию, приложение проверяет параметры, которые передал Битрикс24. При открытии дела из таймлайна Битрикс24 передает в POST-запросе PLACEMENT_OPTIONS. Значение содержит JSON-строку с двумя параметрами:
action— действие, с которым открыта страница. Для дела приложения значение равноview_activityactivity_id— числовой идентификатор открытого дела. Передайте его в методы crm.activity.update или crm.activity.delete
Добавьте в начало файла index.php код, который получает и проверяет эти параметры:
Как использовать примеры в документации
<?php
header('Content-Type: text/html; charset=UTF-8');
$placementOptions = [];
if (!empty($_POST['PLACEMENT_OPTIONS']))
{
$decodedOptions = json_decode($_POST['PLACEMENT_OPTIONS'], true);
if (is_array($decodedOptions))
{
$placementOptions = $decodedOptions;
}
}
$activityId = isset($placementOptions['activity_id'])
? (int)$placementOptions['activity_id']
: 0;
$isActivityView = ($placementOptions['action'] ?? '') === 'view_activity'
&& $activityId > 0;
?>
Если страница открыта из дела, переменная $isActivityView получит значение true, а $activityId — числовой идентификатор дела.
3. Добавьте интерфейс страницы
Сразу после PHP-блока добавьте HTML-разметку. Она покажет нужные кнопки в зависимости от значения $isActivityView:
<!DOCTYPE html>
<html lang="ru">
<head>
<meta charset="UTF-8">
<title>Дело приложения</title>
</head>
<body hidden>
<script src="//api.bitrix24.tech/api/v1/"></script>
<?php if ($isActivityView): ?>
<p>Идентификатор дела: <?= $activityId ?></p>
<button type="button" onclick="updateActivity(<?= $activityId ?>)">
Завершить дело
</button>
<button type="button" onclick="deleteActivity(<?= $activityId ?>)">
Удалить дело
</button>
<?php else: ?>
<button type="button" onclick="selectCRMEntity()">Выбрать лид</button>
<span id="selected-entity">Лид не выбран</span>
<button type="button" onclick="addActivity()">Создать дело</button>
<?php endif; ?>
<p id="status" role="status"></p>
Когда пользователь запускает приложение в Битрикс24, страница показывает кнопки для выбора лида и создания дела. Когда пользователь открывает созданное дело из таймлайна, страница показывает его идентификатор и действия для завершения или удаления.
4. Инициализируйте BX24.js
После HTML-разметки добавьте общие переменные и вспомогательные функции. Замените значение responsibleId на идентификатор сотрудника, ответственного за дело.
Библиотека BX24.js уже подключена в предыдущем блоке. Дождитесь ее инициализации с помощью BX24.init, прежде чем вызывать методы Битрикс24.
<script>
const responsibleId = 1;
let selectedEntityId = null;
BX24.init(() => {
document.body.hidden = false;
});
function showStatus(message, isError = false)
{
const status = document.getElementById('status');
status.textContent = message;
status.style.color = isError ? 'red' : 'green';
}
function showError(result)
{
showStatus(
`Ошибка: ${result.error()} — ${result.error_description()}`,
true
);
}
</script>
После выполнения BX24.init страница станет видимой. Функции showStatus и showError будут выводить результат REST-вызовов.
5. Добавьте создание дела
Чтобы создать дело приложения, вызовите метод crm.activity.add с полем PROVIDER_ID=REST_APP. Дело с PROVIDER_ID=REST_APP можно создать только из установленного приложения. Изменить или удалить его может только приложение, которое его создало.
При вызове через вебхук Битрикс24 вернет ошибку Application context required., а при вызове из другого приложения — Access denied.
Метод crm.activity.add помечен как устаревший, но в этом сценарии заменить его на crm.activity.todo.add нельзя: метод не принимает поле PROVIDER_ID.
В примере пользователь выбирает лид через BX24.selectCRM. Для лида функция возвращает идентификатор с префиксом, например L_123. Приложение удаляет префикс L_ и передает числовую часть в OWNER_ID метода crm.activity.add.
Для другого объекта CRM измените entityType, префикс идентификатора и OWNER_TYPE_ID.
Основные поля для создания дела:
Обязательные параметры отмечены *
OWNER_TYPE_ID*— числовой идентификатор типа объекта CRM. Для лида передайте1OWNER_ID*— числовой идентификатор выбранного лидаPROVIDER_ID*— идентификатор провайдера. Для дела приложения передайтеREST_APPPROVIDER_TYPE_ID— тип дела приложения. Если поле не передано, Битрикс24 использует значениеLINKSUBJECT*— название дела в таймлайнеRESPONSIBLE_ID*— идентификатор сотрудника, ответственного за дело
Поле TYPE_ID обычно обязательно для crm.activity.add. Для REST_APP его можно не передавать: метод автоматически устанавливает тип дела «Провайдер».
Добавьте после предыдущего блока функции для выбора лида и создания дела:
<script>
function selectCRMEntity()
{
BX24.selectCRM(
{ entityType: ['lead'] },
(selected) => {
const lead = selected.lead && selected.lead[0];
if (!lead)
{
return;
}
const id = Number(lead.id.replace(/^L_/, ''));
if (!Number.isInteger(id) || id <= 0)
{
showStatus('Не удалось определить идентификатор лида', true);
return;
}
selectedEntityId = id;
document.getElementById('selected-entity').textContent = lead.title;
showStatus(`Выбран лид с идентификатором ${id}`);
}
);
}
function addActivity()
{
if (!selectedEntityId)
{
showStatus('Сначала выберите лид', true);
return;
}
BX24.callMethod(
'crm.activity.add',
{
fields: {
OWNER_TYPE_ID: 1,
OWNER_ID: selectedEntityId,
PROVIDER_ID: 'REST_APP',
PROVIDER_TYPE_ID: 'LINK',
SUBJECT: 'Новое дело приложения',
COMPLETED: 'N',
RESPONSIBLE_ID: responsibleId,
DESCRIPTION: 'Описание нового дела'
}
},
(result) => {
if (result.error())
{
showError(result);
return;
}
showStatus(`Дело создано. Идентификатор: ${result.data()}`);
}
);
}
</script>
После успешного вызова crm.activity.add страница покажет числовой идентификатор созданного дела.
6. Добавьте изменение и удаление дела
Чтобы завершить дело, передайте его идентификатор в метод crm.activity.update и установите поле COMPLETED=Y.
Чтобы удалить дело, передайте тот же идентификатор в метод crm.activity.delete.
Добавьте после функций создания дела следующий блок. Он также закрывает элементы body и html, поэтому разместите его в конце файла:
<script>
function updateActivity(id)
{
BX24.callMethod(
'crm.activity.update',
{
id,
fields: {
COMPLETED: 'Y',
SUBJECT: 'Дело выполнено',
DESCRIPTION: 'Описание выполненного дела'
}
},
(result) => {
if (result.error())
{
showError(result);
return;
}
showStatus('Дело изменено');
}
);
}
function deleteActivity(id)
{
if (!window.confirm('Удалить дело?'))
{
return;
}
BX24.callMethod(
'crm.activity.delete',
{ id },
(result) => {
if (result.error())
{
showError(result);
return;
}
showStatus('Дело удалено');
}
);
}
</script>
</body>
</html>
Методы вернут true после успешного изменения или удаления дела. Страница выведет сообщение о выполненном действии.
7. Разместите и проверьте приложение
Сохраните index.php и разместите его на сервере, доступном из внешней сети. Полученный URL укажите как адрес основной страницы приложения, затем установите приложение в Битрикс24.
Проверьте сценарий:
- Откройте приложение, выберите лид и создайте дело
- Проверьте, что приложение показало числовой идентификатор нового дела
- Откройте карточку выбранного лида и найдите дело в таймлайне
- Нажмите на дело и проверьте, что Битрикс24 открыл приложение с тем же идентификатором
- Завершите или удалите дело и проверьте результат в таймлайне