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

Обновить настройки встраивания формы

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

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

Параметры

Параметр Тип Обяз. Описание
Параметрid (path) Типnumber Обяз.да ОписаниеПоложительный ID формы из списка форм

Поля запроса (body)

Примеры настроек: click.settings.button.text, auto.settings.delay.

Получите updatedTime через Получить форму перед запросом. Замените YOUR_UPDATED_TIME в примерах этим значением. Передавайте настройки плоско, как в примерах, или в виде {updatedTime, fields: {click: {...}, auto: {...}}}. Для обёртки fields нужен объект. Не смешивайте вложенные настройки с настройками в корне.

Таблица содержит примеры настроек, а не исчерпывающий список. Пути свойств, значения и возможность очистки через null проверяет Битрикс24. Текущие варианты значений — в кодах встраивания формы.

Поле Тип Обяз. Описание
ПолеupdatedTime Типstring Обяз.да ОписаниеТекущая версия формы из GET /v1/crm-forms/:id
Полеclick.settings.type Типstring / null Обяз.нет Описаниеpopup, panel
Полеclick.settings.position Типstring / null Обяз.нет Описаниеleft, center, right
Полеclick.settings.vertical Типstring / null Обяз.нет Описаниеbottom, top
Полеauto.settings.type Типstring / null Обяз.нет Описаниеpopup, panel
Полеauto.settings.position Типstring / null Обяз.нет Описаниеleft, center, right
Полеauto.settings.vertical Типstring / null Обяз.нет Описаниеbottom, top
Полеclick.settings.button.use Типboolean / null Обяз.нет ОписаниеИспользовать создаваемую кнопку
Полеclick.settings.button.text Типstring / null Обяз.нет ОписаниеПодпись кнопки
Полеclick.settings.button.font Типstring / null Обяз.нет Описаниеmodern, classic, elegant
Полеclick.settings.button.align Типstring / null Обяз.нет Описаниеinline, left, center, right
Полеclick.settings.button.plain Типboolean / null Обяз.нет ОписаниеПлоское оформление кнопки
Полеclick.settings.button.rounded Типboolean / null Обяз.нет ОписаниеСкруглённые углы кнопки
Полеclick.settings.button.outlined Типboolean / null Обяз.нет ОписаниеКонтурная кнопка
Полеclick.settings.button.decoration Типstring / null Обяз.нет ОписаниеОформление, например dotted, solid или пустая строка
Полеclick.settings.button.color.text Типstring / null Обяз.нет ОписаниеЦвет текста. Формат: #RGB, #RGBA, #RRGGBB, #RRGGBBAA
Полеclick.settings.button.color.textHover Типstring / null Обяз.нет ОписаниеЦвет текста при наведении. Формат: #RGB, #RGBA, #RRGGBB, #RRGGBBAA
Полеclick.settings.button.color.background Типstring / null Обяз.нет ОписаниеЦвет фона. Формат: #RGB, #RGBA, #RRGGBB, #RRGGBBAA
Полеclick.settings.button.color.backgroundHover Типstring / null Обяз.нет ОписаниеЦвет фона при наведении. Формат: #RGB, #RGBA, #RRGGBB, #RRGGBBAA
Полеauto.settings.delay Типinteger / null Обяз.нет ОписаниеСекунды: 3, 5, 7, 10, 15, 20, 25, 30, 40, 60, 120

Какие свойства можно записывать, решает Битрикс24. Поля ответа встраивания не задают локальный перечень настроек для записи.

Примеры

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

Terminal 
curl -X PATCH "https://vibecode.bitrix24.tech/v1/crm-forms/59/embedding" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updatedTime": "YOUR_UPDATED_TIME",
  "auto": {
    "settings": {
      "delay": 10
    }
  },
  "click": {
    "settings": {
      "button": {
        "text": "Write us"
      }
    }
  }
}'

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

Terminal 
curl -X PATCH "https://vibecode.bitrix24.tech/v1/crm-forms/59/embedding" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "updatedTime": "YOUR_UPDATED_TIME",
  "auto": {
    "settings": {
      "delay": 10
    }
  },
  "click": {
    "settings": {
      "button": {
        "text": "Write us"
      }
    }
  }
}'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-forms/59/embedding', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    updatedTime: 'YOUR_UPDATED_TIME',
    auto: { settings: { delay: 10 } },
    click: { settings: { button: { text: 'Write us' } } },
  }),
})

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

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-forms/59/embedding', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    updatedTime: 'YOUR_UPDATED_TIME',
    auto: { settings: { delay: 10 } },
    click: { settings: { button: { text: 'Write us' } } },
  }),
})

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

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue при успехе
Полеdata Типobject ОписаниеНастройки встраивания из Битрикс24 после записи или {id}, если дополнительное чтение не удалось
Полеdata.id Типnumber ОписаниеID формы при сбое дополнительного чтения
Полеmeta.warnings Типobject[] ОписаниеПодтверждённая запись остаётся успешной при сбое чтения. CRM_FORM_READBACK_FAILED требует прочитать форму и встраивание до следующего изменения, не повторяя запись
Полеmeta.redacted Типstring[] ОписаниеПути с заменёнными учётными данными соединения. Такой ответ не является полной конфигурацией для обратного сохранения
Поле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 ОписаниеТекущие настройки из Битрикс24, включая 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

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

Публичные домены и подписи в примере условные.

JSON 
{
  "success": true,
  "data": {
    "formActive": true,
    "resourcesReady": true,
    "publicUrl": "https://example.bitrix24.ru/crm_form_nfby7/?telemetry_sign=DUMMY_PUBLIC_SIGNATURE",
    "inline": {
      "code": "<script data-b24-form=\"inline/59/p4yyaj\" data-b24-form-telemetry-sign=\"DUMMY_PUBLIC_SIGNATURE\" data-skip-moving=\"true\">\n\t(function(w,d,u){\n\t\tvar s=d.createElement('script');s.async=true;s.src=u+'?'+(Date.now()/180000|0);\n\t\tvar h=d.getElementsByTagName('script')[0];h.parentNode.insertBefore(s,h);\n\t})(window,document,'https://cdn.example.com/b13743910/crm/form/loader_59.js');\n</script>",
      "previewUrl": "https://example.bitrix24.ru/pub/form/59_probe/p4yyaj/?view=preview&preview=inline",
      "settings": null,
      "options": null
    },
    "click": {
      "code": "<script data-b24-form=\"click/59/p4yyaj\" data-b24-form-telemetry-sign=\"DUMMY_PUBLIC_SIGNATURE\" data-skip-moving=\"true\">\n\t(function(w,d,u){\n\t\tvar s=d.createElement('script');s.async=true;s.src=u+'?'+(Date.now()/180000|0);\n\t\tvar h=d.getElementsByTagName('script')[0];h.parentNode.insertBefore(s,h);\n\t})(window,document,'https://cdn.example.com/b13743910/crm/form/loader_59.js');\n</script>",
      "previewUrl": "https://example.bitrix24.ru/pub/form/59_probe/p4yyaj/?view=preview&preview=click",
      "settings": {
        "type": "panel",
        "position": "right",
        "vertical": "bottom",
        "button": {
          "use": true,
          "text": "Write us",
          "font": null,
          "align": null,
          "plain": false,
          "rounded": false,
          "outlined": false,
          "decoration": null,
          "color": {
            "text": null,
            "textHover": null,
            "background": null,
            "backgroundHover": null
          }
        }
      },
      "options": {
        "type": [
          "popup",
          "panel"
        ],
        "position": [
          "left",
          "center",
          "right"
        ],
        "vertical": [
          "bottom",
          "top"
        ],
        "button": {
          "font": [
            "modern",
            "classic",
            "elegant"
          ],
          "align": [
            "inline",
            "left",
            "center",
            "right"
          ]
        }
      }
    },
    "auto": {
      "code": "<script data-b24-form=\"auto/59/p4yyaj\" data-b24-form-telemetry-sign=\"DUMMY_PUBLIC_SIGNATURE\" data-skip-moving=\"true\">\n\t(function(w,d,u){\n\t\tvar s=d.createElement('script');s.async=true;s.src=u+'?'+(Date.now()/180000|0);\n\t\tvar h=d.getElementsByTagName('script')[0];h.parentNode.insertBefore(s,h);\n\t})(window,document,'https://cdn.example.com/b13743910/crm/form/loader_59.js');\n</script>",
      "previewUrl": "https://example.bitrix24.ru/pub/form/59_probe/p4yyaj/?view=preview&preview=auto",
      "settings": {
        "type": "popup",
        "position": "right",
        "vertical": "bottom",
        "delay": 10
      },
      "options": {
        "type": [
          "popup",
          "panel"
        ],
        "position": [
          "left",
          "center",
          "right"
        ],
        "vertical": [
          "bottom",
          "top"
        ],
        "delay": [
          3,
          5,
          7,
          10,
          15,
          20,
          25,
          30,
          40,
          60,
          120
        ]
      }
    }
  }
}

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

400 — не передан updatedTime:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "updatedTime from GET /v1/crm-forms/:id is required"
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодINVALID_PARAMS ОписаниеНекорректный ID формы или структура запроса
HTTP400 КодINVALID_PARAMS ОписаниеНеизвестный параметр или некорректная структура запроса
HTTP400 КодINVALID_PARAMS ОписаниеНе передан updatedTime
HTTP400 КодINVALID_PARAMS ОписаниеБитрикс24 отклонил настройку. Уточнения — в error.validation, исходный код — в error.b24Code
HTTP409 КодCRM_FORM_REST_NOT_ENABLED ОписаниеREST-методы CRM-форм выключены на портале. Исходный код отсутствующего метода — в error.b24Code
HTTP403 КодBITRIX_INSUFFICIENT_SCOPE ОписаниеТокену Битрикс24 не хватает скоупа. Исходный код — в error.b24Code
HTTP404 КодENTITY_NOT_FOUND ОписаниеФорма не найдена
HTTP402 КодCRM_FORM_WRITE_RESTRICTED ОписаниеТариф Битрикс24 не разрешает запись CRM-форм — бесплатный и демо-тариф
HTTP403 КодSCOPE_DENIED ОписаниеAPI-ключ не имеет скоупа crm
HTTP403 КодBITRIX_ACCESS_DENIED ОписаниеУ пользователя нет прав доступа
HTTP403 КодCRM_FORM_SYSTEM_IMMUTABLE ОписаниеФорма системная — system: true в списке форм
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеAPI-ключ работает только на чтение
HTTP409 КодCRM_FORM_VERSION_MISMATCH ОписаниеФорму изменили после переданного updatedTime. Текущее время изменения — в error.currentUpdatedTime
HTTP401 КодTOKEN_MISSING ОписаниеУ API-ключа не настроены учётные данные
HTTP500 КодCRM_FORM_SIDE_EFFECT_FAILED ОписаниеИзменения уже записаны, но последующий шаг на стороне Битрикс24 не выполнен. Прочитайте форму перед повтором
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеНекорректный ответ с данными встраивания

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

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

Ответ встраивания не добавляет выдуманную updatedTime. Перед следующим изменением встраивания или самой формы перечитайте форму. Если meta.warnings сообщает о сбое чтения, запись уже выполнена: не повторяйте её. Прочитайте форму и встраивание.

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

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