## Проверить видимость объектов Диска `POST /v1/disk/sync/check` Проверяет, видит ли сейчас пользователь Битрикс24, от имени которого работает ключ, указанные файлы и папки Диска, и отдаёт их текущие карточки. Метод работает и на портале, где синхронизация Диска недоступна. ## Поля запроса (body) | Поле | Тип | Обяз. | Описание | |------|-----|:-----:|----------| | `objectIds` | string[] | да | ID файлов и папок Диска — строки из цифр, от 1 до 50 ID без повторов. Поиск: [`POST /v1/disk/search`](/docs/disk/search), поле `data.items[].objectId`. Содержимое папки: [`GET /v1/files?folderId=…`](/docs/entities/files/list) | | `sections` | string[] | нет | Разделы проверки видимости: `metadata`, `location`, `access`, `relations`. От 1 до 4 значений без повторов | ## Примеры ### curl — личный ключ ```bash 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-приложение ```bash 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`](/docs/entities/storages/list) | | `data.items[].card.parentId` | string | ID родительской папки. Папка: [`GET /v1/folders/:id`](/docs/entities/folders/get) | | `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 | Код | Описание | |------|-----|----------| | 400 | `INVALID_PARAMS` | Тело не прошло проверку: пустой `objectIds`, больше 50 ID, повторяющиеся ID, ID не строкой из цифр, неизвестное или повторяющееся значение в `sections`, лишнее поле в теле | | 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` | | 401 | `INVALID_API_KEY` | Ключ не опознан | | 401 | `TOKEN_MISSING` | У ключа нет настроенных токенов портала | | 401 | `DISK_AUTH_UNAVAILABLE` | Не удалось подтвердить пользователя Битрикс24, от имени которого работает ключ: для ключа приложения не передан или не подходит токен сессии в `Authorization: Bearer`, входящий вебхук ключа выдан другому пользователю, ключ работает через личную OAuth-авторизацию, либо портал отклонил токен как истёкший | | 401 | `TOKEN_REFRESH_FAILED` | Не удалось обновить авторизацию портала для ключа. Повтор не поможет, пока ключ не авторизован заново | | 403 | `SCOPE_DENIED` | У ключа нет скоупа `disk` | | 403 | `DISK_ACCESS_DENIED` | Портал отказал в доступе к проверке видимости | | 502 | `DISK_READ_UNAVAILABLE` | Хотя бы один объект из `objectIds` прочитать не удалось: такого ID нет, у пользователя нет к нему доступа или объект в корзине. Отказ относится ко всему запросу | | 502 | `DISK_UNSUPPORTED` | Портал вернул результат проверки в формате, который не удалось разобрать | | 503 | `QUERY_LIMIT_EXCEEDED` | Портал отклонил вызов из-за превышения лимита запросов | | 503 | `BITRIX_TIMEOUT` | Портал не ответил за отведённое время | | 503 | `QUEUE_OVERFLOW`, `QUEUE_TIMEOUT` | Очередь запросов к порталу переполнена. Паузу перед повтором называет заголовок `Retry-After` | | 503 | `RATE_LIMITED` | Портал ответил HTTP 429. Паузу перед повтором называет заголовок `Retry-After` | | 503 | `ERROR_LOOP_DETECTED` | Повторяющиеся ошибки этого ключа на этом методе временно остановили вызовы. Паузу называет заголовок `Retry-After` | | 503 | `user_self_deletion_pending` | Владелец ключа ожидает удаления аккаунта на портале. Доступ вернётся после отмены удаления | Полный список общих ошибок API — [Ошибки](/docs/errors). ## Известные особенности - **Нечитаемый ID ищите по одному.** На портале, где синхронизация Диска недоступна, каждый объект в ответе приходит с `visible: true` и карточкой, а частичного результата нет. Чтобы найти ID, из-за которого отклонён запрос, проверяйте объекты по одному. Признак доступности синхронизации — поле `sync.available` в [`GET /v1/disk/capabilities`](/docs/disk/capabilities). - **Набор полей карточки от `sections` не зависит.** Карточка `card` собирается из текущих данных объекта одинаково при любом значении `sections`. - **`retrySafe` не подсказывает повтор.** У отказов этого метода `error.retrySafe` всегда `false`. Решение о повторе принимайте по коду и заголовку `Retry-After`. ## Смотрите также - [Получить возможности Диска](/docs/disk/capabilities) - [Поиск по Диску](/docs/disk/search) - [Список файлов папки](/docs/entities/files/list) - [Получить папку](/docs/entities/folders/get) - [Ошибки](/docs/errors)