# 创建设备分机

## 接口描述

创建一个设备分机，并把设备的 SIP 注册参数自动下发给设备（设备配置只推送不拉取，设备收到配置后会自动注册到平台）。

**前置条件**：`sn` 对应的设备必须已绑定到当前账号所属公司且未被封禁，否则无法创建。

分机号在同一 SIP 域名内全局唯一：不能与已有的设备分机、坐席分机、呼叫中心号码重复；同一域名内一台设备只允许配一个分机。设备分机数量受公司配额限制。

通过 `voip_group_id` 指定所属对讲分组；不传或传 `0` 表示公司级默认分组。对讲分组的概念参见[遍历对讲分组](/voip/遍历对讲分组.md)。

**默认呼叫号码**：设备配置的允许呼入号码——只有分机号（坐席分机号）或呼叫中心号码与该号码匹配的坐席，才能在小程序中看到并主动呼叫该设备。不传默认为空，即暂不允许任何坐席主动呼叫该设备（不影响设备主动呼叫坐席）。

## 请求说明
| 接口ID | 协议 | 方法 | PATH |
| --- | --- | --- | --- |
| 105 | HTTPS | POST | /openapi/v1/voip/devices |

### PATH参数

无

### URL参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| accesskey_id | string | 是 | 参见[签名认证](/签名认证.md) |
| expires | int | 是 | 参见[签名认证](/签名认证.md) |
| signature | string | 是 | 参见[签名认证](/签名认证.md) |

### HTTP请求头
| 名称 | 必填 | 说明 |
| --- | --- | --- |
| Content-Type | 是 | `application/json` |

### 请求参数

请求参数以Json格式放置于Body中，如下：

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| dial_id | string | 是 | 分机号，5-20 位，只能包含字母、数字及 `_.-`；建议直接使用设备 SN |
| sn | string | 是 | 设备SN，格式为 `xxxxxxxx-xxxxxxxx`（16 位十六进制）或 20 位数字 |
| password | string | 是 | 分机密码（设备 SIP 注册使用） |
| display_name | string | 是 | 设备显示名称 |
| remark | string | 否 | 备注 |
| default_call_number | string | 否 | 默认呼叫号码，须为本域名内的坐席分机号或呼叫中心号码 |
| voip_group_id | int | 否 | 所属对讲分组ID；不传或传 `0` 表示公司级默认分组 |

### 请求示例

```
POST https://open.vzicloud.com/openapi/v1/voip/devices?accesskey_id=8d9EsDAD2115Q5PM8tuP6g1IdAglkayp&expires=1619022787&signature=G29eTBjMm0gZF7cpXNLX7Hrn0yM%3D HTTP/1.1
Host: open.vzicloud.com
Content-Type: application/json

{
  "dial_id": "5c88cc28-eeee7a12",
  "sn": "5c88cc28-eeee7a12",
  "password": "dev123456",
  "display_name": "门口机-1",
  "remark": "",
  "default_call_number": "80001",
  "voip_group_id": 12
}
```

## 返回说明

### 返回参数
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| id | int | 设备分机ID |
| sn | string | 设备SN |
| dial_id | string | 分机号 |
| display_name | string | 设备显示名称 |
| enable | int | 启用状态（0:启用 / 1:停用） |
| status | int | SIP 注册状态（0:在线 / 1:离线） |
| default_call_number | string | 默认呼叫号码（未配置时为空串） |
| domain | string | SIP 域名（公司级如 `2.voip1.sip`，分组级如 `2.xiaoqu-a.voip1.sip`） |
| voip_group_id | int | 所属对讲分组ID；`0` = 公司级默认分组（与修改接口的 `voip_group_id` 取值一致） |
| voip_group_name | string | 所属对讲分组名称；公司级默认分组时为 `-` |

**注：返回参数里可能还包含其他信息但未在上面的表格内列出，请勿使用！**

### 返回示例


```json
{
  "id": 101,
  "sn": "5c88cc28-eeee7a12",
  "dial_id": "5c88cc28-eeee7a12",
  "display_name": "门口机-1",
  "enable": 0,
  "status": 1,
  "default_call_number": "80001",
  "domain": "2.xiaoqu-a.voip1.sip",
  "voip_group_id": 12,
  "voip_group_name": "小区A"
}
```