# Перенести задачу с порядком

`POST /v1/tasks/:taskId/move-stage`

Переносит задачу на стадию канбана её рабочей группы или на стадию «Моего плана» владельца ключа и при необходимости ставит её перед другой задачей или после неё.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|----------|
| `taskId` (path) | number | да | ID переносимой задачи. Список: [`GET /v1/tasks`](/docs/entities/tasks/list) |

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

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|----------|
| `stageId` | number | да | ID целевой стадии: стадия канбана группы задачи или стадия «Моего плана». Список: [`GET /v1/tasks/stages/:entityId`](/docs/task-stages/list), для группы — ID группы, для «Моего плана» — `0` |
| `beforeTaskId` | number | нет | ID задачи, перед которой встанет переносимая. Задача из той же группы при переносе по канбану группы или из «Моего плана» при переносе по плану. Не передаётся вместе с `afterTaskId` |
| `afterTaskId` | number | нет | ID задачи, после которой встанет переносимая. Те же условия, что у `beforeTaskId`. Не передаётся вместе с `beforeTaskId` |

Другие поля в теле отклоняются с `400 INVALID_PARAMS`.

## Примеры

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

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/tasks/4127/move-stage" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stageId": 625, "beforeTaskId": 4125}'
```

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

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/tasks/4127/move-stage" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"stageId": 625, "beforeTaskId": 4125}'
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/tasks/4127/move-stage', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ stageId: 625, beforeTaskId: 4125 }),
})

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

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/tasks/4127/move-stage', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ stageId: 625, beforeTaskId: 4125 }),
})

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

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

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | Всегда `true` при успехе |
| `data` | object | Результат переноса |
| `data.taskId` | number | ID перенесённой задачи |
| `data.stageId` | number | ID стадии, на которой задача оказалась |
| `data.moved` | boolean | Всегда `true`: перенос проверен повторным чтением задачи |

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

```json
{
  "success": true,
  "data": {
    "taskId": 4127,
    "stageId": 625,
    "moved": true
  }
}
```

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

409 — задачи нет в «Моём плане» владельца ключа, перенос не выполнен:

```json
{
  "success": false,
  "error": {
    "code": "TASK_NOT_IN_PLAN",
    "message": "The task is not in your My Plan and was not moved"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | `taskId` или `stageId` не положительное целое число либо в теле есть другие поля: `taskId and stageId must be positive integers` |
| 400 | `INVALID_PARAMS` | Переданы оба поля `beforeTaskId` и `afterTaskId`: `Use either beforeTaskId or afterTaskId` |
| 400 | `INVALID_PARAMS` | Задача для порядка совпадает с переносимой или не положительное целое число: `The ordering task must be a different positive task id` |
| 400 | `INVALID_PARAMS` | Стадия не из канбана группы задачи и не из «Моего плана»: `stageId must belong to the task group or your My Plan` |
| 400 | `INVALID_PARAMS` | Перенос по канбану группы, а задача для порядка из другой группы или её нет: `Ordering task must belong to the same group` |
| 400 | `INVALID_PARAMS` | Перенос по «Моему плану», а задачи для порядка в нём нет: `Ordering task must belong to your My Plan` |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `TOKEN_MISSING` | У ключа нет действующего токена Битрикс24 |
| 403 | `SCOPE_DENIED` | У ключа нет скоупа `task` или `tasks` |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ только для чтения |
| 403 | `BITRIX_ACCESS_DENIED` | У пользователя ключа нет прав на задачу или на канбан группы |
| 404 | `ENTITY_NOT_FOUND` | Задачи с таким `taskId` нет: `Task was not found` |
| 409 | `TASK_NOT_IN_PLAN` | Перенос по «Моему плану», а задачи в плане владельца ключа нет: `The task is not in your My Plan and was not moved` |
| 422 | `BITRIX_ERROR` | Битрикс24 не подтвердил перенос: `Bitrix24 did not confirm the move; reread the task before retrying` |
| 422 | `BITRIX_ERROR` | После переноса по канбану группы задача не на запрошенной стадии: `Bitrix24 did not move the task to the requested stage; reread the task before retrying` |
| 422 | `BITRIX_ERROR` | Битрикс24 отклонил перенос, текст в `message` |

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

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

- **«Мой план» не зависит от канбана группы.** Перенос по «Моему плану» не меняет `stageId` задачи в группе. Позицию задачи в плане читают фильтром `filter[stagesId]=<ID стадии>` в [списке задач](/docs/entities/tasks/list).
- **В «Мой план» задачи не добавляются.** В плане есть только задачи, где владелец ключа участвует, например постановщик или ответственный.
- **Порядок в канбане группы общий.** Карточки группы видят в одном порядке все её участники, поэтому `beforeTaskId` и `afterTaskId` меняют доску для всех.
- **Задачи спринта Scrum переносятся другим методом.** Для доски спринта используйте [этапы Scrum-канбана](/docs/scrum/stages).

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

- [Задачи: канбан, «Мой план» и план дня](/docs/tasks)
- [Стадии канбана задач](/docs/task-stages)
- [Прочитать право сортировать канбан](/docs/tasks/stages-can-move)
- [Список задач](/docs/entities/tasks/list)
- [Этапы Scrum-канбана](/docs/scrum/stages)