中国联通APaaS能力开放平台API规范积分商城分册v19.docx

中国联通APaaS能力开放平台API规范积分商城分册v19.docx

《中国联通APaaS能力开放平台API规范积分商城分册v19.docx》由会员分享，可在线阅读，更多相关《中国联通APaaS能力开放平台API规范积分商城分册v19.docx（64页珍藏版）》请在冰点文库上搜索。

中国联通APaaS能力开放平台API规范积分商城分册v19

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-PaaS

Ability-PlatformasaService

业务能力层

I-PaaS

IntegrationPlatformasaService

技术组件层

AU

AbilityUnit

能力单元

BU

BusinessUnit

业务单元

APP-KEY

APP-KEY

应用ID

APP_SECRET

APP_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格式示例如下：

http:

//10.124.8.43:

8001/api/xxx（服务名称）/xx（版本号）?

2.2API调用方式

本章节主要介绍通过接口地址调用服务的技术实现方式，简称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调用方式

通过HTTPPOST请求方式进行API调用，并根据API规范拼接正确的URL，就能够办理相应业务或取得相应数据。

2.2.3调用参数

发起API调用的请求有二类参数：

系统参数、应用参数，系统参数与应用参数以POST的方式把提交的数据则放置在HTTP包的包体中传输；

1）系统参数

名称

类型

必填?

说明

备注

app_key

char（30）

Y

接入标识码

timestamp

timestamp

Y

时间戳

当前的系统时间戳，单位为毫秒，举例：

2016-03-2512:

12:

12187

serial_number

char（23）

Y

序列号

YYYYMMDDHHMMSS+毫秒（3）+6位随机数

sign

varchar（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-2512:

12:

12187,serial_number=912321eqwrwqq

参数名和参数值链接后，得到拼装字符串：

app_keyabcserial_number912321eqwrwqqtimestamp2016-03-2512:

12:

12187

2.拼接app_secret

app_secret为应用申请时分配的App密钥，不在URL中传递，双方配置在自己系统中，用于计算sign值，增强安全性。

app_secret值拼接到上面的字串中后面，加入app_secret值为B2732427，最终得到：

app_keyabcserial_number912321eqwrwqqtimestamp2016-03-2512:

12:

12187B2732427

3.系统支持MD5（64位）加密方式

md5：

将app_secret拼接到参数字符串尾后进行md5（64位）加密，格式是：

md5（key1value1key2value2...app_secret）

4.Sign计算：

把上面得到的源串进行MD5计算，得到sign值为ewqewq123214tuiiwe39

2.3SDK调用方式

A-PaaS能力开放平台SDK提供了调用接口（API）的请求封装、签名、返回解析、消息监听等功能，使用SDK可以轻松完成API的调用，API结果的获取，消息的实时监听。

3实时接口

3.1积分消费记录查询

3.1.1应用场景

用于查询客户的积分消费历史；

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/v1

HTTP请求方式

HTTP-POST

格式

JSON

API授权类型

需要授权

是否收费API

否

类型

基础服务

版本

v1

3.1.3输入参数

3.1.3.1 应用级输入参数

名称

类型

必填?

说明

备注

reqts

char（14）

Y

请求发起时间戳

yyyyMMddHHmmss

channelcode

varchar（50）

Y

发起方渠道编码

bizparams

varchar（65536）

Y

json字符串

{“param1”:

”value1”,”param2”:

”value2”,......}

参数列表参数以其参数名的字典序升序进行排序，结果进行aes加密，并且转成base64字符串。

加密所用key由积分商城提供（同appSecrect）

所传参数见下表

authsign

varchar（256）

Y

数字签名

channelcode+reqts+{“param1”:

”value1”,”param2”:

”value2”,......}+appSecrect

加号不传

参数列表参数以其参数名的字典序升序进行排序,按照上面顺序进行排序后MD5加密（UTF-8编码），

接入渠道编码channelcode，密钥appSecrect由积分商城提供

所传参数见下表

加密解密方法：

测试时，系统参数里面加密使用的是申请应用的时候提供的appkey/appsecret；应用参数里面加密时使用的渠道编码为“AP+两位省份编码”，密钥为“RyiQwkaIB2AMvmpJk5RG1g==”

biz_params入参

名称

类型

必填?

说明

备注

transid

varchar（50）

Y

发起方流水

渠道编码+yyyymmddhh24miss+6位不重复序列

reqservicecode

varchar（9）

Y

服务编码

积分消费记录查询：

11011002

provincecode

char（3）

Y

省份编码

citycode

char（3）

Y

地市编码

nettype

char

（2）

Y

网别

012G

023G

994G

paytype

char

（2）

Y

付费类型

1预付费

2后付费

usertype

char

（1）

Y

用户类型

0手机

1宽带

2固话

3上网卡

usernumber

varchar（30）

Y

服务号码

telareacode

varchar（4）

N

区号

固网必填

begindate

char（8）

Y

开始时间

YYYYMMDD

enddate

char（8）

Y

结束时间

YYYYMMDD

3.1.4返回结果

名称

类型

必填?

说明

备注

respcode

char（4）

Y

应答编码

应答编码

0000成功

9999系统异常

respdesc

varchar（500）

N

应答描述

应答描述

rspts

char（14）

Y

响应时间戳yyyyMMddHHmmss

rspmsg

varchar（65536）

Y

业务应答（业务参数列表）消息

应答参数为json格式，同请求参数一样，整体结果进行aes加密，并且转成base64字符串

rspmsg内参数说明

名称

类型

必填?

说明

备注

respcode

char（4）

Y

应答编码

应答编码

0000成功

1203黑名单用户

1204号码不存在

1420客户无积分

respdesc

varchar（500）

N

应答描述

应答描述

scoredetailinfo

scoredetailinfo_entity[]

N

积分消费记录信息实体

3.1.5实体列表

3.1.5.1积分消费记录信息实体

3.1.5.1.1实体说明

实体名称

scoredetailinfo_entity[]

实体描述

3.1.5.1.2实体数据

名称

类型

必填?

说明

备注

scoreexpenddate

char（14）

Y

积分消费时间

YYYYMMDDHH24MISS

tradeid

varchar（30）

Y

业务流水

payfeemode

char

（1）

Y

支付方式

0积分支付

1积分+现金

scorevalue

varchar（50）

Y

消费积分数

chantype

char

（1）

Y

积分消费渠道:

0积分商城

1网上营业厅

2手机营业厅   

3短信营业厅

4实体营业厅

5自助终端机

6微信厅

7迷你厅

8省分积分平台

9合作伙伴积分平台

expendlist

expendlist_entity[]

N

消费商品列表实体

3.1.5.2消费商品列表实体

3.1.5.2.1实体说明

实体名称

expendlist_entity[]

实体描述

3.1.5.2.2实体数据

名称

类型

必填?

说明

备注

giftkindcode

varchar（20）

Y

消费商品编码

expensegood

varchar（100）

Y

消费商品名称

actioncount

varchar（4）

Y

消费商品数量

expensetype

char

（1）

Y

积分用途:

0 合作方产品

1 一卡充

21G流量半年包

3网厅交费

4 积分活动

5 积分转赠

6积分销售

7实体营业厅兑换

3.1.6API调用示例

3.1.6.1请求示例

{

"app_key":

"x9lelkX",

"timestamp":

"2014-01-0110:

19:

37212",

"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请求说明

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/v1

HTTP请求方式

HTTP-POST

格式

JSON

API授权类型

需要授权

是否收费API

否

类型

基础服务

版本

v1

3.2.3输入参数

3.2.3.1 应用级输入参数

名称

类型

必填?

说明

备注

reqts

char（14）

Y

请求发起时间戳

yyyyMMddHHmmss

channelcode

varchar（50）

Y

发起方渠道编码

bizparams

varchar（65536）

Y

json字符串

{“param1”:

”value1”,”param2”:

”value2”,......}

参数列表参数以其参数名的字典序升序进行排序，结果进行aes加密，并且转成base64字符串。

加密所用key由积分商城提供同appSecrect

所传参数见下表

authsign

varchar（256）

Y

数字签名

channelcode+reqts+{“param1”:

”value1”,”param2”:

”value2”,......}+appSecrect

加号不传

参数列表参数以其参数名的字典序升序进行排序,按照上面顺序进行排序后MD5加密（UTF-8编码），

接入渠道编码channelcode，密钥appSecrect由积分商城提供

所传参数见下表

biz_params入参

名称

类型

必填?

说明

备注

transid

varchar（50）

Y

发起方流水

渠道编码+yyyymmddhh24miss+6位不重复序列

reqservicecode

varchar（9）

Y

服务编码

积分产生记录查询：

11011003

provincecode

char（3）

Y

省份编码

citycode

char（3）

Y

地市编码

nettype

char

（2）

Y

网别

012G

023G

994G

paytype

char

（2）

Y

付费类型

1预付费

2后付费

usertype

char

（1）

Y

用户类型

0手机

1宽带

2固话

3上网卡

usernumber

varchar（30）

Y

服务号码

telareacode

varchar（4）

N

区号

固网必填

begindate

char（8）

Y

开始时间

YYYYMMDD

enddate

char（8）

Y

结束时间

YYYYMMDD

3.2.4返回结果

名称

类型

必填?

说明

备注

respcode

char（4）

Y

应答编码

应答编码

0000成功

9999系统异常

respdesc

varchar（500）

N

应答描述

应答描述

rspts

char（14）

Y

响应时间戳yyyyMMddHHmmss

rspmsg

varchar（65536）

Y

业务应答（业务参数列表）消息

应答参数为json格式，同请求参数一样，整体结果进行aes加密，并且转成base64字符串

rspmsg内参数说明

名称

类型

必填?

说明

备注

respcode

char（4）

Y

应答编码

应答编码

0000成功

1203黑名单用户

1204号码不存在

1420客户无积分

respdesc

varchar（500）

N

应答描述

应答描述

returninfo

returninfo_entity[]

N

积分产生记录信息实体

3.2.5实体列表

3.2.5.1积分产生记录信息实体

3.2.5.1.1实体说明

实体名称

returninfo_entity[]

实体描述

3.2.5.1.2实体数据

名称

类型

必填?

说明

备注

score

varchar（50）

N

当前积分

scoredetailinfo

scoredetailinfo_entity[]

Y

积分生成详细信息实体

3.2.5.2积分生成详细信息实体

3.2.5.2.1实体说明

实体名称

scoredetailinfo_entity[]

实体描述

3.2.5.2.2实体数据

名称

类型

必填?

说明

备注

scorecreatdate

char（14）

Y

积分生成时间

YYYYMMDDHH24MISS

scoreinvaliddate

char（14）

Y

积分失效时间

YYYYMMDDHH24MISS

scoretype

char

（2）

Y

积分类型

01：

通信消费积分

02：

奖励积分

03：

营销积分

04：

维系积分

05：

转赠积分

06：

回退积分

07:

合作伙伴积分

scorevalue

varchar（50）

Y

积分值

fusionscore

varchar（50）

N

融合业务积分

3.2.6API调用示例

3.2.6.1请求示例

{

"app_key":

"x9lelkX",

"timestamp":

"2014-01-0110:

19:

37212",

"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