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

Изменить форму

PATCH /v1/crm-forms/:id

Изменяет настройки сохранённой CRM-формы: название, поля, привязку к CRM, ответственных и тексты.

Параметры

Параметр Тип Обяз. Описание
Параметрid (path) Типinteger Обяз.да ОписаниеID формы. Список: GET /v1/crm-forms

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

Передавайте плоское тело или объект в fields: {"fields":{"name":"Contact form"}}. Массив в fields — секция полей формы в плоском теле. Объект в fields нельзя сочетать с другими свойствами верхнего уровня, кроме updatedTime — это 400 INVALID_PARAMS. Свойства формы и их значения проверяет портал.

Поле Тип Обяз. Описание
ПолеupdatedTime Типstring Обяз.да ОписаниеТекущая версия формы — data.updatedTime из GET /v1/crm-forms/:id или из ответа предыдущей записи
Полеname Типstring | null Обяз.нет ОписаниеНазвание формы в списке форм
ПолеlanguageId Типstring | null Обяз.нет ОписаниеЯзык формы. Список: data.languages в GET /v1/crm-forms/configuration
ПолеtemplateId Типstring | null Обяз.нет ОписаниеСценарий, из которого создана форма. Список: Список сценариев
Полеcrm Типobject Обяз.нет ОписаниеПривязка к CRM.
Полеcrm.entityScheme Типinteger Обяз.нет ОписаниеСхема создаваемых записей CRM. Список: data.entitySchemes в GET /v1/crm-forms/configuration
Полеappearance Типobject Обяз.нет ОписаниеОформление: заголовок title, описание description, подпись кнопки buttonCaption и другие свойства.
Полеfields Типarray | object Обяз.нет ОписаниеМассив полей формы или объект с конфигурацией запроса
Полеfields[].name Типstring Обяз.нет ОписаниеИмя поля, например LEAD_NAME. Список: GET /v1/crm-forms/entity-fields
Полеfields[].type Типstring Обяз.нет ОписаниеТип поля. Список: data.fieldTypes в GET /v1/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
Полеagreements Типobject Обяз.нет ОписаниеНастройки соглашений в схеме Битрикс24
Полеsubmission Типobject Обяз.нет ОписаниеНастройки после отправки: тексты и адреса перехода при успехе и ошибке.
Полеcallback Типobject Обяз.нет ОписаниеНастройки обратного звонка.
Полеpayment Типobject Обяз.нет ОписаниеНастройки оплаты.
Полеbooking Типobject Обяз.нет ОписаниеНастройки бронирования.
ПолеpresetFields Типarray Обяз.нет ОписаниеПредустановленные значения полей
Полеdependencies Типarray Обяз.нет ОписаниеЗависимости между полями
Полеanalytics Типobject Обяз.нет ОписаниеНастройки аналитики
Полеintegrations Типobject Обяз.нет ОписаниеНастройки интеграций
ПолеspamProtection Типobject Обяз.нет ОписаниеЗащита от спама

Справочник Поля контракта формы описывает метаданные только верхнего уровня. Имена вложенных свойств и исходные значения секций для сохранённой формы берите из полного ответа Прочитать форму. Секции передаются в схеме Битрикс24; доступность записи настроек определяет портал.

Примеры

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

Terminal 
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-приложение

Terminal 
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 ОписаниеИзменённая форма в том же формате, что у Прочитать форму. Метаданные свойств верхнего уровня: Поля контракта формы
Поле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 конкретной настроенной формы. Поля контракта формы описывают метаданные только верхнего уровня.

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 Код Описание
HTTP409 КодCRM_FORM_VERSION_MISMATCH ОписаниеupdatedTime не совпадает с текущей версией формы. Изменения не сохранены, текущая версия — в error.currentUpdatedTime
HTTP404 КодENTITY_NOT_FOUND ОписаниеФормы с таким id нет
HTTP400 КодINVALID_PARAMS ОписаниеВ теле нет updatedTime
HTTP400 КодINVALID_PARAMS Описаниеid не положительное целое число, тело не JSON-объект, смешаны форматы тела или передан параметр строки запроса
HTTP402 КодCRM_FORM_WRITE_RESTRICTED ОписаниеТариф Битрикс24 не разрешает запись CRM-форм — бесплатный и демо-тариф
HTTP403 КодCRM_FORM_SYSTEM_IMMUTABLE ОписаниеФорма системная, её настройки не изменяются
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеКлюч только для чтения. Нужен ключ с правом записи
HTTP403 КодBITRIX_INSUFFICIENT_SCOPE ОписаниеУ токена Битрикс24 нет необходимого скоупа
HTTP409 КодCRM_FORM_REST_NOT_ENABLED ОписаниеНа портале выключены методы CRM-форм
HTTP403 КодBITRIX_ACCESS_DENIED ОписаниеБитрикс24 отказал в доступе: у пользователя нет права на изменение CRM-форм
HTTP403 КодSCOPE_DENIED ОписаниеКлючу не хватает скоупа crm
HTTP401 КодMISSING_API_KEY ОписаниеНе передан X-Api-Key
HTTP401 КодTOKEN_MISSING ОписаниеУ ключа нет токенов доступа к Битрикс24
HTTP422 КодBITRIX_ERROR ОписаниеДругой отказ Битрикс24. Исходное сообщение сохраняется в error.message
HTTP500 КодCRM_FORM_SIDE_EFFECT_FAILED ОписаниеИзменения уже записаны, но последующий шаг на стороне Битрикс24 не выполнен. Прочитайте форму перед повтором
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеБитрикс24 недоступен или вернул ответ неверного вида. Изменения могли сохраниться — прочитайте форму перед повтором

Ошибки портала содержат исходный код в error.b24Code и ошибки полей в error.validation, если они переданы. Коды CRM_FORM_* сохраняют HTTP-статус, код и сообщение. Общие ответы 429, 502 и 503 — Лимиты и оптимизация. Полный список общих ошибок API — Ошибки.

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

Частичное обновление. Свойства, которых нет в теле, остаются прежними. Переданный массив или объект заменяет прежний целиком: чтобы добавить одно поле формы, передайте в fields все поля вместе с новым. Пустой массив очищает коллекцию, null у скалярного свойства очищает его значение.

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