[toc]

1 概述

1.1 API的封装

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

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

1.2 消息格式规定

1. WEB对外接口统一使用HTTP POST消息。回调接口一般使用HTTP POST。
2. 所有发向ZWAN服务器的消息均需要签名。
3. HTTP请求中的参数值需要进行URL转义（URLEncode）。
4. 参数名称严格区分大小写。

1.3 签名算法

消息签名算法如下：

1. 将HTTP请求参数按参数名以字典顺序排序；
2. 将请求参数名和参数值以=连接；
3. 将步骤2中得到的各字符串按步骤1规定的顺序连接，连接时使用&作为分隔；
4. 对步骤3得到的字符串求MD5散列值，并按16进制方式编码为字符串（如有字母则小写）；
5. 将步骤4得到的字符串与签名密钥连接，连接时不使用分隔符；
6. 对步骤5得到的字符串再求一次MD5散列值，并按16进制方式编码为字符串（如有字母则小写）；
7. 上述算法中得到的字符串，作为HTTP参数digest，一起发送给服务端。digest本身不参与签名算法。

1.4 消息签名密钥

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

2 号码绑定管理接口

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

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

2.1.1 描述

2.1.2 请求参数

2.1.3 响应参数

以HTTP 响应码表示，见下表

响应体为json数据，如下：

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

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

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

2.2.1 描述

2.2.2 请求参数

2.2.3 响应参数

以HTTP 响应码表示，见下表

响应体为json数据，如下：

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

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

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

2.3.1 描述

2.3.2 请求参数

2.3.3 响应参数

以HTTP 响应码表示，见下表

响应体为json数据，如下：

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

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

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

2.4.1 描述

2.4.2 请求参数

2.4.3 响应参数

以HTTP 响应码表示，见下表

响应体为json数据，如下：

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

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

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

2.5.1 描述

2.5.2 请求参数

2.5.3 响应参数

以HTTP 响应码表示，见下表

响应体为json数据，如下：

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

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

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

2.6.1 描述

2.6.2 请求参数

2.6.3 响应参数

以HTTP 响应码表示，见下表

响应体为json数据，如下：

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

3 呼叫信息推送回调接口

3.1 推送呼叫信息

3.1.1 描述

3.1.2 请求参数

2.1.3 响应参数

以HTTP 响应码表示，见下表

4 黑白名单管理接口

4.1 系统黑名单管理

4.1.1 描述

4.1.2 请求参数

4.1.3 响应参数

以HTTP 响应码表示，见下表

5 管理功能接口

5.1 系统号码资源上传

5.1.1 描述

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

5.13.2 请求参数

5.13.3 响应参数

以HTTP 响应码表示，见下表

以HTTP 响应码表示，见下表

响应体为json数据，如下：

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

5.1 批量删除系统号码资源

5.13.1 描述

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

5.13.2 请求参数

5.13.3 响应参数

以HTTP 响应码表示，见下表

以HTTP 响应码表示，见下表

响应体为json数据，如下：

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

5.2 账号管理

5.2.1 创建企业账号

5.2.1.1 描述

5.2.1.2 请求参数

5.2.1.3 响应参数

以HTTP 响应码表示，见下表

以HTTP 响应码表示，见下表

响应体为json数据，如下：

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

5.2.2 删除企业账号

5.2.2.1 描述

5.2.2.2 请求参数

5.2.2.3 响应参数

以HTTP 响应码表示，见下表

响应体为json数据，如下：

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

5.2.3 查询企业账号信息

5.2.3.1 描述

5.2.3.2 请求参数

5.2.3.3 响应参数

以HTTP 响应码表示，见下表

响应体为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 描述

5.3.1.2 请求参数

5.3.1.3 响应参数

以HTTP 响应码表示，见下表

响应体为json数据，如下：

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

5.3.2 删除SIP设备及账户

5.3.2.1 描述

5.3.2.2 请求参数

5.3.2.3 响应参数

以HTTP 响应码表示，见下表

响应体为json数据，如下：

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

5.3.3 查询设备状态

5.3.3.1 描述

5.3.3.2 请求参数

5.3.3.3 响应参数

以HTTP 响应码表示，见下表

响应体为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 描述

5.1.4.2 请求参数

5.1.4.3 响应参数、

以HTTP 响应码表示，见下表

响应体为json数据，如下：

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

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

5.3.5.1 描述

5.3.5.2 请求参数

5.3.5.3 响应参数

以HTTP 响应码表示，见下表

响应体为json数据，如下：

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

5.4 坐席组管理

5.4.1 查询坐席组

5.4.1.1 描述

5.4.1.2 请求参数

5.4.1.3 响应参数

以HTTP 响应码表示，见下表

响应体为json数据，如下：

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

5.4.2 增加坐席组

5.4.2.1 描述

5.4.2.2 请求参数

5.4.2.3 响应参数

以HTTP 响应码表示，见下表

响应体为json数据，如下：

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

5.4.3 删除坐席组

5.4.3.1 描述

5.4.3.2 请求参数

5.4.3.3 响应参数

以HTTP 响应码表示，见下表

响应体为json数据，如下：

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

5.5 坐席组坐席管理

5.5.1 坐席状态查询

5.5.1.1 描述

5.5.1.2 请求参数

5.5.1.3 响应参数

以HTTP 响应码表示，见下表

响应体为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 描述

5.5.2.2 请求参数

5.5.2.3 响应参数

以HTTP 响应码表示，见下表

响应体为json数据，如下：

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

5.5.3 坐席出组

5.5.3.1 描述

5.5.3.2 请求参数

5.5.3.3 响应参数

以HTTP 响应码表示，见下表

响应体为json数据，如下：

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