Битрикс24 API календарь в 2025: инструкция по интеграции и настройке

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

Основы работы с API календаря Битрикс24

API календаря Битрикс24 предоставляет разработчикам мощный инструмент для создания, редактирования и управления событиями календаря. Основные возможности включают:

• Создание и редактирование событий — добавление новых встреч, задач и мероприятий
• Управление участниками — приглашение сотрудников и внешних участников
• Синхронизация данных — обмен информацией с внешними календарными системами
• Настройка уведомлений — автоматическая отправка напоминаний
• Анализ занятости — проверка доступности участников

Аутентификация и подключение к API

Для работы с API календаря необходимо получить токен доступа. Битрикс24 поддерживает несколько способов аутентификации:

OAuth 2.0 аутентификация

Наиболее безопасный и рекомендуемый способ подключения:

// Получение токена доступа
$clientId = 'your_client_id';
$clientSecret = 'your_client_secret';
$redirectUri = 'https://your-site.com/callback';
$authUrl = 'https://your-portal.bitrix24.com/oauth/authorize/?' .
'client_id=' . $clientId .
'&redirect_uri=' . urlencode($redirectUri) .
'&response_type=code';

Webhook подключение

Для быстрого тестирования можно использовать входящие вебхуки:

$webhookUrl = 'https://your-portal.bitrix24.com/rest/user_id/webhook_code/';
$method = 'calendar.event.get';
$params = array('id' => 123);
$response = file_get_contents($webhookUrl . $method . '?' . http_build_query($params));

Основные методы API календаря

calendar.event.add — создание события

Метод позволяет создать новое событие в календаре:

$params = array(
'type' => 'user',
'ownerId' => 1,
'name' => 'Встреча с клиентом',
'description' => 'Обсуждение условий контракта',
'from' => '2025-01-15T10:00:00',
'to' => '2025-01-15T11:00:00',
'attendees' => array(2, 3, 4),
'location' => 'Офис, переговорная №1',
'remind' => array(
array('type' => 'min', 'count' => 15),
array('type' => 'min', 'count' => 60)
)
);
$result = callBitrix24Api('calendar.event.add', $params);

calendar.event.get — получение события

Метод возвращает подробную информацию о событии:

$params = array('id' => 123);
$event = callBitrix24Api('calendar.event.get', $params);
echo 'Название: ' . $event['result']['name'];
echo 'Дата: ' . $event['result']['date_from'];
echo 'Участники: ' . implode(', ', $event['result']['attendees']);

calendar.event.update — обновление события

Редактирование существующего события:

$params = array(
'id' => 123,
'name' => 'Обновленное название встречи',
'from' => '2025-01-15T11:00:00',
'to' => '2025-01-15T12:00:00',
'attendees' => array(2, 3, 4, 5)
);
$result = callBitrix24Api('calendar.event.update', $params);

calendar.event.delete — удаление события

Удаление события из календаря:

$params = array('id' => 123);
$result = callBitrix24Api('calendar.event.delete', $params);

Работа с различными типами календарей

Пользовательские календари

Для работы с личными календарями сотрудников используется тип ‘user’:

$params = array(
'type' => 'user',
'ownerId' => 1, // ID пользователя
'from' => '2025-01-01',
'to' => '2025-01-31'
);
$events = callBitrix24Api('calendar.event.get', $params);

Групповые календари

Календари рабочих групп и проектов:

$params = array(
'type' => 'group',
'ownerId' => 5, // ID группы
'name' => 'Планерка команды разработки',
'from' => '2025-01-16T09:00:00',
'to' => '2025-01-16T10:00:00'
);
$result = callBitrix24Api('calendar.event.add', $params);

Календари компании

Общие корпоративные события:

$params = array(
'type' => 'company',
'ownerId' => 0,
'name' => 'Общее собрание',
'from' => '2025-01-20T14:00:00',
'to' => '2025-01-20T16:00:00',
'accessibility' => 'busy'
);
$result = callBitrix24Api('calendar.event.add', $params);

Управление участниками и приглашениями

Добавление участников

При создании события можно указать список участников:

$params = array(
'type' => 'user',
'ownerId' => 1,
'name' => 'Встреча отдела продаж',
'from' => '2025-01-17T15:00:00',
'to' => '2025-01-17T16:00:00',
'attendees' => array(2, 3, 4, 5), // ID участников
'host' => 1, // Организатор встречи
'meeting' => array(
'notify' => true, // Отправить уведомления
'reinvite' => false // Не отправлять повторные приглашения
)
);
$result = callBitrix24Api('calendar.event.add', $params);

Проверка доступности участников

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

$params = array(
'users' => array(1, 2, 3),
'from' => '2025-01-18T09:00:00',
'to' => '2025-01-18T18:00:00'
);
$accessibility = callBitrix24Api('calendar.accessibility.get', $params);

Настройка уведомлений и напоминаний

Типы напоминаний

Битрикс24 поддерживает различные типы напоминаний:

$reminders = array(
array('type' => 'min', 'count' => 5),    // За 5 минут
array('type' => 'min', 'count' => 30),   // За 30 минут
array('type' => 'hour', 'count' => 2),   // За 2 часа
array('type' => 'day', 'count' => 1),    // За 1 день
array('type' => 'week', 'count' => 1)    // За 1 неделю
);
$params = array(
'type' => 'user',
'ownerId' => 1,
'name' => 'Важная встреча',
'from' => '2025-01-19T10:00:00',
'to' => '2025-01-19T11:00:00',
'remind' => $reminders
);
$result = callBitrix24Api('calendar.event.add', $params);

Настройка email-уведомлений

Управление отправкой уведомлений по электронной почте:

$params = array(
'type' => 'user',
'ownerId' => 1,
'name' => 'Презентация проекта',
'from' => '2025-01-21T14:00:00',
'to' => '2025-01-21T15:30:00',
'meeting' => array(
'notify' => true,
'hideGuests' => false,
'allowInvite' => true
)
);
$result = callBitrix24Api('calendar.event.add', $params);

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

Интеграция с Google Calendar

Пример синхронизации событий с Google Calendar:

function syncWithGoogleCalendar($bitrix24Event) {
$googleClient = new Google_Client();
$googleClient->setAccessToken($googleAccessToken);
$calendarService = new Google_Service_Calendar($googleClient);
$googleEvent = new Google_Service_Calendar_Event();
$googleEvent->setSummary($bitrix24Event['name']);
$googleEvent->setDescription($bitrix24Event['description']);
$start = new Google_Service_Calendar_EventDateTime();
$start->setDateTime($bitrix24Event['date_from']);
$googleEvent->setStart($start);
$end = new Google_Service_Calendar_EventDateTime();
$end->setDateTime($bitrix24Event['date_to']);
$googleEvent->setEnd($end);
$calendarService->events->insert('primary', $googleEvent);
}

Экспорт в формат iCal

Создание iCal файла для импорта в другие календарные приложения:

function exportToICal($events) {
$ical = "BEGIN:VCALENDAR\r\n";
$ical .= "VERSION:2.0\r\n";
$ical .= "PRODID:-//Bitrix24//Calendar//EN\r\n";
foreach ($events as $event) {
$ical .= "BEGIN:VEVENT\r\n";
$ical .= "UID:" . $event['id'] . "@bitrix24.com\r\n";
$ical .= "DTSTAMP:" . gmdate('Ymd\THis\Z') . "\r\n";
$ical .= "DTSTART:" . date('Ymd\THis\Z', strtotime($event['date_from'])) . "\r\n";
$ical .= "DTEND:" . date('Ymd\THis\Z', strtotime($event['date_to'])) . "\r\n";
$ical .= "SUMMARY:" . $event['name'] . "\r\n";
$ical .= "DESCRIPTION:" . $event['description'] . "\r\n";
$ical .= "END:VEVENT\r\n";
}
$ical .= "END:VCALENDAR\r\n";
return $ical;
}

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

Создание регулярных событий

Настройка повторяющихся событий с различными интервалами:

$params = array(
'type' => 'user',
'ownerId' => 1,
'name' => 'Еженедельная планерка',
'from' => '2025-01-20T09:00:00',
'to' => '2025-01-20T10:00:00',
'rrule' => array(
'freq' => 'weekly',
'interval' => 1,
'byday' => array('MO'), // Понедельник
'until' => '2025-12-31T23:59:59'
)
);
$result = callBitrix24Api('calendar.event.add', $params);

Различные типы повторений

Примеры настройки различных типов повторяющихся событий:

// Ежедневно в рабочие дни
$dailyWorkdays = array(
'freq' => 'daily',
'interval' => 1,
'byday' => array('MO', 'TU', 'WE', 'TH', 'FR')
);
// Ежемесячно в первый понедельник
$monthlyFirstMonday = array(
'freq' => 'monthly',
'interval' => 1,
'byday' => array('1MO')
);
// Ежегодно
$yearly = array(
'freq' => 'yearly',
'interval' => 1,
'bymonth' => 1,
'bymonthday' => 15
);

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

Типичные ошибки и их решения

При работе с API календаря могут возникать различные ошибки. Рассмотрим наиболее частые:

• ACCESS_DENIED — недостаточно прав доступа
• INVALID_DATETIME — некорректный формат даты
• EVENT_NOT_FOUND — событие не найдено
• CALENDAR_NOT_FOUND — календарь не существует

function handleBitrix24Error($response) {
if (isset($response['error'])) {
switch ($response['error']) {
case 'ACCESS_DENIED':
error_log('Недостаточно прав для выполнения операции');
break;
case 'INVALID_DATETIME':
error_log('Некорректный формат даты: ' . $response['error_description']);
break;
case 'EVENT_NOT_FOUND':
error_log('Событие не найдено');
break;
default:
error_log('Ошибка API: ' . $response['error_description']);
}
return false;
}
return true;
}

Логирование и мониторинг

Для отладки рекомендуется вести подробные логи взаимодействия с API:

function logApiRequest($method, $params, $response) {
$logEntry = array(
'timestamp' => date('Y-m-d H:i:s'),
'method' => $method,
'params' => $params,
'response' => $response,
'success' => !isset($response['error'])
);
file_put_contents('bitrix24_api.log', json_encode($logEntry) . "\n", FILE_APPEND);
}

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

Автоматическое создание встреч из CRM

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

function createMeetingFromDeal($dealId) {
// Получаем данные сделки
$dealData = callBitrix24Api('crm.deal.get', array('id' => $dealId));
if (!$dealData['result']) {
return false;
}
$deal = $dealData['result'];
// Создаем встречу
$meetingParams = array(
'type' => 'user',
'ownerId' => $deal['ASSIGNED_BY_ID'],
'name' => 'Встреча по сделке: ' . $deal['TITLE'],
'description' => 'Обсуждение сделки ' . $deal['TITLE'] . ' на сумму ' . $deal['OPPORTUNITY'],
'from' => date('Y-m-d\TH:i:s', strtotime('+1 day 10:00')),
'to' => date('Y-m-d\TH:i:s', strtotime('+1 day 11:00')),
'attendees' => array($deal['ASSIGNED_BY_ID'])
);
$result = callBitrix24Api('calendar.event.add', $meetingParams);
// Привязываем встречу к сделке
if ($result['result']) {
$activityParams = array(
'fields' => array(
'OWNER_TYPE_ID' => 2, // Сделка
'OWNER_ID' => $dealId,
'TYPE_ID' => 1, // Встреча
'SUBJECT' => 'Встреча по сделке: ' . $deal['TITLE'],
'CALENDAR_EVENT_ID' => $result['result']['id']
)
);
callBitrix24Api('crm.activity.add', $activityParams);
}
return $result;
}

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

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

function bookMeetingRoom($roomId, $dateFrom, $dateTo, $userId, $purpose) {
// Проверяем доступность комнаты
$checkParams = array(
'type' => 'location',
'ownerId' => $roomId,
'from' => $dateFrom,
'to' => $dateTo
);
$existingEvents = callBitrix24Api('calendar.event.get', $checkParams);
if (!empty($existingEvents['result'])) {
return array('error' => 'Переговорная занята в указанное время');
}
// Бронируем комнату
$bookingParams = array(
'type' => 'location',
'ownerId' => $roomId,
'name' => 'Бронирование: ' . $purpose,
'from' => $dateFrom,
'to' => $dateTo,
'attendees' => array($userId),
'location' => getRoomName($roomId)
);
$result = callBitrix24Api('calendar.event.add', $bookingParams);
if ($result['result']) {
// Отправляем уведомление
sendBookingNotification($userId, $roomId, $dateFrom, $dateTo);
}
return $result;
}

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

Пакетные операции

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

function batchCreateEvents($events) {
$batchCommands = array();
foreach ($events as $key => $event) {
$batchCommands['event_' . $key] = array(
'method' => 'calendar.event.add',
'params' => $event
);
}
$params = array(
'halt' => 0, // Не останавливаться при ошибке
'cmd' => $batchCommands
);
$result = callBitrix24Api('batch', $params);
return $result;
}

Кэширование данных

Реализация кэширования для уменьшения количества API-запросов:

class Bitrix24CalendarCache {
private $cacheDir = 'cache/';
private $cacheTtl = 300; // 5 минут
public function getCachedEvents($userId, $dateFrom, $dateTo) {
$cacheKey = md5($userId . $dateFrom . $dateTo);
$cacheFile = $this->cacheDir . $cacheKey . '.json';
if (file_exists($cacheFile) &&
(time() - filemtime($cacheFile)) < $this->cacheTtl) {
return json_decode(file_get_contents($cacheFile), true);
}
// Загружаем данные из API
$params = array(
'type' => 'user',
'ownerId' => $userId,
'from' => $dateFrom,
'to' => $dateTo
);
$events = callBitrix24Api('calendar.event.get', $params);
// Сохраняем в кэш
file_put_contents($cacheFile, json_encode($events));
return $events;
}
}

Безопасность и права доступа

Управление правами доступа

При работе с API необходимо учитывать права доступа пользователей:

function checkCalendarPermissions($userId, $calendarType, $calendarId) {
$permissions = callBitrix24Api('calendar.permissions.get', array(
'type' => $calendarType,
'ownerId' => $calendarId,
'userId' => $userId
));
if (!$permissions['result']) {
return false;
}
return array(
'view' => $permissions['result']['view'],
'edit' => $permissions['result']['edit'],
'delete' => $permissions['result']['delete']
);
}

Валидация данных

Всегда проверяйте входящие данные перед отправкой в API:

function validateEventData($eventData) {
$errors = array();
// Проверка обязательных полей
if (empty($eventData['name'])) {
$errors[] = 'Название события обязательно';
}
if (empty($eventData['from']) || empty($eventData['to'])) {
$errors[] = 'Дата и время начала и окончания обязательны';
}
// Проверка формата даты
if (!DateTime::createFromFormat('Y-m-d\TH:i:s', $eventData['from'])) {
$errors[] = 'Некорректный формат даты начала';
}
if (!DateTime::createFromFormat('Y-m-d\TH:i:s', $eventData['to'])) {
$errors[] = 'Некорректный формат даты окончания';
}
// Проверка логики дат
if (strtotime($eventData['from']) >= strtotime($eventData['to'])) {
$errors[] = 'Дата окончания должна быть позже даты начала';
}
return $errors;
}

Мобильная разработка и API

Адаптация для мобильных приложений

При разработке мобильных приложений учитывайте особенности работы с API:

// Пример для React Native
class Bitrix24CalendarAPI {
constructor(webhookUrl) {
this.webhookUrl = webhookUrl;
}
async getEvents(userId, dateFrom, dateTo) {
try {
const params = {
type: 'user',
ownerId: userId,
from: dateFrom,
to: dateTo
};
const response = await fetch(
`${this.webhookUrl}calendar.event.get`,
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(params)
}
);
const data = await response.json();
return data.result || [];
} catch (error) {
console.error('Ошибка получения событий:', error);
return [];
}
}
async createEvent(eventData) {
try {
const response = await fetch(
`${this.webhookUrl}calendar.event.add`,
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(eventData)
}
);
const data = await response.json();
return data.result;
} catch (error) {
console.error('Ошибка создания события:', error);
return null;
}
}
}

Заключение

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

Ключевые моменты при работе с API календаря:

• Правильная аутентификация — используйте OAuth 2.0 для продакшн-приложений
• Обработка ошибок — всегда проверяйте ответы API и обрабатывайте исключения
• Оптимизация производительности — используйте пакетные операции и кэширование
• Безопасность — валидируйте входящие данные и учитывайте права доступа
• Мониторинг — ведите логи для отладки и анализа работы интеграции

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