Как подготовить пользовательский шаблон

Scope: landing

Кто может выполнять методы: чтобы пройти сценарий целиком, нужно самое строгое из перечисленных прав — право «экспорт» сайтов

landing.site.fullExport — пользователь с правом «экспорт» сайтов

landing.demos.register и landing.demos.getList — пользователь с правом Просмотр в разделе Сайты

Выберите инструмент для разработки с AI-агентом:

используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Пользовательский шаблон — это готовая заготовка сайта или страницы, которую можно добавить в мастер создания сайтов. Мастер — это экран, на котором пользователь Битрикс24 выбирает оформление при создании нового сайта или страницы. Свой шаблон появляется в этом списке после того, как приложение его зарегистрирует.

Шаблон создают на основе уже готового сайта или страницы из раздела Сайты. Сначала сайт экспортируют — выгружают его структуру в набор данных, который можно сохранить и передать дальше. Затем этот набор регистрируют методами landing.demos.* из приложения Битрикс24.

Проверяемый результат: шаблон зарегистрирован для приложения, возвращается методом landing.demos.getList и отображается в мастере создания сайта или страницы.

Сценарий состоит из трех шагов:

Экспортировать готовый сайт методом landing.site.fullExport
Передать результат экспорта в landing.demos.register
Проверить регистрацию методом landing.demos.getList

Порядок вызовов важен: landing.demos.register принимает объект result, который возвращает landing.site.fullExport, а landing.demos.getList проверяет результат регистрации.

Когда использовать пользовательский шаблон

Используйте пользовательский шаблон, если нужно:

добавить собственный шаблон в мастер создания сайтов
распространять готовый сайт или страницу через приложение
повторно использовать один и тот же набор страниц, блоков и настроек

Если шаблон нужно только установить в одном Битрикс24 без повторного использования, достаточно создать и настроить сайт или страницу обычным способом.

Если шаблон распространяется как приложение с сайтом, смотрите статьи Установка шаблонов сайтов и Требования к сайтам перед публикацией.

Как устроен пользовательский шаблон

Шаблон собирается из трех частей, связанных между собой:

исходный сайт или страница — основа шаблона, ее готовят в разделе Сайты
экспорт — структура сайта в виде данных, которую создает метод landing.site.fullExport
зарегистрированный шаблон — запись, которая появляется в мастере после вызова landing.demos.register

Методы landing.demos.* выполняют отдельные операции с шаблоном:

landing.demos.register — регистрирует шаблон в мастере создания сайта и страницы
landing.demos.getList — возвращает зарегистрированные шаблоны и позволяет проверить результат регистрации. Если метод вызван из приложения, в ответ попадают только шаблоны этого приложения
landing.demos.getSiteList — возвращает шаблоны сайтов, которые доступны в мастере для выбранного типа сайта. В список попадают и встроенные шаблоны Битрикс24, и подходящие шаблоны, которые вы зарегистрировали. Например, для типа store метод вернет шаблоны интернет-магазинов
landing.demos.getPageList — возвращает шаблоны страниц, которые доступны в мастере для выбранного типа сайта
landing.demos.unregister — удаляет зарегистрированный шаблон

Как подготовить шаблон

Перед экспортом проверьте сам сайт:

страницы связаны между собой корректно
используются нужные блоки и темы
изображения и внешние ресурсы доступны по рабочим URL
название, описание и изображения предпросмотра подготовлены для шаблона

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

Подготовьте данные

Перед началом подготовьте:

идентификатор сайта, который станет основой шаблона
внешний код шаблона, например myfirstsite2026
URL опубликованной страницы для preview_url
установленное приложение с OAuth-авторизацией и правом landing
установленный и инициализированный SDK: B24JsSDK, B24PhpSDK или B24PySDK

Идентификатор сайта можно получить методом landing.site.getList или из результата метода landing.site.add. Внешний код должен содержать только строчные латинские буквы и цифры без разделителей.

В примерах замените 326, myfirstsite2026 и URL предпросмотра своими значениями. Выполняйте примеры выбранной вкладки последовательно в одном скрипте: переменная с результатом экспорта используется на следующем шаге.

OAuth-токен дает доступ к Битрикс24. Храните его в настройках приложения или переменных окружения и не добавляйте в исходный код.

1. Экспортируйте сайт

Вызовите landing.site.fullExport. В параметре id передайте идентификатор сайта, а в params.code — внешний код шаблона. Метод вернет полную структуру сайта в поле result.

Как использовать примеры в документации

PHP

Python

// $b24 — предварительно инициализированный экземпляр B24JsSDK
const exportResponse = await $b24.actions.v2.call.make({
  method: 'landing.site.fullExport',
  params: {
    id: 326,
    params: {
      code: 'myfirstsite2026',
      name: 'Сайт автомастерской',
      preview_url: 'https://example.com/previews/myfirstsite2026'
    }
  }
})

if (!exportResponse.isSuccess) {
  throw new Error(exportResponse.getErrorMessages().join('; '))
}

const exportData = exportResponse.getData().result

// $b24Service — предварительно инициализированный B24PhpSDK
$response = $b24Service->core->call(
    'landing.site.fullExport',
    [
        'id' => 326,
        'params' => [
            'code' => 'myfirstsite2026',
            'name' => 'Сайт автомастерской',
            'preview_url' => 'https://example.com/previews/myfirstsite2026',
        ],
    ]
);

$exportData = $response->getResponseData()->getResult();

# client — предварительно инициализированный B24PySDK
export_data = client.landing.site.full_export(
    bitrix_id=326,
    params={
        "code": "myfirstsite2026",
        "name": "Сайт автомастерской",
        "preview_url": "https://example.com/previews/myfirstsite2026",
    },
).response.result

Сокращенный ответ:

{
    "result": {
        "charset": "UTF-8",
        "code": "myfirstsite2026",
        "name": "Сайт автомастерской",
        "type": "page",
        "version": 3,
        "items": {
            "myfirstsite2026": {
                "code": "myfirstsite2026",
                "name": "Сайт автомастерской",
                "type": "page",
                "version": 3,
                "items": {}
            }
        }
    }
}

Сохраните весь объект result, а не только отдельные поля. Переменные exportData, $exportData и export_data содержат данные для следующего шага.

2. Зарегистрируйте шаблон

Передайте сохраненный объект экспорта в параметр data метода landing.demos.register. Не перестраивайте структуру вручную: в ней уже есть внешний код code, карта страниц items, поля, блоки и настройки сайта.

Примеры продолжают код первого шага.

PHP

Python

const registerResponse = await $b24.actions.v2.call.make({
  method: 'landing.demos.register',
  params: {
    data: exportData
  }
})

if (!registerResponse.isSuccess) {
  throw new Error(registerResponse.getErrorMessages().join('; '))
}

const registeredTemplateIds = registerResponse.getData().result
if (registeredTemplateIds.length === 0) {
  throw new Error('Шаблон не зарегистрирован')
}

$response = $b24Service->core->call(
    'landing.demos.register',
    [
        'data' => $exportData,
    ]
);

$registeredTemplateIds = $response->getResponseData()->getResult();
if ($registeredTemplateIds === []) {
    throw new RuntimeException('Шаблон не зарегистрирован');
}

registered_template_ids = client.landing.demos.register(
    data=export_data,
).response.result

if not registered_template_ids:
    raise RuntimeError("Шаблон не зарегистрирован")

Успешный ответ содержит идентификаторы созданных или обновленных шаблонов:

{
    "result": [5]
}

Сохраните массив result. Если он пуст, не переходите к проверке в интерфейсе и проверьте данные запроса.

3. Проверьте регистрацию шаблона

Вызовите landing.demos.getList и найдите запись с внешним кодом XML_ID, равным myfirstsite2026. Метод, вызванный из приложения, возвращает только шаблоны этого приложения.

PHP

Python

const listResponse = await $b24.actions.v2.call.make({
  method: 'landing.demos.getList',
  params: {
    params: {
      select: ['ID', 'XML_ID', 'TITLE', 'TYPE']
    }
  }
})

if (!listResponse.isSuccess) {
  throw new Error(listResponse.getErrorMessages().join('; '))
}

const template = listResponse
  .getData()
  .result
  .find((item) => item.XML_ID === 'myfirstsite2026')

if (!template) {
  throw new Error('Шаблон не найден')
}

$response = $b24Service->core->call(
    'landing.demos.getList',
    [
        'params' => [
            'select' => ['ID', 'XML_ID', 'TITLE', 'TYPE'],
        ],
    ]
);

$templates = $response->getResponseData()->getResult();
$template = array_values(array_filter(
    $templates,
    static fn(array $item): bool => $item['XML_ID'] === 'myfirstsite2026'
))[0] ?? null;
if ($template === null) {
    throw new RuntimeException('Шаблон не найден');
}

templates = client.landing.demos.get_list(
    params={
        "select": ["ID", "XML_ID", "TITLE", "TYPE"],
    },
).response.result

template = next(
    (item for item in templates if item["XML_ID"] == "myfirstsite2026"),
    None,
)

if template is None:
    raise RuntimeError("Шаблон не найден")

Сокращенный ответ:

{
    "result": [
        {
            "ID": "5",
            "XML_ID": "myfirstsite2026",
            "TITLE": "Сайт автомастерской",
            "TYPE": "page"
        }
    ]
}

Проверим результат

Сценарий выполнен успешно, если:

landing.demos.register вернул непустой массив идентификаторов
landing.demos.getList вернул шаблон с ожидаемыми значениями XML_ID, TITLE и TYPE
шаблон появился в мастере создания сайта или страницы и открывается его предпросмотр

Ошибки и диагностика

Если метод вернул ошибку или результат сценария не соответствует ожидаемому, проверьте данные запроса и права пользователя.

Код или текст ошибки	Причина и действие
`BX_EMPTY_REQUIRED`	На втором шаге не заполнено обязательное поле. Проверьте `data.code` и поле `code` у каждой страницы в `data.items`
`REGISTER_ERROR_DATA`	На втором шаге переданы некорректные данные. Передайте в `data` весь объект `result` из `landing.site.fullExport`
`CONTENT_IS_BAD`	Содержимое шаблона не прошло проверку. Проверьте его методом `landing.repo.checkcontent`, затем повторите регистрацию
`AI_SITE_EXPORT_NOT_ALLOWED`	Экспорт AI-сайтов не поддерживается. На первом шаге выберите другой сайт
`ACCESS_DENIED`	На первом шаге проверьте право пользователя на «экспорт» сайтов, на втором и третьем — право Просмотр в разделе Сайты
`Шаблон не найден`	На третьем шаге проверьте `XML_ID`, контекст приложения и результат `landing.demos.register`, затем повторите третий шаг
`Предпросмотр не открывается`	Проверьте доступность `preview_url` без авторизации

Что важно учитывать

Для многостраничного сайта передавайте в data весь результат landing.site.fullExport, включая карту страниц items
Поле type задает назначение шаблона, а tpl_type — его место в мастере: S для сайта и P для страницы
Внешние изображения и preview_url должны оставаться доступными после регистрации шаблона
Передавайте OAuth-токены только через настройки приложения или переменные окружения, не добавляйте их в исходный код
Для локализации названия и описания передайте в landing.demos.register параметры lang и lang_original
Для удаления шаблона получите его внешний код XML_ID методом landing.demos.getList и передайте код в landing.demos.unregister

Продолжите изучение

Была ли статья полезна?

Обзор методов

Локализация

Как подготовить пользовательский шаблон

Когда использовать пользовательский шаблонКогда использовать пользовательский шаблон

Как устроен пользовательский шаблонКак устроен пользовательский шаблон

Как подготовить шаблонКак подготовить шаблон

Подготовьте данныеПодготовьте данные

1. Экспортируйте сайт1. Экспортируйте сайт

2. Зарегистрируйте шаблон2. Зарегистрируйте шаблон

3. Проверьте регистрацию шаблона3. Проверьте регистрацию шаблона

Проверим результатПроверим результат

Ошибки и диагностикаОшибки и диагностика

Что важно учитыватьЧто важно учитывать

Продолжите изучениеПродолжите изучение

Была ли статья полезна?

Когда использовать пользовательский шаблон

Как устроен пользовательский шаблон

Как подготовить шаблон

Подготовьте данные

1. Экспортируйте сайт

2. Зарегистрируйте шаблон

3. Проверьте регистрацию шаблона

Проверим результат

Ошибки и диагностика

Что важно учитывать

Продолжите изучение