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

Заменить разметку блока

PATCH /v1/pages/:pageId/blocks/:blockId

Заменяет HTML-разметку блока на странице лендинга целиком: новая разметка не объединяется с текущей.

Поля передаются плоско в корне JSON, без обёртки fields. Работа со страницами и их блоками — в разделе Страницы.

Параметры

Параметр Тип Обяз. Описание
pageId (path) number да ID страницы. Список: GET /v1/pages
blockId (path) number да ID блока в черновике страницы. Список: GET /v1/pages/:pageId/blocks — по умолчанию читает черновик. ID из ?version=published и ID блоков в корзине не подходят
scope (query) string нет Раздел Битрикс24, к которому относится страница: KNOWLEDGE — база знаний, GROUP — база знаний группы, MAINPAGE — главная страница. Для страницы обычного сайта не передаётся

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

Поле Тип Обяз. Описание
content string да Новая HTML-разметка блока. Заменяет текущую полностью
designed boolean нет Признак блока с собственным оформлением. По умолчанию false. Принимаются также строки "true", "false", "1", "0" и числа 1, 0. Блок, который такой признак не поддерживает, отвечает 422 BLOCK_DESIGN_NOT_SUPPORTED

Примеры

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

Terminal 
curl -X PATCH "https://vibecode.bitrix24.tech/v1/pages/20/blocks/32" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "<section class=\"landing-block\"><div class=\"container\"><h2>Updated</h2><p>Second line</p></div></section>"
  }'

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

Terminal 
curl -X PATCH "https://vibecode.bitrix24.tech/v1/pages/20/blocks/32" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "<section class=\"landing-block\"><div class=\"container\"><h2>Updated</h2><p>Second line</p></div></section>"
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/pages/20/blocks/32', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    content: '<section class="landing-block"><div class="container"><h2>Updated</h2><p>Second line</p></div></section>',
  }),
})

const { success, data } = await res.json()
console.log('Publish with:', data.publishWith)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/pages/20/blocks/32', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    content: '<section class="landing-block"><div class="container"><h2>Updated</h2><p>Second line</p></div></section>',
  }),
})

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

Поля ответа

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

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

JSON 
{
  "success": true,
  "data": {
    "id": 32,
    "version": "draft",
    "published": false,
    "publishWith": "POST /v1/pages/20/publication"
  }
}

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

404 — блока с таким ID нет в черновике страницы:

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 MISSING_BLOCK_CONTENT Не передан content или передан не строкой
400 INVALID_DESIGNED designed не является логическим значением
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 ответил, что блока на странице нет
422 BLOCK_DESIGN_NOT_SUPPORTED Передан designed: true, а блок не поддерживает признак собственного оформления. Повторите запрос без designed
502 BLOCK_LIST_UNCONFIRMED Битрикс24 не вернул черновик страницы — наличие блока не проверено, разметка не изменена
502 BLOCK_CONTENT_UPDATE_UNCONFIRMED Битрикс24 не подтвердил замену разметки
403 BITRIX_ACCESS_DENIED У сотрудника, под которым выпущен ключ, нет прав на страницу в Битрикс24
422 BITRIX_ERROR Битрикс24 отклонил запрос, текст ошибки — в message
403 SCOPE_DENIED API-ключ не имеет скоупа landing
403 WRITE_BLOCKED_READONLY_KEY Ключ в режиме «только чтение»
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

Полный список общих ошибок API — Ошибки.

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

Обёртка блока сохраняется. После замены чтение GET /v1/pages/:pageId/blocks?content=true отдаёт новую разметку внутри прежнего элемента <div id="b<id>" class="block-wrapper …">.

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