## Изменить форму `PATCH /v1/crm-forms/:id` Изменяет настройки сохранённой CRM-формы: название, поля, привязку к CRM, ответственных и тексты. ## Параметры | Параметр | Тип | Обяз. | Описание | |----------|-----|:-----:|----------| | `id` (path) | integer | да | ID формы. Список: [`GET /v1/crm-forms`](/docs/entities/crm-forms/list) | ## Поля запроса (body) Передавайте плоское тело или объект в `fields`: `{"fields":{"name":"Contact form"}}`. Массив в `fields` — секция полей формы в плоском теле. Объект в `fields` нельзя сочетать с другими свойствами верхнего уровня, кроме `updatedTime` — это `400 INVALID_PARAMS`. Свойства формы и их значения проверяет портал. | Поле | Тип | Обяз. | Описание | |------|-----|:-----:|----------| | `updatedTime` | string | да | Текущая версия формы — `data.updatedTime` из [`GET /v1/crm-forms/:id`](/docs/entities/crm-forms/get) или из ответа предыдущей записи | | `name` | string \| null | нет | Название формы в списке форм | | `languageId` | string \| null | нет | Язык формы. Список: `data.languages` в [`GET /v1/crm-forms/configuration`](/docs/entities/crm-forms/configuration) | | `templateId` | string \| null | нет | Сценарий, из которого создана форма. Список: [Список сценариев](/docs/entities/crm-forms/scenarios) | | `crm` | object | нет | Привязка к CRM. | | `crm.entityScheme` | integer | нет | Схема создаваемых записей CRM. Список: `data.entitySchemes` в [`GET /v1/crm-forms/configuration`](/docs/entities/crm-forms/configuration) | | `appearance` | object | нет | Оформление: заголовок `title`, описание `description`, подпись кнопки `buttonCaption` и другие свойства. | | `fields` | array \| object | нет | Массив полей формы или объект с конфигурацией запроса | | `fields[].name` | string | нет | Имя поля, например `LEAD_NAME`. Список: [`GET /v1/crm-forms/entity-fields`](/docs/entities/crm-forms/entity-fields) | | `fields[].type` | string | нет | Тип поля. Список: `data.fieldTypes` в [`GET /v1/crm-forms/configuration`](/docs/entities/crm-forms/configuration) | | `fields[].label` | string | нет | Подпись поля в форме | | `fields[].required` | boolean | нет | Обязательно ли поле для отправки. Передавайте явно: без флага сохраняется `true` | | `fields[].multiple` | boolean | нет | Принимает ли поле несколько значений. Передавайте явно: без флага сохраняется `true` | | `responsible` | object | нет | Ответственные за результаты формы | | `responsible.userIds` | array of integer | нет | ID ответственных. Список: [`GET /v1/users`](/docs/entities/users) | | `agreements` | object | нет | Настройки соглашений в схеме Битрикс24 | | `submission` | object | нет | Настройки после отправки: тексты и адреса перехода при успехе и ошибке. | | `callback` | object | нет | Настройки обратного звонка. | | `payment` | object | нет | Настройки оплаты. | | `booking` | object | нет | Настройки бронирования. | | `presetFields` | array | нет | Предустановленные значения полей | | `dependencies` | array | нет | Зависимости между полями | | `analytics` | object | нет | Настройки аналитики | | `integrations` | object | нет | Настройки интеграций | | `spamProtection` | object | нет | Защита от спама | Справочник [Поля контракта формы](/docs/entities/crm-forms/fields) описывает метаданные только верхнего уровня. Имена вложенных свойств и исходные значения секций для сохранённой формы берите из полного ответа [Прочитать форму](/docs/entities/crm-forms/get). Секции передаются в схеме Битрикс24; доступность записи настроек определяет портал. ## Примеры ### curl — личный ключ ```bash curl -X PATCH "https://vibecode.bitrix24.tech/v1/crm-forms/91" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "updatedTime": "2026-11-05T11:16:55+03:00", "name": "VIBE-PROBE 777758 flat, companies" }' ``` ### curl — OAuth-приложение ```bash curl -X PATCH "https://vibecode.bitrix24.tech/v1/crm-forms/91" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "updatedTime": "2026-11-05T11:16:55+03:00", "name": "VIBE-PROBE 777758 flat, companies" }' ``` ### JavaScript — личный ключ ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-forms/91', { method: 'PATCH', headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ updatedTime: '2026-11-05T11:16:55+03:00', name: 'VIBE-PROBE 777758 flat, companies', }), }) const { data } = await res.json() console.log('Новая версия:', data.updatedTime) ``` ### JavaScript — OAuth-приложение ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-forms/91', { method: 'PATCH', headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application/json', }, body: JSON.stringify({ updatedTime: '2026-11-05T11:16:55+03:00', name: 'VIBE-PROBE 777758 flat, companies', }), }) const { data } = await res.json() ``` ## Поля ответа HTTP `200`. Ответ — сохранённая форма, перечитанная после изменения. Свойства формы, кроме `id`, присутствуют только при успешном чтении. | Поле | Тип | Описание | |------|-----|----------| | `success` | boolean | `true` при успехе | | `data` | object | Изменённая форма в том же формате, что у [Прочитать форму](/docs/entities/crm-forms/get). Метаданные свойств верхнего уровня: [Поля контракта формы](/docs/entities/crm-forms/fields) | | `data.id` | integer | ID формы | | `data.name` | string | Название формы | | `data.updatedTime` | string \| null | Новая версия формы. Передаётся в следующий запрос записи | | `data.fields` | array | Поля формы в сохранённом виде | | `meta.warnings` | array | Предупреждение, если сохранённое состояние не удалось прочитать | | `meta.redacted` | array of string | Пути JSON, где заменены учётные данные текущего подключения. Такое представление нельзя сохранять обратно как полную конфигурацию | Если запись прошла, а последующее чтение не удалось, ответ остаётся успешным: `200` только с `data.id` и `meta.warnings[].code: "CRM_FORM_READBACK_FAILED"`. До следующей записи перечитайте форму через GET, чтобы получить текущую `updatedTime`. Успешную запись не повторяйте. ## Пример ответа Пример сокращён. Имена вложенных свойств и их значения берите из полного [ответа GET](/docs/entities/crm-forms/get) конкретной настроенной формы. [Поля контракта формы](/docs/entities/crm-forms/fields) описывают метаданные только верхнего уровня. ```json { "success": true, "data": { "id": 91, "code": "91", "name": "VIBE-PROBE 777758 flat, companies", "active": false, "system": false, "createdTime": "2026-11-05T11:16:55+03:00", "updatedTime": "2026-11-05T11:25:29+03:00", "crm": { "entityScheme": 1, "duplicateMode": "", "dealCategoryId": null, "dealDuplicateControlEnabled": false, "smartProcessCategoryId": null, "smartProcessDuplicateControlEnabled": false }, "fields": [ { "name": "LEAD_NAME", "type": "string", "label": null, "sort": 10, "required": false, "multiple": false, "placeholder": null, "valueType": null, "value": null } ], "agreements": { "enabled": false, "items": [] } } } ``` ## Пример ответа при ошибке 409 — форма изменилась после чтения, переданный `updatedTime` устарел: ```json { "success": false, "error": { "code": "CRM_FORM_VERSION_MISMATCH", "message": "Версия CRM-формы устарела, изменения не сохранены: получите форму заново и повторите запрос", "b24Code": "CRM_FORM_VERSION_MISMATCH", "currentUpdatedTime": "2026-11-05T11:25:30+03:00" } } ``` ## Ошибки | HTTP | Код | Описание | |------|-----|----------| | 409 | `CRM_FORM_VERSION_MISMATCH` | `updatedTime` не совпадает с текущей версией формы. Изменения не сохранены, текущая версия — в `error.currentUpdatedTime` | | 404 | `ENTITY_NOT_FOUND` | Формы с таким `id` нет | | 400 | `INVALID_PARAMS` | В теле нет `updatedTime` | | 400 | `INVALID_PARAMS` | `id` не положительное целое число, тело не JSON-объект, смешаны форматы тела или передан параметр строки запроса | | 402 | `CRM_FORM_WRITE_RESTRICTED` | Тариф Битрикс24 не разрешает запись CRM-форм — бесплатный и демо-тариф | | 403 | `CRM_FORM_SYSTEM_IMMUTABLE` | Форма системная, её настройки не изменяются | | 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ только для чтения. Нужен ключ с правом записи | | 403 | `BITRIX_INSUFFICIENT_SCOPE` | У токена Битрикс24 нет необходимого скоупа | | 409 | `CRM_FORM_REST_NOT_ENABLED` | На портале выключены методы CRM-форм | | 403 | `BITRIX_ACCESS_DENIED` | Битрикс24 отказал в доступе: у пользователя нет права на изменение CRM-форм | | 403 | `SCOPE_DENIED` | Ключу не хватает скоупа `crm` | | 401 | `MISSING_API_KEY` | Не передан `X-Api-Key` | | 401 | `TOKEN_MISSING` | У ключа нет токенов доступа к Битрикс24 | | 422 | `BITRIX_ERROR` | Другой отказ Битрикс24. Исходное сообщение сохраняется в `error.message` | | 500 | `CRM_FORM_SIDE_EFFECT_FAILED` | Изменения уже записаны, но последующий шаг на стороне Битрикс24 не выполнен. Прочитайте форму перед повтором | | 502 | `BITRIX_UNAVAILABLE` | Битрикс24 недоступен или вернул ответ неверного вида. Изменения могли сохраниться — прочитайте форму перед повтором | Ошибки портала содержат исходный код в `error.b24Code` и ошибки полей в `error.validation`, если они переданы. Коды `CRM_FORM_*` сохраняют HTTP-статус, код и сообщение. Общие ответы 429, 502 и 503 — [Лимиты и оптимизация](/docs/optimization). Полный список общих ошибок API — [Ошибки](/docs/errors). ## Известные особенности **Частичное обновление.** Свойства, которых нет в теле, остаются прежними. Переданный массив или объект заменяет прежний целиком: чтобы добавить одно поле формы, передайте в `fields` все поля вместе с новым. Пустой массив очищает коллекцию, `null` у скалярного свойства очищает его значение. ## Смотрите также - [Прочитать форму](/docs/entities/crm-forms/get) - [Проверить форму](/docs/entities/crm-forms/validate) - [Создать форму](/docs/entities/crm-forms/create) - [Включить форму](/docs/entities/crm-forms/activate) - [Выключить форму](/docs/entities/crm-forms/deactivate) - [Поля контракта формы](/docs/entities/crm-forms/fields) - [Получить конфигурацию конструктора](/docs/entities/crm-forms/configuration) - [Лимиты и оптимизация](/docs/optimization)