## Отправить данные посетителя

`POST /v1/crm-forms/:id/results`

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

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|----------|
| `id` (path) | integer | да | Идентификатор формы. Список: [Список форм](/docs/entities/crm-forms/list) |

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

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|----------|
| `fields` | object | да | Непустой объект значений. Ключи — имена полей формы `fields[].name` из [Получить форму](/docs/entities/crm-forms/get), например `LEAD_NAME`, `LEAD_PHONE`. Поля типа `file` не поддерживаются |
| `presets` | object | нет | Предустановленные значения, передаются без изменений |
| `fromUrl` | string | нет | Адрес страницы, на которой заполнена форма |

Другие поля в теле не принимаются. Состав и значения полей проверяются по настройкам формы.

## Примеры

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

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/crm-forms/75/results" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fields":{"LEAD_NAME":"Анна","LEAD_PHONE":"+12025550123"},"fromUrl":"https://example.com/contact"}'
```

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

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/crm-forms/75/results" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fields":{"LEAD_NAME":"Анна","LEAD_PHONE":"+12025550123"},"fromUrl":"https://example.com/contact"}'
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-forms/75/results', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fields: { LEAD_NAME: 'Анна', LEAD_PHONE: '+12025550123' },
    fromUrl: 'https://example.com/contact',
  }),
})

const { data } = await res.json()
console.log('Результат формы:', data.resultId)
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-forms/75/results', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fields: { LEAD_NAME: 'Анна', LEAD_PHONE: '+12025550123' },
    fromUrl: 'https://example.com/contact',
  }),
})

const { data } = await res.json()
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | `true`, когда результат сохранён |
| `data.resultId` | number | Идентификатор результата заполнения формы. Это не ID созданного лида или сделки |

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

HTTP 201 — результат сохранён:

```json
{
  "success": true,
  "data": {
    "resultId": 231
  }
}
```

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

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

```json
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Form not found."
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `MISSING_REQUIRED_FIELDS` | `fields` не передан, пуст или не объект, сообщение «fields must be a non-empty object» |
| 400 | `INVALID_PARAMS` | `id` не положительное целое число, сообщение «id must be a positive safe integer» |
| 400 | `INVALID_PARAMS` | Тело не JSON-объект, сообщение «Request body must be a JSON object» |
| 400 | `INVALID_PARAMS` | В теле есть поле, кроме `fields`, `presets`, `fromUrl`, сообщение «Only fields, presets and fromUrl are accepted» |
| 400 | `INVALID_PARAMS` | `presets` не объект или `fromUrl` не строка |
| 404 | `ENTITY_NOT_FOUND` | Формы с таким `id` нет, сообщение «Form not found.» |
| 422 | `BITRIX_ERROR` | Битрикс24 не принял результат: форма выключена («Form is not active.») или передано поле типа `file`. Текст Битрикс24 приходит в `message`, исходный код — в `b24Code`, для выключенной формы `ERROR_CORE` |
| 403 | код Битрикс24 | Битрикс24 отказал в доступе. `code` и `message` приходят от Битрикс24 без изменений |
| 409 | код Битрикс24 | Битрикс24 отклонил результат из-за состояния формы или портала. `code` и `message` приходят от Битрикс24 без изменений |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ только для чтения. Для отправки нужен ключ с правом записи |
| 429 | `RATE_LIMITED` | Превышена частота запросов к Битрикс24 |
| 502 | `BITRIX_RESPONSE_INVALID` | Битрикс24 не вернул идентификатор результата, сообщение `Bitrix24 returned no result ID; do not retry blindly` |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 недоступен: ответил ошибкой сервера или соединение оборвалось |
| 503 | `BITRIX_TIMEOUT` | Битрикс24 принял запрос, но не ответил за отведённое время |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `TOKEN_MISSING` | У API-ключа нет настроенных токенов Битрикс24 |
| 403 | `SCOPE_DENIED` | У API-ключа нет скоупа `crm` |

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

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

- **Не повторяйте отправку вслепую.** Каждый вызов сохраняет новый результат, и Вайбкод сам отправку не повторяет. После `502`, `503` или обрыва соединения результат мог сохраниться и уже запустить автоматизацию, поэтому повторный вызов создаст второй результат.
- **Неизвестные ключи `fields` не отклоняются.** Значение с именем, которого нет в форме, не вызывает ошибку: результат создаётся и возвращается `201`. Сверяйте ключи с `fields[].name` формы до отправки.

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

- [Получить форму](/docs/entities/crm-forms/get)
- [Список форм](/docs/entities/crm-forms/list)
- [Включить форму](/docs/entities/crm-forms/activate)
- [Отправить CRM-форму клиенту](/docs/openlines/send-form)
- [Лимиты и оптимизация](/docs/optimization)