广东流量赠送 API参考文档.doc

浙江移动流量包赠送能力目 录目 录1 流量包赠送能力11.1 简介11.1.1 开放规范11.1.2 接口鉴权21.1.3 HTTP返回码31.2 流量包赠送能力41.2.1 流量包赠送 接口功能 请求方法 请求URI 请求消息 响应消息 返回码71.2.2 流量包赠送结果查询 接口功能 请求方法 请求URI 请求消息 响应消息 返回码10文档版本 01 (2015-09-21)i浙江移动流量包赠送能力1 流量包赠送能力1 流量包赠送能力1.1 简介1.2 流量包赠送能力1.1 简介1.1.1 开放规范能力接入模式基于业务流（例如发送短信消息）和管理流（例如认证鉴权）是否经过能力工具箱，能力工具箱支持下列三种接入模式：l 代理模式：业务流和管理流都经过能力工具箱；l 半代理模式：管理流经过能力工具箱，业务流不经过能力工具箱而是直接从App到Enabler；l 透明代理：业务流和管理流都不经过能力工具箱，能力产品仅仅是在能力工具箱的API Store展现而已，开发者能够在能力工具箱的API Store里了解该API并下载相应的文档或SDK。能力开放范围能力工具箱聚合并开放通信能力或者移动互联网的OTT能力。l 常见的通信能力包括短信、彩信、呼叫等；l OTT：默认采用REST、SOAP协议接入能力网元。接口协议能力工具箱与App之间的接口，协议为REST。1.1.2 接口鉴权AppKey鉴权策略能力工具箱提供的开放接口，采用AppKey鉴权策略。l 鉴权正确，HTTP返回状态码为 200 ok；l 鉴权不正确，HTTP返回状态码为 401 或 403。当App通过能力工具箱调用API时， 能力工具箱将对请求消息头中的AppKey和AppSecret进行认证。AppKey和App Secret由能力工具箱分配。l AppKey：应用标识，调用接口时用于鉴权。l AppSecret：应用私钥，调用接口时用于鉴权。AuthorizationAuthorization参数如表1-1所示。表1-1 Authorization参数Header nameParameter NameDescriptionAuthorization-认证鉴权方式。能力工具箱采用 WSSE UsernameToken，该参数固定为 “WSSE”。realm认证鉴权方，能力工具箱中默认为“SDP”。profile能力工具箱采用WSSE 的UsernameToken，该参数应该填为 “UsernameToken”。type认证类型，固定为”Appkey”。X-WSSEX-WSSE参数如表1-2所示。表1-2 X-WSSE参数Header nameParameter NameDescriptionX-WSSE-标识WSSE的认证类型： 能力工具箱使用WSSE的 UsernameToken进行认证，本参数填写“UsernameToken”。Username用户安全子系统标识，即能力工具箱分配的Appkey。PasswordDigest密码摘要。摘要算法如下：PasswordDigest = Base64 (SHA256 (nonce + created + App Secret)。Nonce随机数。参见OASIS WS-Security standard。Created创建时间（UTC 时间）。格式 yyyy-MM-ddTHH:mm:ssZ示例码流Authorization: WSSE realm=SDP, profile=UsernameToken, type=AppKey X-WSSE: UsernameToken Username=XXXX, PasswordDigest= weYI3nXd8LjMNVksCKFV8t3rgHh3Rw=, Nonce=WScqanjCEAC4mQoBE07sAQ=, Created=2009-03-24T12:30:04Z1.1.3 HTTP返回码GET方法200 OK：获取资源成功。302 FOUND：重定向响应。可以直接通过GET方法获取定位响应消息头中URI对应的资源。500 Internal Server Error：内部服务器错误。POST方法200 OK：更新资源成功。201 CREATED：创建资源成功。400 BAD REQUEST：参数错误，或参数格式错误。通用状态码401 UNAUTHORIZED：鉴权失败。403 Forbidden：鉴权正确，但是没有权限访问该资源，服务器收到请求但拒绝提供服务。404 NOT FOUND：资源找不到。405 METHOD NOT ALLOWED：资源对应该方法不支持。415 UNSUPPORTED MEDIA TYPE：请求中的Content_type不支持。429 TOO MANY REQUESTS：同一时间请求数过多。500 Internal Server Error：内部服务器错误。503 SERVICE UNAVAIABLE：内部服务不可用。1.2 流量包赠送能力1.2.1 流量包赠送 接口功能API开发者调用该接口，给指定的浙江移动手机号赠送流量加油包。 请求方法请设置成“POST”。 请求URIhttp:/ServerRoot/mbb/presentDataTraffic/v1l ServerRoot能力工具箱对外开放REST服务的域名，请根据实际情况进行修改。 请求消息请求消息体中的参数如表1-3所示。表1-3 请求消息体中的参数说明参数名类型选取原则说明optCodeString(20)必选交易码。固定值 LLSLtradeSerialNoString(50)必选交易流水。格式 交易码+交易时间的年月日时分秒+外围渠道编号+8位序列号共28位。示例 LLSL20150408151147HY10000237tradeDateString(14)必选交易日期。格式 yyyyMMddhh24mmss示例 20140910153030bizCodeString(16)必选外围渠道，需要向移动申请。取值范围l 阿里：L1l 浙江研究院：H1billIdString(30)必选手机号码。示例ccountDateString(8)必选清算日期，交易时间的次一日。格式 yyyyMMdd示例 20140901offerIdString(12)必选流量包编号，由移动统一分配。示例 000001clientIpString(15)可选客户端IP。macAddressString(17)可选客户端Mac地址。请求消息如下所示：POST /mbb/presentDataTraffic/v1 HTTP/1.1 Host: ServerRoot Accept: application/json Content-Length: 50 Content-Type: application/json; charset=UTF-8 Authorization: WSSE realm=SDP, profile=UsernameToken, type=Appkey X-WSSE: UsernameToken Username=bob, PasswordDigest=weYI3nXd8LjMNVksCKFV8t3rgHh3Rw=, Nonce=WScqanjCEAC4mQoBE07sAQ=, Created=2009-03-24T12:30:04Z optCode:LLSL, tradeSerialNo:LLSL20150408151147HY10000237, tradeDate:20140910153030, bizCode:L1, billId accountDate:20140901, offerId:000001 响应消息响应消息体中的参数如表1-4所示。表1-4 响应消息体中的参数说明参数名类型选取原则说明codeString必选返回码。descriptionString必选返回码描述。resultResponse可选当存在返回结果时，该字段有值，区域信息。表1-5 Response参数说明参数名类型选取原则说明busiLogIdString必选业务操作流水号。示例 808977885685685busiSerialNoString可选业务流水号。示例 808977885685685osbSerialNoString必选Osb生成流水号。示例 808977885685685正常时响应消息示例如下：HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Connection: close Content-Length: 20 code: 000000, description: SUCCESS, result: busiLogId: 808977885685685, busiSerialNo: 808977885685685, osbSerialNo: 808977885685685 失败时响应消息示例如下：HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Connection: close Content-Length: 20 code: 010003, description: 请求处理超时 返回码表1-6 返回码结果码描述000000SUCCESS。010001业务参数校验错误。010002请求参数不合法。010003请求处理超时。010004构造响应消息失败。010005服务地址获取失败。1.2.2 流量包赠送结果查询 接口功能API开发者调用该接口，携带事务标识查询赠送结果。 请求方法请设置成“POST”。 请求URIhttp:/ServerRoot/mbb/queryPresentResult/v1l ServerRoot能力工具箱对外开放REST服务的域名，请根据实际情况进行修改。 请求消息请求消息体中的参数如表1-3所示。表1-7 请求消息体中的参数说明参数名类型选取原则说明optCodeString(20)必选LLQY。tradeSerialNoString(28)必选交易流水。格式 交易码+交易时间的年月日时分秒+外围渠道编号+8位序列号共28位。示例 LLSL20150408151147HY10000237bizCodeString(16)必选外围渠道。取值范围l 阿里：L1l 浙江研究院：H1billIdString(30)必选手机号码。示例rderOrgTradeNoString(50)必选原始交易流水，对应“流量包赠送”接口的请求消息参数tradeSerialNo。示例 808977885685685clientIpString(15)可选客户端IP。macAddressString(17)可选客户端Mac地址。请求消息如下所示：POST /mbb/queryPresentResult/v1 HTTP/1.1 Host: ServerRoot Accept: application/json Content-Length: 50 Content-Type: application/json; charset=UTF-8 Authorization: WSSE realm=SDP, profile=UsernameToken, type=Appkey X-WSSE: UsernameToken Username=bob, PasswordDigest=weYI3nXd8LjMNVksCKFV8t3rgHh3Rw=, Nonce=WScqanjCEAC4mQoBE07sAQ=, Created=2009-03-24T12:30:04Z optCode:LLQY, tradeSerialNo: LLSL20150408151147HY10000237, bizCode: L1, billId: orderOrgTradeNo: 808977885685685 响应消息响应消息体中的参数如表1-4所示。表1-8 响应消息体中的参数说明参数名类型选取原则说明codeString必选返回码。descriptionString必选返回码描述。resultResponse可选当存在返回结果时，该字段有值，区域信息。表1-9 Response参数说明参数名类型选取原则说明transactionResultString必选取值范围l 1：交易成功l 2：交易不存在l 3：交易失败l 4：查询失败l 5：交易中busiSerialNoString可选业务流水号。osbSerialNoString可选Osb生成流水号。正常时响应消息示例如下：HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Connection: close Content-Length: 20 code: 000000, description: SUCCESS, result: