中国联通A-PaaS能力开放平台API规范-积分商城分册v1.9

中国联通A-PaaS能力开放平台API规范积分商城分册2017-2发布2017-2实施中国联通公司发布1.1背景随着行业和公司发展，IT和各业务领域更深度融合，IT已不仅是信息化部门的专有任务，越来越多业务单元需要直接参与到IT建设中。

传统IT模式正在转变，“平台+应用”新格局快速形成，IT部门将逐步更加聚焦于IT整体规划、共享能力提供、数据聚合、基础设施和服务提供等领域。

为构建平台和应用间桥梁，A-PaaS能力体系应运而生，在2015年IT整体规划中，参照IT三层架构总体规划，进一步将各类公共业务能力进行沉淀，形成应用能力层（Ａ-PaaS），通过A-PaaS实现IT、数据、运营、应用能力的复用和整合，促进集中统一运营红利释放。

各类业务单元（BU）作为A-PaaS能力使用方，获得更加透明、标准化的平台能力支撑，通过平台+业务应用新的IT模式，最大程度发挥自身运营灵活性，并也可实现自身能力复用、沉淀。

各类能力单元（AU）做为A-PaaS能力提供方，视角也在逐步发生变化，由系统建设组织者逐步变为公共能力的生产者或运营者，可以专注能力潜力挖掘，打造更有价值的能力。

此文档是A-PaaS能力开放平台对外提供的服务接口规范，适用于所有通过API和SDK 方式调用开放能力的场景。

所有业务应用需要按照此规范要求进行服务调用，并根据返回结果做适当的业务处理。

1.3平台介绍A-PaaS运营支撑平台是面向业务单元的一个能力视图，是具体的服务、管理、交易平台，包括能力商店、能力开放平台、应用部署环境管理。

通过能力商店实现能力提供统一管理，所有开放能力均在能力商店上架，统一管理，统一订购；通过能力开放平台，实现能力开放，对第三方、子公司、省分BU、总部BU提供统一能力调用；通过应用部署环境管理，为创新应用提供自助式分布式部署环境。

对于BU来说，A-PaaS运营支撑平台呈现业务标准化能力，屏蔽各能力提供平台差异化服务；另一方面对于内部各类AU提供规范服务接入，A-PaaS运营支撑平台是公司平台化运营的基础业务能力体系。

本规范主要是针对A-PaaS能力开放平台对外提供的服务接口规范；1.4参考文献1.5缩略语与术语1.5.1缩略语1.5.2术语本文档所涉及的术语定义请参见下表。

2接入技术2.1传输协议采用HTTP传输协议，并采用RESTFUL风格的服务访问方式。

POST把提交的数据则放置在HTTP包的包体中。

所有参数值需要转换为UTF-8编码。

支持POST请求方式的API接口，所需要拼接的URL格式示例如下：http://10.124.8.43:8001/api/xxx(服务名称)/xx(版本号)?本章节主要介绍通过接口地址调用服务的技术实现方式，简称API调用方式；2.2.1传输协议采用HTTP传输协议，并采用RESTFUL风格的服务访问方式。

POST把提交的数据则放置在HTTP包的包体中。

所有参数值需要转换为UTF-8编码。

支持POST请求方式的API接口，所需要拼接的URL格式示例如下：http://10.249.214.2:8001/api/xxx(服务名称)/xx(版本号)?2.2.2调用方式通过HTTP POST请求方式进行API调用，并根据API规范拼接正确的URL，就能够办理相应业务或取得相应数据。

2.2.3调用参数发起API调用的请求有二类参数：系统参数、应用参数，系统参数与应用参数以POST的方式把提交的数据则放置在HTTP包的包体中传输；1)系统参数应参参数参照实时接口规范调用api值需要进行签名sign值的校验，服务器也会对该请求参数进行验证是否合法的。

签名值sign是将请求源串以及app_secret根据一定签名方法生成的签名值；方法如下：1.根据系统参数名称（除sign签名）将所有请求系统参数按照字母先后顺序排序:key + value .... key + value例如：请求URL为：http://10.249.214.2:8001/api/cuseser/v1；将系统参数值app_key=abc,timestamp=2016-03-25 12:12:12 187,serial_number=912321eqwrwqq参数名和参数值链接后，得到拼装字符串：app_keyabcserial_number912321eqwrwqqtimestamp2016-03-25 12:12:12 1872.拼接app_secretapp_secret为应用申请时分配的App密钥，不在URL中传递，双方配置在自己系统中，用于计算sign值，增强安全性。

app_secret值拼接到上面的字串中后面，加入app_secret值为B2732427，最终得到：app_keyabcserial_number912321eqwrwqqtimestamp2016-03-25 12:12:12 187B27324273.系统支持MD5(64位)加密方式md5：将app_secret拼接到参数字符串尾后进行md5(64位)加密，格式是：md5(key1value1key2value2... app_secret)4.Sign计算：把上面得到的源串进行MD5计算，得到sign值为ewqewq123214tuiiwe392.3 SDK调用方式A-PaaS能力开放平台SDK提供了调用接口（API）的请求封装、签名、返回解析、消息监听等功能，使用SDK可以轻松完成API的调用，API结果的获取，消息的实时监听。

3实时接口3.1积分消费记录查询3.1.1应用场景用于查询客户的积分消费历史；3.1.2请求说明3.1.3输入参数3.1.3.1应用级输入参数SignUtil2.zip加密解密方法：测试时，系统参数里面加密使用的是申请应用的时候提供的appkey/appsecret；应用参数里面加密时使用的渠道编码为“AP+两位省份编码”，密钥为“RyiQwkaIB2AMvmpJk5RG1g==”3.1.4返回结果3.1.5实体列表3.1.5.1积分消费记录信息实体3.1.5.1.1实体说明3.1.5.2消费商品列表实体3.1.5.2.1实体说明3.1.5.2.2实体数据3.1.6API调用示例3.1.6.1请求示例{"app_key":"x9lelkX","timestamp": "2014-01-01 10:19:37 212","serial_number":"cOKD31n20140101101937816x93z92", "sign":"cOKD31SLKJKLSDAKDJASLDAKJDJKAS", "data": {"reqts":"201702141010", "channelcode":"123456", "bizparams":"xxxxxxxxxx","authsign": "xxxxxxxxxxxxxxxxx"}}3.1.6.2返回示例正确返回{"data":{"respcode": "0000","respdesc": "成功","rspts": "201702141010","rspmsg": "业务应答消息aes加密base64编码"}}异常返回（积分商城返回异常）：{"data":{"rspcode":"9999","rspdesc":"系统异常"}}异常返回（开放平台自身异常）：{"data":{"status": "S-AF-001","message": "appkey校验失败"}}3.1.7SDK调用示例3.1.7.1请求示例3.1.7.2返回示例3.1.8错误码解释3.1.9备注说明3.2积分产生记录查询3.2.1应用场景查询用户的积分生成详细信息。

3.2.2请求说明3.2.3输入参数3.2.3.1应用级输入参数3.2.4返回结果3.2.5 实体列表3.2.5.1积分产生记录信息实体 3.2.5.1.1实体说明3.2.5.2积分生成详细信息实体3.2.5.2.1实体说明3.2.6API调用示例3.2.6.1请求示例{"app_key":"x9lelkX","timestamp": "2014-01-01 10:19:37 212","serial_number":"cOKD31n20140101101937816x93z92", "sign":"cOKD31SLKJKLSDAKDJASLDAKJDJKAS", "data": {"reqts":"201702141010", "channelcode":"123456","bizparams":"xxxxxxxxxx","authsign": "xxxxxxxxxxxxxxxxx"}}3.2.6.2返回示例正确返回{"data":{"respcode": "0000","respdesc": "成功""rspts": "201702141010","rspmsg": "业务应答消息aes加密base64编码"}}异常返回（积分商城返回异常）：{"data":{"rspcode":"9999","rspdesc":"系统异常"}}异常返回（开放平台自身异常）：{"data":{"status": "S-AF-001","message": "appkey校验失败"}}3.2.7SDK调用示例3.2.7.1请求示例3.2.7.2返回示例3.2.8错误码解释3.2.9备注说明3.1综合积分查询3.1.1应用场景用于查询当前可用积分、积分累计值、已兑换值、即将失效积分等信息。