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

中国联通公司企业标准QB/CUXXX—2016中国联通A-PaaS能力开放平台API规范积分商城分册2017-2发布2017-2实施1概述1.1背景随着行业和公司发展，IT和各业务领域更深度融合，IT已不仅是信息化部门的专有任务，越来越多业务单元需要直接参与到IT建设中。传统IT模式正在转变，“平台+应用”新格局快速形成，IT部门将逐步更加聚焦于IT整体规划、共享能力提供、数据聚合、基础设施和服务提供等领域。为构建平台和应用间桥梁，A-PaaS能力体系应运而生，在2015年IT整体规划中，参照IT三层架构总体规划，进一步将各类公共业务能力进行沉淀，形成应用能力层（Ａ-PaaS），通过A-PaaS实现IT、数据、运营、应用能力的复用和整合，促进集中统一运营红利释放。各类业务单元（BU）作为A-PaaS能力使用方，获得更加透明、标准化的平台能力支撑，通过平台+业务应用新的IT模式，最大程度发挥自身运营灵活性，并也可实现自身能力复用、沉淀。各类能力单元（AU）做为A-PaaS能力提供方，视角也在逐步发生变化，由系统建设组织者逐步变为公共能力的生产者或运营者，可以专注能力潜力挖掘，打造更有价值的能力。1.2范围此文档是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缩略语英文缩写英文全称中文解释A-PaaSAbility-PlatformasaService业务能力层I-PaaSIntegrationPlatformasaService技术组件层AUAbilityUnit能力单元BUBusinessUnit业务单元APP-KEYAPP-KEY应用IDAPP_SECRETAPP_SECRET应用密钥1.5.2术语本文档所涉及的术语定义请参见下表。名词解释能力用于支撑各类业务活动的公共要素或环节，各类业务应用的“公约数”、承载一定业务功能，可复用，相对稳定。一个能力可以包括多个服务服务服务是指提供某项业务功能的具体API接口应用接入业务单元使用能力开放平台的能力，完成业务应用建设的过程业务经理业务应用的建设与维护人员，能力经理能力的建设和运营人员，AU的能力提供方平台运营方A-PaaS整体运营基本责任单元，负责A-PaaS体系的运营API调用方式通过接口地址调用服务的技术实现方式SDK调用方式通过SDK方式调用服务的技术实现方式2接入技术2.1传输协议采用HTTP传输协议，并采用RESTFUL风格的服务访问方式。POST把提交的数据则放置在HTTP包的包体中。所有参数值需要转换为UTF-8编码。支持POST请求方式的API接口，所需要拼接的URL格式示例如下：(服务名称)/xx(版本号)?2.2API调用方式本章节主要介绍通过接口地址调用服务的技术实现方式，简称API调用方式；2.2.1传输协议采用HTTP传输协议，并采用RESTFUL风格的服务访问方式。POST把提交的数据则放置在HTTP包的包体中。所有参数值需要转换为UTF-8编码。支持POST请求方式的API接口，所需要拼接的URL格式示例如下：(服务名称)/xx(版本号)?2.2.2调用方式通过HTTPPOST请求方式进行API调用，并根据API规范拼接正确的URL，就能够办理相应业务或取得相应数据。2.2.3调用参数发起API调用的请求有二类参数：系统参数、应用参数，系统参数与应用参数以POST的方式把提交的数据则放置在HTTP包的包体中传输；1)系统参数名称类型必填?说明备注app_keychar(30)Y接入标识码timestamptimestampY时间戳当前的系统时间戳，单位为毫秒，举例：2016-03-2512:12:12187serial_numberchar(23)Y序列号YYYYMMDDHHMMSS+毫秒(3)+6位随机数signvarchar(256)Y签名信息2）应用参数应参参数参照实时接口规范2.2.4签名方式调用api值需要进行签名sign值的校验，服务器也会对该请求参数进行验证是否合法的。签名值sign是将请求源串以及app_secret根据一定签名方法生成的签名值；方法如下：1.根据系统参数名称（除sign签名）将所有请求系统参数按照字母先后顺序排序:key+value....key+value例如：请求URL为：；将系统参数值app_key=abc,timestamp=2016-03-2512:12:12187,serial_number=912321eqwrwqq参数名和参数值链接后，得到拼装字符串：app_keyabcserial_number912321eqwrwqqtimestamp2016-03-2512:12:121872.拼接app_secretapp_secret为应用申请时分配的App密钥，不在URL中传递，双方配置在自己系统中，用于计算sign值，增强安全性。app_secret值拼接到上面的字串中后面，加入app_secret值为B2732427，最终得到：app_keyabcserial_number912321eqwrwqqtimestamp2016-03-2512:12:12187B27324273.系统支持MD5(64位)加密方式md5：将app_secret拼接到参数字符串尾后进行md5(64位)加密，格式是：md5(key1value1key2value2...app_secret)4.Sign计算：把上面得到的源串进行MD5计算，得到sign值为ewqewq123214tuiiwe392.3SDK调用方式A-PaaS能力开放平台SDK提供了调用接口（API）的请求封装、签名、返回解析、消息监听等功能，使用SDK可以轻松完成API的调用，API结果的获取，消息的实时监听。3实时接口3.1积分消费记录查询3.1.1应用场景用于查询客户的积分消费历史；3.1.2请求说明API名称cn.integralmall.corebasicquery.scoreexpendrecord外网调用入口内网调用入口请求方式HTTP-POST格式JSONAPI授权类型需要授权是否收费API否类型基础服务版本v13.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”:”value1”,”param2”:”value2”,......}+appSecrect加号不传参数列表参数以其参数名的字典序升序进行排序,按照上面顺序进行排序后MD5加密（UTF-8编码），接入渠道编码channelcode，密钥appSecrect由积分商城提供所传参数见下表加密解密方法：SignUtil2.zip测试时，系统参数里面加密使用的是申请应用的时候提供的appkey/appsecret；应用参数里面加密时使用的渠道编码为“AP+两位省份编码”，密钥为“RyiQwkaIB2AMvmpJk5RG1g==”biz_params入参名称类型必填?说明备注transidvarchar(50)Y发起方流水渠道编码+yyyymmddhh24miss+6位不重复序列reqservicecodevarchar(9)Y服务编码积分消费记录查询：11011002provincecodechar(3)Y省份编码citycodechar(3)Y地市编码nettypechar(2)Y网别012G023G994Gpaytypechar(2)Y付费类型1预付费2后付费usertypechar(1)Y用户类型0手机1宽带2固话3上网卡usernumbervarchar(30)Y服务号码telareacodevarchar(4)N区号固网必填begindatechar(8)Y开始时间YYYYMMDDenddatechar(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客户无积分respdescvarchar(500)N应答描述应答描述scoredetailinfoscoredetailinfo_entity[]N积分消费记录信息实体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)Y消费积分数chantypechar(1)Y积分消费渠道:0积分商城1网上营业厅2手机营业厅3短信营业厅4实体营业厅5自助终端机6微信厅7迷你厅8省分积分平台9合作伙伴积分平台expendlistexpendlist_entity[]N消费商品列表实体3.1.5.2消费商品列表实体3.1.5.2.1实体说明实体名称expendlist_entity[]实体描述3.1.5.2.2实体数据名称类型必填?说明备注giftkindcodevarchar(20)Y消费商品编码expensegoodvarchar(100)Y消费商品名称actioncoun