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

`POST /v1/crm-forms`

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

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

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

Перед созданием черновик можно проверить без сохранения: [Проверить форму](/docs/entities/crm-forms/validate).

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|----------|
| `name` | string | да | Название формы в списке форм |
| `crm` | object | да | Привязка к CRM. Вложенные настройки берите из конфигурации конкретной формы |
| `crm.entityScheme` | integer | да | Схема создаваемых записей CRM. Список: `data.entitySchemes` в [`GET /v1/crm-forms/configuration`](/docs/entities/crm-forms/configuration) |
| `active` | boolean | нет | Включена ли форма. По умолчанию `true`. Отдельные операции управления активностью — [включение](/docs/entities/crm-forms/activate) и [выключение](/docs/entities/crm-forms/deactivate) |
| `languageId` | string \| null | нет | Язык формы. Список: `data.languages` в [`GET /v1/crm-forms/configuration`](/docs/entities/crm-forms/configuration) |
| `templateId` | string \| null | нет | Сценарий, из которого создана форма. Список: [Список сценариев](/docs/entities/crm-forms/scenarios) |
| `appearance` | object | нет | Оформление: заголовок `title`, описание `description`, подпись кнопки `buttonCaption` и другие свойства. |
| `fields` | array \| object | нет | Массив полей формы или объект с конфигурацией запроса |
| `fields[].name` | string | нет | Имя поля, например `LEAD_NAME`. Список: [`GET /v1/crm-forms/entity-fields`](/docs/entities/crm-forms/entity-fields) |
| `fields[].type` | string | нет | Тип поля. Список: `data.fieldTypes` в [`GET /v1/crm-forms/configuration`](/docs/entities/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`](/docs/entities/users) |
| `agreements` | object | нет | Настройки соглашений в схеме Битрикс24 |
| `submission` | object | нет | Настройки после отправки: тексты и адреса перехода при успехе и ошибке. |
| `callback` | object | нет | Настройки обратного звонка. |
| `payment` | object | нет | Настройки оплаты. |
| `booking` | object | нет | Настройки бронирования. |
| `presetFields` | array | нет | Предустановленные значения полей |
| `dependencies` | array | нет | Зависимости между полями |
| `analytics` | object | нет | Настройки аналитики |
| `integrations` | object | нет | Настройки интеграций |
| `spamProtection` | object | нет | Защита от спама |

Справочник [Поля контракта формы](/docs/entities/crm-forms/fields) описывает метаданные только верхнего уровня. Если создаёте форму по образцу существующей, имена вложенных свойств и исходные значения секций берите из полного ответа [Прочитать форму](/docs/entities/crm-forms/get). Секции передаются в схеме Битрикс24; доступность записи настроек определяет портал.

## Примеры

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

```bash
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-приложение

```bash
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 | Созданная форма в том же формате, что у [Прочитать форму](/docs/entities/crm-forms/get). Метаданные свойств верхнего уровня: [Поля контракта формы](/docs/entities/crm-forms/fields) |
| `data.id` | integer | ID созданной формы |
| `data.name` | string | Название формы |
| `data.active` | boolean \| null | Включена ли форма |
| `data.updatedTime` | string \| null | Время последнего изменения. Передаётся в [`PATCH /v1/crm-forms/:id`](/docs/entities/crm-forms/update) |
| `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](/docs/entities/crm-forms/get) конкретной настроенной формы. [Поля контракта формы](/docs/entities/crm-forms/fields) описывают метаданные только верхнего уровня.

```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 | Код | Описание |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | Тело не JSON-объект или передан параметр строки запроса |
| 400 | `INVALID_PARAMS` | Битрикс24 отклонил конфигурацию, например не передан `crm.entityScheme`. Нарушения перечислены в `error.validation` |
| 400 | `CRM_FORM_PARTIALLY_CREATED` | Форма существует: `error.id` — её ID, `error.b24Code` — исходный код, `error.validation` — ошибки секций. Перечитайте форму, затем исправьте или удалите её. Создание не повторяйте |
| 402 | `CRM_FORM_WRITE_RESTRICTED` | Тариф Битрикс24 не разрешает запись CRM-форм — бесплатный и демо-тариф |
| 402 | `CRM_FORM_ACTIVATION_LIMIT_REACHED` | Форма создаётся включённой, а лимит активных форм исчерпан. Лимит — `data.limits.activeForms` в [`GET /v1/crm-forms/configuration`](/docs/entities/crm-forms/configuration) |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ только для чтения. Нужен ключ с правом записи |
| 403 | `BITRIX_INSUFFICIENT_SCOPE` | У токена Битрикс24 нет необходимого скоупа |
| 404 | `ENTITY_NOT_FOUND` | Портал не нашёл запрошенную сущность или описание поля. Исходный код — `error.b24Code` |
| 409 | `CRM_FORM_REST_NOT_ENABLED` | На портале выключены методы CRM-форм |
| 403 | `BITRIX_ACCESS_DENIED` | Битрикс24 отказал в доступе: у пользователя нет права на изменение CRM-форм |
| 403 | `SCOPE_DENIED` | Ключу не хватает скоупа `crm` |
| 401 | `MISSING_API_KEY` | Не передан `X-Api-Key` |
| 401 | `TOKEN_MISSING` | У ключа нет токенов доступа к Битрикс24 |
| 422 | `BITRIX_ERROR` | Другой отказ Битрикс24. Исходное сообщение сохраняется в `error.message` |
| 500 | `CRM_FORM_SIDE_EFFECT_FAILED` | Форма уже записана, но последующий шаг на стороне Битрикс24 не выполнен. `error.id` — ID созданной формы. Прочитайте форму перед повтором |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 недоступен или вернул ответ неверного вида. Форма может быть уже создана — найдите её в [списке форм](/docs/entities/crm-forms/list) перед повтором |

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

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

- [Проверить форму](/docs/entities/crm-forms/validate)
- [Прочитать форму](/docs/entities/crm-forms/get)
- [Изменить форму](/docs/entities/crm-forms/update)
- [Включить форму](/docs/entities/crm-forms/activate)
- [Поля контракта формы](/docs/entities/crm-forms/fields)
- [Получить конфигурацию конструктора](/docs/entities/crm-forms/configuration)
- [Список полей сущностей](/docs/entities/crm-forms/entity-fields)
- [Лимиты и оптимизация](/docs/optimization)