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

Изменить области шаблона страницы

PATCH /v1/pages/:id/template-areas

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

Параметры

Параметр Тип Обяз. Описание
id (path) number да ID страницы. Список: GET /v1/pages
scope (query) string нет Внутренняя область лендингов: KNOWLEDGE / GROUP / MAINPAGE. Указывайте, если сайт страницы принадлежит соответствующей области. Иначе возвращается 404 ENTITY_NOT_FOUND. Для обычного сайта не передаётся

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

Поле Тип Обяз. Описание
areas object да Изменяемые области, хотя бы одна. Ключ — номер области: целое число со знаком от -2147483648 до 2147483647, включая 0. Значение — ID страницы, которая встанет в область, или null, чтобы снять привязку с этой области. Список страниц: GET /v1/pages

Других полей тело не принимает: лишнее поле отвечает 400 INVALID_PARAMS. Снять привязки со всех областей сразу — DELETE /v1/pages/:id/template-areas.

Примеры

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

Terminal 
curl -X PATCH "https://vibecode.bitrix24.tech/v1/pages/2381/template-areas" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"areas": {"1": 2387}}'

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

Terminal 
curl -X PATCH "https://vibecode.bitrix24.tech/v1/pages/2381/template-areas" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"areas": {"1": 2387}}'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/pages/2381/template-areas', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ areas: { 1: 2387 } }),
})

const { success, data } = await res.json()
console.log('Области страницы:', data.areas)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/pages/2381/template-areas', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ areas: { 1: 2387 } }),
})

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

Поля ответа

В ответе — все привязки страницы после изменения, а не только переданные.

Поле Тип Описание
success boolean Всегда true при успехе
data.areas object Привязки областей страницы. Ключ — номер области строкой в десятичной записи, значение — ID страницы. Получить страницу: GET /v1/pages/:id. Если после изменения привязок не осталось — пустой объект {}

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

JSON 
{
  "success": true,
  "data": {
    "areas": {
      "1": 2387
    }
  }
}

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

409 — в это же время идёт другая запись областей этой страницы:

JSON 
{
  "success": false,
  "error": {
    "code": "TEMPLATE_AREAS_BUSY",
    "message": "Another template-area update is in progress; retry"
  }
}

Ошибки

HTTP Код Описание
409 TEMPLATE_AREAS_BUSY Другой запрос через API в это же время меняет области этой страницы. Повторите запрос, когда та запись завершится
404 ENTITY_NOT_FOUND Entity not found or not visible — страница с таким ID не найдена, недоступна пользователю или лежит в другой области: передан не тот scope
404 ENTITY_NOT_FOUND Area page not found or not visible — страница из значения areas не найдена или недоступна пользователю
400 MISSING_REQUIRED_FIELDS В теле нет areas или areas — пустой объект
400 INVALID_PARAMS Area keys must be distinct signed 32-bit integers; page IDs must be positive safe integers; null removes an area — номер области не целое число или вне диапазона, два ключа дают один номер (1 и 01), значение не ID страницы и не null
400 INVALID_PARAMS id must be a positive safe integer — id не является положительным целым числом
400 INVALID_PARAMS Unsupported body field — в теле есть поле, кроме areas
400 INVALID_PARAMS Body must be a JSON object — тело не является JSON-объектом, например передан массив
400 INVALID_PARAMS Unsupported query parameter — передан query-параметр, которого метод не принимает
400 INVALID_SCOPE scope не равен KNOWLEDGE, GROUP или MAINPAGE
409 LANDING_MODULE_NOT_ENABLED Модуль «Сайты» недоступен на портале. Попросите администратора портала включить его — пока модуль выключен, повтор запроса вернёт тот же отказ
422 BITRIX_ERROR Bitrix24 did not save the template areas; settings permission may be missing — после записи области страницы не совпали с ожидаемыми. Проверьте, есть ли у пользователя право менять настройки страницы
422 BITRIX_ERROR Bitrix24 did not confirm the template-area change — Битрикс24 не подтвердил запись
422 BITRIX_ERROR Bitrix24 returned invalid template areas — Битрикс24 вернул области в неожиданном виде
403 WRITE_BLOCKED_READONLY_KEY Ключ работает в режиме только для чтения. Запрос отклоняется до обращения к порталу
403 SCOPE_DENIED API-ключ не имеет скоупа landing
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

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

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

  • Номер области не сверяется с раскладкой. Принимается любой номер из допустимого диапазона, даже если у раскладки страницы столько областей нет. Число областей каждой раскладки — на странице Шаблоны раскладки.
  • Ключи приходят в десятичной записи. Ключ 007 в ответе становится 7, +3 — 3.
  • Страница может быть с другого сайта. В область встаёт любая страница, которую видит пользователь, в том числе со стороннего сайта. Одна страница может занимать несколько областей.

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