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

Получить CRM-форму

GET /v1/crm-forms/:id

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

Параметры

Параметр Тип Обяз. Описание
Параметрid (path) Типnumber Обяз.да ОписаниеИдентификатор формы, положительное целое число. Список: GET /v1/crm-forms, в том числе с active=false для неактивных форм

Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/crm-forms/1" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/crm-forms/1" \
  -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/1', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { data } = await res.json()
const required = data.fields.filter((field) => field.required).map((field) => field.name)
console.log(data.title, 'обязательные поля:', required)

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

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

const { data } = await res.json()

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue при успешном запросе
Полеdata.id Типnumber ОписаниеИдентификатор формы
Полеdata.name Типstring ОписаниеНазвание формы в списке форм
Полеdata.title Типstring | null ОписаниеЗаголовок, который видит посетитель
Полеdata.description Типstring | null ОписаниеТекст под заголовком
Полеdata.buttonCaption Типstring | null ОписаниеПодпись кнопки отправки
Полеdata.fields Типarray ОписаниеПоля формы в порядке отображения
Полеdata.fields[].id Типstring | null ОписаниеИдентификатор поля в форме
Полеdata.fields[].name Типstring | null ОписаниеИмя поля, например LEAD_NAME, LEAD_PHONE
Полеdata.fields[].type Типstring | null ОписаниеТип поля, например name, phone, email, string, product
Полеdata.fields[].label Типstring | null ОписаниеПодпись поля
Полеdata.fields[].required Типboolean | null ОписаниеОбязательно ли поле для отправки
Полеdata.fields[].visible Типboolean | null ОписаниеПоказывается ли поле посетителю
Полеdata.fields[].multiple Типboolean | null ОписаниеМожно ли выбрать несколько вариантов
Полеdata.fields[].placeholder Типstring | null ОписаниеПодсказка внутри пустого поля
Полеdata.fields[].items Типarray ОписаниеВарианты выбора. Пустой массив у полей без вариантов
Полеdata.fields[].items[].id Типstring | number | boolean | null ОписаниеИдентификатор варианта
Полеdata.fields[].items[].value Типstring | number | boolean | null ОписаниеЗначение варианта
Полеdata.fields[].items[].label Типstring | null ОписаниеПодпись варианта
Полеdata.result.successText Типstring | null ОписаниеТекст после успешной отправки
Полеdata.result.failureText Типstring | null ОписаниеТекст после неудачной отправки
Полеdata.responsible.userIds Типnumber[] ОписаниеОтветственные за результаты формы. Список: GET /v1/users
Полеdata.agreements Типarray ОписаниеСогласия, которые посетитель отмечает перед отправкой. Пустой массив, если согласий нет
Полеdata.agreements[].id Типnumber | null ОписаниеИдентификатор согласия
Полеdata.agreements[].name Типstring | null ОписаниеСистемное имя согласия
Полеdata.agreements[].label Типstring | null ОписаниеТекст согласия рядом с флажком
Полеdata.agreements[].required Типboolean | null ОписаниеНужно ли отметить согласие, чтобы отправить форму
Полеdata.agreements[].checked Типboolean | null ОписаниеОтмечено ли согласие заранее

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

JSON 
{
  "success": true,
  "data": {
    "id": 1,
    "name": "Контактные данные",
    "title": "Контактные данные",
    "description": "Оставьте контактные данные и мы обязательно свяжемся с вами",
    "buttonCaption": "Отправить",
    "fields": [
      {
        "id": "LEAD_NAME",
        "name": "LEAD_NAME",
        "type": "name",
        "label": "Имя",
        "required": false,
        "visible": true,
        "multiple": false,
        "placeholder": null,
        "items": []
      },
      {
        "id": "LEAD_PHONE",
        "name": "LEAD_PHONE",
        "type": "phone",
        "label": "Телефон",
        "required": false,
        "visible": true,
        "multiple": false,
        "placeholder": null,
        "items": []
      }
    ],
    "result": {
      "successText": "Спасибо, ваше сообщение отправлено.",
      "failureText": "К сожалению, сообщение не удалось отправить. Пожалуйста, попробуйте повторить отправку позже."
    },
    "responsible": {
      "userIds": [1]
    },
    "agreements": [
      {
        "id": 29,
        "name": "AGREEMENT_29",
        "label": "Нажимая кнопку «Отправить», я даю свое согласие на обработку моих персональных данных, в соответствии с Федеральным законом от 27.07.2006 года №152-ФЗ «О персональных данных», на условиях и для целей, определенных в Согласии на обработку персональных данных",
        "required": false,
        "checked": false
      }
    ]
  }
}

Показаны два поля из четырёх.

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

404 — формы с таким id нет:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "CRM form not found"
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодINVALID_PARAMS Описаниеid не положительное целое число, например abc или 0
HTTP404 КодENTITY_NOT_FOUND ОписаниеФормы с таким id нет ни среди активных, ни среди неактивных, либо у пользователя ключа нет права просмотра форм
HTTP403 КодBITRIX_ACCESS_DENIED ОписаниеБитрикс24 отказал пользователю ключа в доступе
HTTP422 КодBITRIX_ERROR ОписаниеБитрикс24 отклонил запрос, текст причины в message
HTTP429 КодRATE_LIMITED ОписаниеПревышена частота запросов к Битрикс24, повторите через 1-2 секунды
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеБитрикс24 вернул список форм или форму в неожиданном виде, сообщение «Bitrix24 returned an invalid CRM form response»
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеБитрикс24 недоступен: ответил ошибкой сервера или соединение оборвалось
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP401 КодTOKEN_MISSING ОписаниеУ API-ключа нет настроенных токенов Битрикс24
HTTP403 КодSCOPE_DENIED ОписаниеУ API-ключа нет скоупа crm

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

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

  • Учётные данные в тексте формы скрыты. Если в любом текстовом поле формы встречается пара вида apiKey: …, token=…, адрес входящего вебхука или параметр с учётными данными в ссылке, на его месте приходит [redacted].

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