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

Список полей сущностей

GET /v1/crm-forms/entity-fields

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

Параметры

Параметр Тип Обяз. Описание
ПараметрentityName (query) Типstring Обяз.да ОписаниеИмя сущности CRM, например LEAD, CONTACT, COMPANY, DEAL, DYNAMIC_177. Список: data.entitySchemes[].entityNames в Конфигурация конструктора.
Несколько сущностей — до 10 имён одним из способов: через запятую ?entityName=LEAD,CONTACT, повтором ?entityName=LEAD&entityName=CONTACT или ?entityName[]=LEAD&entityName[]=CONTACT

Других параметров строки запроса эндпоинт не принимает.

Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/crm-forms/entity-fields?entityName=LEAD" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/crm-forms/entity-fields?entityName=LEAD" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-forms/entity-fields?entityName=LEAD', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log(data.map(field => `${field.name} — ${field.label}`))

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-forms/entity-fields?entityName=LEAD', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata Типarray ОписаниеПоля всех запрошенных сущностей одним массивом. Постраничной выдачи нет
Полеdata[].name Типstring ОписаниеИмя поля в форме: имя сущности и код поля, например LEAD_NAME. Это значение передаётся в fields[].name при создании формы
Полеdata[].label Типstring ОписаниеНазвание поля
Полеdata[].type Типstring ОписаниеТип поля: string, text, list, date, datetime, double, file, typed_string, crm_entity, resourcebooking. Тип typed_string — у полей связи: телефона, электронной почты, сайта, мессенджера
Полеdata[].required Типboolean ОписаниеОбязательно ли поле
Полеdata[].multiple Типboolean ОписаниеПринимает ли поле несколько значений
Полеdata[].entityName Типstring ОписаниеСущность, которой принадлежит поле, например LEAD
Полеdata[].entityLabel Типstring ОписаниеНазвание сущности
Полеdata[].items Типarray ОписаниеВарианты значения поля типа list. У полей других типов — пустой массив
Полеdata[].items[].id Типstring ОписаниеИдентификатор варианта, например WEB у поля LEAD_SOURCE_ID
Полеdata[].items[].label Типstring ОписаниеНазвание варианта

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

Показаны четыре поля из ответа по лиду. Идентификаторы вариантов зависят от портала; подписи в примере условные:

JSON 
{
  "success": true,
  "data": [
    {
      "name": "LEAD_TITLE",
      "label": "Название лида",
      "type": "string",
      "required": false,
      "multiple": false,
      "entityName": "LEAD",
      "entityLabel": "Лид",
      "items": []
    },
    {
      "name": "LEAD_HONORIFIC",
      "label": "Обращение",
      "type": "list",
      "required": false,
      "multiple": false,
      "entityName": "LEAD",
      "entityLabel": "Лид",
      "items": [
        {
          "id": "HNR_RU_1",
          "label": "г-н"
        },
        {
          "id": "HNR_RU_2",
          "label": "г-жа"
        }
      ]
    },
    {
      "name": "LEAD_NAME",
      "label": "Имя",
      "type": "string",
      "required": false,
      "multiple": false,
      "entityName": "LEAD",
      "entityLabel": "Лид",
      "items": []
    },
    {
      "name": "LEAD_PHONE",
      "label": "Телефон",
      "type": "typed_string",
      "required": false,
      "multiple": true,
      "entityName": "LEAD",
      "entityLabel": "Лид",
      "items": []
    }
  ]
}

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

400 — не передан entityName:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "entityName is required"
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодMISSING_REQUIRED_FIELDS ОписаниеНе передан entityName
HTTP400 КодINVALID_PARAMS ОписаниеБольше 10 имён, пустое имя или неизвестный параметр запроса
HTTP403 КодBITRIX_ACCESS_DENIED ОписаниеУ пользователя Битрикс24 нет прав на формы
HTTP403 КодBITRIX_INSUFFICIENT_SCOPE ОписаниеУ токена Битрикс24 нет необходимого скоупа
HTTP404 КодENTITY_NOT_FOUND ОписаниеПортал не нашёл запрошенную сущность или описание поля. Исходный код — error.b24Code
HTTP409 КодCRM_FORM_REST_NOT_ENABLED ОписаниеREST-методы CRM-форм недоступны на этом портале Битрикс24. Это не означает отсутствие отдельной формы
HTTP400–599 КодCRM_FORM_* ОписаниеОтказ по правилам форм. Код и HTTP-статус сохранены, исходный код — в error.b24Code
HTTP422 КодBITRIX_ERROR ОписаниеДругой отказ Битрикс24. Причина — в error.message, исходный код — в error.b24Code
HTTP429 КодRATE_LIMITED ОписаниеПревышена частота запросов. Учитывайте заголовок Retry-After
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеБитрикс24 вернул ответ в неожиданном виде
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеБитрикс24 недоступен: ошибка сервера или разрыв соединения
HTTP503 КодBITRIX_TIMEOUT ОписаниеБитрикс24 не ответил вовремя. Чтение можно повторить
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP401 КодTOKEN_MISSING ОписаниеУ ключа не настроен доступ к Битрикс24
HTTP403 КодSCOPE_DENIED ОписаниеУ API-ключа Вайбкод нет скоупа crm

Полный список общих ошибок API — Ошибки.

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