Для AI-агентов: markdown этой страницы — /docs-content/entities/timelines/create.md индекс документации — /llms.txt

Добавить комментарий

POST /v1/timelines

Создаёт новый комментарий таймлайна, привязанный к записи CRM. Используется для фиксации заметок по сделкам, лидам, контактам и компаниям.

Поля запроса (body)

Поле Тип Обяз. Описание
entityType string да Тип родительской записи CRM: deal, lead, contact, company или DYNAMIC_<entityTypeId> для смарт-процессов. Например, DYNAMIC_174 для смарт-процесса с entityTypeId: 174 из GET /v1/smart-processes
entityId number да ID родительской записи. Источник зависит от типа: GET /v1/deals, GET /v1/leads, GET /v1/contacts, GET /v1/companies, GET /v1/items/:entityTypeId (элементы смарт-процессов)
comment string да Текст комментария. Пустая строка отклоняется ошибкой BITRIX_ERROR Empty comment message
FILES array нет Вложения к комментарию. Каждый элемент — массив из двух строк [имяФайла, base64Содержимое]. Тип поля в схеме Битрикс24 — attached_diskfile

При создании через API автор (authorId) проставляется по владельцу API-ключа, дата создания (createdAt) — сервером.

Прикрепление файлов. Поле FILES — массив пар [имяФайла, base64Содержимое], по одной паре на файл. Содержимое файла передаётся как строка в кодировке base64, файл загружается на Диск Битрикс24 и привязывается к комментарию.

В ответе на создание и при чтении комментария (GET /v1/timelines/:id) прикреплённые файлы возвращаются в поле FILES — объект, где ключ это ID файла на Диске, а значение содержит метаданные:

JSON 
"FILES": {
  "9317": {
    "id": 9317,
    "date": "2026-04-24T15:34:05+03:00",
    "type": "file",
    "name": "report.pdf",
    "size": 11,
    "image": false,
    "authorId": 1,
    "authorName": "Иван Петров",
    "urlPreview": null,
    "urlShow": "https://example.bitrix24.ru/disk/downloadFile/9317/?&ncc=1&filename=report.pdf",
    "urlDownload": "https://example.bitrix24.ru/disk/downloadFile/9317/?&ncc=1&filename=report.pdf"
  }
}

Адреса urlShow и urlDownload ведут на Диск портала и ключом не авторизуются. Файл скачивается через GET /v1/timelines/:commentId/files/:fileRef/download.

Примеры

curl — личный ключ

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/timelines \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "deal",
    "entityId": 741,
    "comment": "Первый контакт: клиент заинтересовался предложением"
  }'

curl — OAuth-приложение

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/timelines \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "deal",
    "entityId": 741,
    "comment": "Первый контакт: клиент заинтересовался предложением"
  }'

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/timelines', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    entityType: 'deal',
    entityId: 741,
    comment: 'Первый контакт: клиент заинтересовался предложением',
  }),
})

const { success, data } = await res.json()
console.log('Comment ID:', data.id)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/timelines', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    entityType: 'deal',
    entityId: 741,
    comment: 'Первый контакт: клиент заинтересовался предложением',
  }),
})

const { success, data } = await res.json()

curl — комментарий с файлом

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/timelines \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "deal",
    "entityId": 741,
    "comment": "Отчёт во вложении",
    "FILES": [["report.pdf", "JVBERi0xLjQKJ..."]]
  }'

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data object Созданный комментарий
data.id number ID созданного комментария
data.entityType string Тип родительской записи
data.entityId number ID родительской записи
data.comment string Текст комментария
data.authorId number ID автора — при создании через API соответствует владельцу ключа
data.createdAt datetime Дата создания, ISO 8601 в UTC
data.FILES object Прикреплённые файлы — только если были переданы. Ключ — ID файла на Диске, значение — метаданные файла, их состав показан в разделе «Прикрепление файлов» выше
meta.warnings array Есть, когда в теле переданы поля, которых нет ни в схеме комментария, ни в списке полей GET /v1/timelines/fields, например имя с опечаткой. Код предупреждения UNRECOGNIZED_WRITE_FIELD: такое поле могло не сохраниться. Ответ приходит с кодом 201. Объект fields на маршруте, который сам оборачивает карту полей и где схема не объявляет fields, отклоняется с 400 NESTED_FIELDS_ENVELOPE; передавайте поля плоско в корне JSON.

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

JSON 
{
  "success": true,
  "data": {
    "id": 66303,
    "entityId": 741,
    "entityType": "deal",
    "comment": "Первый контакт: клиент заинтересовался предложением",
    "authorId": 1,
    "createdAt": "2026-04-24T12:34:05.000Z"
  }
}

Пример ответа при ошибке

422 — не передан обязательный comment:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Empty comment message"
  }
}

Ошибки

HTTP Код Описание
400 READONLY_FIELD В теле передано поле, которое нельзя задать при создании: authorId, id или createdAt. Автора Битрикс24 берёт из учётных данных вызова — чтобы комментарий вышел от нужного пользователя, сделайте вызов от его имени
400 INVALID_FILES_SHAPE Поле FILES передано не массивом пар [[имяФайла, base64Содержимое]]
422 BITRIX_ERROR Нарушение требований: пустой comment, неверный entityType
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

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

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