# Сайты

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

База знаний 2.0 создаётся и управляется через те же методы с дополнительным параметром `scope: "KNOWLEDGE"` (см. [создание](./sites/create.md)).

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

## Операции

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

## Поля

### Изменяемые поля

Принимаются при [создании](./sites/create.md) и [обновлении](./sites/update.md).

| Поле | Тип | Описание |
|------|-----|---------|
| `title` | string | Название сайта, до 255 символов |
| `code` | string | Символьный код сайта в URL. Если оставить пустым при создании — генерируется из `title`. Если код состоит только из цифр, добавляется префикс `site` |
| `type` | string | Тип сайта: `PAGE` — лендинг, `STORE` — интернет-магазин, `KNOWLEDGE` — база знаний 2.0. Для `KNOWLEDGE` при создании и изменении нужен `scope: "KNOWLEDGE"`. В ответах у сайтов, созданных вне API, встречаются и другие значения — см. «Что нужно знать перед работой» |
| `active` | boolean | Только для чтения: через API не устанавливается, запрос с этим полем отклоняется с `400 READONLY_FIELD`. Новый сайт неактивен, активируется при публикации в интерфейсе портала Битрикс24 |
| `domainId` | number | Идентификатор домена. Если не передать при создании — адрес формируется из `code` |
| `description` | string \| null | Описание сайта, до 255 символов. В ответе приходит `null`, если не задано |
| `xmlId` | string \| null | Внешний идентификатор, до 255 символов. В ответе приходит `null`, если не задан |
| `landingIdIndex` | number \| null | Идентификатор главной страницы. Задаётся только в обновлении — после создания страниц. `null`, если главная не назначена |
| `landingId404` | number \| null | Идентификатор страницы ошибки 404. Задаётся только в обновлении. Если не назначена — `0` или `null` |
| `landingId503` | number \| null | Идентификатор страницы ошибки 503. Задаётся только в обновлении. Если не назначена — `0` или `null` |

### Только для чтения

Приходят в ответе, но не принимаются при создании и обновлении.

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | number | Идентификатор сайта |
| `deleted` | string | Признак нахождения в корзине: `"Y"` / `"N"`. Доступен в фильтре (`filter[deleted]=Y`) |
| `createdById` | number | Идентификатор создавшего пользователя |
| `modifiedById` | number | Идентификатор пользователя, изменившего сайт последним |
| `dateCreate` | datetime | Дата создания. Формат локали Битрикс24, не ISO 8601 — см. «Что нужно знать перед работой» |
| `dateModify` | datetime | Дата последнего изменения. Формат локали Битрикс24, не ISO 8601 |
| `tplId` | number | Идентификатор шаблона сайта |
| `tplCode` | string \| null | Символьный код шаблона сайта. `null`, если у шаблона нет кода |
| `smnSiteId` | string \| null | Идентификатор связанного сайта «Управление сайтом» типа `SMN`. `null` у обычных сайтов |
| `lang` | string \| null | Код языка сайта, например `ru`. `null`, если язык не задан |
| `special` | string | Служебный признак Битрикс24: `"Y"` / `"N"` |
| `version` | number | Версия внутренней структуры сайта |

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

1. **Тело запроса плоское.** При создании и обновлении передавайте поля прямо в корне JSON: `{"title": "...", "code": "..."}`. Обёртка `fields` не нужна.
2. **Удалить можно только пустой сайт.** Если у сайта есть хотя бы одна страница (включая страницы в корзине), `DELETE /v1/sites/:id` вернёт ошибку `BITRIX_ERROR` с описанием «Сайт содержит страницы». Сначала удалите страницы, затем сам сайт.
3. **Видимость зависит от прав пользователя.** Список и агрегация возвращают только те сайты, к которым у владельца API-ключа есть право «просмотр». Если на портале есть сайты, но ответ пустой — проверьте права пользователя, под которым выпущен ключ.
4. **Корзина — `filter[deleted]=Y`.** По умолчанию удалённые сайты не возвращаются. Чтобы получить сайты в корзине, добавьте в фильтр `deleted=Y`. Значения — `Y` или `N`.
5. **Полный список полей — [`GET /v1/sites/fields`](./sites/fields.md).** Эндпоинт возвращает карту всех 22 полей с типом, признаком `readonly`, подписью, описанием и признаком `nullable` у полей, которые могут прийти со значением `null`. У поля `type` дополнительно приходит перечень допустимых значений `enum`. Рядом с картой полей возвращается список `aggregatable` — поля, по которым доступна группировка в агрегации. Перечень с описаниями приведён в разделе «Поля» выше.
6. **Формат дат — локаль-зависимый, не ISO 8601.** Поля `dateCreate` и `dateModify` приходят строкой в локальном формате портала: на RU-локали — `ДД.ММ.ГГГГ ЧЧ:ММ:СС` (`30.12.2021 12:30:52`), на EN-локали — `MM/DD/YYYY hh:mm:ss am/pm` (`04/22/2020 02:39:17 pm`). Значение возвращается как есть, без приведения к ISO. `new Date(value)` вернёт `Invalid Date` либо перепутает день и месяц — не разбирайте дату по фиксированному шаблону, ориентируйтесь на региональные настройки портала.
7. **Поле `type` в ответах шире, чем при создании.** Через API создаются сайты типов `PAGE`, `STORE`, `KNOWLEDGE`. В ответах у сайтов, собранных другими средствами, встречаются и другие значения — `VIBE` (сайт из конструктора) и `SMN` (связка с модулем «Управление сайтом»). Эти два типа возвращаются только для чтения. Полный перечень значений теперь покрыт схемой — [`GET /v1/sites/fields`](./sites/fields.md) отдаёт их в `type.enum` с подписями.
8. **Отсутствие значения — `null` или `0`.** Значение может отсутствовать у восьми полей — у них в схеме стоит `nullable`. Строковые `description`, `xmlId`, `tplCode`, `smnSiteId`, `lang` приходят как `null`. Числовые идентификаторы страниц `landingIdIndex`, `landingId404`, `landingId503` — как `0` или `null`. Проверяйте оба варианта.
9. **Фильтр по `code` — со слешами.** В фильтре значение `code` сравнивается с хранимой формой, обрамлённой слешами: `filter[code]=/my-code/` находит сайт, голое `filter[code]=my-code` — нет. Используйте то значение `code`, которое сайт отдаёт в ответе.

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

| Сущность | Эндпоинт | Назначение |
|----------|----------|-----------|
| Страницы | [`GET /v1/pages`](/docs/entities/pages) | Страницы сайта. Получите список страниц с `filter[siteId]=:id` перед удалением сайта или для редактирования содержимого. |

## Лимиты

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

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

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