# Страницы

Управление страницами лендингов и интернет-магазинов на платформе Битрикс24: создание, получение, обновление, удаление. Страница всегда принадлежит сайту и наследует от него тип `PAGE` или `STORE`.

Битрикс24 API: `landing.landing.*`
Скоуп: `landing`

## Операции

- [Создать страницу](./pages/create.md) — `POST /v1/pages`
- [Список страниц](./pages/list.md) — `GET /v1/pages`
- [Получить страницу](./pages/get.md) — `GET /v1/pages/:id`
- [Обновить страницу](./pages/update.md) — `PATCH /v1/pages/:id`
- [Удалить страницу](./pages/delete.md) — `DELETE /v1/pages/:id`
- [Поиск страниц](./pages/search.md) — `POST /v1/pages/search`
- [Поля страницы](./pages/fields.md) — `GET /v1/pages/fields`
- [Агрегация страниц](./pages/aggregate.md) — `POST /v1/pages/aggregate`

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

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | number | Идентификатор страницы (только чтение) |
| `title` | string | Название страницы, до 255 символов. Обязательно при создании |
| `code` | string | Символьный код страницы в URL. Если не передавать — генерируется из `title`. Не должен содержать `/`. Внутри сайта или папки должен быть уникальным — иначе автоматически добавляется числовой суффикс |
| `siteId` | number | Идентификатор сайта, которому принадлежит страница. Источник: [`GET /v1/sites`](/docs/entities/sites/list). Обязательно при создании |
| `active` | boolean | Опубликована ли страница. Только для чтения: новые страницы создаются неактивными, публикация — отдельными вызовами `POST /v1/pages/:id/publication` и `POST /v1/pages/:id/unpublish` |
| `description` | string \| null | Произвольное описание страницы. Приходит `null`, если не задано (в операционных доках [get](./pages/get.md) / [list](./pages/list.md) тип уже `string \| null` — здесь приведено к ним для единообразия) |
| `createdById` | number | Идентификатор создавшего сотрудника (только чтение). Источник: [`GET /v1/users`](/docs/entities/users) |
| `dateCreate` | datetime | Дата создания (только чтение) |
| `dateModify` | datetime | Дата последнего изменения (только чтение) |

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

1. **Тело запроса плоское.** При создании и обновлении передавайте поля прямо в корне JSON: `{"title": "...", "code": "...", "siteId": 3}`. Обёртка `fields` не нужна.
2. **Минимум для создания:** `title` + `siteId`. Остальные поля опциональны.
3. **Публикация — отдельные вызовы, поле `active` в теле не принимается.** При создании страница получает `active: false`. Передача `active` в `POST` или `PATCH` отклоняется с `400 READONLY_FIELD`, причём вместе с ним не применяется и остальное тело запроса. Опубликовать страницу — `POST /v1/pages/:id/publication`, снять с публикации — `POST /v1/pages/:id/unpublish`. Для страниц базы знаний, рабочих групп и главных страниц обоим вызовам нужен параметр `scope` со значением `KNOWLEDGE`, `GROUP` или `MAINPAGE` — без него страница не находится и приходит `404`. Обычным страницам сайта параметр не нужен.
4. **Полный список полей — [`GET /v1/pages/fields`](./pages/fields.md).** Эндпоинт возвращает карту всех полей страницы с типом, признаком `readonly`, подписью и — у девяти полей, которые могут прийти со значением `null`, — признаком `nullable`. Ключевые поля приведены в разделе «Ключевые поля» выше, полный перечень из 27 полей — на странице [Поля страницы](./pages/fields.md).
5. **Ответ может содержать дополнительные поля Битрикс24 — в camelCase.** Помимо ключевых полей, по умолчанию возвращаются дополнительные — в **camelCase**, **не** в `UPPER_CASE`: `deleted`, `xmlId`, `tplId`, `sitemap`, `folder`, `folderId`, `searchContent`, `modifiedById`, `domainId`, `initiatorAppCode`, `rule`, `public`, `sys`, `views`, `tplCode`, `version`, `historyStep`, `datePublic` и другие. Чтение по документированному имени `data[].XML_ID` / `MODIFIED_BY_ID` вернёт `undefined` — используйте camelCase. Чтобы получить только ключевые поля, передавайте параметр `select` в `GET /v1/pages`: `?select=id,title,code,siteId,active,description,createdById,dateCreate,dateModify`. См. примеры в [Списке страниц](./pages/list.md). Для `GET /v1/pages/:id` параметр `select` не применяется — отбор полей доступен только в списке.
   - Поле `datePublic` приходит `null`, если у Битрикс24 нет даты публикации по странице, — это обычный случай и для опубликованной страницы, поэтому признаком публикации оно не является. Публикацию определяйте по `active` или `public`. Описание поля — в [Полях страницы](./pages/fields.md).
6. **`offset` для постраничного перехода поддерживается.** Вайбкод возвращает запрошенное окно `[offset, offset + limit)`. Значение `meta.total` — точное число записей под фильтром. Для больших выборок также работает `limit > 50`.
7. **Сортировка поддерживается.** `?order[поле]=asc|desc` или короткая форма `?sort=-поле` (по убыванию), в теле [`POST /v1/pages/search`](./pages/search.md) — поле `sort`. Без параметра выборка идёт по возрастанию `id`. Для подсчёта количества страниц используйте `meta.total` из [Списка страниц](./pages/list.md): `GET /v1/pages?filter[siteId]=3&limit=1` вернёт `meta.total` без выгрузки записей.
8. **Формат дат — локаль-зависимый, не ISO 8601.** Поля `dateCreate`, `dateModify` и `datePublic` приходят строкой в локальном формате портала: на RU-локали — `ДД.ММ.ГГГГ ЧЧ:ММ:СС` (`30.12.2021 12:30:52`), на EN-локали — `MM/DD/YYYY hh:mm:ss am/pm` (`12/30/2021 12:30:52 pm`). Значение возвращается как есть, одинаково в списке и в карточке. `new Date(value)` вернёт `Invalid Date` либо перепутает день и месяц — не разбирайте дату по фиксированному шаблону. Тот же формат нужен и в фильтре: значение в формате другой локали или в ISO Битрикс24 не распознаёт и возвращает пустой список с кодом 200.

## Связанные сущности

| Сущность | Эндпоинт | Назначение |
|----------|----------|-----------|
| Сайты | [`GET /v1/sites`](/docs/entities/sites) | Контейнеры страниц. Источник `siteId` для создания страницы. Удалить сайт можно только после удаления всех его страниц. |

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

1. Найти сайт: [`GET /v1/sites`](/docs/entities/sites/list).
2. Посмотреть его страницы: [`GET /v1/pages?filter[siteId]=3`](./pages/list.md).
3. Создать новую или обновить существующую: [`POST /v1/pages`](./pages/create.md) / [`PATCH /v1/pages/:id`](./pages/update.md).
4. Удалить ненужные: [`DELETE /v1/pages/:id`](./pages/delete.md).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Максимум записей на запрос | 5000 (`limit ≤ 5000`) |
| Постраничный переход | через `offset` — окно `[offset, offset + limit)` |
| `offset` | поддерживается — окно `[offset, offset + limit)` применяется на стороне Вайбкод |
| Batch-запросы | до 50 операций в [`POST /v1/batch`](/docs/batch) |
| Rate limit | общий для API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [Сайты](/docs/entities/sites)
- [Entity API](/docs/entity-api)
- [Синтаксис фильтрации](/docs/filtering)
- [Batch](/docs/batch)
- [Справочник API](/docs/api-reference)