隐私号ProtectionNumber（中间号）呼叫接口规范

[toc]

1 概述

1.1 API的封装

zwan呼叫接口采用HTTP作为API接口。

other=>operation: 第三方应用
imp=>operation: HTTP接口
scp=>operation: 呼叫平台
other->imp->scp

1.2 消息格式规定

WEB对外接口统一使用HTTP POST消息。回调接口一般使用HTTP POST。

所有发向ZWAN服务器的消息均需要签名。

HTTP请求中的参数值需要进行URL转义（URLEncode）。

参数名称严格区分大小写。

1.3 签名算法

消息签名算法如下：

将HTTP请求参数按参数名以字典顺序排序；

将请求参数名和参数值以=连接；

将步骤2中得到的各字符串按步骤1规定的顺序连接，连接时使用&作为分隔；

对步骤3得到的字符串求MD5散列值，并按16进制方式编码为字符串（如有字母则小写）；

将步骤4得到的字符串与签名密钥连接，连接时不使用分隔符；

对步骤5得到的字符串再求一次MD5散列值，并按16进制方式编码为字符串（如有字母则小写）；

上述算法中得到的字符串，作为HTTP参数digest，一起发送给服务端。digest本身不参与签名算法。

1.4 消息签名密钥

消息签名密钥可以在企业管理台中设置。修改后实时生效。

2 号码绑定管理接口

2.1 中间号AXB型绑定请求接口

AXB型，表示A拨打X将会被路由到B。B拨打X将会被路由到A，A和B看到的来电号码均为X。

2.1.1 描述

条目	说明
功能	应用系统可以调用此接口获取AXB型绑定的临时中间号码。系统呼叫主被叫双方时，显示号码将采用绑定的显示号码。
请求方向	应用系统->ZWAN服务器
请求地址	POST http://ip:port/zwpn/bindAxb

2.1.2 请求参数

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，确保不重复。建议在流水号中包含时间戳
companyid	18	是	企业编号，保存在系统的唯一编号，用于向企业计费
callnumberA	20	是	AXB中的A号码。A号码可设置为手机号码或固定电话，固定电话需要加区号，区号和号码中间不需要加连字符，例如057188992688。
callnumberB	20	是	AXB中的B号码，A号码拨打X号码时会转接到B号码，可通过接口UpdateSubscription更新B号码。B号码可设置为手机号码或固定电话，固定电话需要加区号，区号和号码中间不需要加连字符，例如057188992688。
areacode	10	否	区号，指定城市进行X号码的选号。如果当前号池中没有该城市的可用号码，或未指定此参数，将从当前号码池中随机分配一个其他城市的号码作为X号码。
callmode	1	否	呼叫模式 0_不需要录音 1_需要录音，默认全程录音
expiration	30	是	绑定关系的过期时间。必须晚于当前时间1分钟以上。
callnumberX	20	否	AXB中的X号码，A号码拨打X号码时会转接到B号码，可通过接口bindupdate更新B号码。若指定X号码，则采用X号码进行绑定，否则由系统在号码池中随机选择一个匹配地区的可用号码
digest	32	是	消息签名，见“签名算法”

2.1.3 响应参数

以HTTP 响应码表示，见下表

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，请求携带的值原样返回
code	4	是	结果状态码描述，含义参考下表
message	100	是	结果状态码的描述
bindId	30	否	绑定关系ID，后续对绑定关系操作的唯一标识。状态码=200时有效
callnumberX	20	是	AXB中的X号码。状态码=200时有效。请求中携带X则原样返回

响应码	含义	建议
200	成功
503	服务暂停	稍后再试，或者联系运营提供商
401	验签失败	检查签名算法和签名密钥
403	企业不存在或状态异常	联系运营提供商
400	参数错误	参数不满足格式要求，或者参数值为空

响应体为json数据，如下：

{
    "result": "200",    //登录成功
    "deviceid": "470"   //登录成功的deviceid
    "username": "测试员"   //用户名称（昵称）
}

2.2 中间号AXN型绑定请求接口

给用户A号码分配小号X，别人可以通过拨打X接通到用户A。

2.2.1 描述

条目	说明
功能	应用系统采用AXN隐私号接口是为A号码分配一个专属的隐私号，任何号码N通过拨打X号码都可以转接到A。
请求方向	应用系统->ZWAN服务器
请求地址	POST http://ip:port/zwpn/bindAxn

2.2.2 请求参数

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，确保不重复。建议在流水号中包含时间戳
companyid	18	是	企业编号，保存在系统的唯一编号，用于向企业计费
callnumberA	20	是	AXN中的A号码。A号码可设置为手机号码或固定电话，固定电话需要加区号，区号和号码中间不需要加连字符，例如057188992688。
areacode	10	否	区号，指定城市进行X号码的选号。如果当前号池中没有该城市的可用号码，或未指定此参数，将从当前号码池中随机分配一个其他城市的号码作为X号码。
callmode	1	否	呼叫模式 0_不需要录音 1_需要录音，默认全程录音
expiration	30	是	绑定关系的过期时间。必须晚于当前时间1分钟以上。
callnumberX	20	否	AXN中的X号码。若指定X号码，则采用X号码进行绑定，否则由系统在号码池中随机选择一个匹配地区的可用号码
digest	32	是	消息签名，见“签名算法”

2.2.3 响应参数

以HTTP 响应码表示，见下表

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，请求携带的值原样返回
code	4	是	结果状态码描述，含义参考下表
message	100	是	结果状态码的描述
bindId	30	否	绑定关系ID，后续对绑定关系操作的唯一标识。状态码=200时有效
callnumberX	20	是	AXN中的X号码。状态码=200时有效。

响应码	含义	建议
200	成功
503	服务暂停	稍后再试，或者联系运营提供商
401	验签失败	检查签名算法和签名密钥
403	企业不存在或状态异常	联系运营提供商
400	参数错误	参数不满足格式要求，或者参数值为空

响应体为json数据，如下：

{
    "result": "200",    //登录成功
    "deviceid": "470"   //登录成功的deviceid
    "username": "测试员"   //用户名称（昵称）
}

2.3 中间号AXG型绑定请求接口

AXG隐私号是针对有用户分级需求、限制呼叫范围、限制抢单等场景的客户需求提供的号码隐私保护解决方案，其中G代表一个号码组，可以根据需要添加号码。

2.3.1 描述

条目	说明
功能	应用系统采用AXG隐私号接口是为A号码分配一个专属的隐私号，创建一个组G，任何组内号码G1.G2通过拨打X号码都可以转接到A。
请求方向	应用系统->ZWAN服务器
请求地址	POST http://ip:port/zwpn/bindAxg

2.3.2 请求参数

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，确保不重复。建议在流水号中包含时间戳
companyid	18	是	企业编号，保存在系统的唯一编号，用于向企业计费
callnumberA	20	是	AXN中的A号码。A号码可设置为手机号码或固定电话，固定电话需要加区号，区号和号码中间不需要加连字符，例如057188992688。
groupid	20	是	AXG中的G组id号码，组ID通过addgroup创建组时获得
areacode	10	否	区号，指定城市进行X号码的选号。如果当前号池中没有该城市的可用号码，或未指定此参数，将从当前号码池中随机分配一个其他城市的号码作为X号码。
callmode	1	否	呼叫模式 0_不需要录音 1_需要录音，默认全程录音
expiration	30	是	绑定关系的过期时间。必须晚于当前时间1分钟以上。
callnumberX	20	否	AXG中的X号码。若指定X号码，则采用X号码进行绑定，否则由系统在号码池中随机选择一个匹配地区的可用号码
digest	32	是	消息签名，见“签名算法”

2.3.3 响应参数

以HTTP 响应码表示，见下表

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，请求携带的值原样返回
code	4	是	结果状态码描述，含义参考下表
message	100	是	结果状态码的描述
bindId	30	否	绑定关系ID，后续对绑定关系操作的唯一标识。状态码=200时有效
callnumberX	20	是	AXN中的X号码。状态码=200时有效。

响应码	含义	建议
200	成功
503	服务暂停	稍后再试，或者联系运营提供商
401	验签失败	检查签名算法和签名密钥
403	企业不存在或状态异常	联系运营提供商
400	参数错误	参数不满足格式要求，或者参数值为空

响应体为json数据，如下：

{
    "result": "200",    //登录成功
    "deviceid": "470"   //登录成功的deviceid
    "username": "测试员"   //用户名称（昵称）
}

2.4 中间号解除绑定请求接口

调用接口unbind解除号码的绑定关系。用于在指定的自动释放绑定关系时间前解除绑定关系。

2.4.1 描述

条目	说明
功能	应用系统采用本接口解除号码的绑定关系。
请求方向	应用系统->ZWAN服务器
请求地址	POST http://ip:port/zwpn/unbind

2.4.2 请求参数

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，确保不重复。建议在流水号中包含时间戳
companyid	18	是	企业编号，保存在系统的唯一编号，用于向企业计费
bindId	30	是	绑定关系ID，后续对绑定关系操作的唯一标识。状态码=200时有效
digest	32	是	消息签名，见“签名算法”

2.4.3 响应参数

以HTTP 响应码表示，见下表

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，请求携带的值原样返回
code	4	是	结果状态码描述，含义参考下表
message	100	是	结果状态码的描述

响应码	含义	建议
200	成功
503	服务暂停	稍后再试，或者联系运营提供商
401	验签失败	检查签名算法和签名密钥
403	企业不存在或状态异常	联系运营提供商
400	参数错误	参数不满足格式要求，或者参数值为空

响应体为json数据，如下：

{
    "result": "200",    //登录成功
    "deviceid": "470"   //登录成功的deviceid
    "username": "测试员"   //用户名称（昵称）
}

2.5 中间号绑定关系更新请求接口

调用接口binddelay 更新号码的绑定关系有效期或号码归属地区。用于在指定的自动释放绑定关系时间前延长绑定关系。

2.5.1 描述

条目	说明
功能	应用系统采用本接口解除号码的绑定关系。
请求方向	应用系统->ZWAN服务器
请求地址	POST http://ip:port/zwpn/bindupdate

2.5.2 请求参数

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，确保不重复。建议在流水号中包含时间戳
companyid	18	是	企业编号，保存在系统的唯一编号，用于向企业计费
bindId	30	是	绑定关系ID，后续对绑定关系操作的唯一标识。状态码=200时有效
areacode	10	否	区号，指定城市进行X号码的选号。如果当前号池中没有该城市的可用号码，或未指定此参数，将从当前号码池中随机分配一个其他城市的号码作为X号码。
expiration	30	否	绑定关系的过期时间。必须晚于当前时间1分钟以上。
digest	32	是	消息签名，见“签名算法”

2.5.3 响应参数

以HTTP 响应码表示，见下表

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，请求携带的值原样返回
code	4	是	结果状态码描述，含义参考下表
message	100	是	结果状态码的描述

响应码	含义	建议
200	成功
503	服务暂停	稍后再试，或者联系运营提供商
401	验签失败	检查签名算法和签名密钥
403	企业不存在或状态异常	联系运营提供商
400	参数错误	参数不满足格式要求，或者参数值为空

响应体为json数据，如下：

{
    "result": "200",    //登录成功
    "deviceid": "470"   //登录成功的deviceid
    "username": "测试员"   //用户名称（昵称）
}

2.6 中间号AXYB型绑定请求接口

AXYB产品为双向号码保护场景提供服务。A指商家号码，X为平台分配给A的长期绑定的中间号；号码B指通过中间号X呼叫商家A的用户号码，Y为发送呼叫时平台为用户B分配的临时中间号。

2.6.1 描述

条目	说明
功能	应用系统采用AXYB隐私号接口是为A号码分配一个专属的隐私号，任何号码B通过拨打X号码都可以转接到A，转接时显示号码为Y。A在一定周期内回拨Y会接续到B
请求方向	应用系统->ZWAN服务器
请求地址	POST http://ip:port/zwpn/bindaxyb

2.6.2 请求参数

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，确保不重复。建议在流水号中包含时间戳
companyid	18	是	企业编号，保存在系统的唯一编号，用于向企业计费
callnumberA	20	是	AXYB中的A号码。A号码可设置为手机号码或固定电话，固定电话需要加区号，区号和号码中间不需要加连字符，例如057188992688。
areacode	10	否	区号，指定城市进行X号码的选号。如果当前号池中没有该城市的可用号码，或未指定此参数，将从当前号码池中随机分配一个其他城市的号码作为X号码。
callmode	1	否	呼叫模式 0_不需要录音 1_需要录音，默认全程录音
expiration	30	是	绑定关系的过期时间。必须晚于当前时间1分钟以上。
callnumberX	20	否	AXYB中的X号码，A号码拨打X号码时会转接到B号码，可通过接口bindupdate更新B号码。若指定X号码，则采用X号码进行绑定，否则由系统在号码池中随机选择一个匹配地区的可用号码
digest	32	是	消息签名，见“签名算法”

2.6.3 响应参数

以HTTP 响应码表示，见下表

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，请求携带的值原样返回
code	4	是	结果状态码描述，含义参考下表
message	100	是	结果状态码的描述
bindId	30	否	绑定关系ID，后续对绑定关系操作的唯一标识。状态码=200时有效
callnumberX	20	是	AXYB中的X号码。状态码=200时有效。

响应码	含义	建议
200	成功
503	服务暂停	稍后再试，或者联系运营提供商
401	验签失败	检查签名算法和签名密钥
403	企业不存在或状态异常	联系运营提供商
400	参数错误	参数不满足格式要求，或者参数值为空

响应体为json数据，如下：

{
    "result": "200",    //登录成功
    "deviceid": "470"   //登录成功的deviceid
    "username": "测试员"   //用户名称（昵称）
}

3 呼叫信息推送回调接口

3.1 推送呼叫信息

3.1.1 描述

条目	说明
功能	呼叫系统可以调用此接口向业务系统推送的呼叫信息。
请求方向	ZWAN服务器->应用系统
请求地址	POST 回调URL由应用系统提供

3.1.2 请求参数

参数名	最大长度	必填	含义说明
companyid	18	是	企业编号，保存在系统的唯一编号
callflowid	20	是	呼叫流水号，在同一企业必须保证不重复。建议在流水号中包含时间戳
bindId	30	是	绑定关系ID
status	3	呼叫结果: [100]开始呼叫; [200]外呼成功（用户已接听） [201]外呼成功（用户已挂机） [404]外呼失败（用户号码不正确或空号找不到用户） [486]外呼失败（用户主动拒绝或用户忙） [487]外呼失败（用户超时无应答） [489]未呼出（另外一方已经提前挂机） [500]外呼失败(内部线路故障) [600]外呼失败（原因：无可用网关线路或线路全忙，未呼出）
callingnumberA	30	上面状态对应的呼叫方
callednumberB	30	上面状态对应的被叫方
callingdisplaynumberA	30	A对外显示号码
calleddisplaynumberB	30	B对外的显示号码
starttime	30	呼叫开始时间
ringingtime	30	振铃开始时间
answertime	30	被叫应答开始时间
endtime	30	呼叫结束时间
duration	10	通话时长，单位: s，结束时间减去应答开始时间
recordurl	255	录音文件下载路径
digest	32	是	消息签名，见“签名算法”

2.1.3 响应参数

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，请求携带的值原样返回
code	4	是	结果状态码描述，含义参考下表
message	100	是	结果状态码的描述

以HTTP 响应码表示，见下表

响应码	含义	建议
200	成功
503	服务暂停	稍后再试，或者联系运营提供商
401	验签失败	检查签名算法和签名密钥
403	企业不存在或状态异常	联系运营提供商
400	参数错误	参数不满足格式要求，或者参数值为空

4 黑白名单管理接口

4.1 系统黑名单管理

4.1.1 描述

条目	说明
功能	呼叫系统可以调用此接口向业务系统推送的呼叫信息。
请求方向	ZWAN服务器->应用系统
请求地址	POST 回调URL由应用系统提供

4.1.2 请求参数

参数名	最大长度	必填	含义说明
参数名	最大长度	必填	含义说明
--------	-----	------	------
callflowid	30	是	呼叫流水号，确保不重复。建议在流水号中包含时间戳
loginname	20	是	PAAS系统管理员登录账户
loginpass	20	是	PAAS系统管理员登录密码[MD5一次避免明文传输]
blacknumber	30	黑名单号码
blacklistdescription	300	是	黑名单号码资源描述
digest	32	是	消息签名，见“签名算法”

4.1.3 响应参数

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，请求携带的值原样返回
code	4	是	结果状态码描述，含义参考下表
message	100	是	结果状态码的描述

以HTTP 响应码表示，见下表

响应码	含义	建议
200	成功
503	服务暂停	稍后再试，或者联系运营提供商
401	验签失败	检查签名算法和签名密钥
403	企业不存在或状态异常	联系运营提供商
400	参数错误	参数不满足格式要求，或者参数值为空

5 管理功能接口

5.1 系统号码资源上传

5.1.1 描述

采用该接口向系统批量上传号码资源，系统自动去重。

条目	说明
功能	应用系统可以通过此服务上传X号码资源列表
请求方向	应用系统->ZWAN服务器
请求地址	POST http://ip:port/zwgw/uploadcallingnumber

5.13.2 请求参数

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，确保不重复。建议在流水号中包含时间戳
loginname	20	是	PAAS系统管理员登录账户
loginpass	20	是	PAAS系统管理员登录密码[MD5一次避免明文传输]
description	300	是	号码资源描述
companyid	18	否	企业编号，保存在系统的唯一编号，不传指定企业，则号码资源存储至系统资源池，指定企业，则号码资源只分配给该企业
numberlimit	4	否	该批次导入的主叫号码是否限制单位时间（小时）使用次数【0表示或不传表示不限制次数】，整数表示限制的使用次数
digest	32	是	消息签名，见“数字签名算法”
file	2M	是	file类型，号码列表文件，号码格式为plain_text文本格式，每个号码一行，每行包含 "号码+地区码"信息采用竖线分割，地区码可为空

5.13.3 响应参数

以HTTP 响应码表示，见下表

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，请求携带的值原样返回
code	4	是	结果状态码描述，含义参考下表
message	100	是	结果状态码的描述

以HTTP 响应码表示，见下表

响应码	含义	建议
200	成功
503	服务暂停	稍后再试，或者联系运营提供商
401	验签失败	检查签名算法和签名密钥
403	企业不存在或状态异常	联系运营提供商
400	参数错误	参数不满足格式要求，或者参数值为空

响应体为json数据，如下：

{
    "code": 200,
    "result": "accepted"
}

5.1 批量删除系统号码资源

5.13.1 描述

采用该接口向系统批量删除号码资源。

条目	说明
功能	应用系统可以通过此服务删除X号码资源
请求方向	应用系统->ZWAN服务器
请求地址	POST http://ip:port/zwgw/removecallingnumber

5.13.2 请求参数

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，确保不重复。建议在流水号中包含时间戳
loginname	20	是	PAAS系统管理员登录账户
loginpass	20	是	PAAS系统管理员登录密码[MD5一次避免明文传输]
companyid	18	否	企业编号，保存在系统的唯一编号，不传企业id，则删除系统资源池，指定企业，则删除指定企业的号码资源
digest	32	是	消息签名，见“数字签名算法”
file	2M	是	file类型，号码列表文件，号码格式为plain_text文本格式，每个号码一行，每行包含 "号码+地区码"信息采用竖线分割，地区码可为空

5.13.3 响应参数

以HTTP 响应码表示，见下表

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，请求携带的值原样返回
code	4	是	结果状态码描述，含义参考下表
message	100	是	结果状态码的描述

以HTTP 响应码表示，见下表

响应码	含义	建议
200	成功
503	服务暂停	稍后再试，或者联系运营提供商
401	验签失败	检查签名算法和签名密钥
403	企业不存在或状态异常	联系运营提供商
400	参数错误	参数不满足格式要求，或者参数值为空

响应体为json数据，如下：

{
    "code": 200,
    "result": "accepted"
}

5.2 账号管理

5.2.1 创建企业账号

5.2.1.1 描述

条目	说明
功能	应用系统可以通过此服务创建企业账号
请求方向	应用系统->ZWAN服务器
请求地址	POST http://ip:port/zwgw/createcompany

5.2.1.2 请求参数

参数名	最大长度	必填	含义说明
loginname	20	是	PAAS系统管理员登录账户
loginpass	20	是	PAAS系统管理员登录密码[MD5一次避免明文传输]
name	20	是	企业名称
contact	20	否	联系人
phoneno	20	否	联系电话
email	20	否	联系Email

5.2.1.3 响应参数

以HTTP 响应码表示，见下表

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，请求携带的值原样返回
code	4	是	结果状态码描述，含义参考下表
message	100	是	结果状态码的描述
companyid	30	是	企业账号ID
password	50	是	企业秘钥，用于其它接口的digest生成

以HTTP 响应码表示，见下表

响应码	含义	建议
200	成功
503	服务暂停	稍后再试，或者联系运营提供商
401	验签失败	检查签名算法和签名密钥
403	企业不存在或状态异常	联系运营提供商
400	参数错误	参数不满足格式要求，或者参数值为空

响应体为json数据，如下：

    {
        "result": "success",    //或者为fail，表示发生错误
        "companyid":"169",     
        "password":"SvmIWCmDVvMKjffAiTJvjKCJMlcILJeH"   //企业秘钥，用于其它接口的digest生成
    }

5.2.2 删除企业账号

5.2.2.1 描述

条目	说明
功能	应用系统可以通过此服务删除企业
请求方向	应用系统->ZWAN服务器
请求地址	POST http://ip:port/zwgw/deletecompany

5.2.2.2 请求参数

参数名	最大长度	必填	含义说明
loginname	20	是	PAAS系统管理员登录账户
loginpass	20	是	PAAS系统管理员登录密码[MD5一次避免明文传输]
companyid	18	是	企业编号，保存在系统的唯一编号

5.2.2.3 响应参数

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，请求携带的值原样返回
code	4	是	结果状态码描述，含义参考下表
message	100	是	结果状态码的描述

以HTTP 响应码表示，见下表

响应码	含义	建议
200	成功
503	服务暂停	稍后再试，或者联系运营提供商
401	验签失败	检查签名算法和签名密钥
403	企业不存在或状态异常	联系运营提供商
400	参数错误	参数不满足格式要求，或者参数值为空

响应体为json数据，如下：

    {
        "result": "success"    //或者为fail，表示发生错误
    }

5.2.3 查询企业账号信息

5.2.3.1 描述

条目	说明
功能	应用系统可以通过此服务删除企业
请求方向	应用系统->ZWAN服务器
请求地址	POST http://ip:port/zwgw/querycompany

5.2.3.2 请求参数

参数名	最大长度	必填	含义说明
loginname	20	是	PAAS系统管理员登录账户
loginpass	20	是	PAAS系统管理员登录密码[MD5一次避免明文传输]
companyid	18	是	企业编号，保存在系统的唯一编号

5.2.3.3 响应参数

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，请求携带的值原样返回
code	4	是	结果状态码描述，含义参考下表
message	100	是	结果状态码的描述
name	20	是	企业名称
contact	20	否	联系人
phoneno	20	否	联系电话
email	20	否	联系Email
password	50	是	企业秘钥，用于其它接口的digest生成

以HTTP 响应码表示，见下表

响应码	含义	建议
200	成功
503	服务暂停	稍后再试，或者联系运营提供商
401	验签失败	检查签名算法和签名密钥
403	企业不存在或状态异常	联系运营提供商
400	参数错误	参数不满足格式要求，或者参数值为空

响应体为json数据，如下：

    {
        "result": "success",    //或者为fail，表示发生错误
        "company":{
            "name":"企业名称",
            "contact":"联系人",
            "phoneno":"联系电话",
            "email":"联系Email",
            "companyid": "101",
            "password":  "123456"
        }
    }

5.3 SIP分机设备管理

5.3.1 创建SIP设备及根据Mac地址查询登录账户

5.3.1.1 描述

条目	说明
功能	应用系统可以通过此服务自行创建SIP设备及调用此接口通过设备MAC地址（设备号）获得sip账户
请求方向	应用系统->ZWAN服务器
请求地址	POST http://ip:port/zwgw/createdevice

5.3.1.2 请求参数

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号
companyid	18	是	企业编号，保存在系统的唯一编号
deviceid	20	是	设备ID，应用系统自行生成唯一的设备ID，例如手机号码或MAC地址
digest	32	是	消息签名，见“数字签名算法”

5.3.1.3 响应参数

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，请求携带的值原样返回
code	4	是	结果状态码描述，含义参考下表
message	100	是	结果状态码的描述
devicenumber	30	是	SIP账号
password	30	是	SIP随机密码

以HTTP 响应码表示，见下表

响应码	含义	建议
200	成功
503	服务暂停	稍后再试，或者联系运营提供商
401	验签失败	检查签名算法和签名密钥
403	企业不存在或状态异常	联系运营提供商
400	参数错误	参数不满足格式要求，或者参数值为空

响应体为json数据，如下：

    {  
      "zwannumber": "1146009",
      "password": "123456"
    }

5.3.2 删除SIP设备及账户

5.3.2.1 描述

条目	说明
功能	应用系统可以通过此服务删除SIP设备及账户
请求方向	应用系统->ZWAN服务器
请求地址	POST http://ip:port/zwgw/removedevice

5.3.2.2 请求参数

参数名	最大长度	必填	含义说明
companyid	18	是	企业编号，保存在系统的唯一编号
deviceid	20	是	设备ID，企业应用系统自行生成唯一的设备ID
digest	32	是	消息签名，见“数字签名算法”

5.3.2.3 响应参数

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，请求携带的值原样返回
code	4	是	结果状态码描述，含义参考下表
message	100	是	结果状态码的描述
devicenumber	30	是	SIP账号

以HTTP 响应码表示，见下表

响应码	含义	建议
200	成功
503	服务暂停	稍后再试，或者联系运营提供商
401	验签失败	检查签名算法和签名密钥
403	企业不存在或状态异常	联系运营提供商
400	参数错误	参数不满足格式要求，或者参数值为空

响应体为json数据，如下：

    {
        "result": "success",    //或者为其它错误原因password": "gnhebcif",
        "companyid": 101,
        "account": "1576023"
    }

5.3.3 查询设备状态

5.3.3.1 描述

条目	说明
功能	企业应用系统可以通过此服务获得设备在线闲忙状态
请求方向	应用系统->ZWAN服务器
请求地址	POST http://ip:port/zwgw/getagentstatus

5.3.3.2 请求参数

参数名	最大长度	必填	含义说明
companyid	18	是	企业编号，保存在系统的唯一编号
devicenumber	20	否	需要查询的设备的sip账号，如果不带该参数，则返回本企业所有设备的状态
status	1	否	号码状态条件
digest	32	是	消息签名，见“签名算法”

5.3.3.3 响应参数

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，请求携带的值原样返回
code	4	是	结果状态码描述，含义参考下表
message	100	是	结果状态码的描述
numberinfo	DTO	是	SIP账号信息

以HTTP 响应码表示，见下表

响应码	含义	建议
200	成功
503	服务暂停	稍后再试，或者联系运营提供商
401	验签失败	检查签名算法和签名密钥
403	企业不存在或状态异常	联系运营提供商
400	参数错误	参数不满足格式要求，或者参数值为空

响应体为json数据，如下：

    {
    "agentinfo": [
            {
              "devicenumber": "1146009",
              "status": "0",   //0是离线，1是在线，2是通话中
              "deviceid": 1111
            },
            {
              "devicenumber": "1146008",
              "status": "0",   
              "deviceid": 1112
            }
        ]
    }

5.3.4 修改SIP账户密码

5.3.4.1 描述

条目	说明
功能	应用系统可以使用该接口，设置一个sip账号的密码
请求方向	应用系统->ZWAN服务器
请求地址	POST http://ip:port/zwgw/changepwd

5.1.4.2 请求参数

参数名	最大长度	必填	含义说明
account	18	是	sip账号
oldpassword	30	原密码
password	8	是	新密码，密码不超过8位

5.1.4.3 响应参数、

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，请求携带的值原样返回
code	4	是	结果状态码描述，含义参考下表
message	100	是	结果状态码的描述

以HTTP 响应码表示，见下表

响应码	含义	建议
200	成功
503	服务暂停	稍后再试，或者联系运营提供商
401	验签失败	检查签名算法和签名密钥
403	企业不存在或状态异常	联系运营提供商
400	参数错误	参数不满足格式要求，或者参数值为空

响应体为json数据，如下：

    {
        "companyid": 101,
        "account":  "116001",   
        "password": "123456"          //新密码
    }

5.3.5 根据设备id查询登录账户

5.3.5.1 描述

条目	说明
功能	应用系统可以调用此接口通过设备地址（设备号）获得sip账户
请求方向	应用系统->ZWAN服务器
请求地址	POST http://ip:port/zwgw/getaccountfrommac

5.3.5.2 请求参数

参数名	最大长度	必填	含义说明
companyid	18	是	企业编号，保存在系统的唯一编号
deviceid	20	是	设备ID，应用系统自行生成唯一的设备ID，例如手机号码或MAC地址
digest	32	是	消息签名，见“签名算法”

5.3.5.3 响应参数

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，请求携带的值原样返回
code	4	是	结果状态码描述，含义参考下表
message	100	是	结果状态码的描述
numberinfo	DTO	是	SIP账号信息

以HTTP 响应码表示，见下表

响应码	含义	建议
200	成功
503	服务暂停	稍后再试，或者联系运营提供商
401	验签失败	检查签名算法和签名密钥
403	企业不存在或状态异常	联系运营提供商
400	参数错误	参数不满足格式要求，或者参数值为空

响应体为json数据，如下：

    {
        "password": "gnhebcif",
        "companyid": 101,
        "devicenumber": "1146009",
        "status": "0",   //0是离线，1是在线，2是通话中
        "deviceid": 1111
    }

5.4 坐席组管理

5.4.1 查询坐席组

5.4.1.1 描述

条目	说明
功能	企业应用系统可以通过此服务获得坐席组
请求方向	应用系统->ZWAN服务器
请求地址	POST http://ip:port/zwgw/getgroup

5.4.1.2 请求参数

参数名	最大长度	必填	含义说明
companyid	18	是	企业编号，保存在系统的唯一编号
groupid	20	否	组ID，不传时查询本企业所有组
digest	32	是	消息签名，见“签名算法”

5.4.1.3 响应参数

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，请求携带的值原样返回
code	4	是	结果状态码描述，含义参考下表
message	100	是	结果状态码的描述
groupname	20	是	企业名称
groupid	20	是	组ID

以HTTP 响应码表示，见下表

响应码	含义	建议
200	成功
503	服务暂停	稍后再试，或者联系运营提供商
401	验签失败	检查签名算法和签名密钥
403	企业不存在或状态异常	联系运营提供商
400	参数错误	参数不满足格式要求，或者参数值为空

响应体为json数据，如下：

    {
    "groupinfo": [
            {
                "groupname": "test",
                "groupid": "1"
            }
        ]
    }

5.4.2 增加坐席组

5.4.2.1 描述

条目	说明
功能	企业应用系统可以通过此服务创建坐席组
请求方向	应用系统->ZWAN服务器
请求地址	POST http://ip:port/zwgw/addgroup

5.4.2.2 请求参数

参数名	最大长度	必填	含义说明
companyid	18	是	企业编号，保存在系统的唯一编号
groupname	20	是	组名
digest	32	是	消息签名，见“签名算法”

5.4.2.3 响应参数

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，请求携带的值原样返回
code	4	是	结果状态码描述，含义参考下表
message	100	是	结果状态码的描述
groupid	20	是	组ID

以HTTP 响应码表示，见下表

响应码	含义	建议
200	成功
503	服务暂停	稍后再试，或者联系运营提供商
401	验签失败	检查签名算法和签名密钥
403	企业不存在或状态异常	联系运营提供商
400	参数错误	参数不满足格式要求，或者参数值为空

响应体为json数据，如下：

    {
    "groupinfo": [
            {
                "groupname": "test",
                "groupid": "1"
            }
        ]
    }

5.4.3 删除坐席组

5.4.3.1 描述

条目	说明
功能	企业应用系统可以通过此服务删除坐席组
请求方向	应用系统->ZWAN服务器
请求地址	POST http://ip:port/zwgw/delgroup

5.4.3.2 请求参数

参数名	最大长度	必填	含义说明
companyid	18	是	企业编号，保存在系统的唯一编号
groupid	20	是	要删除的组id
digest	32	是	消息签名，见“签名算法”

5.4.3.3 响应参数

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，请求携带的值原样返回
code	4	是	结果状态码描述，含义参考下表
message	100	是	结果状态码的描述

以HTTP 响应码表示，见下表

响应码	含义	建议
200	成功
503	服务暂停	稍后再试，或者联系运营提供商
401	验签失败	检查签名算法和签名密钥
403	企业不存在或状态异常	联系运营提供商
400	参数错误	参数不满足格式要求，或者参数值为空

响应体为json数据，如下：

    {
    "result":"succ"    //或者是"fail"
    }

5.5 坐席组坐席管理

5.5.1 坐席状态查询

5.5.1.1 描述

条目	说明
功能	企业应用系统可以通过此服务获得坐席组成员和在线忙闲状态
请求方向	应用系统->ZWAN服务器
请求地址	POST http://ip:port/zwgw/getgroupmember

5.5.1.2 请求参数

参数名	最大长度	必填	含义说明
companyid	18	是	企业编号，保存在系统的唯一编号
groupid	18	否	坐席组编号，企业内唯一编号,可以通过getgroup服务获得，同时查询多个坐席组可以用","分割，不传表示查询改企业所有坐席
digest	32	是	消息签名，见“签名算法”

5.5.1.3 响应参数

以HTTP 响应码表示，见下表

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，请求携带的值原样返回
code	4	是	结果状态码描述，含义参考下表
message	100	是	结果状态码的描述
groupinfo	DTO	是	坐席组成员信息，格式见示例

响应码	含义	建议
200	成功
503	服务暂停	稍后再试，或者联系运营提供商
401	验签失败	检查签名算法和签名密钥
403	企业不存在或状态异常	联系运营提供商
400	参数错误	参数不满足格式要求，或者参数值为空

响应体为json数据，如下：

    {
        "agentinfo": [
            {
              "zwannumber": "1146009",
              "groupid": "117",
              "status": "0"    //0是离线，1是在线，2是通话中， 3是免打扰
            },
            {
              "zwannumber": "1146008",
              "groupid": null,  //null表示没有在坐席组中
              "status": "0"
            }
        ]
    }

5.5.2 坐席入组

5.5.2.1 描述

条目	说明
功能	企业应用系统可以通过此服务将某一个坐席加入到坐席组中
请求方向	应用系统->ZWAN服务器
请求地址	POST http://ip:port/zwgw/addgroupmember

5.5.2.2 请求参数

参数名	最大长度	必填	含义说明
companyid	18	是	企业编号，保存在系统的唯一编号
groupid	18	是	坐席组编号
number	20	是	坐席的电话号码
digest	32	是	消息签名，见“签名算法”

5.5.2.3 响应参数

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，请求携带的值原样返回
code	4	是	结果状态码描述，含义参考下表
message	100	是	结果状态码的描述

以HTTP 响应码表示，见下表

响应码	含义	建议
200	成功
503	服务暂停	稍后再试，或者联系运营提供商
401	验签失败	检查签名算法和签名密钥
403	企业不存在或状态异常	联系运营提供商
400	参数错误	参数不满足格式要求，或者参数值为空

响应体为json数据，如下：

    {
        "result": "succ"   //失败是"fail"
    }

5.5.3 坐席出组

5.5.3.1 描述

条目	说明
功能	企业应用系统可以通过此服务将某一个坐席从坐席组中删除
请求方向	应用系统->ZWAN服务器
请求地址	POST http://ip:port/zwgw/delgroupmember

5.5.3.2 请求参数

参数名	最大长度	必填	含义说明
companyid	18	是	企业编号，保存在系统的唯一编号
groupid	18	是	坐席组编号
number	20	是	坐席的电话
digest	32	是	消息签名，见“签名算法”

5.5.3.3 响应参数

以HTTP 响应码表示，见下表

参数名	最大长度	必填	含义说明
callflowid	30	是	呼叫流水号，请求携带的值原样返回
code	4	是	结果状态码描述，含义参考下表
message	100	是	结果状态码的描述

响应码	含义	建议
200	成功
503	服务暂停	稍后再试，或者联系运营提供商
401	验签失败	检查签名算法和签名密钥
403	企业不存在或状态异常	联系运营提供商
400	参数错误	参数不满足格式要求，或者参数值为空

响应体为json数据，如下：

    {
        "result": "succ"   //失败是"fail"
    }