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

Управление формами

Создавайте, читайте, изменяйте и удаляйте CRM-формы, проверяйте конфигурацию без сохранения и переключайте активность формы.

Битрикс24 API: crm.form.* Скоуп: crm

Создать форму

POST /v1/crm-forms

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

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

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

Перед созданием черновик можно проверить без сохранения: Проверить форму.

Поле Тип Обяз. Описание
Полеname Типstring Обяз.да ОписаниеНазвание формы в списке форм
Полеcrm Типobject Обяз.да ОписаниеПривязка к CRM. Вложенные настройки берите из конфигурации конкретной формы
Полеcrm.entityScheme Типinteger Обяз.да ОписаниеСхема создаваемых записей CRM. Список: data.entitySchemes в GET /v1/crm-forms/configuration
Полеactive Типboolean Обяз.нет ОписаниеВключена ли форма. По умолчанию true. Отдельные операции управления активностью — включение и выключение
ПолеlanguageId Типstring | null Обяз.нет ОписаниеЯзык формы. Список: data.languages в GET /v1/crm-forms/configuration
ПолеtemplateId Типstring | null Обяз.нет ОписаниеСценарий, из которого создана форма. Список: Список сценариев
Поле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 POST "https://vibecode.bitrix24.tech/v1/crm-forms" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIBE-PROBE 777758 parity",
    "active": false,
    "crm": { "entityScheme": 1 },
    "fields": [
      { "name": "LEAD_NAME", "type": "string", "required": false, "multiple": false }
    ]
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/crm-forms" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIBE-PROBE 777758 parity",
    "active": false,
    "crm": { "entityScheme": 1 },
    "fields": [
      { "name": "LEAD_NAME", "type": "string", "required": false, "multiple": false }
    ]
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-forms', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'VIBE-PROBE 777758 parity',
    active: false,
    crm: { entityScheme: 1 },
    fields: [
      { name: 'LEAD_NAME', type: 'string', required: false, multiple: false },
    ],
  }),
})

const { data } = await res.json()
console.log('Form ID:', data.id, 'updatedTime:', data.updatedTime)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-forms', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'VIBE-PROBE 777758 parity',
    active: false,
    crm: { entityScheme: 1 },
    fields: [
      { name: 'LEAD_NAME', type: 'string', required: false, multiple: false },
    ],
  }),
})

const { data } = await res.json()

Поля ответа

HTTP 201. Ответ — сохранённая форма, перечитанная после создания. Свойства формы, кроме id, присутствуют только при успешном чтении.

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue при успехе
Полеdata Типobject ОписаниеСозданная форма в том же формате, что у Прочитать форму. Метаданные свойств верхнего уровня: Поля контракта формы
Полеdata.id Типinteger ОписаниеID созданной формы
Полеdata.name Типstring ОписаниеНазвание формы
Полеdata.active Типboolean | null ОписаниеВключена ли форма
Полеdata.updatedTime Типstring | null ОписаниеВремя последнего изменения. Передаётся в PATCH /v1/crm-forms/:id
Полеdata.fields Типarray ОписаниеПоля формы в сохранённом виде, включая required и multiple
Полеmeta.warnings Типarray ОписаниеПредупреждение, если сохранённое состояние не удалось прочитать
Полеmeta.redacted Типarray of string ОписаниеПути JSON, где заменены учётные данные текущего подключения. Такое представление нельзя сохранять обратно как полную конфигурацию

Если запись прошла, а последующее чтение не удалось, ответ остаётся успешным: 201 только с data.id и meta.warnings[].code: "CRM_FORM_READBACK_FAILED". До следующей записи перечитайте форму через GET, чтобы получить текущую updatedTime. Успешную запись не повторяйте.

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

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

JSON 
{
  "success": true,
  "data": {
    "id": 91,
    "code": "91",
    "name": "VIBE-PROBE 777758 parity",
    "active": false,
    "system": false,
    "createdTime": "2026-11-05T11:16:55+03:00",
    "updatedTime": "2026-11-05T11:16:55+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": []
    }
  }
}

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

400 — объект в fields смешан с другим свойством верхнего уровня:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Use either a flat body or {fields:{...}}"
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодINVALID_PARAMS ОписаниеТело не JSON-объект или передан параметр строки запроса
HTTP400 КодINVALID_PARAMS ОписаниеБитрикс24 отклонил конфигурацию, например не передан crm.entityScheme. Нарушения перечислены в error.validation
HTTP400 КодCRM_FORM_PARTIALLY_CREATED ОписаниеФорма существует: error.id — её ID, error.b24Code — исходный код, error.validation — ошибки секций. Перечитайте форму, затем исправьте или удалите её. Создание не повторяйте
HTTP402 КодCRM_FORM_WRITE_RESTRICTED ОписаниеТариф Битрикс24 не разрешает запись CRM-форм — бесплатный и демо-тариф
HTTP402 КодCRM_FORM_ACTIVATION_LIMIT_REACHED ОписаниеФорма создаётся включённой, а лимит активных форм исчерпан. Лимит — data.limits.activeForms в GET /v1/crm-forms/configuration
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеКлюч только для чтения. Нужен ключ с правом записи
HTTP403 КодBITRIX_INSUFFICIENT_SCOPE ОписаниеУ токена Битрикс24 нет необходимого скоупа
HTTP404 КодENTITY_NOT_FOUND ОписаниеПортал не нашёл запрошенную сущность или описание поля. Исходный код — error.b24Code
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 не выполнен. error.id — ID созданной формы. Прочитайте форму перед повтором
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеБитрикс24 недоступен или вернул ответ неверного вида. Форма может быть уже создана — найдите её в списке форм перед повтором

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

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