## Создать лид из обращения

`POST /v1/openlines/dialogs/:chatId/lead`

Создаёт лид в CRM по диалогу открытой линии и возвращает карточку CRM, к которой диалог привязан после вызова. Если к диалогу уже привязана карточка CRM, новый лид не создаётся и приходит существующая привязка.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|----------|
| `chatId` (path) | number | да | Идентификатор чата открытой линии — положительное целое без префикса `chat`. Список: поле `chatId` в ответе [`POST /v1/openlines/sessions/search`](/docs/openlines/sessions/search) |

Тело запроса пустое.

## Примеры

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

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/openlines/dialogs/123/lead \
  -H "X-Api-Key: YOUR_API_KEY"
```

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

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/openlines/dialogs/123/lead \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

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

```javascript
const chatId = 123
const res = await fetch(`https://vibecode.bitrix24.tech/v1/openlines/dialogs/${chatId}/lead`, {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { success, data, error } = await res.json()
if (!success) throw new Error(`${error.code}: ${error.message}`)
if (data.leadId === null) {
  console.log(`Диалог уже привязан: ${data.crmEntityType} ${data.crmEntityId}`)
} else {
  console.log('Лид:', data.leadId)
}
```

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

```javascript
const chatId = 123
const res = await fetch(`https://vibecode.bitrix24.tech/v1/openlines/dialogs/${chatId}/lead`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

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

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | `true`, когда привязка диалога прочитана после вызова |
| `data.chatId` | number | Идентификатор чата из запроса |
| `data.crmEntityType` | string | Тип карточки CRM, к которой привязан диалог: `lead`, `deal`, `company` или `contact` |
| `data.crmEntityId` | number | ID карточки CRM, к которой привязан диалог |
| `data.leadId` | number \| null | ID лида, когда диалог привязан к лиду. `null`, когда диалог привязан к сделке, компании или контакту |

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

Диалог привязан к лиду:

```json
{
  "success": true,
  "data": {
    "chatId": 123,
    "crmEntityType": "lead",
    "crmEntityId": 42,
    "leadId": 42
  }
}
```

К диалогу уже была привязана сделка:

```json
{
  "success": true,
  "data": {
    "chatId": 123,
    "crmEntityType": "deal",
    "crmEntityId": 42,
    "leadId": null
  }
}
```

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

400 — `chatId` в пути не положительное целое:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_CHAT_ID",
    "message": "chatId must be a positive safe integer"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `INVALID_JSON_BODY` | Передано тело запроса, которое не разбирается как JSON. Проверка идёт до разбора `chatId` в пути |
| 400 | `INVALID_CHAT_ID` | `chatId` в пути не положительное целое, в том числе форма `chat123`, или число больше 9007199254740991. Битрикс24 не вызывается |
| 404 | `ENTITY_NOT_FOUND` | Битрикс24 не нашёл чат с таким `chatId` |
| 403 | `BITRIX_ACCESS_DENIED` | У сотрудника, от имени которого идёт вызов, нет прав на диалог, лид не создан |
| 403 | `BITRIX_ACCESS_DENIED` | Сообщение `Bitrix24 refused the dialog: it is absent or inaccessible`: Битрикс24 принял вызов, но отказал в чтении привязки диалога. Лид при этом мог быть создан |
| 422 | `BITRIX_ERROR` | Битрикс24 отказал в создании лида, его код приходит в `error.b24Code` |
| 502 | `OPENLINE_OPERATOR_FAILED` | Битрикс24 не подтвердил создание лида либо после вызова не удалось прочитать привязку диалога к CRM. Лид при этом мог быть создан |
| 403 | `SCOPE_DENIED` | У ключа нет скоупа `imopenlines` |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ работает только на чтение |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Ключ не опознан |
| 401 | `TOKEN_MISSING` | У личного ключа нет доступа к порталу Битрикс24, у ключа приложения не передан токен сессии в `Authorization` |
| 429 | `RATE_LIMITED` | Превышен лимит 120 запросов в минуту на портал. Лимит делится между репликами платформы, поэтому код может прийти раньше 120-го запроса. Действующее значение для ключа — в заголовке `x-ratelimit-limit`, остаток — в `x-ratelimit-remaining` |
| 429 | `RATE_LIMITED` | Битрикс24 отклонил вызов по лимиту частоты запросов к порталу. В ответе приходит заголовок `Retry-After` |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 недоступен или соединение с ним оборвалось до полного ответа |
| 503 | `BITRIX_TIMEOUT` | Битрикс24 принял вызов, но не ответил за отведённое время. Лид при этом мог быть создан |

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

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

- **Повтор после сбоя безопасен.** После `502 OPENLINE_OPERATOR_FAILED`, `503 BITRIX_TIMEOUT` и `403 BITRIX_ACCESS_DENIED` вызов можно повторить: если первый вызов успел создать лид, повторный второго лида не создаст и вернёт уже существующую привязку.

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

- [Отправить сообщение клиенту](/docs/openlines/crm/messages)
- [Участники CRM-чата](/docs/openlines/crm/members)
- [Чаты по карточке CRM](/docs/openlines/crm-chats)
- [Поиск сессий](/docs/openlines/sessions/search)
- [Получить лид](/docs/entities/leads/get)