## Обновить настройки встраивания формы `PATCH /v1/crm-forms/:id/embedding` Меняйте настройки показа формы по нажатию и через заданное время для размещения на сайте. Пропущенные настройки сохраняются. ## Параметры | Параметр | Тип | Обяз. | Описание | |---|---|---|---| | `id` (path) | number | да | Положительный ID формы из [списка форм](/docs/entities/crm-forms/list) | ## Поля запроса (body) Примеры настроек: `click.settings.button.text`, `auto.settings.delay`. Получите `updatedTime` через [Получить форму](/docs/entities/crm-forms/get) перед запросом. Замените `YOUR_UPDATED_TIME` в примерах этим значением. Передавайте настройки плоско, как в примерах, или в виде `{updatedTime, fields: {click: {...}, auto: {...}}}`. Для обёртки `fields` нужен объект. Не смешивайте вложенные настройки с настройками в корне. Таблица содержит примеры настроек, а не исчерпывающий список. Пути свойств, значения и возможность очистки через `null` проверяет Битрикс24. Текущие варианты значений — в [кодах встраивания формы](/docs/entities/crm-forms/embedding). | Поле | Тип | Обяз. | Описание | |---|---|---|---| | `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 — личный ключ ```bash 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-приложение ```bash 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..code` | string / null | HTML-код для размещения на сайте, включая `null`, если ресурсы не готовы | | `data..previewUrl` | string | Ссылка на предварительный просмотр, если передана. Отсутствующие поля и `null` сохраняются | | `data..settings` | object / null | Текущие настройки из Битрикс24, включая `null` | | `data..options` | object / null | Допустимые значения из Битрикс24, включая `null` | | `data..options.type` | string[] | `popup`, `panel` | | `data..options.position` | string[] | `left`, `center`, `right` | | `data..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": "", "previewUrl": "https://example.bitrix24.ru/pub/form/59_probe/p4yyaj/?view=preview&preview=inline", "settings": null, "options": null }, "click": { "code": "", "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": "", "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 | Код | Описание | |---|---|---| | 400 | `INVALID_PARAMS` | Некорректный ID формы или структура запроса | | 400 | `INVALID_PARAMS` | Неизвестный параметр или некорректная структура запроса | | 400 | `INVALID_PARAMS` | Не передан `updatedTime` | | 400 | `INVALID_PARAMS` | Битрикс24 отклонил настройку. Уточнения — в `error.validation`, исходный код — в `error.b24Code` | | 409 | `CRM_FORM_REST_NOT_ENABLED` | REST-методы CRM-форм выключены на портале. Исходный код отсутствующего метода — в `error.b24Code` | | 403 | `BITRIX_INSUFFICIENT_SCOPE` | Токену Битрикс24 не хватает скоупа. Исходный код — в `error.b24Code` | | 404 | `ENTITY_NOT_FOUND` | Форма не найдена | | 402 | `CRM_FORM_WRITE_RESTRICTED` | Тариф Битрикс24 не разрешает запись CRM-форм — бесплатный и демо-тариф | | 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `crm` | | 403 | `BITRIX_ACCESS_DENIED` | У пользователя нет прав доступа | | 403 | `CRM_FORM_SYSTEM_IMMUTABLE` | Форма системная — `system: true` в [списке форм](/docs/entities/crm-forms/list) | | 403 | `WRITE_BLOCKED_READONLY_KEY` | API-ключ работает только на чтение | | 409 | `CRM_FORM_VERSION_MISMATCH` | Форму изменили после переданного `updatedTime`. Текущее время изменения — в `error.currentUpdatedTime` | | 401 | `TOKEN_MISSING` | У API-ключа не настроены учётные данные | | 500 | `CRM_FORM_SIDE_EFFECT_FAILED` | Изменения уже записаны, но последующий шаг на стороне Битрикс24 не выполнен. Прочитайте форму перед повтором | | 502 | `BITRIX_UNAVAILABLE` | Некорректный ответ с данными встраивания | Ошибки Битрикс24 содержат исходный `error.b24Code` и переданные уточнения по полям в `error.validation`. Общие ошибки API — [Ошибки](/docs/errors). ## Известные особенности Ответ встраивания не добавляет выдуманную `updatedTime`. Перед следующим изменением встраивания или самой формы перечитайте [форму](/docs/entities/crm-forms/get). Если `meta.warnings` сообщает о сбое чтения, запись уже выполнена: не повторяйте её. Прочитайте форму и встраивание. Объект встраивания сохраняет исходные поля. Переданные Битрикс24 `resourcesReady: false` и `code: null` остаются успешным ответом. Заменяются только учётные данные текущего соединения с путями в `meta.redacted`. ## Смотрите также - [Получить форму](/docs/entities/crm-forms/get) - [Получить коды встраивания формы](/docs/entities/crm-forms/embedding)