流量API接口文档说明

前言

本协议规定了企业用户接入流量平台的流程和规范。

第一章 架构说明

1.1 业务受理流程
1.2 请求和响应报文
本协议采用http进行交互，支持POST方式提交，提交参数采用UTF-8编码。
企业用户接入时需先在流量平台开户，分配api_key，并配置好状态报告接收地址。

第二章 单号码充流量接口

2.1 提交url地址
http://120.77.65.113/xxdataflow/charge
2.2 提交方式
协议：HTTP + POST + JSON
方向：企业用户 ---->流量平台
2.3 提交参数定义
以下参数类型都是字符串类型。
参数名称 参数说明 类型 必须项 备注
account 企业帐号登录名 String 是
mobile 冲流量的目标手机号码 String 是
package 流量套餐编号 String 是 单位：MB
sign 签名 String 是 sign = hex(md5(account + api_key)), api_key由流量平台提供， 对account和api_key连接的字符串进行md5, 得到16字节的二进制串，然后进行十六进制字符串化，得到32字节长度的字符串。
request_id 下游系统生成唯一性任务ID String 否 可以判断下游系统是否重复提交，最长64个字符。
注：标准JSON需要使用双引号， 不要使用单引号。
例子：JSON格式
{
    "account":  "abc123456", 
    "mobile":  "18900001111", 
    "package":  " 10", 
    "sign":   "10AB10AB10AB10AB10AB10AB10AB10AB"
}
              
{
    "account":  "abc123456", 
    "mobile":  "18900001111", 
    "package":  " 10", 
    "sign":  "10AB10AB10AB10AB10AB10AB10AB10AB",  
    "request_id":  "20151022162238797213"
}
2.4 应答参数说明
参数名称 参数说明 类型 必须项 备注
result_code 执行结果码 String 是 0--成功，其它失败
result_msg 执行结果描述 String 是 文本描述失败原因
msg_id 平台分配唯一ID String 是 与状态报告推送接口的msg_id对应
guid 平台分配GUID String 是 与状态报告推送接口的guid对应
request_id 下游系统生成唯一性任务ID String 是 1) 如果请求时, 没有提供request_id，则与低版本一样，我们没有任何处理。
2) 如果请求时，下游系统有提交这个ID，则应答时会提供；同时，系统会检查这个request_id是否已经存在，如果已经存在(客户以前提交过)，则系统认为客户在重复提交，不予处理并返回错误码：15，错误描述：request repeatedly。这样可以防止客户由于某种原因导致的重复提交，避免不必要的损失，所以建议客户使用这个功能。
注：msg_id和guid在单号码充流量接口里，都可以作为唯一性。区别在于，将来支持批量充流量接口，msg_id表示充流量任务的唯一性，guid表示任务里各个号码的唯一性。
例子：JSON格式
在接收到客户端发送的http请求后，返回处理结果格式为：
成功：
{
    "result_code":  "0", 
    "result_msg":  "OK", 
    "msg_id":  "20150101083010000001", 
    "guid":  "F9DC312E-9DCF-2880-123D-0F103D4794CB",
    "request_id":  "20151022162238797213"
}
              
{
    "result_code":  "0", 
    "result_msg":  "OK", 
    "msg_id":  "20150101083010000001", 
    "guid":  "F9DC312E-9DCF-2880-123D-0F103D4794CB"
}
失败：
{
    "result_code":  "1", 
    "result_msg":  "invalid account"
}
注：标准JSON需要使用双引号， 不要使用单引号。
2.5 错误码
result_code result_msg 备注
0 OK 成功
1 invalid account 帐户错误
2 invalid parameter 参数错误
2 invalid mobile 手机号码错误
3 invalid package 流量包错误
4 invalid sign 签名（sign）错误
5 Authorize Fail, no such user 无此帐号
5 Authorize Fail, no privilege to access API services 无api接入权限
5 Authorize Fail, no privilege to IP_access services ip地址无接入权限
5 Authorize Fail, your ip is not enrolled 客户IP未注册
6 Authorize Fail, invalid sign 签名（sign）非法
7 Authorize Fail, no money for charge 帐号无余额
7 Authorize Fail, proxy has no money for charge 上游代理商余额不足
8 Authorize Fail, unknown phone segment 非法手机号码，查无此号段
9 no such traffic package 流量包错误
10 corp fee charge fail 企业帐户扣费失败
10 proxy fee charge fail 上游代理商余额扣费失败
10 operator channel fee charge fail 通道余额扣费失败
11 task save fail 保存充流量任务失败
12 Authorize Fail, your parent has no privilege 父级代理商权限未开启流量业务
13 no top corp rebate (顶级)企业没有设置折扣
14 no found such traffic package 找不到可用流量包信息
15 request repeatedly 重复请求
16 do not welcome the user 黑名单用户

第三章 状态报告推送接口

3.1 提交url地址
http://xxx.xxx.xxx.xxx:xxxx/statusreport
企业用户提供的状态报告接收地址，具体自己定义。
3.2 提交方式
协议：HTTP + POST + JSON
方向：流量平台 ---->企业用户
3.3 提交参数定义
以下参数类型都是字符串类型。
参数名称 参数说明 类型 必须项 备注
msg_id 平台分配唯一ID String 是 与充流量接口返回的msg_id对应
result_code 受理结果代码(透传的状态报告值) String 是 根据不同的资源通道编号channel_no而具有不同的含义, 具体参见：《流量平台状态报告v1.0.0.docx》。
channel_no 资源通道编号 String 是 由于不同通道返回的状态报告值的定义都是不相同的，所以提供资源通道编号
exec_result 执行结果 String 是 执行结果：
0--成功(状态报告成功),
1--任务提交失败,
2--状态报告失败。
guid 平台分配GUID String 否 与充流量接口返回的guid对应
result_desc 受理结果详细描述 String 是 对受理结果进行文字描述, 因为很多上游资源方的受理结果代码太笼统，失败的具体原因都是以文本描述的。
request_id 下游系统生成唯一性任务ID String 是 下游系统充流量时提供的request_id, 如果没有提供，则为空。
sp_type 运营商类型 String 是 运营商类型：
0--中国移动，
1--中国联通，
2--中国电信
province_no 省份编号 String 是 省份编号: 3-4位, 00--全国(未知)
city_no 地市编号 String 是 6位, 000000--未知
例子：JSON格式
注：标准JSON需要使用双引号， 不要使用单引号。
成功（中国电信）：广州号码
{
    "msg_id":  "20150101083010000001", 
    "result_code":  "00000", 
    "channel_no":  "GDDX0001", 
    "exec_result":  "0", 
    "guid":  "F9DC312E-9DCF-2880-123D-0F103D4794CB",
    "result_desc":  "",
    "request_id":  "",
    "sp_type":  "2",
    "province_no":  "44",
    "city_no":  "440100"
}
注意：中国电信由于状态报告都有详细的错误码，它并不提供受理结果文字描述。

成功（中国联通）：广州号码
{
    "msg_id":  "20150101083010000002", 
    "result_code":  "1", 
    "channel_no":  "01000002", 
    "exec_result":  "0", 
    "guid":  "F9DC312E-9DCF-2880-123D-0F103D4794CC",
    "result_desc":  "成功",
    "request_id":  "",
    "sp_type":  "1",
    "province_no":  "44",
    "city_no":  "440100"
}

成功（中国移动）：广州号码
{
    "msg_id":  "20150101083010000003", 
    "result_code":  "1000", 
    "channel_no":  "00000003", 
    "exec_result":  "0", 
    "guid":  "F9DC312E-9DCF-2880-123D-0F103D4794DD",
    "result_desc":  "成功",
    "request_id":  "",
    "sp_type":  "0",
    "province_no":  "44",
    "city_no":  "440100"
}
3.4 应答参数说明
文本：OK

第四章 查询余额接口

4.1 提交url地址
http://120.77.65.113/xxdataflow/getBalance
4.2 提交方式
协议：HTTP + POST + JSON
方向：企业用户 ----> 流量平台
4.3 提交参数定义
以下参数类型都是字符串类型。
参数名称 参数说明 类型 必须项 备注
account 企业帐号登录名 String 是
sign 签名 String 是 sign = hex(md5(account + api_key)), api_key由流量平台提供， 对account和api_key连接的字符串进行md5, 得到16字节的二进制串，然后进行十六进制字符串化，得到32字节长度的字符串。
注：标准JSON需要使用双引号， 不要使用单引号。
例子：JSON格式
{
    "account":  "zktest", 
    "sign":  "c979578a80a399c79f2fabecd819d9f2"
}
4.4 应答参数说明
参数名称 参数说明 类型 必须项 备注
result_code 执行结果码 String 是 0--成功，其它失败
result_msg 执行结果描述 String 是 文本描述失败原因
balance 余额 float 是 当执行失败，没有这个字段； 当执行成功，才返回这个字段。
成功：
{
    "result_code":  "0", 
    "result_msg":  "OK", 
    "balance":  1000.55
}
失败：
{
    "result_code":  "2", 
    "result_msg":  " no found balance"
}

第五章 查询流量包定义接口

5.1 提交url地址
http://120.77.65.113/xxdataflow/getPackage
5.2 提交方式
协议：HTTP + POST + JSON
方向：企业用户 ----> 流量平台
5.3 提交参数定义
以下参数类型都是字符串类型。
参数名称 参数说明 类型 必须项 备注
account 企业帐号登录名 String 是
sign 签名 String 是 sign = hex(md5(account + api_key)), api_key由流量平台提供， 对account和api_key连接的字符串进行md5, 得到16字节的二进制串，然后进行十六进制字符串化，得到32字节长度的字符串。
type 运营商类型 String 是 运营商类型：0:移动, 1:联通, 2:电信
注：标准JSON需要使用双引号， 不要使用单引号。
例子：JSON格式
{
    "account":  "zktest", 
    "sign":  "c979578a80a399c79f2fabecd819d9f2",
    "type":  "0"
}
5.4 应答参数说明
参数名称 参数说明 类型 必须项 备注
result_code 执行结果码 String 是 0--成功，其它失败
result_msg 执行结果描述 String 是 文本描述失败原因
packages 流量包定义 JSON 是 当执行失败，没有这个字段； 当执行成功，才返回这个字段，是一个JSON数组。
流量包定义参数：
参数名称 参数说明 类型 必须项 备注
package_number 流量包 int 是 数字，如：10, 30, 50, 100, 500, 1024, 2048
price 价格 float 是 如：5.0， 10.5
rebate 折扣 float 是 如：0.98， 0.85
channel 通道名 String 是 如：cmcc XXTS
成功：
{
    "result_code":  "0", 
    "result_msg":  "OK", 
    "packages": [
        {
            "package_number": 50, "price": 6.0, "rebate": 0.91,"channel":"cmcc XXKJ-gdyd"
        },    
        {
            "package_number": 200, "price": 15.0, "rebate": 0.91,"channel":"cmcc XXKJ-gdyd"
        }
    ]
}
失败：
{
    "result_code":  "3", 
    "result_msg":  "no found any packages"
}

第六章 查询任务状态接口

6.1 提交url地址
http://120.77.65.113/xxdataflow/getTaskStatus
6.2 提交方式
协议：HTTP + POST + JSON
方向：企业用户 ----> 流量平台
6.3 提交参数定义
以下参数类型都是字符串类型。
参数名称 参数说明 类型 必须项 备注
account 企业帐号登录名 String 是
sign 签名 String 是 sign = hex(md5(account + api_key)), api_key由流量平台提供， 对account和api_key连接的字符串进行md5, 得到16字节的二进制串，然后进行十六进制字符串化，得到32字节长度的字符串。
task_no 任务编号 String 是 任务编号, 具体看类型
no_type 编号类型 String 是 编号类型：0--guid, 1--msg_id, 2--request_id
注：标准JSON需要使用双引号， 不要使用单引号。
例子：JSON格式
{
    "account":  "zktest", 
    "sign":  "c979578a80a399c79f2fabecd819d9f2",
    "task_no":  "74374532-470C-7D39-0F07-456168DE883E",
    "no_type":  "0"
}
6.4 应答参数说明
参数名称 参数说明 类型 必须项 备注
result_code 执行结果码 String 是 0--成功，其它失败
result_msg 执行结果描述 String 是 文本描述失败原因
guid 平台分配GUID String 是 与状态报告推送接口的guid对应。
msg_id 平台分配唯一ID String 是 与状态报告推送接口的msg_id对应。
channel_no 资源通道编号 String 是 由于不同通道返回的状态报告值的定义都是不相同的，所以提供资源通道编号。
sp_type 运营商类型 String 是 运营商类型：0--中国移动，1--中国联通，2--中国电信。
province_no 省份编号 String 是 省份编号: 3-4位, 00--全国(未知)。
city_no 地市编号 String 是 6位, 000000--未知。
exec_result 执行结果 int 是 执行结果：0--成功(状态报告成功), 1--提交失败, 2--待提交, 3--已提交(提交成功，未返回状态报告), 4--状态报告失败。
submit_code 提交结果代码 String 是 在向运营商系统提交时，返回的代码。
submit_desc 提交详细描述 String 是 提交结果的详细描述。
statusreport_code 状态报告代码 String 是 运营商系统回调给我系统的状态报告代码。
statusreport_desc 状态报告详细描述 String 是 状态报告详细描述
成功：
{
    "result_code":  "0",
    "result_msg":  "OK",
    "guid":  "74374532-470C-7D39-0F07-456168DE883E",
    "msg_id":  "20160624114552902107",
    "channel_no":  "044482",
    "sp_type":  "0", 
    "province_no":  "44",
    "city_no":  "440100",
    "exec_result":  1,
    "submit_code":  "8", 
    "submit_desc":  "系统繁忙，请稍候再试",
    "statusreport_code":  "",       
    "statusreport_desc":  ""
}
失败：
{
    "result_code":  "2", 
    "result_msg":     "invalid no_type: 5"
}