#Таймлайн CRM

12 REST-эндпоинтов для журналирования действий в таймлайне CRM-сущностей: создание лог-записей, заметки к ним, закрепление, привязка к нескольким сущностям одновременно. Удобно для AI-агентов, фоновых интеграций и автоматизации, которым нужно оставлять структурированный след в карточке сделки или контакта.

Скоуп: crm | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key

Быстрый старт | AI-агент логирует свои действия (полный пример) | Коды ошибок | Справочник эндпоинтов

#Разделы документации

• Записи журнала — создание, просмотр, удаление лог-записей
• Заметки — заметка-комментарий к лог-записи
• Закрепления — закрепить или открепить запись в верхней части таймлайна
• Привязки — связать одну запись с несколькими сущностями CRM

#Когда использовать

• Записать действие AI-агента: проанализировал клиента, подготовил коммерческое предложение, отправил уведомление.
• Зафиксировать событие из внешней системы: оплата прошла, заказ собран, документ подписан.
• Создать аудиторский след интеграции: какие данные обработала, на основании чего приняла решение.
• Закрепить ключевое событие сделки в верхней части таймлайна, чтобы менеджер сразу видел контекст.

Для текстовых комментариев пользователя (не системных событий) используйте `/v1/timelines` — это отдельный API над crm.timeline.comment.*.

#Быстрый старт

#1. Создайте запись в таймлайне сделки

curl -X POST https://vibecode.bitrix24.tech/v1/timeline-logs \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityTypeId": 2,
    "entityId": 100,
    "title": "AI-агент обработал заявку",
    "text": "Проанализированы данные клиента. Рекомендация: предложить тариф Enterprise."
  }'

Ответ:

{
  "success": true,
  "data": {
    "id": 5012,
    "created": "2026-04-27T10:00:00+03:00",
    "authorId": 1,
    "title": "AI-агент обработал заявку",
    "text": "Проанализированы данные клиента. Рекомендация: предложить тариф Enterprise.",
    "iconCode": ""
  }
}

#2. Закрепите запись в верхней части таймлайна

curl -X POST https://vibecode.bitrix24.tech/v1/timeline-logs/5012/pin \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "entityTypeId": 2, "entityId": 100 }'

#3. Прикрепите внутреннюю заметку

curl -X POST https://vibecode.bitrix24.tech/v1/timeline-logs/5012/note \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "entityTypeId": 2, "entityId": 100, "text": "Клиент обычно отвечает в течение 2 дней." }'

#Полный пример: AI-агент логирует свои действия

Сценарий: AI-агент анализирует сделку, оставляет лог-запись с результатом, привязывает её к контакту и компании, прикрепляет заметку для менеджера, закрепляет в таймлайне.

const VIBE_KEY = process.env.VIBE_KEY
const BASE = 'https://vibecode.bitrix24.tech/v1'

async function api(method, path, body = null) {
  const opts = { method, headers: { 'X-Api-Key': VIBE_KEY } }
  if (body) {
    opts.headers['Content-Type'] = 'application/json'
    opts.body = JSON.stringify(body)
  }
  const res = await fetch(`${BASE}${path}`, opts)
  return res.json()
}

const dealId = 100
const contactId = 50
const companyId = 10

// 1. Записать факт начала работы
const start = await api('POST', '/timeline-logs', {
  entityTypeId: 2,
  entityId: dealId,
  title: 'AI-агент начал обработку',
  text: 'Анализ данных клиента, проверка кредитного лимита, подготовка предложения.',
})
const startId = start.data.id

// 2. Связать запись с контактом и компанией — менеджеры обоих увидят
//    то же событие в своих таймлайнах
await api('POST', `/timeline-logs/${startId}/bind`, { entityTypeId: 3, entityId: contactId })
await api('POST', `/timeline-logs/${startId}/bind`, { entityTypeId: 4, entityId: companyId })

// ... AI-агент выполняет работу ...

// 3. Записать результат отдельной лог-записью
const result = await api('POST', '/timeline-logs', {
  entityTypeId: 2,
  entityId: dealId,
  title: 'AI-агент завершил обработку',
  text: [
    '[b]Результаты анализа:[/b]',
    '- Кредитный лимит: OK (500 000 руб.)',
    '- Рекомендованный тариф: Enterprise',
    '- Скидка: 10% (постоянный клиент)',
    '- КП сформировано и отправлено на email',
  ].join('\n'),
})
const resultId = result.data.id

// 4. Закрепить итоговую запись в верхней части таймлайна
await api('POST', `/timeline-logs/${resultId}/pin`, { entityTypeId: 2, entityId: dealId })

// 5. Оставить внутреннюю заметку для менеджера
await api('POST', `/timeline-logs/${resultId}/note`, {
  entityTypeId: 2,
  entityId: dealId,
  text: 'Клиент обычно отвечает в течение 2 дней. Напомнить менеджеру, если нет ответа.',
})

console.log('AI-агент завершил работу, все действия залогированы')

#Какой ключ использовать

CRUD-операции работают с любым типом ключа — личным (vibe_api_*) или OAuth-приложением (vibe_app_*). Однако DELETE /v1/timeline-logs/:id накладывает ограничение: Битрикс24 разрешает удалить лог-запись только тому же приложению, которое её создало.

• OAuth-приложение (vibe_app_* + Authorization: Bearer ...) — стабильное client_id, удалить свои записи можно. Если планируете удалять созданные записи через API, используйте этот тип ключа.
• Личный ключ (vibe_api_*) — Вайбкод ротирует токены между вызовами, для Битрикс24 каждый вызов выглядит как отдельное приложение. DELETE всегда возвращает 403 CROSS_APP_DELETE_FORBIDDEN, в том числе на свежесозданные записи.

Если приложение, создавшее запись, недоступно — удалить её нельзя в принципе. Битрикс24 не предоставляет UI-кнопку удаления log-записи в карточке сущности. Учитывайте это при проектировании сценариев аудита.

Подробнее — Удалить запись.

#Типы родительских сущностей

Параметр entityTypeId (числовой код CRM-сущности) указывает, в чьём таймлайне создаётся запись:

В привязках (bind/unbind) можно использовать как числовой entityTypeId, так и строковый entityType напрямую ("deal", "contact", "dynamic_174" и т. п.) — см. Привязать запись.

#Коды ошибок

#Ошибки таймлайна

#Системные ошибки

Полный список общих кодов API — Ошибки.

#Справочник эндпоинтов

Все 12 эндпоинтов:

#Смотрите также

• Комментарии таймлайна — текстовые комментарии пользователя (отдельный API на crm.timeline.comment.*)
• Сделки, Лиды, Контакты, Компании — типичные родительские сущности
• Смарт-процессы — для записей в таймлайне пользовательских CRM-типов
• Batch — массовые операции
• Лимиты и оптимизация — rate limits