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

Проверить видимость объектов Диска

POST /v1/disk/sync/check

Проверяет, видит ли сейчас пользователь Битрикс24, от имени которого работает ключ, указанные файлы и папки Диска, и отдаёт их текущие карточки. Метод работает и на портале, где синхронизация Диска недоступна.

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

Поле Тип Обяз. Описание
ПолеobjectIds Типstring[] Обяз.да ОписаниеID файлов и папок Диска — строки из цифр, от 1 до 50 ID без повторов. Поиск: POST /v1/disk/search, поле data.items[].objectId. Содержимое папки: GET /v1/files?folderId=…
Полеsections Типstring[] Обяз.нет ОписаниеРазделы проверки видимости: metadata, location, access, relations. От 1 до 4 значений без повторов

Примеры

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/disk/sync/check \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "objectIds": ["10899", "9987"]
  }'

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/disk/sync/check \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "objectIds": ["10899", "9987"]
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/disk/sync/check', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    objectIds: ['10899', '9987'],
  }),
})

const { success, data, error } = await res.json()
if (!success) throw new Error(error.code)
for (const item of data.items) {
  console.log(item.objectId, item.visible, item.card?.name)
}

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/disk/sync/check', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    objectIds: ['10899', '9987'],
  }),
})

const { success, data, error } = await res.json()
if (!success) throw new Error(error.code)
for (const item of data.items) {
  console.log(item.objectId, item.visible, item.card?.name)
}

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue при успешной проверке
Полеdata.items Типarray ОписаниеРезультат по каждому ID — в том же порядке, что в objectIds
Полеdata.items[].objectId Типstring ОписаниеID объекта из запроса
Полеdata.items[].visible Типboolean Описаниеtrue — пользователь видит объект сейчас, false — не видит
Полеdata.items[].card Типobject ОписаниеТекущая карточка объекта. Не приходит, когда visible равно false или текущие данные объекта получить не удалось
Полеdata.items[].card.objectId Типstring ОписаниеID объекта
Полеdata.items[].card.objectType Типstring ОписаниеТип объекта: file или folder
Полеdata.items[].card.name Типstring ОписаниеИмя файла или папки
Полеdata.items[].card.storageId Типstring ОписаниеID хранилища. Список: GET /v1/storages
Полеdata.items[].card.parentId Типstring ОписаниеID родительской папки. Папка: GET /v1/folders/:id
Полеdata.items[].card.size Типstring ОписаниеРазмер файла в байтах, строкой из цифр. Только у файлов
Полеdata.items[].card.contentFileId Типstring ОписаниеID текущего содержимого файла. Только у файлов
Полеdata.items[].card.contentGeneration Типstring ОписаниеСчётчик версий содержимого файла, строкой из цифр. Только у файлов
Полеdata.items[].card.versionId Типstring ОписаниеID текущей версии файла. Приходит не на всех порталах
Полеdata.items[].card.versionNumber Типstring ОписаниеНомер текущей версии файла, строкой из цифр. Приходит не на всех порталах
Полеdata.items[].card.contentAvailable Типboolean ОписаниеДоступно ли содержимое файла. Приходит не на всех порталах
Полеdata.items[].card.safeLink Типstring ОписаниеHTTPS-ссылка на объект в веб-интерфейсе Битрикс24
Полеdata.items[].card.source Типstring ОписаниеПроисхождение карточки. native-current — карточка собрана из текущих данных объекта на момент запроса

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

Файл и папка, которые пользователь видит:

JSON 
{
  "success": true,
  "data": {
    "items": [
      {
        "objectId": "10899",
        "visible": true,
        "card": {
          "objectId": "10899",
          "objectType": "file",
          "name": "vibe-disk-docs-check.txt",
          "storageId": "1",
          "parentId": "1",
          "size": "27",
          "contentFileId": "39553",
          "contentGeneration": "1",
          "safeLink": "https://example.bitrix24.ru/company/personal/user/1/disk/file/vibe-disk-docs-check.txt",
          "source": "native-current"
        }
      },
      {
        "objectId": "9987",
        "visible": true,
        "card": {
          "objectId": "9987",
          "objectType": "folder",
          "name": "2026-08",
          "storageId": "11",
          "parentId": "9075",
          "safeLink": "https://example.bitrix24.ru/docs/path/Reports/2026-08",
          "source": "native-current"
        }
      }
    ]
  }
}

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

400 — пустой массив objectIds:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Disk request unavailable",
    "retrySafe": false
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодINVALID_PARAMS ОписаниеТело не прошло проверку: пустой objectIds, больше 50 ID, повторяющиеся ID, ID не строкой из цифр, неизвестное или повторяющееся значение в sections, лишнее поле в теле
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP401 КодINVALID_API_KEY ОписаниеКлюч не опознан
HTTP401 КодTOKEN_MISSING ОписаниеУ ключа нет настроенных токенов портала
HTTP401 КодDISK_AUTH_UNAVAILABLE ОписаниеНе удалось подтвердить пользователя Битрикс24, от имени которого работает ключ: для ключа приложения не передан или не подходит токен сессии в Authorization: Bearer, входящий вебхук ключа выдан другому пользователю, ключ работает через личную OAuth-авторизацию, либо портал отклонил токен как истёкший
HTTP401 КодTOKEN_REFRESH_FAILED ОписаниеНе удалось обновить авторизацию портала для ключа. Повтор не поможет, пока ключ не авторизован заново
HTTP403 КодSCOPE_DENIED ОписаниеУ ключа нет скоупа disk
HTTP403 КодDISK_ACCESS_DENIED ОписаниеПортал отказал в доступе к проверке видимости
HTTP502 КодDISK_READ_UNAVAILABLE ОписаниеХотя бы один объект из objectIds прочитать не удалось: такого ID нет, у пользователя нет к нему доступа или объект в корзине. Отказ относится ко всему запросу
HTTP502 КодDISK_UNSUPPORTED ОписаниеПортал вернул результат проверки в формате, который не удалось разобрать
HTTP503 КодQUERY_LIMIT_EXCEEDED ОписаниеПортал отклонил вызов из-за превышения лимита запросов
HTTP503 КодBITRIX_TIMEOUT ОписаниеПортал не ответил за отведённое время
HTTP503 КодQUEUE_OVERFLOW, QUEUE_TIMEOUT ОписаниеОчередь запросов к порталу переполнена. Паузу перед повтором называет заголовок Retry-After
HTTP503 КодRATE_LIMITED ОписаниеПортал ответил HTTP 429. Паузу перед повтором называет заголовок Retry-After
HTTP503 КодERROR_LOOP_DETECTED ОписаниеПовторяющиеся ошибки этого ключа на этом методе временно остановили вызовы. Паузу называет заголовок Retry-After
HTTP503 Кодuser_self_deletion_pending ОписаниеВладелец ключа ожидает удаления аккаунта на портале. Доступ вернётся после отмены удаления

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

Известные особенности

  • Нечитаемый ID ищите по одному. На портале, где синхронизация Диска недоступна, каждый объект в ответе приходит с visible: true и карточкой, а частичного результата нет. Чтобы найти ID, из-за которого отклонён запрос, проверяйте объекты по одному. Признак доступности синхронизации — поле sync.available в GET /v1/disk/capabilities.
  • Набор полей карточки от sections не зависит. Карточка card собирается из текущих данных объекта одинаково при любом значении sections.
  • retrySafe не подсказывает повтор. У отказов этого метода error.retrySafe всегда false. Решение о повторе принимайте по коду и заголовку Retry-After.

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