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

Получить операцию загрузки

GET /v1/disk/uploads/:operationId

Показывает состояние операции загрузки файла на Диск Битрикс24 и сверяет записанный файл с его текущим состоянием. Запрос не отправляет запись повторно ни в каком состоянии операции.

Параметры

Параметр Тип Обяз. Описание
ПараметрoperationId (path) Типstring Обяз.да ОписаниеИдентификатор операции, от 1 до 512 символов. Источник: ответ POST /v1/disk/uploads/reserve или список GET /v1/disk/uploads

Примеры

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

Terminal 
curl https://vibecode.bitrix24.tech/v1/disk/uploads/xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl https://vibecode.bitrix24.tech/v1/disk/uploads/xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

javascript 
const operationId = 'xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU'
const res = await fetch(`https://vibecode.bitrix24.tech/v1/disk/uploads/${operationId}`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { success, data, error } = await res.json()
if (!success) throw new Error(error.code)
console.log(data.application, data.verification)

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

javascript 
const operationId = 'xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU'
const res = await fetch(`https://vibecode.bitrix24.tech/v1/disk/uploads/${operationId}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue при успешном чтении
Полеdata.operationId Типstring ОписаниеИдентификатор операции
Полеdata.phase Типstring ОписаниеЭтап операции: prepared — зарезервирована, submitting — запись передана в Битрикс24, settled — завершена
Полеdata.application Типstring ОписаниеРезультат записи: applied — Битрикс24 подтвердил запись, not_applied — запись в Битрикс24 не отправлялась, unknown — запись отправлена, но подтверждения нет
Полеdata.verification Типstring ОписаниеСверка с текущим состоянием файла на момент запроса: matched — файл совпадает с записанным, superseded — файл с тех пор изменился, unavailable — сверка не выполнена
Полеdata.fileId Типstring ОписаниеID файла на Диске. Приходит при application: "applied"
Полеdata.contentFileId Типstring ОписаниеID содержимого, записанного этой операцией. Приходит при application: "applied"
Полеdata.contentGeneration Типstring ОписаниеНомер версии содержимого, записанной этой операцией. Приходит при application: "applied"
Полеdata.safeLink Типstring ОписаниеHTTPS-адрес файла в Битрикс24. Приходит, когда Битрикс24 его вернул. Доступ ограничен правами сотрудника в Битрикс24
Полеdata.atomicConcurrency Типboolean ОписаниеВсегда false: запись не защищена от одновременного изменения файла другим пользователем
Полеdata.conflictDetected Типboolean Описаниеtrue, если в режиме version состояние файла не совпало с ожидаемым и запись не выполнялась
Полеdata.outcomeUnknown Типboolean Описаниеtrue при application: "unknown"

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

Файл записан этой операцией, но позже получил новую версию:

JSON 
{
  "success": true,
  "data": {
    "operationId": "xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU",
    "phase": "settled",
    "application": "applied",
    "verification": "superseded",
    "fileId": "10901",
    "contentFileId": "39571",
    "contentGeneration": "1",
    "safeLink": "https://example.bitrix24.ru/company/personal/user/1/disk/file/vibe-disk-docs-check-2.txt",
    "atomicConcurrency": false,
    "conflictDetected": false,
    "outcomeUnknown": false
  }
}

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

409 — операции с таким operationId нет в контексте ключа:

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

Ошибки

HTTP Код Описание
HTTP400 КодINVALID_PARAMS ОписаниеoperationId длиннее 512 символов
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP401 КодINVALID_API_KEY ОписаниеКлюч не опознан
HTTP401 КодTOKEN_MISSING ОписаниеУ ключа нет подключения к Битрикс24
HTTP401 КодDISK_AUTH_UNAVAILABLE ОписаниеНе удалось подтвердить пользователя Битрикс24: ключ приложения передан без Authorization: Bearer, сессия не принадлежит приложению ключа или ключ не поддерживается агентом Диска
HTTP401 КодTOKEN_REFRESH_FAILED ОписаниеНе удалось обновить авторизацию портала для ключа. Повтор не поможет, пока ключ не авторизован заново
HTTP403 КодSCOPE_DENIED ОписаниеУ ключа нет скоупа disk
HTTP403 КодDISK_ACCESS_DENIED ОписаниеБитрикс24 отказал в доступе при проверке пользователя
HTTP409 КодDISK_OPERATION_EXPIRED ОписаниеОперации с таким operationId нет в контексте ключа: идентификатор неизвестен или операция создана другим пользователем, другим ключом либо другим приложением
HTTP502 КодDISK_READ_UNAVAILABLE ОписаниеБитрикс24 вернул ошибку, которую Вайбкод не распознал
HTTP503 КодQUERY_LIMIT_EXCEEDED ОписаниеБитрикс24 ограничил частоту запросов. Повторите позже
HTTP503 КодBITRIX_TIMEOUT ОписаниеБитрикс24 не ответил вовремя
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 — Ошибки.

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

  • verification вычисляется заново при каждом запросе. Для application: "applied" Вайбкод читает текущий файл в Битрикс24 и сравнивает его с записанным содержимым. superseded значит, что файл с тех пор изменился, а не что запись не удалась: application при этом остаётся applied. Если файл не удалось прочитать, приходит unavailable.
  • Ключ «только чтение» читает операции. Запрос не изменяет данные и доступен ключу в режиме «только чтение», в отличие от резерва и загрузки.
  • Состояние unknown не меняется само. Чтение не проверяет, появился ли файл после неподтверждённой записи. Найдите файл через POST /v1/disk/search или POST /v1/disk/sync/check.

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