Работа с timestamp и datetime в Битрикс24 в 2025: инструкция

Работа с временными метками и датами является критически важным аспектом при разработке интеграций с Битрикс24. Правильное понимание форматов timestamp и datetime поможет вам избежать ошибок при синхронизации данных, создании отчетов и автоматизации бизнес-процессов. В этой статье мы рассмотрим все нюансы работы с временными форматами в Битрикс24, включая практические примеры и рекомендации.

Что такое timestamp и datetime в контексте Битрикс24

В системе Битрикс24 используются два основных формата для представления времени:

• Timestamp — числовое значение, представляющее количество секунд, прошедших с 1 января 1970 года (Unix время)
• Datetime — строковое представление даты и времени в формате ISO 8601 или других стандартных форматах

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

Форматы timestamp в Битрикс24

Unix timestamp

Битрикс24 использует стандартный Unix timestamp для многих операций. Этот формат представляет собой целое число секунд:

Пример: 1704067200 соответствует 1 января 2024 года, 00:00:00 UTC

Миллисекунды в timestamp

В некоторых случаях Битрикс24 может использовать timestamp с миллисекундами, особенно при работе с веб-хуками и событиями реального времени:

Пример: 1704067200000 (добавлены три нуля для миллисекунд)

Форматы datetime в Битрикс24

ISO 8601 формат

Основной формат datetime в Битрикс24 соответствует стандарту ISO 8601:

Формат: YYYY-MM-DDTHH:MM:SS+TZ

Пример: 2024-01-01T12:00:00+03:00

Упрощенный формат

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

Формат: YYYY-MM-DD HH:MM:SS

Пример: 2024-01-01 12:00:00

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

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

• UTC — используется для внутренних расчетов системы
• Локальная зона — зона пользователя или портала
• Явное указание — в формате +03:00 или -05:00

Настройка временной зоны портала

Временная зона портала влияет на отображение всех дат для пользователей. Проверить текущую настройку можно через:

Настройки → Общие настройки → Региональные настройки

API методы для работы с датами

Получение данных с датами

При запросе данных через REST API Битрикс24 возвращает даты в различных форматах в зависимости от типа поля:

Пример ответа API:

{
"DATE_CREATE": "2024-01-01T12:00:00+03:00",
"DATE_MODIFY": "1704067200",
"UF_CUSTOM_DATE": "2024-01-01 12:00:00"
}

Отправка данных с датами

При создании или обновлении записей важно использовать правильный формат:

• Для полей типа datetime используйте ISO 8601
• Для полей типа date используйте формат YYYY-MM-DD
• Для пользовательских полей проверьте требуемый формат

Практические примеры работы с датами

Конвертация timestamp в datetime

Для конвертации Unix timestamp в читаемый формат используйте следующие подходы:

JavaScript:

const timestamp = 1704067200;
const date = new Date(timestamp * 1000);
const isoString = date.toISOString();
console.log(isoString); // 2024-01-01T00:00:00.000Z

PHP:

$timestamp = 1704067200;
$date = new DateTime("@$timestamp");
$date->setTimezone(new DateTimeZone('Europe/Moscow'));
echo $date->format('Y-m-d\TH:i:sP'); // 2024-01-01T03:00:00+03:00

Фильтрация по датам в API

При использовании фильтров в API Битрикс24 можно применять различные операторы для дат:

• >= — больше или равно
• <= — меньше или равно
• > — больше
• < — меньше

Пример фильтра:

filter: {
">=DATE_CREATE": "2024-01-01T00:00:00+03:00",
"<=DATE_CREATE": "2024-01-31T23:59:59+03:00"
}

Особенности работы с датами в разных модулях

CRM модуль

В CRM даты создания и изменения записей хранятся в формате ISO 8601:

• DATE_CREATE — дата создания
• DATE_MODIFY — дата изменения
• CLOSEDATE — дата закрытия сделки

Задачи и проекты

В модуле задач используются следующие поля с датами:

• CREATED_DATE — дата создания задачи
• DEADLINE — срок выполнения
• START_DATE_PLAN — планируемая дата начала
• END_DATE_PLAN — планируемая дата окончания

Календарь и события

События календаря имеют специфические поля для работы с датами:

• DATE_FROM — дата начала события
• DATE_TO — дата окончания события
• DT_SKIP_TIME — флаг события на весь день

Обработка ошибок при работе с датами

Типичные ошибки

При работе с датами в Битрикс24 часто возникают следующие ошибки:

• Неправильный формат — использование некорректного формата даты
• Временная зона — игнорирование временной зоны
• Валидация — отправка некорректных дат

Валидация дат

Перед отправкой данных в API всегда проверяйте корректность формата:

Пример валидации в JavaScript:

function validateDateTime(dateString) {
const date = new Date(dateString);
return date instanceof Date && !isNaN(date);
}

Лучшие практики работы с датами

Рекомендации по форматированию

1. Всегда указывайте временную зону при работе с datetime
2. Используйте ISO 8601 для максимальной совместимости
3. Валидируйте даты перед отправкой в API
4. Учитывайте локальные настройки пользователей

Работа с пользовательскими полями

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

• Тип поля влияет на формат хранения
• Настройки отображения для пользователей
• Возможность использования в отчетах

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

Синхронизация данных

При интеграции с внешними системами важно обеспечить корректную передачу временных меток:

• Маппинг форматов — соответствие между системами
• Обработка временных зон — конвертация в нужный формат
• Валидация данных — проверка корректности

Веб-хуки и события

При работе с веб-хуками Битрикс24 передает временные метки в стандартном формате:

{
"event": "ONCRMLEADADD",
"data": {
"FIELDS": {
"DATE_CREATE": "2024-01-01T12:00:00+03:00"
}
},
"ts": 1704067200,
"auth": {...}
}

Отладка и тестирование

Инструменты для отладки

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

• Консоль разработчика в браузере
• Postman для тестирования API
• Логи сервера для отслеживания ошибок

Тестовые сценарии

Обязательно тестируйте следующие сценарии:

• Создание записей с различными форматами дат
• Фильтрация по датам
• Работа с разными временными зонами
• Обработка граничных случаев

Обновления и изменения в API

Битрикс24 регулярно обновляет API, что может повлиять на работу с датами:

• Следите за документацией API
• Тестируйте изменения в тестовой среде
• Используйте версионирование для критичных интеграций

Заключение

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

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

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