REST API активности в Битрикс24: инструкция по работе с методами и автоматизации

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

Основы REST API активностей в Битрикс24

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

Основные типы активностей

• Звонки — входящие и исходящие телефонные звонки
• Встречи — запланированные встречи с клиентами
• Задачи — различные задачи по работе с лидами и сделками
• Письма — электронная переписка
• Открытые линии — обращения через чат-боты и мессенджеры
• Пользовательские активности — созданные администратором типы действий

Методы REST API для работы с активностями

crm.activity.add — создание новой активности

Этот метод позволяет создать новую активность в системе. Базовая структура запроса:

POST /rest/crm.activity.add
{
"fields": {
"OWNER_TYPE_ID": "2",
"OWNER_ID": "123",
"TYPE_ID": "1",
"SUBJECT": "Звонок клиенту",
"DESCRIPTION": "Обсуждение условий договора",
"START_TIME": "2024-01-15T10:00:00",
"END_TIME": "2024-01-15T10:30:00",
"COMPLETED": "N",
"PRIORITY": "2",
"RESPONSIBLE_ID": "1"
}
}

crm.activity.get — получение информации об активности

Метод для получения детальной информации о конкретной активности:

GET /rest/crm.activity.get?id=456

crm.activity.list — получение списка активностей

Позволяет получить список активностей с различными фильтрами:

GET /rest/crm.activity.list?filter[OWNER_TYPE_ID]=2&filter[OWNER_ID]=123&select[]=ID&select[]=SUBJECT&select[]=START_TIME

crm.activity.update — обновление активности

Метод для изменения существующей активности:

POST /rest/crm.activity.update
{
"id": "456",
"fields": {
"COMPLETED": "Y",
"DESCRIPTION": "Звонок завершен успешно"
}
}

crm.activity.delete — удаление активности

Удаление активности из системы:

POST /rest/crm.activity.delete?id=456

Параметры и поля активностей

Обязательные поля

• OWNER_TYPE_ID — тип владельца (1 — лид, 2 — сделка, 3 — контакт, 4 — компания)
• OWNER_ID — ID владельца
• TYPE_ID — тип активности
• SUBJECT — тема активности
• RESPONSIBLE_ID — ID ответственного

Дополнительные поля

• DESCRIPTION — описание активности
• START_TIME — время начала
• END_TIME — время окончания
• DEADLINE — крайний срок
• COMPLETED — признак завершения (Y/N)
• PRIORITY — приоритет (1 — низкий, 2 — средний, 3 — высокий)
• LOCATION — место проведения
• CREATED — дата создания
• LAST_UPDATED — дата последнего обновления

Работа с типами активностей

Получение списка типов активностей

Для получения доступных типов активностей используйте метод:

GET /rest/crm.activity.type.list

Стандартные типы активностей

• 1 — Звонок
• 2 — Встреча
• 3 — Задача
• 4 — Письмо
• 5 — Уведомление

Привязка файлов к активностям

Битрикс24 позволяет прикреплять файлы к активностям через REST API. Для этого используется поле STORAGE_ELEMENT_IDS:

POST /rest/crm.activity.add
{
"fields": {
"OWNER_TYPE_ID": "2",
"OWNER_ID": "123",
"TYPE_ID": "1",
"SUBJECT": "Звонок с документами",
"STORAGE_ELEMENT_IDS": ["file_123", "file_456"]
}
}

Работа с коммуникациями

Активности могут содержать информацию о коммуникациях (телефоны, email). Для работы с ними используется поле COMMUNICATIONS:

{
"fields": {
"COMMUNICATIONS": [
{
"TYPE": "PHONE",
"VALUE": "+7 (495) 123-45-67",
"ENTITY_TYPE_ID": "3",
"ENTITY_ID": "123"
},
{
"TYPE": "EMAIL",
"VALUE": "client@example.com",
"ENTITY_TYPE_ID": "3",
"ENTITY_ID": "123"
}
]
}
}

Фильтрация и сортировка активностей

Основные фильтры

• OWNER_TYPE_ID — фильтр по типу владельца
• OWNER_ID — фильтр по ID владельца
• TYPE_ID — фильтр по типу активности
• COMPLETED — фильтр по статусу завершения
• RESPONSIBLE_ID — фильтр по ответственному
• >=START_TIME — активности с определенной даты
• <=END_TIME — активности до определенной даты

Пример сложного фильтра

GET /rest/crm.activity.list?filter[OWNER_TYPE_ID]=2&filter[COMPLETED]=N&filter[>=START_TIME]=2024-01-01T00:00:00&filter[RESPONSIBLE_ID]=1&order[START_TIME]=ASC&start=0&limit=50

Обработка ошибок и отладка

Основные коды ошибок

• ACCESS_DENIED — недостаточно прав доступа
• NOT_FOUND — активность не найдена
• REQUIRED_FIELD_MISSING — отсутствует обязательное поле
• INVALID_PARAMETER — неверный параметр

Рекомендации по отладке

• Всегда проверяйте права доступа пользователя или приложения
• Используйте валидные ID для владельцев и типов активностей
• Проверяйте формат дат и времени
• Обрабатывайте ошибки и логируйте запросы

Автоматизация с помощью REST API активностей

Создание активностей при поступлении лидов

Пример автоматического создания задачи при поступлении нового лида:

function createFollowUpTask(leadId, responsibleId) {
const taskData = {
fields: {
OWNER_TYPE_ID: "1", // Лид
OWNER_ID: leadId,
TYPE_ID: "3", // Задача
SUBJECT: "Обработать новый лид",
DESCRIPTION: "Необходимо связаться с лидом в течение 2 часов",
DEADLINE: new Date(Date.now() + 2 * 60 * 60 * 1000).toISOString(),
RESPONSIBLE_ID: responsibleId,
PRIORITY: "3"
}
};
return fetch('/rest/crm.activity.add', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(taskData)
});
}

Массовое обновление активностей

Для работы с большим количеством активностей используйте пакетные запросы:

POST /rest/batch
{
"cmd": {
"activity_1": "crm.activity.update?id=123&fields[COMPLETED]=Y",
"activity_2": "crm.activity.update?id=124&fields[COMPLETED]=Y",
"activity_3": "crm.activity.update?id=125&fields[COMPLETED]=Y"
}
}

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

Синхронизация с календарем

Активности типа «Встреча» можно синхронизировать с внешними календарными системами:

// Получение встреч для синхронизации
GET /rest/crm.activity.list?filter[TYPE_ID]=2&filter[>=START_TIME]=2024-01-01T00:00:00&select[]=ID&select[]=SUBJECT&select[]=START_TIME&select[]=END_TIME&select[]=LOCATION

Webhook для уведомлений

Настройка webhook для получения уведомлений о создании и изменении активностей:

POST /rest/event.bind
{
"event": "OnCrmActivityAdd",
"handler": "https://yoursite.com/webhook/activity-created"
}

Оптимизация производительности

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

• Используйте пагинацию — не загружайте все данные сразу
• Выбирайте только нужные поля — используйте параметр select
• Кэшируйте данные — избегайте повторных запросов
• Используйте пакетные запросы — для массовых операций
• Обрабатывайте лимиты — учитывайте ограничения на количество запросов

Пример оптимизированного запроса

GET /rest/crm.activity.list?filter[OWNER_TYPE_ID]=2&filter[COMPLETED]=N&select[]=ID&select[]=SUBJECT&select[]=START_TIME&select[]=RESPONSIBLE_ID&order[START_TIME]=ASC&start=0&limit=50

Безопасность при работе с REST API

Права доступа

• CRM — базовые права на работу с CRM
• task — права на работу с задачами
• calendar — права на работу с календарем

Рекомендации по безопасности

• Используйте HTTPS для всех запросов
• Не передавайте токены доступа в URL
• Регулярно обновляйте токены
• Логируйте все операции для аудита
• Проверяйте входные данные на валидность

Примеры практического использования

Создание автоматических напоминаний

Система может автоматически создавать напоминания о важных событиях:

function createReminder(dealId, reminderText, reminderTime) {
return fetch('/rest/crm.activity.add', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
fields: {
OWNER_TYPE_ID: "2",
OWNER_ID: dealId,
TYPE_ID: "5", // Уведомление
SUBJECT: "Напоминание",
DESCRIPTION: reminderText,
START_TIME: reminderTime,
COMPLETED: "N",
PRIORITY: "2"
}
})
});
}

Отчеты по активностям

Создание отчетов о выполненных активностях сотрудников:

// Получение активностей сотрудника за период
GET /rest/crm.activity.list?filter[RESPONSIBLE_ID]=1&filter[>=START_TIME]=2024-01-01T00:00:00&filter[<=END_TIME]=2024-01-31T23:59:59&filter[COMPLETED]=Y&select[]=ID&select[]=SUBJECT&select[]=TYPE_ID&select[]=START_TIME

Расширенные возможности

Пользовательские поля активностей

Битрикс24 позволяет создавать пользовательские поля для активностей:

// Получение пользовательских полей
GET /rest/crm.activity.userfield.list
// Создание пользовательского поля
POST /rest/crm.activity.userfield.add
{
"fields": {
"FIELD_NAME": "UF_CUSTOM_FIELD",
"USER_TYPE_ID": "string",
"LABEL": "Пользовательское поле",
"MANDATORY": "N"
}
}

Работа с повторяющимися активностями

Для создания повторяющихся задач и встреч используйте поле CALENDAR_EVENT_ID:

{
"fields": {
"CALENDAR_EVENT_ID": "123",
"RRULE": "FREQ=WEEKLY;BYDAY=MO,WE,FR"
}
}

Мониторинг и аналитика

Отслеживание изменений

Для отслеживания изменений в активностях используйте методы timeline:

GET /rest/crm.timeline.list?filter[ENTITY_TYPE_ID]=25&filter[ENTITY_ID]=123

Статистика по активностям

Получение статистики по типам и статусам активностей:

// Группировка по типам
GET /rest/crm.activity.list?filter[OWNER_TYPE_ID]=2&select[]=TYPE_ID&order[TYPE_ID]=ASC
// Группировка по статусам
GET /rest/crm.activity.list?filter[OWNER_TYPE_ID]=2&select[]=COMPLETED&order[COMPLETED]=ASC

Заключение

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

Основные преимущества использования REST API активностей:

• Автоматизация рутинных задач - создание напоминаний, уведомлений и задач
• Интеграция с внешними системами - синхронизация с календарями, CRM и другими сервисами
• Персонализация рабочих процессов - создание пользовательских типов активностей
• Улучшение отчетности - детальная аналитика по активностям и сотрудникам
• Повышение продуктивности - автоматическое распределение задач и контроль выполнения

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