## Удалить блок

`DELETE /v1/pages/:pageId/blocks/:blockId`

Переносит блок страницы в корзину этой страницы. Удаление обратимо: пока блок лежит в корзине, его можно вернуть на страницу методом восстановления.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|----------|
| `pageId` (path) | number | да | ID страницы. Список: [`GET /v1/pages`](/docs/entities/pages/list) |
| `blockId` (path) | number | да | ID блока из черновика страницы. Список: [`GET /v1/pages/:pageId/blocks`](/docs/entities/pages/blocks/list) без параметра `version`. ID блоков опубликованной версии здесь не принимаются |
| `scope` (query) | string | нет | Тип сайта: `KNOWLEDGE` — база знаний, `GROUP` — сайт рабочей группы, `MAINPAGE` — главная страница. Для страниц остальных сайтов параметр не передают |

## Примеры

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

```bash
curl -X DELETE "https://vibecode.bitrix24.tech/v1/pages/20/blocks/30" \
  -H "X-Api-Key: YOUR_API_KEY"
```

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

```bash
curl -X DELETE "https://vibecode.bitrix24.tech/v1/pages/20/blocks/30" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/pages/20/blocks/30', {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})
const body = await res.json()

if (body.success) {
  console.log('Блок в корзине, вернуть:', body.data.restoreWith)
}
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/pages/20/blocks/30', {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const body = await res.json()

if (body.success) {
  console.log('Блок в корзине, вернуть:', body.data.restoreWith)
}
```

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

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | `true` — блок перенесён в корзину |
| `data.id` | number | ID удалённого блока |
| `data.deleted` | boolean | Всегда `true`: блок лежит в корзине страницы |
| `data.version` | string | Версия страницы, которую изменил вызов. Всегда `draft` — черновик |
| `data.published` | boolean | Всегда `false`: опубликованная версия страницы не изменилась |
| `data.publishWith` | string | Вызов, который публикует черновик страницы, с подставленным ID страницы |
| `data.restoreWith` | string | Вызов, который возвращает этот блок из корзины, с подставленными ID страницы и блока |

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

```json
{
  "success": true,
  "data": {
    "id": 30,
    "deleted": true,
    "version": "draft",
    "published": false,
    "publishWith": "POST /v1/pages/20/publication",
    "restoreWith": "POST /v1/pages/20/blocks/30/restore"
  }
}
```

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

404 — блока нет в черновике страницы, например он уже в корзине:

```json
{
  "success": false,
  "error": {
    "code": "BLOCK_NOT_IN_DRAFT",
    "message": "No such block in this page's draft. Ids come from GET /v1/pages/{pageId}/blocks, which reads the draft by default; ids from the published version are not accepted here."
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `INVALID_PAGE_ID` | `pageId` не положительное целое число |
| 400 | `INVALID_BLOCK_ID` | `blockId` не положительное целое число |
| 400 | `INVALID_SCOPE` | `scope` вне списка `KNOWLEDGE`, `GROUP`, `MAINPAGE` |
| 400 | `INVALID_PARAMS` | Битрикс24 отклонил запрос: не хватает обязательного параметра |
| 404 | `BLOCK_NOT_IN_DRAFT` | Блока с таким ID нет в черновике страницы: блок уже в корзине, ID взят из опубликованной версии или не существует |
| 404 | `ENTITY_NOT_FOUND` | Страницы нет или она не видна ключу. Для страницы базы знаний, рабочей группы или главной страницы нужен параметр `scope` |
| 404 | `ENTITY_NOT_FOUND` | Проверка черновика нашла блок, но при переносе в корзину Битрикс24 ответил, что блока на странице нет |
| 502 | `BLOCK_LIST_UNCONFIRMED` | Битрикс24 не вернул черновик страницы, блок не удалось проверить до удаления. Блок не тронут |
| 502 | `BLOCK_DELETE_UNCONFIRMED` | Битрикс24 не подтвердил перенос в корзину. Перед повтором проверьте корзину запросом с `?deleted=true` |
| 403 | `BITRIX_ACCESS_DENIED` | У сотрудника, под которым выпущен ключ, нет прав на страницу в Битрикс24 |
| 422 | `BITRIX_ERROR` | Битрикс24 отклонил запрос, текст ошибки — в `message` |
| 403 | `SCOPE_DENIED` | У ключа нет скоупа `landing` |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ в режиме только для чтения |
| 401 | `TOKEN_MISSING` | У ключа нет настроенных токенов Битрикс24 |

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

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

- **Блок в корзине выпадает из черновика.** Заменить его разметку через [`PATCH /v1/pages/:pageId/blocks/:blockId`](/docs/entities/pages/blocks/update) нельзя до восстановления: ответ `404 BLOCK_NOT_IN_DRAFT`. Найти блок можно в списке [`GET /v1/pages/:pageId/blocks?deleted=true`](/docs/entities/pages/blocks/list).
- **Повтор после потерянного ответа.** Повторный вызов для блока, который уже в корзине, возвращает `404 BLOCK_NOT_IN_DRAFT`, а не успех. Чтобы понять, сработал ли первый вызов, ищите блок в списке с `?deleted=true`.
- **Необратимое удаление — отдельный метод.** Этот вызов только переносит блок в корзину. Удалить блок без возможности восстановления — [Удалить блок навсегда](/docs/entities/pages/blocks/purge).

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

- [Восстановить блок](/docs/entities/pages/blocks/restore)
- [Список блоков страницы](/docs/entities/pages/blocks/list)
- [Удалить блок навсегда](/docs/entities/pages/blocks/purge)
- [Страницы](/docs/entities/pages)
- [Ошибки](/docs/errors)