# Области шаблона сайта

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

Битрикс24 API: `landing.template.getSiteRef`, `landing.template.setSiteRef`
Скоуп: `landing`

## Операции

- [Получить области шаблона сайта](./template-areas-list.md) — `GET /v1/sites/:id/template-areas`
- [Изменить области шаблона сайта](./template-areas-update.md) — `PATCH /v1/sites/:id/template-areas`
- [Очистить области шаблона сайта](./template-areas-delete.md) — `DELETE /v1/sites/:id/template-areas`

## Ключевые поля

Все три метода возвращают один объект — привязки сайта после вызова.

| Поле | Описание |
|------|----------|
| `areas` | Привязки областей. Ключ — номер области строкой, значение — ID страницы, которая встаёт в эту область. У сайта без привязок — пустой объект `{}` |
| номер области | Целое число со знаком от `-2147483648` до `2147483647`, включая `0`. В ответе приходит в десятичной записи: `007` становится `7` |
| ID страницы | ID любой страницы, которую видит пользователь, в том числе со стороннего сайта. Список страниц: [`GET /v1/pages`](/docs/entities/pages/list) |

## Что нужно знать перед работой

1. **Раскладка задаёт области, но номер с ней не сверяется.** Сколько областей у каждой раскладки, показывает страница [Шаблоны раскладки](/docs/entities/site-templates). Запись принимает любой номер из допустимого диапазона, даже если у раскладки столько областей нет.
2. **Раскладку сайта через API не поменять.** Поле `tplId` сайта только для чтения: [`PATCH /v1/sites/:id`](/docs/entities/sites/update) с ним отвечает `400 READONLY_FIELD`. Раскладку страницы меняет [`PATCH /v1/pages/:id`](/docs/entities/pages/update) с полем `tplId`.
3. **У сайта и у страницы свои наборы областей.** [Области шаблона страницы](/docs/entities/pages/template-areas) читаются и пишутся отдельно. Ответ сайта не содержит областей страниц, очистка областей сайта не трогает области страниц.
4. **Изменение сливается с текущим набором.** `PATCH` меняет только переданные области, значение `null` снимает привязку с одной области. Снять все привязки можно только через `DELETE`: пустой `areas` отвечает `400`.
5. **Запись проверяется перечитыванием.** Методы записи после изменения заново читают области и возвращают их. Если изменение не сохранилось, приходит `422 BITRIX_ERROR`, а не `200`.
6. **Одна запись за раз.** Пока идёт запись областей сайта, вторая запись тех же областей через API отвечает `409 TEMPLATE_AREAS_BUSY` — повторите её позже. Блокировка действует только между запросами API: правки в интерфейсе Битрикс24 она не учитывает.
7. **Сайт в отдельной области: база знаний, группа или область `MAINPAGE`.** Для такого сайта передавайте query-параметр `scope` со значением `KNOWLEDGE`, `GROUP` или `MAINPAGE` — без него сайт не находится и приходит `404`. Для обычного сайта `scope` не передаётся.

## Типичный сценарий

1. Найти сайт: [`GET /v1/sites`](/docs/entities/sites/list).
2. Найти страницы для шапки и подвала: [`GET /v1/pages?filter[siteId]=:id`](/docs/entities/pages/list).
3. Посмотреть текущие привязки: [`GET /v1/sites/:id/template-areas`](./template-areas-list.md).
4. Поставить страницы в области: [`PATCH /v1/sites/:id/template-areas`](./template-areas-update.md) с `{"areas": {"1": 2383, "2": 2385}}`.
5. Снять все привязки, когда они больше не нужны: [`DELETE /v1/sites/:id/template-areas`](./template-areas-delete.md).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Номер области | От `-2147483648` до `2147483647` |
| Одновременные записи | Одна на сайт. Вторая в это же время отвечает `409 TEMPLATE_AREAS_BUSY` |
| Частота запросов | Общие лимиты API — [Лимиты и оптимизация](/docs/optimization) |

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

- [Сайты](/docs/entities/sites)
- [Области шаблона страницы](/docs/entities/pages/template-areas)
- [Шаблоны раскладки](/docs/entities/site-templates)
- [Системные страницы](/docs/entities/sites/system-pages)
- [Лимиты и оптимизация](/docs/optimization)