[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-timeline-logs":3,"docs-tabs-timeline-logs":6},{"content":4,"lastmod":5},"\n# Таймлайн CRM\n\n12 REST-эндпоинтов для журналирования действий в таймлайне CRM-сущностей: создание лог-записей, заметки к ним, закрепление, привязка к нескольким сущностям одновременно. Удобно для AI-агентов, фоновых интеграций и автоматизации, которым нужно оставлять структурированный след в карточке сделки или контакта.\n\n**Скоуп:** `crm` | **Базовый URL:** `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1` | **Авторизация:** `X-Api-Key`\n\n[Быстрый старт](#быстрый-старт) | [AI-агент логирует свои действия (полный пример)](#полный-пример-ai-агент-логирует-свои-действия) | [Коды ошибок](#коды-ошибок) | [Справочник эндпоинтов](#справочник-эндпоинтов)\n\n## Разделы документации\n\n- [Записи журнала](\u002Fdocs\u002Ftimeline-logs\u002Flogs) — создание, просмотр, удаление лог-записей\n- [Заметки](\u002Fdocs\u002Ftimeline-logs\u002Fnotes) — заметка-комментарий к лог-записи\n- [Закрепления](\u002Fdocs\u002Ftimeline-logs\u002Fpins) — закрепить или открепить запись в верхней части таймлайна\n- [Привязки](\u002Fdocs\u002Ftimeline-logs\u002Fbindings) — связать одну запись с несколькими сущностями CRM\n\n## Когда использовать\n\n- Записать действие AI-агента: проанализировал клиента, подготовил коммерческое предложение, отправил уведомление.\n- Зафиксировать событие из внешней системы: оплата прошла, заказ собран, документ подписан.\n- Создать аудиторский след интеграции: какие данные обработала, на основании чего приняла решение.\n- Закрепить ключевое событие сделки в верхней части таймлайна, чтобы менеджер сразу видел контекст.\n\nДля текстовых комментариев пользователя (не системных событий) используйте [`\u002Fv1\u002Ftimelines`](\u002Fdocs\u002Fentities\u002Ftimelines) — это отдельный API над `crm.timeline.comment.*`.\n\n## Быстрый старт\n\n### 1. Создайте запись в таймлайне сделки\n\n```bash\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftimeline-logs \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"entityTypeId\": 2,\n    \"entityId\": 100,\n    \"title\": \"AI-агент обработал заявку\",\n    \"text\": \"Проанализированы данные клиента. Рекомендация: предложить тариф Enterprise.\"\n  }'\n```\n\nОтвет:\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 5012,\n    \"created\": \"2026-04-27T10:00:00+03:00\",\n    \"authorId\": 1,\n    \"title\": \"AI-агент обработал заявку\",\n    \"text\": \"Проанализированы данные клиента. Рекомендация: предложить тариф Enterprise.\",\n    \"iconCode\": \"\"\n  }\n}\n```\n\n### 2. Закрепите запись в верхней части таймлайна\n\n```bash\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftimeline-logs\u002F5012\u002Fpin \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{ \"entityTypeId\": 2, \"entityId\": 100 }'\n```\n\n### 3. Прикрепите внутреннюю заметку\n\n```bash\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftimeline-logs\u002F5012\u002Fnote \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{ \"entityTypeId\": 2, \"entityId\": 100, \"text\": \"Клиент обычно отвечает в течение 2 дней.\" }'\n```\n\n## Полный пример: AI-агент логирует свои действия\n\nСценарий: AI-агент анализирует сделку, оставляет лог-запись с результатом, привязывает её к контакту и компании, прикрепляет заметку для менеджера, закрепляет в таймлайне.\n\n```javascript\nconst VIBE_KEY = process.env.VIBE_KEY\nconst BASE = 'https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1'\n\nasync function api(method, path, body = null) {\n  const opts = { method, headers: { 'X-Api-Key': VIBE_KEY } }\n  if (body) {\n    opts.headers['Content-Type'] = 'application\u002Fjson'\n    opts.body = JSON.stringify(body)\n  }\n  const res = await fetch(`${BASE}${path}`, opts)\n  return res.json()\n}\n\nconst dealId = 100\nconst contactId = 50\nconst companyId = 10\n\n\u002F\u002F 1. Записать факт начала работы\nconst start = await api('POST', '\u002Ftimeline-logs', {\n  entityTypeId: 2,\n  entityId: dealId,\n  title: 'AI-агент начал обработку',\n  text: 'Анализ данных клиента, проверка кредитного лимита, подготовка предложения.',\n})\nconst startId = start.data.id\n\n\u002F\u002F 2. Связать запись с контактом и компанией — менеджеры обоих увидят\n\u002F\u002F    то же событие в своих таймлайнах\nawait api('POST', `\u002Ftimeline-logs\u002F${startId}\u002Fbind`, { entityTypeId: 3, entityId: contactId })\nawait api('POST', `\u002Ftimeline-logs\u002F${startId}\u002Fbind`, { entityTypeId: 4, entityId: companyId })\n\n\u002F\u002F ... AI-агент выполняет работу ...\n\n\u002F\u002F 3. Записать результат отдельной лог-записью\nconst result = await api('POST', '\u002Ftimeline-logs', {\n  entityTypeId: 2,\n  entityId: dealId,\n  title: 'AI-агент завершил обработку',\n  text: [\n    '[b]Результаты анализа:[\u002Fb]',\n    '- Кредитный лимит: OK (500 000 руб.)',\n    '- Рекомендованный тариф: Enterprise',\n    '- Скидка: 10% (постоянный клиент)',\n    '- КП сформировано и отправлено на email',\n  ].join('\\n'),\n})\nconst resultId = result.data.id\n\n\u002F\u002F 4. Закрепить итоговую запись в верхней части таймлайна\nawait api('POST', `\u002Ftimeline-logs\u002F${resultId}\u002Fpin`, { entityTypeId: 2, entityId: dealId })\n\n\u002F\u002F 5. Оставить внутреннюю заметку для менеджера\nawait api('POST', `\u002Ftimeline-logs\u002F${resultId}\u002Fnote`, {\n  entityTypeId: 2,\n  entityId: dealId,\n  text: 'Клиент обычно отвечает в течение 2 дней. Напомнить менеджеру, если нет ответа.',\n})\n\nconsole.log('AI-агент завершил работу, все действия залогированы')\n```\n\n## Какой ключ использовать\n\nCRUD-операции работают с любым типом ключа — личным (`vibe_api_*`) или OAuth-приложением (`vibe_app_*`). Однако **`DELETE \u002Fv1\u002Ftimeline-logs\u002F:id` накладывает ограничение**: Битрикс24 разрешает удалить лог-запись только тому же приложению, которое её создало.\n\n- **OAuth-приложение** (`vibe_app_*` + `Authorization: Bearer ...`) — стабильное `client_id`, удалить свои записи можно. Если планируете удалять созданные записи через API, используйте этот тип ключа.\n- **Личный ключ** (`vibe_api_*`) — Вайбкод ротирует токены между вызовами, для Битрикс24 каждый вызов выглядит как отдельное приложение. `DELETE` всегда возвращает `403 CROSS_APP_DELETE_FORBIDDEN`, в том числе на свежесозданные записи.\n\nЕсли приложение, создавшее запись, недоступно — удалить её нельзя в принципе. Битрикс24 не предоставляет UI-кнопку удаления log-записи в карточке сущности. Учитывайте это при проектировании сценариев аудита.\n\nПодробнее — [Удалить запись](\u002Fdocs\u002Ftimeline-logs\u002Flogs\u002Fdelete).\n\n## Типы родительских сущностей\n\nПараметр `entityTypeId` (числовой код CRM-сущности) указывает, в чьём таймлайне создаётся запись:\n\n| `entityTypeId` | Сущность | Где найти ID |\n|:---:|----------|--------------|\n| 1 | Лид | [`GET \u002Fv1\u002Fleads`](\u002Fdocs\u002Fentities\u002Fleads\u002Flist) |\n| 2 | Сделка | [`GET \u002Fv1\u002Fdeals`](\u002Fdocs\u002Fentities\u002Fdeals\u002Flist) |\n| 3 | Контакт | [`GET \u002Fv1\u002Fcontacts`](\u002Fdocs\u002Fentities\u002Fcontacts) |\n| 4 | Компания | [`GET \u002Fv1\u002Fcompanies`](\u002Fdocs\u002Fentities\u002Fcompanies) |\n| 7 | Предложение | [`GET \u002Fv1\u002Fquotes`](\u002Fdocs\u002Fentities\u002Fquotes) |\n| 14 | Заказ | [`GET \u002Fv1\u002Forders`](\u002Fdocs\u002Fentities\u002Forders) |\n| 31 | Счёт | [`GET \u002Fv1\u002Finvoices`](\u002Fdocs\u002Fentities\u002Finvoices) |\n| ≥ 128 | Смарт-процесс | [`GET \u002Fv1\u002Fitems\u002F:entityTypeId`](\u002Fdocs\u002Fentities\u002Fitems\u002Flist); список процессов — [`GET \u002Fv1\u002Fsmart-processes`](\u002Fdocs\u002Fentities\u002Fsmart-processes\u002Flist) |\n\nВ привязках (`bind`\u002F`unbind`) можно использовать как числовой `entityTypeId`, так и строковый `entityType` напрямую (`\"deal\"`, `\"contact\"`, `\"dynamic_174\"` и т. п.) — см. [Привязать запись](\u002Fdocs\u002Ftimeline-logs\u002Fbindings\u002Fbind).\n\n## Коды ошибок\n\n### Ошибки таймлайна\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 400 | `INVALID_PARAMS` | Не переданы или некорректны обязательные параметры (`entityTypeId`, `entityId`, `title`, `text`, `itemType` и т. д. — конкретное поле в `message`) |\n| 400 | `INVALID_ENTITY_TYPE_ID` | В `bindings.bind`\u002F`unbind` передан `entityTypeId` без отображения на `ENTITY_TYPE` (`\u003C 128` и не из таблицы выше) |\n| 403 | `CROSS_APP_DELETE_FORBIDDEN` | Попытка удалить лог-запись через ключ, отличный от того, которым она создана |\n| 404 | `ENTITY_NOT_FOUND` | Лог-запись с указанным `id` не существует — Битрикс24 вернул ошибку `NOT_FOUND` |\n| 404 | `NOT_FOUND` | Только `GET \u002Fv1\u002Ftimeline-logs\u002F:id`: Битрикс24 вернул успешный ответ, но объект записи пуст |\n| 404 | `NOTE_NOT_FOUND` | У указанного элемента таймлайна нет привязанной заметки |\n\n### Системные ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 401 | `AUTH_REQUIRED` | Отсутствует `X-Api-Key` |\n| 401 | `INVALID_API_KEY` | Неверный API-ключ |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов (для `vibe_app_*` нужен `Authorization: Bearer ...`) |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `crm` |\n| 422 | `BITRIX_ERROR` | Битрикс24 вернул ошибку (текст в `message`) |\n| 429 | `RATE_LIMITED` | Превышен лимит запросов. Подождите 1–2 секунды и повторите. Несколько вызовов можно объединить в [`POST \u002Fv1\u002Fbatch`](\u002Fdocs\u002Fbatch) |\n| 429 | `QUEUE_TIMEOUT` | Запрос к B24 не успел выполниться в очереди портала. Запрос не был отправлен в Битрикс24 — безопасно повторить (`Retry-After`). Сузьте фильтр или повторите позже |\n| 502 | `ERROR_LOOP_DETECTED` | Срабатывает circuit breaker: подряд много одинаковых ошибок от B24. Подождите ~60 секунд |\n| 502 | `BITRIX_UNAVAILABLE` | Портал Битрикс24 недоступен |\n| 503 | `BITRIX_TIMEOUT` | Битрикс24 принял запрос, но не ответил за 15 секунд. Для write-операций — сначала перечитайте сущность, изменение могло примениться |\n| 500 | `INTERNAL_ERROR` | Внутренняя ошибка сервера |\n\nПолный список общих кодов API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Справочник эндпоинтов\n\nВсе 12 эндпоинтов:\n\n| Метод | Путь | Bitrix24 метод | Описание |\n|-------|------|---------------|---------|\n| POST | [\u002Fv1\u002Ftimeline-logs](\u002Fdocs\u002Ftimeline-logs\u002Flogs\u002Fcreate) | `crm.timeline.logmessage.add` | Создать лог-запись |\n| GET | [\u002Fv1\u002Ftimeline-logs](\u002Fdocs\u002Ftimeline-logs\u002Flogs\u002Flist) | `crm.timeline.logmessage.list` | Список лог-записей |\n| GET | [\u002Fv1\u002Ftimeline-logs\u002F:id](\u002Fdocs\u002Ftimeline-logs\u002Flogs\u002Fget) | `crm.timeline.logmessage.get` | Получить одну запись |\n| DELETE | [\u002Fv1\u002Ftimeline-logs\u002F:id](\u002Fdocs\u002Ftimeline-logs\u002Flogs\u002Fdelete) | `crm.timeline.logmessage.delete` | Удалить запись |\n| POST | [\u002Fv1\u002Ftimeline-logs\u002F:id\u002Fnote](\u002Fdocs\u002Ftimeline-logs\u002Fnotes\u002Fsave) | `crm.timeline.note.save` | Сохранить или обновить заметку |\n| GET | [\u002Fv1\u002Ftimeline-logs\u002F:id\u002Fnote](\u002Fdocs\u002Ftimeline-logs\u002Fnotes\u002Fget) | `crm.timeline.note.get` | Получить заметку |\n| DELETE | [\u002Fv1\u002Ftimeline-logs\u002F:id\u002Fnote](\u002Fdocs\u002Ftimeline-logs\u002Fnotes\u002Fdelete) | `crm.timeline.note.delete` | Удалить заметку |\n| POST | [\u002Fv1\u002Ftimeline-logs\u002F:id\u002Fpin](\u002Fdocs\u002Ftimeline-logs\u002Fpins\u002Fpin) | `crm.timeline.item.pin` | Закрепить запись |\n| POST | [\u002Fv1\u002Ftimeline-logs\u002F:id\u002Funpin](\u002Fdocs\u002Ftimeline-logs\u002Fpins\u002Funpin) | `crm.timeline.item.unpin` | Открепить запись |\n| POST | [\u002Fv1\u002Ftimeline-logs\u002F:id\u002Fbind](\u002Fdocs\u002Ftimeline-logs\u002Fbindings\u002Fbind) | `crm.timeline.bindings.bind` | Привязать к ещё одной сущности |\n| POST | [\u002Fv1\u002Ftimeline-logs\u002F:id\u002Funbind](\u002Fdocs\u002Ftimeline-logs\u002Fbindings\u002Funbind) | `crm.timeline.bindings.unbind` | Отвязать от сущности |\n| GET | [\u002Fv1\u002Ftimeline-logs\u002F:id\u002Fbindings](\u002Fdocs\u002Ftimeline-logs\u002Fbindings\u002Flist) | `crm.timeline.bindings.list` | Список всех привязок записи |\n\n## Смотрите также\n\n- [Комментарии таймлайна](\u002Fdocs\u002Fentities\u002Ftimelines) — текстовые комментарии пользователя (отдельный API на `crm.timeline.comment.*`)\n- [Сделки](\u002Fdocs\u002Fentities\u002Fdeals), [Лиды](\u002Fdocs\u002Fentities\u002Fleads), [Контакты](\u002Fdocs\u002Fentities\u002Fcontacts), [Компании](\u002Fdocs\u002Fentities\u002Fcompanies) — типичные родительские сущности\n- [Смарт-процессы](\u002Fdocs\u002Fentities\u002Fsmart-processes) — для записей в таймлайне пользовательских CRM-типов\n- [Batch](\u002Fdocs\u002Fbatch) — массовые операции\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization) — rate limits\n","2026-07-02",{}]