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

Публикация и результаты

Получите код встраивания формы на сайт, настройте показ по кнопке и автоматический показ, узнайте, к каким виджетам на сайте и открытым линиям привязана форма, и отправьте данные посетителя в форму.

Битрикс24 API: crm.form.embedding.*, crm.form.sitebutton.list, crm.form.openline.list, crm.webform.result.add Скоуп: crm

Отправка данных посетителя использует REST v2. Встраивание и списки связей используют REST v3.

Получить коды встраивания формы

GET /v1/crm-forms/:id/embedding

Получите код встраивания формы или публичную ссылку для размещения на сайте. Параметры запроса меняют выбранный вариант без сохранения настроек.

Параметры

Параметр Тип Обяз. Описание
Параметрid (path) Типnumber Обяз.да ОписаниеПоложительный ID формы из списка форм
Параметрvariant (query) Типstring Обяз.нет Описаниеinline, click, auto, link. Без параметра — все настройки встраивания
ПараметрbuttonText (query) Типstring Обяз.нет ОписаниеПодпись кнопки для запрошенной встройки. Значение проверяет Битрикс24
ПараметрbuttonType (query) Типstring Обяз.нет ОписаниеТип кнопки, например button или link. Значение проверяет Битрикс24
Параметрdelay (query) Типinteger Обяз.нет ОписаниеЗадержка в секундах. Значение и сочетание с variant проверяет Битрикс24

Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/crm-forms/59/embedding?variant=link" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/crm-forms/59/embedding?variant=link" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-forms/59/embedding?variant=link', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

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

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-forms/59/embedding?variant=link', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue при успехе
Полеdata Типobject ОписаниеОбъект встраивания из Битрикс24 без пересборки. Без variant — доступные варианты и настройки. Для link — {variant, url}
Полеdata.formActive Типboolean ОписаниеАктивна ли форма
Полеdata.resourcesReady Типboolean ОписаниеГотовы ли ресурсы формы
Полеdata.publicUrl Типstring ОписаниеПубличная ссылка на форму вместе с публичной подписью
Полеdata.inline Типobject ОписаниеФорма внутри страницы
Полеdata.click Типobject ОписаниеФорма, открываемая по нажатию
Полеdata.auto Типobject ОписаниеФорма, открываемая через заданное время
Полеdata.<variant>.code Типstring / null ОписаниеHTML-код для размещения на сайте или null, если ресурсы не готовы
Полеdata.<variant>.previewUrl Типstring ОписаниеСсылка на предварительный просмотр, если она передана. Отсутствующие поля и null сохраняются
Полеdata.<variant>.settings Типobject / null ОписаниеТекущие настройки. См. Обновить настройки встраивания. Значения передаются как есть, включая null
Полеdata.<variant>.options Типobject / null ОписаниеДопустимые значения настроек из Битрикс24, включая null
Полеdata.<variant>.options.type Типstring[] Описаниеpopup, panel
Полеdata.<variant>.options.position Типstring[] Описаниеleft, center, right
Полеdata.<variant>.options.vertical Типstring[] Описаниеbottom, top
Полеdata.click.options.button.font Типstring[] Описаниеmodern, classic, elegant
Полеdata.click.options.button.align Типstring[] Описаниеinline, left, center, right
Полеdata.auto.options.delay Типnumber[] Описание3, 5, 7, 10, 15, 20, 25, 30, 40, 60, 120
Полеdata.variant Типstring ОписаниеВыбранный вариант, только при переданном variant
Полеdata.code Типstring / null ОписаниеКод выбранного HTML-варианта, включая null, если он передан
Полеdata.url Типstring ОписаниеПубличная ссылка при variant=link
Полеmeta.redacted Типstring[] ОписаниеПути с заменёнными учётными данными соединения. Такой ответ не является полной конфигурацией для обратного сохранения

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

Ответ при variant=link. Публичный домен и подпись в примере условные.

JSON 
{
  "success": true,
  "data": {
    "variant": "link",
    "url": "https://example.bitrix24.ru/crm_form_tz6sk/?telemetry_sign=DUMMY_PUBLIC_SIGNATURE"
  }
}

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

400 — ID формы не является положительным целым числом:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "id must be a positive safe integer"
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодINVALID_PARAMS ОписаниеНекорректный ID формы или структура запроса
HTTP400 КодINVALID_PARAMS ОписаниеНеизвестный параметр или некорректная структура запроса
HTTP400 КодINVALID_PARAMS ОписаниеБитрикс24 отклонил параметр или сочетание параметров. Исходный код — в error.b24Code, уточнения по полям — в error.validation, если переданы
HTTP409 КодCRM_FORM_REST_NOT_ENABLED ОписаниеREST-методы CRM-форм выключены на портале. Исходный код отсутствующего метода — в error.b24Code
HTTP403 КодBITRIX_INSUFFICIENT_SCOPE ОписаниеТокену Битрикс24 не хватает скоупа. Исходный код — в error.b24Code
HTTP404 КодENTITY_NOT_FOUND ОписаниеФорма не найдена
HTTP403 КодSCOPE_DENIED ОписаниеAPI-ключ не имеет скоупа crm
HTTP403 КодBITRIX_ACCESS_DENIED ОписаниеУ пользователя нет прав доступа
HTTP401 КодTOKEN_MISSING ОписаниеУ API-ключа не настроены учётные данные
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеНекорректный ответ с данными встраивания

Ошибки Битрикс24 содержат исходный error.b24Code и переданные уточнения по полям в error.validation. Общие ошибки API — Ошибки.

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

Если ресурсы не готовы, ответ остаётся успешным с resourcesReady: false и переданным значением code: null. Отсутствующие поля не заполняются. Публичные подписи сохраняются. Заменяются только учётные данные текущего соединения, пути перечисляются в meta.redacted.

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