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

`GET /v1/crm-forms/:id`

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

## Параметры

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

## Примеры

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

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

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

```bash
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`](/docs/entities/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 | Код | Описание |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | `id` не положительное целое число, например `abc` или `0` |
| 404 | `ENTITY_NOT_FOUND` | Формы с таким `id` нет ни среди активных, ни среди неактивных, либо у пользователя ключа нет права просмотра форм |
| 403 | `BITRIX_ACCESS_DENIED` | Битрикс24 отказал пользователю ключа в доступе |
| 422 | `BITRIX_ERROR` | Битрикс24 отклонил запрос, текст причины в `message` |
| 429 | `RATE_LIMITED` | Превышена частота запросов к Битрикс24, повторите через 1-2 секунды |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 вернул список форм или форму в неожиданном виде, сообщение «Bitrix24 returned an invalid CRM form response» |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 недоступен: ответил ошибкой сервера или соединение оборвалось |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `TOKEN_MISSING` | У API-ключа нет настроенных токенов Битрикс24 |
| 403 | `SCOPE_DENIED` | У API-ключа нет скоупа `crm` |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

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

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

- [Список CRM-форм](/docs/entities/crm-forms/list)
- [CRM-формы](/docs/entities/crm-forms)
- [Лиды](/docs/entities/leads)
- [Пользователи](/docs/entities/users)