## Обновить задачу

`PATCH /v1/tasks/:id`

Обновляет поля существующей задачи. Передавайте только изменяемые поля. Полный список — [Поля задачи](./fields.md).

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|---------|
| `id` (path) | number | да | ID задачи |

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

Передавайте только изменяемые поля — поведение PATCH, остальные значения не затрагиваются.

| Поле | Тип | Описание |
|------|-----|---------|
| `title` | string | Название |
| `description` | string | Описание задачи (поддерживает BB-код) |
| `responsibleId` | number | Новый ответственный. Список сотрудников: `GET /v1/users` |
| `createdBy` | number | Новый постановщик. Применяется в пределах прав вызывающего пользователя. Только существующий сотрудник — см. предупреждение под таблицей. Список сотрудников: `GET /v1/users` |
| `status` | number | Статус задачи. Полный список значений: `GET /v1/tasks/fields` → `fields.status.enum` |
| `priority` | number | Приоритет: `0` — низкий, `1` — обычный, `2` — высокий |
| `deadline` | datetime | Крайний срок (ISO 8601) |
| `startDatePlan` | datetime | Плановая дата начала |
| `endDatePlan` | datetime | Плановая дата окончания |
| `timeEstimate` | number | Оценка трудозатрат в секундах |
| `groupId` | number | Рабочая группа. Список: `GET /v1/workgroups` |
| `parentId` | number | Родительская задача. Список: `GET /v1/tasks` |
| `accomplices` | number[] | Соисполнители. Список сотрудников: `GET /v1/users` |
| `auditors` | number[] | Наблюдатели. Список сотрудников: `GET /v1/users` |
| `tags` | string[] | Метки задачи |
| `ufTaskWebdavFiles` | string[] | Файлы задачи. Массив строк вида `n<id>`, где `id` — идентификатор файла из ответа [`POST /v1/files/upload`](../files/upload.md). Запись заменяет весь список вложений, пустой массив снимает все вложения. Очистка пустым массивом работает на `POST /v1/tasks` и `PATCH /v1/tasks/:id`; в батч-запросе (`POST /v1/batch`, `POST /v1/tasks/batch`) пустой массив на провод не уходит и вложения остаются на месте, поэтому очистку отправляйте одиночным запросом. Полное правило для полей-файлов — [Поля задачи](./fields.md) |
| `changedBy` | number | Служебное поле: кто последним изменил задачу. Принимается на записи — см. раздел под таблицей. Список сотрудников: `GET /v1/users` |
| `closedBy` | number | Служебное поле: кто закрыл задачу. Принимается на записи — см. раздел под таблицей. Список сотрудников: `GET /v1/users` |
| `statusChangedBy` | number | Служебное поле: кто последним сменил статус. Принимается на записи — см. раздел под таблицей. Список сотрудников: `GET /v1/users` |
| `createdDate` | datetime | Служебное поле: дата создания задачи, ISO 8601. Принимается на записи — см. раздел под таблицей |
| `changedDate` | datetime | Служебное поле: дата последнего изменения, ISO 8601. Переданное значение сохраняется вместо текущего времени — см. раздел под таблицей |
| `closedDate` | datetime | Служебное поле: дата закрытия, ISO 8601. Принимается на записи даже у незакрытой задачи — см. раздел под таблицей |

Поля `id`, `dateStart`, `activityDate`, `realStatus` — read-only, в body не передаются.

### Служебные поля задачи можно задавать

`createdBy` (постановщик), `changedBy`, `closedBy`, `statusChangedBy`, `createdDate`, `changedDate`, `closedDate` **принимаются** и при создании, и при обновлении: Битрикс24 сохраняет переданные значения, а Вайбкод — обёртка над ним и не запрещает того, что разрешает платформа. Принимаются оба написания — и `createdBy`, и `CREATED_BY`. Передавайте одно из двух, а не оба сразу: при обоих в одном теле применится то, которое встретится позже, без предупреждения.

Значение применяется в пределах прав вызывающего пользователя. Если Битрикс24 отказывает в правке задачи, отказ приходит как есть — `422` с его собственным текстом, без подмены на нашу ошибку и без ложного успеха.

**Что видно в журнале задачи.** Смену постановщика Битрикс24 пишет в журнал изменений задачи, и там остаётся настоящий вызывающий пользователь, а не тот, кого передали в `createdBy`. Для остальных шести полей отдельной записи в журнале не предусмотрено: по значению в карточке нельзя определить, кто его выставил.

**Дата без часового пояса.** У `createdDate`, `changedDate` и `closedDate` значение вида `2019-05-15T13:47:00` в написании `createdDate` получает смещение вашего пояса из заголовка `X-Vibe-Timezone`, а в написании `CREATED_DATE` уходит как есть и читается в поясе владельца ключа. Передавайте дату со смещением — `2019-05-15T13:47:00+03:00` — и оба написания дадут один и тот же момент.

Ограничить подмену служебных полей может только модель прав Битрикс24 — это отдельная доработка на стороне платформы, а не нашей обёртки.

> **Передавайте только существующего сотрудника.** Битрикс24 не проверяет идентификатор пользователя на существование ни в `createdBy`, ни в `changedBy`, `closedBy`, `statusChangedBy` — он запишет любое число. Задача с несуществующим постановщиком перестаёт управляться через API: Битрикс24 отказывает и в дальнейшем обновлении, и в удалении (`Действие над задачей не разрешено`), причём и через обёртку, и напрямую, даже ключу администратора. Такой исход проверен на `createdBy`. У трёх остальных полей идентификатор не проверяется так же, поэтому передавайте существующего сотрудника и в них. Список сотрудников: [`GET /v1/users`](/docs/entities/users).

## Часто обновляемые поля

| Поле | Когда используется |
|------|-------------------|
| `status` | Закрытие (`5`), возврат в работу (`3`), отказ (`7`). Расшифровка: `GET /v1/tasks/fields` → `fields.status.enum` |
| `responsibleId` | Передача задачи другому сотруднику. Источник: `GET /v1/users` |
| `deadline` | Перенос срока (ISO 8601 со смещением часового пояса портала) |

## Примеры

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

```bash
curl -X PATCH "https://vibecode.bitrix24.tech/v1/tasks/3871" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": 5,
    "priority": 2
  }'
```

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

```bash
curl -X PATCH "https://vibecode.bitrix24.tech/v1/tasks/3871" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": 5,
    "priority": 2
  }'
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/tasks/3871', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    status: 5,
    priority: 2,
  }),
})

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

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/tasks/3871', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    status: 5,
    priority: 2,
  }),
})

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

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data` | object | Обновлённый объект задачи со всеми полями — см. [Поля задачи](./fields.md) |

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

```json
{
  "success": true,
  "data": {
    "id": 3871,
    "title": "Подготовить отчёт за квартал",
    "status": 5,
    "priority": 2,
    "responsibleId": 1,
    "createdBy": 1,
    "createdDate": "2026-05-12T08:46:12.000Z",
    "changedDate": "2026-05-12T10:02:48.000Z",
    "closedDate": "2026-05-12T10:02:48.000Z",
    "deadline": "2026-05-19T15:00:00.000Z",
    "accomplices": [],
    "auditors": []
  }
}
```

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

400 — попытка изменить поле, доступное только на чтение:

```json
{
  "success": false,
  "error": {
    "code": "READONLY_FIELD",
    "message": "Field 'activityDate' is read-only and cannot be set"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 422 | `BITRIX_ERROR` | Битрикс24 отклонил обновление — например, задача с таким ID недоступна или не существует, либо переданное значение отклонено порталом |
| 404 | `ENTITY_NOT_FOUND` | Связанная сущность не найдена — например, `responsibleId` указывает на несуществующего сотрудника |
| 400 | `READONLY_FIELD` | Попытка обновить поле, доступное только на чтение (`id`, `dateStart`, `activityDate`, `realStatus`) |
| 400 | `INVALID_DISK_ATTACHMENT_VALUE` | Значение поля-файла передано не массивом строк вида `n<id>` — числом, строкой без префикса или одиночной строкой вместо массива |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `tasks` |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

**Закрытие задачи.** Чтобы пометить задачу выполненной, отправьте `status: 5`. После этого Битрикс24 сам заполняет `closedDate` — при переводе в статус `5` (завершена) или `6` (отложена). Передавать `closedDate` вручную тоже можно — см. раздел о служебных полях выше. Если поле не передано, платформа проставит его сама.

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

- [Получить задачу](./get.md)
- [Поля задачи](./fields.md)
- [Удалить задачу](./delete.md)
- [Список задач](./list.md)
- [Загрузить файл](../files/upload.md)
- [Batch](/docs/batch)
- [Лимиты и оптимизация](/docs/optimization)