#Документы

⚠️ Методы в процессе раскатки — выходят в обновлении note 26.100.0. Доступны не на всех порталах Битрикс24. Если на вашем портале метод ещё не доступен, API вернёт 422 METHOD_NOT_YET_AVAILABLE — это не ошибка интеграции, а признак того, что обновление пока не приехало на портал.

Управление документами Базы знаний. Все методы требуют скоуп note. OAuth-приложения добавляют заголовок Authorization: Bearer USER_SESSION_TOKEN к каждому вызову.

#Создать документ

POST /v1/note/documents

Создаёт документ в базе знаний и возвращает его идентификатор. Если передан непустой markdown, документ создаётся с готовым содержимым. Без markdown создаётся пустой документ для совместного редактирования.

Параметр Где Тип Обяз. Описание
collectionId body integer да Идентификатор базы знаний
title body string да Заголовок документа
parentId body integer нет Родительский документ для вложенности. Должен принадлежать той же базе знаний
markdown body string нет Начальное содержимое в Markdown. Максимум 1 048 576 байт (1 МиБ)
Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/note/documents \
  -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"collectionId": 42, "title": "Глава 1", "parentId": 10, "markdown": "# Глава 1\n\nТекст"}'
javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/note/documents', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ collectionId: 42, title: 'Глава 1', markdown: '# Глава 1\n\nТекст' }),
})
const { success, data } = await res.json()
console.log(data.id) // идентификатор созданного документа

#Поля ответа

data = { id } — идентификатор созданного документа.

JSON 
{ "success": true, "data": { "id": 77 } }

#Ошибки

HTTP Код Когда
400 INVALID_PARAMS Не передан collectionId или title, либо параметр неверного типа
403 BITRIX_ACCESS_DENIED Нет права создавать документы в базе знаний
404 ENTITY_NOT_FOUND База знаний или родительский документ не существуют
422 BITRIX_ERROR parentId из другой базы знаний, либо размер markdown превышает лимит (текст в error.message)
422 METHOD_NOT_YET_AVAILABLE Обновление note 26.100.0 ещё не приехало на портал
502 BITRIX_UNAVAILABLE Bitrix24 недоступен

#Обновить документ

PATCH /v1/note/documents/:id

Обновляет заголовок и/или содержимое документа. Нужно передать хотя бы одно из полей title / markdown. Передача markdown полностью заменяет содержимое.

Если документ редактируется совместно и на сервере есть несохранённые изменения, при overwrite: false API вернёт 422 BITRIX_ERROR с пояснением. Чтобы переписать содержимое принудительно, повторите запрос с overwrite: true.

Параметр Где Тип Обяз. Описание
id path integer да Идентификатор документа
title body string нет¹ Новый заголовок
markdown body string нет¹ Новое содержимое в Markdown. Максимум 1 048 576 байт
overwrite body boolean нет Переписать содержимое при несохранённых изменениях. По умолчанию false

¹ Хотя бы одно из полей title / markdown обязано присутствовать.

Terminal 
curl -X PATCH https://vibecode.bitrix24.tech/v1/note/documents/77 \
  -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"title": "Глава 1 (ред.)", "markdown": "# Глава 1\n\nОбновлённый текст", "overwrite": false}'
javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/note/documents/77', {
  method: 'PATCH',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ title: 'Глава 1 (ред.)', markdown: '# Глава 1\n\nОбновлённый текст' }),
})
const { success, data } = await res.json()
console.log(data.updated) // true

#Поля ответа

data = { updated: true } при успешном обновлении.

JSON 
{ "success": true, "data": { "updated": true } }

#Ошибки

HTTP Код Когда
400 INVALID_PARAMS Не передан ни title, ни markdown, либо id неверного типа
403 BITRIX_ACCESS_DENIED Нет права редактировать документ
404 ENTITY_NOT_FOUND Документ не существует, архивный или в корзине
422 BITRIX_ERROR Есть несохранённые изменения и передан overwrite: false, либо размер markdown превышает лимит (текст в error.message)
422 METHOD_NOT_YET_AVAILABLE Обновление note 26.100.0 ещё не приехало на портал

#Архивировать документ

POST /v1/note/documents/:id/archive

Архивирует документ вместе с его поддеревом. Архивные документы доступны для чтения, но не для редактирования.

Параметр Где Тип Обяз. Описание
id path integer да Идентификатор корневого документа поддерева
Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/note/documents/77/archive \
  -H "X-Api-Key: YOUR_API_KEY"
javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/note/documents/77/archive', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { success, data } = await res.json()
console.log(data.archived) // true

#Поля ответа

data = { archived: true } при успешной архивации.

JSON 
{ "success": true, "data": { "archived": true } }

#Ошибки

HTTP Код Когда
400 INVALID_PARAMS id не положительное целое
403 BITRIX_ACCESS_DENIED Нет права редактировать документ
404 ENTITY_NOT_FOUND Документ не существует, в корзине или уже архивирован
422 METHOD_NOT_YET_AVAILABLE Обновление note 26.100.0 ещё не приехало на портал

#Удалить документ

DELETE /v1/note/documents/:id

Перемещает документ вместе с его поддеревом в корзину. Документ исчезает из дерева и поиска. Восстановление возможно только в интерфейсе Битрикс24.

Параметр Где Тип Обяз. Описание
id path integer да Идентификатор корневого документа поддерева
Terminal 
curl -X DELETE https://vibecode.bitrix24.tech/v1/note/documents/77 \
  -H "X-Api-Key: YOUR_API_KEY"
javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/note/documents/77', {
  method: 'DELETE',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { success, data } = await res.json()
console.log(data.deleted) // true

#Поля ответа

data = { deleted: true } при успешном удалении.

JSON 
{ "success": true, "data": { "deleted": true } }

#Ошибки

HTTP Код Когда
400 INVALID_PARAMS id не положительное целое
403 BITRIX_ACCESS_DENIED Нет права редактировать документ
404 ENTITY_NOT_FOUND Документ не существует или уже в корзине
422 METHOD_NOT_YET_AVAILABLE Обновление note 26.100.0 ещё не приехало на портал

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