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

`POST /v1/calls/:callId/finish`

Завершает зарегистрированный звонок: фиксирует длительность и итоговый статус, создаёт дело в связанной CRM-сущности. Вызывайте после окончания разговора, до прикрепления транскрипции.

## Параметры

| Параметр | В | Тип | Обяз. | Описание |
|----------|---|-----|:-----:|---------|
| `callId` | path | string | да | `callId` из ответа [`POST /v1/calls/register`](./register.md) |

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

| Параметр | Тип | Обяз. | По умолч. | Описание |
|----------|-----|:-----:|-----------|---------|
| `userId` | number | да | — | ID пользователя Битрикс24, завершившего звонок. Положительное целое число, принимается также числовая строка `"42"`. [Список пользователей](/docs/entities/users) |
| `duration` | number | да | — | Длительность звонка в секундах. Неотрицательное число, принимается также числовая строка |
| `statusCode` | string | нет | `"200"` при duration > 0, иначе `"304"` | Код завершения: `"200"` успешно, `"304"` пропущен, `"403"` запрещено, `"486"` занято, `"603"` отклонён, `"603-S"` отменён клиентом, `"402"` нет средств, `"404"` неверный номер, `"423"` заблокирован, `"480"` временно недоступен, `"484"` / `"503"` недоступное направление, `"OTHER"` |
| `add_to_chat` | boolean | нет | — | Добавить событие о звонке в чат сотрудника |
| `vote` | number | нет | — | Оценка звонка: `1`–`5`. Попадает в поле `CALL_VOTE` («Оценка», звёздочки) раздела [Статистика звонков](/docs/telephony/analytics/statistics). Допускается также UPPER-форма `VOTE` |

## Примеры

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

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/calls/CALL_ID/finish \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 1,
    "duration": 120,
    "statusCode": "200"
  }'
```

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

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/calls/CALL_ID/finish \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 1,
    "duration": 120,
    "statusCode": "200"
  }'
```

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

```javascript
const callId = 'externalCall.00b1e735843c558431be668e3687a58b.1777974304'

const res = await fetch(`https://vibecode.bitrix24.tech/v1/calls/${callId}/finish`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: 1,
    duration: 120,
    statusCode: '200',
  }),
})

const { success, data } = await res.json()
console.log('Дело:', data.crmActivityId)
```

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

```javascript
const callId = 'externalCall.00b1e735843c558431be668e3687a58b.1777974304'

const res = await fetch(`https://vibecode.bitrix24.tech/v1/calls/${callId}/finish`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: 1,
    duration: 120,
    statusCode: '200',
  }),
})

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

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

| Поле | Тип | Описание |
|------|-----|---------|
| `callId` | string | Идентификатор звонка |
| `externalCallId` | string \| null | Внешний идентификатор, переданный при регистрации |
| `portalUserId` | number | ID пользователя Битрикс24 |
| `phoneNumber` | string | Номер телефона |
| `portalNumber` | string | Номер линии на портале |
| `incoming` | string | Тип звонка: `"1"` — исходящий, `"2"` — входящий, `"3"` — входящий с перенаправлением, `"4"` — обратный звонок, `"5"` — информационный |
| `callDuration` | number | Длительность в секундах |
| `callStartDate` | object | Дата начала звонка. Возвращается как пустой объект `{}` — см. [особенности](#известные-особенности) |
| `callStatus` | number | Статус завершения |
| `callVote` | number | Оценка звонка |
| `cost` | number | Стоимость звонка |
| `costCurrency` | string | Валюта стоимости |
| `callFailedCode` | string | Переданный `statusCode` |
| `callFailedReason` | string | Текстовое описание причины завершения |
| `restAppId` | number \| null | ID приложения |
| `restAppName` | string \| false | Имя приложения |
| `crmActivityId` | number \| false | ID созданного дела. `false`, если сущность не привязана |
| `comment` | string \| null | Комментарий к звонку |
| `id` | number | Внутренний ID записи о звонке |
| `ERRORS` | object \| null | Ошибки, не прервавшие завершение (например `ACTIVITY_CREATION`) |
| `crmEntityType` | string | Тип привязанной CRM-сущности (только при наличии привязки) |
| `crmEntityId` | number | ID привязанной CRM-сущности (только при наличии привязки) |

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

HTTP 200 — звонок завершён, дело создано:

```json
{
  "success": true,
  "data": {
    "callId": "externalCall.00b1e735843c558431be668e3687a58b.1777974304",
    "externalCallId": null,
    "portalUserId": 1,
    "phoneNumber": "+79161234567",
    "portalNumber": "REST_APP:",
    "incoming": "2",
    "callDuration": 120,
    "callStartDate": {},
    "callStatus": 1,
    "callVote": 0,
    "cost": 0,
    "costCurrency": "",
    "callFailedCode": "200",
    "callFailedReason": "",
    "restAppId": null,
    "restAppName": false,
    "crmActivityId": 7995,
    "comment": null,
    "crmEntityType": "LEAD",
    "crmEntityId": 1001069,
    "id": 61
  }
}
```

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

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

```json
{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "Required: userId (positive integer), duration (number ≥ 0, seconds)"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `MISSING_PARAMS` | `userId` не передан или не распознан как положительное целое число, либо `duration` не передан или не распознан как неотрицательное число |
| 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` | Битрикс24 вернул ошибку (текст в `error.message`) |
| 429 | `RATE_LIMITED` | Превышен лимит запросов |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 недоступен |

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

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

**`callStartDate` всегда возвращается как пустой объект `{}`.** Реальную дату начала звонка смотрите в [статистике](/docs/telephony/analytics/statistics).

**`CRM_ACTIVITY_ID: false` при отсутствии привязки.** В поле `ERRORS.ACTIVITY_CREATION` возвращается текстовое описание причины. Звонок при этом считается завершённым.

**Значение `statusCode` влияет на метку в CRM.** Явная передача позволяет зафиксировать причину завершения независимо от длительности.

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

- [Зарегистрировать звонок](./register.md)
- [Прикрепить транскрипцию](./transcription.md)
- [Показать карточку](./show.md)
- [Статистика звонков](/docs/telephony/analytics/statistics)
- [Лиды](/docs/entities/leads)
- [Контакты](/docs/entities/contacts)
- [Сделки](/docs/entities/deals)