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

`GET /v1/disk/uploads/:operationId`

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

## Параметры

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

## Примеры

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

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

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

```bash
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 | Код | Описание |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | `operationId` длиннее 512 символов |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Ключ не опознан |
| 401 | `TOKEN_MISSING` | У ключа нет подключения к Битрикс24 |
| 401 | `DISK_AUTH_UNAVAILABLE` | Не удалось подтвердить пользователя Битрикс24: ключ приложения передан без `Authorization: Bearer`, сессия не принадлежит приложению ключа или ключ не поддерживается агентом Диска |
| 401 | `TOKEN_REFRESH_FAILED` | Не удалось обновить авторизацию портала для ключа. Повтор не поможет, пока ключ не авторизован заново |
| 403 | `SCOPE_DENIED` | У ключа нет скоупа `disk` |
| 403 | `DISK_ACCESS_DENIED` | Битрикс24 отказал в доступе при проверке пользователя |
| 409 | `DISK_OPERATION_EXPIRED` | Операции с таким `operationId` нет в контексте ключа: идентификатор неизвестен или операция создана другим пользователем, другим ключом либо другим приложением |
| 502 | `DISK_READ_UNAVAILABLE` | Битрикс24 вернул ошибку, которую Вайбкод не распознал |
| 503 | `QUERY_LIMIT_EXCEEDED` | Битрикс24 ограничил частоту запросов. Повторите позже |
| 503 | `BITRIX_TIMEOUT` | Битрикс24 не ответил вовремя |
| 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).

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

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

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

- [Список операций загрузки](/docs/disk/uploads-list)
- [Зарезервировать загрузку файла на Диск](/docs/disk/uploads-reserve)
- [Загрузить содержимое файла на Диск](/docs/disk/uploads)
- [Поиск по Диску](/docs/disk/search)
- [Ошибки](/docs/errors)