# SIP-подключения

Управление SIP-подключениями офисных и облачных АТС, через которые портал Битрикс24 принимает и совершает звонки.

**Скоуп:** `telephony` | **Базовый URL:** `https://vibecode.bitrix24.tech/v1` | **Авторизация:** `X-Api-Key`

## Что нужно знать перед работой

1. **Два типа АТС.** `cloud` — облачная АТС, `office` — офисная. Тип задаётся при создании, по умолчанию `cloud`, и потом не меняется. Офисной АТС Битрикс24 при создании выдаёт адрес и логин для входящих вызовов — поля `incomingServer` и `incomingLogin`.
2. **Пароли только на запись.** `password` передаётся при создании и изменении, но в ответ не попадает: вместо паролей приходят признаки `hasPassword` и `hasIncomingPassword`. По этим признакам нельзя фильтровать и сортировать список.
3. **Через API задаются пять полей:** `type`, `title`, `server`, `login`, `password`. Остальные поля подключения только для чтения, а лишнее поле в теле запроса даёт `400 READONLY_FIELD`.
4. **Видны только подключения своего приложения.** Методы раздела работают с подключениями, созданными тем же приложением Битрикс24, что и ключ: ключ приложения — с подключениями своего приложения, личный ключ — с подключениями, созданными через вебхуки портала. Подключение другого приложения не попадает в список, а по его `configId` методы отвечают `404 ENTITY_NOT_FOUND`.
5. **Тип `configId` зависит от метода.** В ответах списка, получения, создания и изменения это строка, в ответе удаления — число. В пути ID передаётся числом: `/v1/voximplant-sip/17`.

## Быстрый старт

Список SIP-подключений, доступных ключу:

```bash
curl "https://vibecode.bitrix24.tech/v1/voximplant-sip" \
  -H "X-Api-Key: YOUR_API_KEY"
```

Ответ содержит массив подключений в `data` и их число в `meta.total`. Поля подключения описаны на странице [Список подключений](/docs/voximplant-sip/list).

## Полный пример

Подключение офисной АТС от создания до удаления: создать, прочитать, сменить логин и пароль, удалить. Скрипт запускается в Node.js 18+ из файла с расширением `.mjs`.

```javascript
const BASE = 'https://vibecode.bitrix24.tech/v1/voximplant-sip'
const API_KEY = 'YOUR_API_KEY'

async function call(method, path, body) {
  const headers = { 'X-Api-Key': API_KEY }
  if (body) headers['Content-Type'] = 'application/json'
  const res = await fetch(BASE + path, { method, headers, body: body && JSON.stringify(body) })
  const json = await res.json()
  if (!json.success) throw new Error(`${json.error.code}: ${json.error.message}`)
  return json.data
}

// 1. Создать подключение офисной АТС
const created = await call('POST', '', {
  type: 'office',
  title: 'Офисная АТС',
  server: 'sip.example.com',
  login: 'office-line',
  password: 'EXAMPLE_SIP_PASSWORD',
})
console.log('Создано:', created.configId, 'сервер для входящих:', created.incomingServer)

// 2. Прочитать подключение
const sip = await call('GET', `/${created.configId}`)
console.log('Тип:', sip.type, 'пароль задан:', sip.hasPassword)

// 3. Сменить логин и пароль
const updated = await call('PATCH', `/${created.configId}`, {
  login: 'office-line-2',
  password: 'EXAMPLE_NEW_SIP_PASSWORD',
})
console.log('Новый логин:', updated.login)

// 4. Удалить подключение
const removed = await call('DELETE', `/${created.configId}`)
console.log('Удалено:', removed.deleted)
```

## Справочник эндпоинтов

| Метод | Путь | Bitrix24 метод | Описание |
|-------|------|---------------|----------|
| GET | [`/v1/voximplant-sip`](/docs/voximplant-sip/list) | voximplant.sip.get | Список подключений с фильтром, сортировкой и постраничным выводом |
| GET | [`/v1/voximplant-sip/:configId`](/docs/voximplant-sip/get) | voximplant.sip.get | Одно подключение по ID |
| POST | [`/v1/voximplant-sip`](/docs/voximplant-sip/create) | voximplant.sip.add | Создать подключение |
| PATCH | [`/v1/voximplant-sip/:configId`](/docs/voximplant-sip/update) | voximplant.sip.update | Изменить название, сервер, логин или пароль |
| DELETE | [`/v1/voximplant-sip/:configId`](/docs/voximplant-sip/delete) | voximplant.sip.delete | Удалить подключение |

## Коды ошибок

### Ошибки SIP-подключений

| HTTP | Код | Когда |
|------|-----|-------|
| 400 | `INVALID_PARAMS` | Неверные параметры списка `filter`, `sort`, `order`, `start`, `configId` — не целое положительное число, тело — не JSON-объект, `type` — не `office` и не `cloud`, значение поля — не строка, при изменении нет поля, кроме `type` |
| 400 | `MISSING_REQUIRED_FIELDS` | При создании не передан `server` или `login` |
| 400 | `READONLY_FIELD` | В теле есть поле, кроме `type`, `title`, `server`, `login`, `password`, или при изменении `type` отличается от текущего |
| 404 | `ENTITY_NOT_FOUND` | Подключения с таким `configId` нет среди подключений, доступных ключу |
| 422 | `BITRIX_ERROR` | Битрикс24 отклонил запрос или не подтвердил изменение либо удаление, причина — в `error.message` |

### Системные ошибки

| HTTP | Код | Когда |
|------|-----|-------|
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Платформа не знает такой строки ключа: опечатка, обрезанное значение или удалённый ключ |
| 401 | `TOKEN_MISSING` | У ключа нет доступа к порталу: у личного ключа нет вебхука портала, ключу приложения не передан `Authorization: Bearer` с токеном сессии |
| 403 | `SCOPE_DENIED` | У ключа нет скоупа `telephony` |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ только для чтения пытается создать, изменить или удалить подключение |
| 403 | `BITRIX_ACCESS_DENIED` | Битрикс24 отказал в доступе — [разбор причин](/docs/errors/auth#bitrix_access_denied-403) |
| 429 | `RATE_LIMITED` | Превышена частота запросов |
| 429 | `QUEUE_OVERFLOW` | Очередь запросов к порталу переполнена, запрос отклонён без ожидания. Задержку подсказывает заголовок `Retry-After` |
| 429 | `QUEUE_TIMEOUT` | Запрос не дождался очереди к порталу и не был отправлен в Битрикс24. Задержку подсказывает заголовок `Retry-After` |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 недоступен |
| 503 | `BITRIX_TIMEOUT` | Битрикс24 не ответил вовремя |

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

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

- [Исходящая линия по умолчанию](/docs/voximplant-lines/default)
- [Телефония сотрудников](/docs/telephony-users)
- [Звонки](/docs/calls)
- [Телефония](/docs/telephony)