1、中国联通APaaS能力开放平台API规范积分商城分册v19QB/CU XXX 2016中国联通公司企业标准中国联通公司发布中国联通A-PaaS能力开放平台API规范积分商城分册2017-2实施2017-2发布1 概述1.1 背景随着行业和公司发展，IT和各业务领域更深度融合，IT已不仅是信息化部门的专有任务，越来越多业务单元需要直接参与到IT建设中。传统IT模式正在转变，“平台+应用”新格局快速形成，IT部门将逐步更加聚焦于IT整体规划、共享能力提供、数据聚合、基础设施和服务提供等领域。为构建平台和应用间桥梁，A-PaaS能力体系应运而生，在2015年IT整体规划中，参照IT三层架构总体规划，
2、进一步将各类公共业务能力进行沉淀，形成应用能力层（-PaaS），通过A-PaaS实现IT、数据、运营、应用能力的复用和整合，促进集中统一运营红利释放。各类业务单元（BU）作为A-PaaS能力使用方，获得更加透明、标准化的平台能力支撑，通过平台+业务应用新的IT模式，最大程度发挥自身运营灵活性，并也可实现自身能力复用、沉淀。 各类能力单元（AU）做为A-PaaS能力提供方，视角也在逐步发生变化，由系统建设组织者逐步变为公共能力的生产者或运营者，可以专注能力潜力挖掘，打造更有价值的能力。1.2 范围此文档是A-PaaS能力开放平台对外提供的服务接口规范，适用于所有通过API和SDK方式调用开放能力
3、的场景。所有业务应用需要按照此规范要求进行服务调用，并根据返回结果做适当的业务处理。1.3 平台介绍A-PaaS运营支撑平台是面向业务单元的一个能力视图，是具体的服务、管理、交易平台，包括能力商店、能力开放平台、应用部署环境管理。通过能力商店实现能力提供统一管理，所有开放能力均在能力商店上架，统一管理，统一订购；通过能力开放平台，实现能力开放，对第三方、子公司、省分BU、总部BU提供统一能力调用；通过应用部署环境管理，为创新应用提供自助式分布式部署环境。对于BU来说，A-PaaS运营支撑平台呈现业务标准化能力，屏蔽各能力提供平台差异化服务；另一方面对于内部各类AU提供规范服务接入，A-PaaS
4、运营支撑平台是公司平台化运营的基础业务能力体系。本规范主要是针对A-PaaS能力开放平台对外提供的服务接口规范；1.4 参考文献1.5 缩略语与术语1.5.1 缩略语英文缩写英文全称中文解释A-PaaSAbility-Platform as a Service业务能力层I-PaaSIntegration Platform as a Service技术组件层AUAbility Unit能力单元BUBusiness Unit业务单元APP-KEY APP-KEY应用IDAPP_SECRETAPP_SECRET应用密钥1.5.2 术语本文档所涉及的术语定义请参见下表。名词解释能力用于支撑各类业务活动
5、的公共要素或环节，各类业务应用的“公约数”、承载一定业务功能，可复用，相对稳定。一个能力可以包括多个服务服务服务是指提供某项业务功能的具体API接口应用接入业务单元使用能力开放平台的能力，完成业务应用建设的过程业务经理业务应用的建设与维护人员，能力经理能力的建设和运营人员，AU的能力提供方平台运营方A-PaaS整体运营基本责任单元，负责A-PaaS体系的运营API调用方式通过接口地址调用服务的技术实现方式SDK调用方式通过SDK方式调用服务的技术实现方式2 接入技术2.1 传输协议 采用HTTP传输协议，并采用RESTFUL风格的服务访问方式。 POST把提交的数据则放置在HTTP包的包体中。
6、 所有参数值需要转换为UTF-8编码。 支持POST请求方式的API接口，所需要拼接的URL格式示例如下：http:/10.124.8.43:8001/api/xxx(服务名称)/xx(版本号)?2.2 API调用方式 本章节主要介绍通过接口地址调用服务的技术实现方式，简称API调用方式；2.2.1 传输协议 采用HTTP传输协议，并采用RESTFUL风格的服务访问方式。 POST把提交的数据则放置在HTTP包的包体中。 所有参数值需要转换为UTF-8编码。 支持POST请求方式的API接口，所需要拼接的URL格式示例如下：http:/10.249.214.2:8001/api/xxx(服务名
7、称)/xx(版本号)?2.2.2 调用方式通过HTTP POST请求方式进行API调用，并根据API规范拼接正确的URL，就能够办理相应业务或取得相应数据。2.2.3 调用参数发起API调用的请求有二类参数：系统参数、应用参数，系统参数与应用参数以POST的方式把提交的数据则放置在HTTP包的包体中传输；1) 系统参数名称类型必填?说明备注app_keychar(30)Y接入标识码timestamptimestampY时间戳当前的系统时间戳，单位为毫秒，举例：2016-03-25 12:12:12 187serial_numberchar(23)Y序列号YYYYMMDDHHMMSS+毫秒(3)
8、 +6位随机数signvarchar(256)Y签名信息 2）应用参数 应参参数参照实时接口规范2.2.4 签名方式调用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 1
9、2: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_number912321eqwrwqqtimestamp20
10、16-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
11、 应用场景用于查询客户的积分消费历史；3.1.2 请求说明API名称cn.integralmall.corebasicquery.scoreexpendrecord外网调用入口http:/111.198.162.42:8001/api/integralmall/corebasicquery/scoreexpendrecord/v1内网调用入口http:/10.249.214.2:8001/api/integralmall/corebasicquery/scoreexpendrecord/v1HTTP请求方式HTTP-POST格式JSONAPI授权类型需要授权是否收费API否类型基础服务版本v1
12、3.1.3 输入参数3.1.3.1 应用级输入参数名称类型必填?说明备注reqtschar(14)Y请求发起时间戳yyyyMMddHHmmsschannelcodevarchar(50)Y发起方渠道编码bizparamsvarchar(65536)Yjson字符串“param1”:”value1”,”param2”:”value2”,.参数列表参数以其参数名的字典序升序进行排序，结果进行aes加密，并且转成base64字符串。加密所用key由积分商城提供（同appSecrect）所传参数见下表authsignvarchar(256)Y数字签名channelcode+reqts+“param1”
13、:”value1”,”param2”:”value2”,.+appSecrect加号不传参数列表参数以其参数名的字典序升序进行排序,按照上面顺序进行排序后MD5加密（UTF-8编码），接入渠道编码channelcode，密钥appSecrect由积分商城提供所传参数见下表加密解密方法： 测试时，系统参数里面加密使用的是申请应用的时候提供的appkey/appsecret；应用参数里面加密时使用的渠道编码为“AP+两位省份编码”，密钥为“RyiQwkaIB2AMvmpJk5RG1g=”biz_params入参名称类型必填?说明备注transidvarchar(50)Y发起方流水渠道编码+ yyy
14、ymmddhh24miss+6位不重复序列reqservicecodevarchar(9)Y服务编码积分消费记录查询：11011002provincecodechar(3)Y省份编码citycodechar(3)Y地市编码nettypechar(2)Y网别01 2G02 3G99 4Gpaytypechar(2)Y付费类型1 预付费2 后付费usertypechar(1)Y用户类型0 手机1宽带2固话3上网卡usernumbervarchar(30)Y服务号码telareacodevarchar(4)N区号固网必填begindatechar(8)Y开始时间YYYYMMDDenddatechar
15、(8)Y结束时间YYYYMMDD3.1.4 返回结果名称类型必填?说明备注respcodechar(4)Y应答编码应答编码0000 成功9999 系统异常respdescvarchar(500)N应答描述应答描述rsptschar(14)Y响应时间戳yyyyMMddHHmmssrspmsgvarchar(65536)Y业务应答（业务参数列表）消息应答参数为json格式，同请求参数一样，整体结果进行aes加密，并且转成base64字符串rspmsg内参数说明名称类型必填?说明备注respcodechar(4)Y应答编码应答编码0000 成功1203黑名单用户1204 号码不存在1420 客户无积
16、分respdescvarchar(500)N应答描述应答描述scoredetailinfoscoredetailinfo_entityN积分消费记录信息实体3.1.5 实体列表3.1.5.1 积分消费记录信息实体3.1.5.1.1 实体说明实体名称scoredetailinfo_entity实体描述3.1.5.1.2 实体数据名称类型必填?说明备注scoreexpenddatechar(14)Y积分消费时间YYYYMMDDHH24MISStradeidvarchar(30)Y业务流水payfeemodechar(1)Y支付方式0 积分支付1 积分+现金scorevaluevarchar(50)
17、Y消费积分数chantypechar(1)Y积分消费渠道:0积分商城1网上营业厅2手机营业厅3短信营业厅4 实体营业厅5 自助终端机6 微信厅7 迷你厅8 省分积分平台9 合作伙伴积分平台expendlistexpendlist_entityN消费商品列表实体3.1.5.2 消费商品列表实体3.1.5.2.1 实体说明实体名称expendlist_entity实体描述3.1.5.2.2 实体数据名称类型必填?说明备注giftkindcodevarchar(20)Y消费商品编码expensegoodvarchar(100)Y消费商品名称actioncountvarchar(4)Y消费商品数量ex
18、pensetypechar(1)Y积分用途:0合作方产品1一卡充2 1G流量半年包3网厅交费4积分活动5积分转赠6 积分销售7实体营业厅兑换3.1.6 API调用示例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
19、: 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.7 SDK调用示例3.1.7.1 请求示例3.1.7.2 返回示例3.1.8 错误码解释3.1.9 备注说明3.2 积分产生记录查询3.2.1
20、 应用场景查询用户的积分生成详细信息。3.2.2 请求说明API名称cn.integralmall.corebasicquery.scorerecord外网调用入口http:/111.198.162.42:8001/api/integralmall/corebasicquery/scorerecord/v1内网调用入口http:/10.249.214.2:8001/api/integralmall/corebasicquery/scorerecord/v1HTTP请求方式HTTP-POST格式JSONAPI授权类型需要授权是否收费API否类型基础服务版本v13.2.3 输入参数3.2.3.1
21、应用级输入参数名称类型必填?说明备注reqtschar(14)Y请求发起时间戳yyyyMMddHHmmsschannelcodevarchar(50)Y发起方渠道编码bizparamsvarchar(65536)Yjson字符串“param1”:”value1”,”param2”:”value2”,.参数列表参数以其参数名的字典序升序进行排序，结果进行aes加密，并且转成base64字符串。加密所用key由积分商城提供同appSecrect所传参数见下表authsignvarchar(256)Y数字签名channelcode+reqts+“param1”:”value1”,”param2”:”
22、value2”,.+appSecrect加号不传参数列表参数以其参数名的字典序升序进行排序,按照上面顺序进行排序后MD5加密（UTF-8编码），接入渠道编码channelcode，密钥appSecrect由积分商城提供所传参数见下表biz_params入参名称类型必填?说明备注transidvarchar(50)Y发起方流水渠道编码+ yyyymmddhh24miss+6位不重复序列reqservicecodevarchar(9)Y服务编码积分产生记录查询：11011003provincecodechar(3)Y省份编码citycodechar(3)Y地市编码nettypechar(2)Y网别
23、01 2G02 3G99 4Gpaytypechar(2)Y付费类型1 预付费2 后付费usertypechar(1)Y用户类型0 手机1宽带2固话3上网卡usernumbervarchar(30)Y服务号码telareacodevarchar(4)N区号固网必填begindatechar(8)Y开始时间YYYYMMDDenddatechar(8)Y结束时间YYYYMMDD3.2.4 返回结果名称类型必填?说明备注respcodechar(4)Y应答编码应答编码0000 成功9999 系统异常respdescvarchar(500)N应答描述应答描述rsptschar(14)Y响应时间戳yyy
24、yMMddHHmmssrspmsgvarchar(65536)Y业务应答（业务参数列表）消息应答参数为json格式，同请求参数一样，整体结果进行aes加密，并且转成base64字符串rspmsg内参数说明名称类型必填?说明备注respcodechar(4)Y应答编码应答编码0000 成功1203黑名单用户1204 号码不存在1420 客户无积分respdescvarchar(500)N应答描述应答描述returninforeturninfo_entityN积分产生记录信息实体3.2.5 实体列表3.2.5.1 积分产生记录信息实体3.2.5.1.1 实体说明实体名称returninfo_ent
25、ity实体描述3.2.5.1.2 实体数据名称类型必填?说明备注scorevarchar(50)N当前积分scoredetailinfoscoredetailinfo_entityY积分生成详细信息实体3.2.5.2 积分生成详细信息实体3.2.5.2.1 实体说明实体名称scoredetailinfo_entity实体描述3.2.5.2.2 实体数据名称类型必填?说明备注scorecreatdatechar(14)Y积分生成时间YYYYMMDDHH24MISSscoreinvaliddatechar(14)Y积分失效时间YYYYMMDDHH24MISSscoretypechar(2)Y积分类
26、型01：通信消费积分02：奖励积分03：营销积分04：维系积分05：转赠积分06：回退积分07:合作伙伴积分scorevaluevarchar(50)Y积分值fusionscorevarchar(50)N融合业务积分3.2.6 API调用示例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: a
