## Обновить линию

`PATCH /v1/telephony-lines/:number`

Обновляет параметры существующей внешней линии приложения. Идентификатор `number` задаётся при создании и не меняется. Поля передаются плоско в корне JSON — без обёртки `fields`.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|---------|
| `number` (path) | string | да | Идентификатор линии, заданный при создании. Если содержит спецсимволы — URL-кодировать |

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

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|---------|
| `name` | string | нет | Новое отображаемое название линии |
| `crmAutoCreate` | boolean | нет | Автосоздание CRM-сущности при исходящем звонке: `true` / `false` |

## Примеры

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

```bash
curl -X PATCH "https://vibecode.bitrix24.tech/v1/telephony-lines/sip-line-1" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Основная линия (обновлено)"
  }'
```

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

```bash
curl -X PATCH "https://vibecode.bitrix24.tech/v1/telephony-lines/sip-line-1" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Основная линия (обновлено)"
  }'
```

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

```javascript
const number = 'sip-line-1'
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/telephony-lines/${encodeURIComponent(number)}`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Основная линия (обновлено)',
    }),
  }
)

const { success, data } = await res.json()
console.log('Идентификатор линии:', data.id)
```

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

```javascript
const number = 'sip-line-1'
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/telephony-lines/${encodeURIComponent(number)}`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Основная линия (обновлено)',
    }),
  }
)

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

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

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data.id` | string | Идентификатор обновлённой линии (значение `number` из URL) |

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

```json
{
  "success": true,
  "data": {
    "id": "sip-line-1"
  }
}
```

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

422 — линия не найдена или ошибка Битрикс24:

```json
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "NUMBER should not be empty"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `READONLY_FIELD` | В теле передано поле только для чтения — `serverName` |
| 422 | `BITRIX_ERROR` | Битрикс24 вернул ошибку — текст в `error.message` |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Неверный API-ключ |
| 401 | `TOKEN_MISSING` | Ключ не имеет настроенных токенов |
| 401 | `KEY_INACTIVE` | API-ключ неактивен или отозван |
| 403 | `SCOPE_DENIED` | Ключу не хватает скоупа `telephony` |
| 429 | `RATE_LIMITED` | Превышен лимит запросов |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 недоступен |

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

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

**Нужно хотя бы одно обновляемое поле.** Распознаются только `name` и `crmAutoCreate`. Тело без них (пустое или только с нераспознанными полями) отвечает `422 «There are no fields to update»`.

**`serverName` — только для чтения.** Битрикс24 его не хранит и не возвращает, поэтому запись отклоняется до обращения к Битрикс24: `PATCH` с этим полем отвечает `400 READONLY_FIELD` (раньше — `422 «There are no fields to update»`). Поле остаётся видимым в `GET /v1/telephony-lines/fields` с признаком «только для чтения».

**`data.id` — это `number` из URL и адресуемый строковый идентификатор.** Ответ `POST /v1/telephony-lines` также возвращает адресуемый строковый `number`: при создании — значение из тела запроса, при обновлении — значение из пути.

**Изменить `number` через обновление нельзя.** Идентификатор фиксируется при создании. Чтобы сменить `number` — удалите линию и создайте новую с нужным значением.

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

- [Список линий приложения](./list.md)
- [Добавить линию](./create.md)
- [Удалить линию](./delete.md)