## Зарегистрировать звонок

`POST /v1/calls/register`

Регистрирует входящий или исходящий звонок в Битрикс24 CRM. При `crmCreate: true` создаёт лид, если номер телефона не найден среди существующих сущностей. Возвращает `callId` для всех последующих операций со звонком.

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

| Параметр | Тип | Обяз. | По умолч. | Описание |
|----------|-----|:-----:|-----------|---------|
| `userId` | number | да | — | ID пользователя Битрикс24, принимающего звонок. Положительное целое число, принимается также числовая строка `"42"`. [Список пользователей](/docs/entities/users) |
| `phoneNumber` | string | да | — | Номер телефона звонящего в международном формате. Непустая строка или число. Пробелы по краям отбрасываются, строка из одних пробелов считается пустой |
| `type` | number | да | — | Направление: `1` — исходящий, `2` — входящий, `3` — входящий с перенаправлением, `4` — обратный звонок, `5` — информационный |
| `lineNumber` | string | нет | — | Номер внешней линии приложения. [Список линий](/docs/telephony/lines/list) |
| `crmCreate` | boolean | нет | `false` | `true` — создать лид, если номер не найден в CRM |

## Примеры

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

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/calls/register \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 1,
    "phoneNumber": "+79161234567",
    "type": 2,
    "crmCreate": true
  }'
```

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

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/calls/register \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 1,
    "phoneNumber": "+79161234567",
    "type": 2,
    "crmCreate": true
  }'
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/calls/register', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: 1,
    phoneNumber: '+79161234567',
    type: 2,
    crmCreate: true,
  }),
})

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

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/calls/register', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: 1,
    phoneNumber: '+79161234567',
    type: 2,
    crmCreate: true,
  }),
})

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

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

| Поле | Тип | Описание |
|------|-----|---------|
| `callId` | string | Идентификатор звонка для всех последующих операций |
| `crmCreatedLead` | number \| null | ID созданного лида. `null`, если лид не создан |
| `crmCreatedEntities` | array | Массив созданных CRM-сущностей `[{entityType, entityId}]` |
| `crmEntityType` | string | Тип привязанной CRM-сущности: `LEAD`, `CONTACT`, `COMPANY` или пустая строка |
| `crmEntityId` | number \| null | ID привязанной CRM-сущности. `null`, если сущность не привязана |

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

HTTP 201 — звонок зарегистрирован, создан новый лид:

```json
{
  "success": true,
  "data": {
    "callId": "externalCall.00b1e735843c558431be668e3687a58b.1777974304",
    "crmCreatedLead": 1001069,
    "crmCreatedEntities": [{"entityType": "LEAD", "entityId": 1001069}],
    "crmEntityType": "LEAD",
    "crmEntityId": 1001069
  }
}
```

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

400 — не переданы обязательные параметры:

```json
{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "Required: userId (positive integer), phoneNumber (non-empty string)"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `MISSING_PARAMS` | `userId` не передан или не распознан как положительное целое число, либо `phoneNumber` не передан или не распознан как непустая строка или число |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Неверный API-ключ |
| 401 | `TOKEN_MISSING` | Ключ не имеет настроенных токенов Битрикс24 |
| 401 | `KEY_INACTIVE` | API-ключ неактивен или отозван |
| 403 | `SCOPE_DENIED` | Ключу не хватает скоупа `telephony` |
| 422 | `BITRIX_ERROR` | `type` не передан или его значение вне перечня `1`–`5` — в `error.message` приходит `Unknown TYPE` |
| 422 | `BITRIX_ERROR` | Битрикс24 вернул ошибку (текст в `error.message`) |
| 429 | `RATE_LIMITED` | Превышен лимит запросов |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 недоступен |

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

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

**Поиск существующей CRM-сущности при `crmCreate: true`.** Битрикс24 сначала ищет лид, контакт или компанию с совпадающим номером телефона. При нахождении `crmEntityId` указывает на существующую сущность, а `crmCreatedLead` остаётся `null`. Новый лид создаётся только если совпадений нет.

**`CRM_*` поля пустые при `crmCreate: false`.** Привязка к CRM может произойти автоматически при завершении через [`POST /v1/calls/:callId/finish`](./finish.md), если Битрикс24 найдёт совпадение по номеру в момент завершения.

**`callId` — обязательный параметр для всех следующих шагов.** Сохраните его сразу: все операции `show`, `hide`, `finish`, `transcription` принимают `callId` в пути запроса.

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

- [Завершить звонок](./finish.md)
- [Показать карточку](./show.md)
- [Скрыть карточку](./hide.md)
- [Прикрепить транскрипцию](./transcription.md)
- [Лиды](/docs/entities/leads)
- [Контакты](/docs/entities/contacts)
- [Линии](/docs/telephony/lines)