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

Проверить форму

POST /v1/crm-forms/validate

POST /v1/crm-forms/:id/validate

Проверяет конфигурацию CRM-формы без сохранения и возвращает список нарушений. Первый путь проверяет черновик новой формы, второй — изменения сохранённой формы с указанным ID.

Параметры

Параметр Тип Обяз. Описание
Параметрid (path) Типinteger Обяз.нет ОписаниеID сохранённой формы — только для пути POST /v1/crm-forms/:id/validate. Список: GET /v1/crm-forms

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

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

Тело — те же свойства, что у создания и изменения формы. Для черновика передайте конфигурацию целиком. Для сохранённой формы — только изменяемые свойства, без updatedTime. Пустой объект {} проверяет форму в сохранённом виде.

Поле Тип Обяз. Описание
Полеname Типstring | null Обяз.нет ОписаниеНазвание формы. Черновик без name получает нарушение по этому полю
Полеcrm Типobject Обяз.нет ОписаниеПривязка к CRM.
Полеcrm.entityScheme Типinteger Обяз.нет ОписаниеСхема создаваемых записей CRM. Список: data.entitySchemes в GET /v1/crm-forms/configuration
Полеactive Типboolean Обяз.нет ОписаниеВключена ли форма. Допустимость свойства проверяет портал
Поле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/validate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Форма обратной связи",
    "crm": { "entityScheme": 1 },
    "fields": [
      { "name": "LEAD_NAME", "type": "string", "label": "Имя", "required": false, "multiple": false },
      { "name": "LEAD_PHONE", "type": "phone", "label": "Телефон", "required": false, "multiple": false }
    ]
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/crm-forms/validate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Форма обратной связи",
    "crm": { "entityScheme": 1 },
    "fields": [
      { "name": "LEAD_NAME", "type": "string", "label": "Имя", "required": false, "multiple": false },
      { "name": "LEAD_PHONE", "type": "phone", "label": "Телефон", "required": false, "multiple": false }
    ]
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-forms/validate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Форма обратной связи',
    crm: { entityScheme: 1 },
    fields: [
      { name: 'LEAD_NAME', type: 'string', label: 'Имя', required: false, multiple: false },
      { name: 'LEAD_PHONE', type: 'phone', label: 'Телефон', required: false, multiple: false },
    ],
  }),
})

const { data } = await res.json()
if (!data.valid) console.log('Нарушения:', data.violations)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-forms/validate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Форма обратной связи',
    crm: { entityScheme: 1 },
    fields: [
      { name: 'LEAD_NAME', type: 'string', label: 'Имя', required: false, multiple: false },
      { name: 'LEAD_PHONE', type: 'phone', label: 'Телефон', required: false, multiple: false },
    ],
  }),
})

const { data } = await res.json()

Поля ответа

HTTP 200 на обоих путях, в том числе когда проверка не пройдена.

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue — проверка выполнена. Результат проверки — в data.valid
Полеdata.valid Типboolean Описаниеtrue — нарушений нет, false — конфигурацию нужно исправить
Полеdata.violations Типarray ОписаниеНарушения. Пустой массив при valid: true
Полеdata.violations[].field Типstring ОписаниеПуть к свойству с нарушением, например name
Полеdata.violations[].message Типstring ОписаниеТекст нарушения
Полеmeta.redacted Типarray of string ОписаниеПути JSON, где заменены учётные данные текущего подключения

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

Нарушений нет:

JSON 
{
  "success": true,
  "data": {
    "valid": true,
    "violations": []
  }
}

Проверка не пройдена — в черновике нет name:

JSON 
{
  "success": true,
  "data": {
    "valid": false,
    "violations": [
      {
        "field": "name",
        "message": "Name of the CRM form is required"
      }
    ]
  }
}

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

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

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

Ошибки

HTTP Код Описание
HTTP404 КодENTITY_NOT_FOUND ОписаниеПортал не нашёл запрошенную сущность или описание поля. Исходный код — error.b24Code
HTTP400 КодINVALID_PARAMS Описаниеid не положительное целое число, тело не JSON-объект или передан параметр строки запроса
HTTP403 КодCRM_FORM_SYSTEM_IMMUTABLE ОписаниеТолько путь с id: форма системная, её настройки не изменяются
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
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеБитрикс24 недоступен или вернул ответ неверного вида

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

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

Работает с ключом только для чтения. Проверка ничего не сохраняет и не меняет updatedTime формы, поэтому доступна и такому ключу.

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