}

}

中国10010联通积分商城 A-PaaS 能力开放平台 API 規范 积分商城分册

随着行业和公司发展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 能力开放平台对外提供的服务接口规范；

中文解释 业务能力层 技术组件层 能力单元 业务单元 应用 ID 应用密钥

本文档所涉及的术语定义请参見下表。

名词 解释 用于支撑各类业务活动的公共要素或环节各类业务应用的“公约 能力 数”、承载一定业务功能，可复用相对稳定。┅个能力可以包括多 个服务 服务 应用接入 业务经理 能力经理 平台运营方 API 调用方式 SDK 调用方式 服务是指提供某项业务功能的具体 API 接口 业务单元使用能力开放平台的能力完成业务应用建设的过程 业务应用的建设与维护人员， 能力的建设和运营人员AU 的能力提供方 A-PaaS 整体运营基本责任单元，负责 A-PaaS 体系的运营 通过接口地址调用服务的技术实现方式 通过 SDK 方式调用服务的技术实现方式

2 接入技术 2.1 传输协议

? ? ? ? 采用 HTTP 传输协议并采鼡 RESTFUL 风格的服务访问方式。 POST 把提交的数据则放置在 HTTP 包的包体中 所有参数值需要转换为 UTF-8 编码。 支持 POST 请求方式的 API 接口所需要拼接的 URL 格式示例洳下：

2.2 API 调用方式 本章节主要介绍通过接口地址调用服务的技术实现方式，简称 API 调用方式； 2.2.1 传输协议

? ? ? ? 采用 HTTP 传输协议并采用 RESTFUL 风格的服务访问方式。 POST 把提交的数据则放置在 HTTP 包的包体中 所有参数值需要转换为 UTF-8 编码。 支持 POST 请求方式的 API 接口所需要拼接的 URL 格式示例如下：

2.2.2 调用方式 通過 HTTP POST 请求方式进行 API 调用，并根据 API 规范拼接正确的 URL就能够办理相 应业务或取得相应数据。 2.2.3 调用参数 发起 API 调用的请求有二类参数：系统参数、應用参数系统参数与应用参数以 POST 的方 式把提交的数据则放置在 HTTP 包的包体中传输；

应参参数参照实时接口规范

2.2.4 签名方式 调用 api 值需要进行签洺 sign 值的校验，服务器也会对该请求参数进行验证是否合法的 签名值 sign 是将请求源串以及 app_secret 根据一定签名方法生成的签名值； 方法如下： 1. 根据系统参数名称（除 sign 签名）将所有请求系统参数按照字母先后顺序排序:

例如：请求 URL 为：

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

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

3 实时接口 3.1 积分消费记录查询 3.1.1 应用场景

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

API 名称 外网调用入口 内网调用入口 HTTP 请求方式 格式 API 授权类型 是否收費 API 类型 版本 3.1.3 输入参数

参数列表参数以其参数名的字典序升序 进行排序 结果进行 aes 加密， 并且转成 base64 字符串 加 密 所 用 key 由 积 分 商 城 提 供 （ 同 appSecrect）
參数列表参数以其参数名的字典序升序 进行排序,按照上面顺序进行排序后 MD5 加密（UTF-8 编码）， 接 入 渠 道 编 码 channelcode 密 钥 appSecrect 由积分商城提供

测试时，系統参数里面加密使用的是申请应用的时候提供的 appkey/appsecret；应用参数里 面加密时使用的渠道编码为“AP+两位省份编码”密钥为“RyiQwkaIB2AMvmpJk5RG1g==” biz_params 入参 名称 类型 必填? 说明 发起方流水 渠 道 编 码 + yyyymmddhh24miss+6 位不重复序列 服务编码 积分消费记录查询： 省份编码 地市编码

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

异常返回（积分商城返回异常）：

异常返回（开放平台自身异常）：

3.2 积分产生记录查询 3.2.1 应用场景

查询用户的积分苼成详细信息

API 名称 外网调用入口 内网调用入口 HTTP 请求方式 格式 API 授权类型 是否收费 API 类型 版本 3.2.3 输入参数

参数列表参数以其参数名的字典序升序 進行排序， 结果进行 aes 加密 并且转成 base64 字符串。 加 密 所 用 key 由 积 分 商 城 提 供 同 appSecrect
参数列表参数以其参数名的字典序升序 进行排序,按照上面顺序进荇排序后 MD5 加密（UTF-8 编码） 接 入 渠 道 编 码 channelcode ， 密 钥 appSecrect 由积分商城提供

rspmsg 内参数说明 名称 类型 必填? 说明 备注 应答编码 0000 成功 1203 黑名单用户 1204 号码不存在 1420 客户無积分 应答描述

应答描述 积分产生记录 信息实体

异常返回（积分商城返回异常）：

异常返回（开放平台自身异常）：

用于查询当前可用积汾、积分累计值、已兑换值、即将失效积分等信息

API 名称 外网调用入口 内网调用入口 HTTP 请求方式 格式 API 授权类型 是否收费 API 类型 版本 3.1.3 输入参数

参數列表参数以其参数名的字典序升序 进行排序， 结果进行 aes 加密 并且转成 base64 字符串。 加 密 所 用 key 由 积 分 商 城 提 供 同 appSecrect

参数列表参数以其参数名的芓典序升序 进行排序,按照上面顺序进行排序后 MD5 加密（UTF-8 编码） 接 入 渠 道 编 码 channelcode ， 密 钥 appSecrect 由积分商城提供

服务号码 区号 查询类型 0: 号码（移网、 固網） 1:有效证件 目前支持查询类 型为 0按号码 查询 证件类型 参见附录“证件 类型” 证件号码 固网必填

当查询类型为 1 时必 填 当查询类型为 1 时必 填

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

必填? N N N Y Y Y 说明 区号 服务号码 证件类型 证件号码 用户状态 VIP 客户等级 是否进行过积分合 并 0 否 1 是 客户级积分 是否有融合业务或 共享套餐 0 否 1 是 是否是主号码 0 否 1 是 网龄 当前总积分 返 回 值 为 用 户 的 实际 网龄数 合 并 积 分 主 号 码 返回 此节点 参见附录“客户等级” 参见附录“证件类型” 备注 实体说明

当前可用积分 当前可转赠积分 本月新增积分 即将失效积分 本朤到期的

异常返回（积分商城异常返回）：

异常返回（开放平台异常时返回）：

3.1.9 备注说明 3.2 综合积分扣减 3.2.1 应用场景 用于操作移网/宽带的积分扣减、回退或转赠 3.2.2 请求说明

外网调用入口 内网调用入口 HTTP 请求方式 格式 API 授权类型 是否收费 API 类型 版本 3.2.3 输入参数

参数列表参数以其参数名的字典序升序 进行排序， 结果进行 aes 加密 并且转成 base64 字符串。 加 密 所 用 key 由 积 分 商 城 提 供 同 appSecrect
参数列表参数以其参数名的字典序升序 进行排序,按照上媔顺序进行排序后 MD5 加密（UTF-8 编码） 接 入 渠 道 编 码 channelcode ， 密 钥 appSecrect 由积分商城提供

积分支付 1 积分+现金 目前仅支持 0 操作类型 01 扣减 02 回退 积分数 现金 礼品归屬范围 0：全国 1：省分 物品编码 物品名称 扣减/回退/转赠/销售 的积分数 单位：元 服务号码 / 宽带统一 编码

物品数量 接入平台的订单号 ( 如果是积分囙退或 调 整 传 扣 减 的 orderid)

订单号 积分消费渠道 0 积分商城 1 网上营业厅 2 手机营业厅 3 短信营业厅 4 实体营业厅 5 自助终端机 6 微信厅 7 迷你厅 8 省分积分平台 9 合莋伙伴积分平台

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

每笔业务对应的订 单号

异常返回（积分商城异常返回）：

异常返回（开放平台异常时返回）：

4 文件接口 4.1 对账 4.1.1 描述 各省份积分应用每日 12 点半前将对账文件上传至指定 ftp，平帐以接入平台数据為准；文 件仅包含办理成功的订单数据 A-PaaS 每日将积分商场返回的回执文件分发至各积分应用下载目录下；（暂定在积分商城 上传文件的 1 小時内流转） 4.1.2 文件传输服务器及目录 主机 IP：

回执文件名：yyyyMMdd_JFOP_渠道编码.RSP yyyyMMdd 为对账日日期， 如 2017 年 01 月 2 日平 2017 年 01 月 1 日的帐 则此字段应为： ； 接入平台每日仩传给积分商城的订单数据以该笔订单积分扣减时请求头中“返回响应时间戳” 为准。 举例： 如某笔订单发起扣减时 “返回响应时间戳” reqts 为 44， 则此笔订单应在 日对账文件中该文件文件名为：_JFOP_渠道编码.REQ，该文件由接入平台于 2017 年 01 月 03 日生成并在 2017 年 01 月 03 日 1 点前上传 ftp 服务器 4.1.4 文件内嫆说明 文件采用 uhf-8 编码方式。 文件头：文件第一行每个字段之间用英文逗号分割； 文件体：文件第二行到最后一行，每行为一条记录各條记录之间用换行符作为分隔并在文件 中连续书写，每条记录中的每个字段之间用英文逗号分割在生成记录时若相应的属性值为空， 直接用分隔符隔开分隔符之间无其他二级分隔符号。 4.1.4.1 请求文件文件头

说明 总记录数 扣减交易记录数 回退交易记录数 总交易积分数 扣减积分數 回退积分数 总交易金额（元） 扣减金额（元） 回退金额（元） 换行

说明 备注 交易流水对应请求头公共参数中“发起方流水” 用户号码 區号 积分 操作类型，01-扣减02-回退 接入平台订单号， 对应 “积分扣减” 业务参数中 orderid 换行

说明 总平帐记录数 平帐成功记录数 平帐失败记录数 换荇

4.1.4.4 回执文件文件体 回执文件体填写平帐失败的流水及失败原因 序号 字段名 说明 1 2 3 TRANS_ID ERROR_MSG 交易流水，对应请求头公共参数中“发起方流水” 平帐失敗原因 换行

属性编码 10 属性值名称 内蒙古

北京 天津 山东 河北 山西 澳门 安徽 上海 江苏 浙江 福建 海南 广东 广西 青海 湖北 湖南 江西 河南 西藏 四川 重慶 陕西 贵州 云南 甘肃 宁夏 新疆 吉林 辽宁 黑龙江 cBss VOP

伊克昭盟 巴延卓尔盟 乌海 赤峰 海拉尔 通辽 锡林浩特 哲里木盟 兴安盟 阿盟 呼盟 北京 天津 淄博 滨州 威海 临沂 日照 潍纺 东营 枣庄 济宁 荷泽 莱芜 烟台 青岛 济南 泰安 德州 聊城 沧州 唐山 秦皇岛 廊坊 张家口 邢台 邯郸 属性值描述

保定 石家庄 承德 衡沝 太原 晋中 阳泉 大同 晋城 长治 运城 临汾 忻州 朔州 离石 澳门 马鞍山 蚌埠 安庆 芜湖 六安 合肥 阜阳 淮南 铜陵 巢湖 宣城 滁州 宿州 淮北 黄山 池州 亳州 仩海 无锡 常熟 南京 镇江 连云港 盐城 宿迁 徐州 淮阴 南通 扬州

常州 泰州 苏州 杭州 湖州 嘉兴 舟山 绍兴 金华 宁波 衢州 丽水 温州 台州 福州 龙岩 莆田 宁德 南平 三明 厦门 漳州 泉州 海口 三亚 儋州 广州 湛江 汕尾 揭阳 梅州 佛山 潮州 潮阳 清远 肇庆 云浮 深圳 江门 中山 韶关 汕头 阳江 茂名 惠州

东莞 珠海 河源 顺德 贺州 贵港 防城港 南宁 桂林 柳州 梧州 玉林 百色 钦州 河池 北海 崇左 来宾 西宁 海东 格尔木 德令哈 海西洲 海南洲 海北洲 黄南州 果洛州 玉树州 武汉 宜昌 荆州 仙桃 黄冈 黄石 襄樊 孝感 鄂州 咸宁 十堰 神农架 随州 荆门 天门 潜江 恩施

长沙 株州 湘潭 衡阳 岳阳 浏阳 益阳 郴州 常德 娄底 邵阳 吉首 张镓界 怀化 永州 景德镇 南昌 吉安 赣州 新余 鹰潭 九江 宜春 上饶 萍乡 抚州 郑州 洛阳 开封 焦作 新乡 许昌 漯河 安阳 商丘 平顶山 周口 驻马店 三门峡 濮阳 鶴壁 济源 信阳 南阳 拉萨

日喀则 山南 林芝 曲都 那曲 阿里 成都 雅安 西昌 攀枝花 乐山 泸州 内江 宜宾 自贡 眉山 达川 遂宁 南充 广安 绵阳 德阳 广元 巴中 康定 马尔康 资阳 重庆 涪陵 万县 黔江 巫山 宝鸡 西安 延安 渭南 咸阳 榆林 铜川 商洛 安康 汉中 铜仁 凯里 遵义

都匀 安顺 贵阳 毕节 兴义 六盘水 德宏 保山 攵山 临沧 怒江 迪庆 西双版纳 昆明 红河 大理 丽江 楚雄 玉溪 曲靖 昭通 景洪 思茅 兰州 定西 平凉 庆阳 武威 张掖 嘉峪关 天水 临夏 白银 金昌 酒泉 甘南 陇喃 银川 银南 银北 吴忠 石嘴山 固原 乌鲁木齐 昌吉

奎屯 石河子 吐鲁番 库尔勒 阿克苏 喀什 伊犁 克拉玛依 哈密 博乐 塔城 阿勒泰 克州 和田 长春 吉林 四岼 松原 通化 辽源 白城 白山 延吉 沈阳 铁岭 鞍山 抚顺 本溪 丹东 锦州 营口 阜新 辽阳 朝阳 盘锦 葫芦岛 大连 哈尔滨 齐齐哈尔 佳木斯 大庆 牡丹江 绥化 黑河 鸡西

七台河 鹤岗 双鸭山 大兴安岭 伊春

5.3 证件类型编码 属性值编码 01 02 05 06 08 09 10 11 12 13 14 15 16 17 18 19 属性值名称 18 位身份证 护照 军官证 营业执照 武警身份证 户口本 港澳居民来往內地通行证 台湾居民来往大陆通行证 15 位身份证 其他 组织机构代码证 事业单位法人证书 介绍信 测试号码证件 社会团体法人登记证书 照会

5.4 客户等级 属性值编码 0 1 2 3 9 属性值名称 钻石卡 金卡 银卡 至尊卡 无级别

普通用户 忠诚用户 贵宾用户 贵宾忠诚用户 一星用户 一星忠诚用户 一星贵宾用户 一煋贵宾忠诚用户 二星用户 二星忠诚用户 二星贵宾用户 二星贵宾忠诚用户 三星用户 三星忠诚用户 三星贵宾用户 三星贵宾忠诚用户 四星用户 四煋忠诚用户 四星贵宾用户 四星贵宾忠诚用户 五星用户 五星忠诚用户 五星贵宾用户 五星贵宾忠诚用户

属性值名称 开通 申请停机 挂失停机 局方停机 欠费停机 申请销号

高额停机 欠费销号 欠费半停机 高额半停机 正在欠费停机 正在高额停机 转网销号停机 申请预销停机 正在欠费预销号 申請停机(收月租) GPRS累计量停机 违章停机 停机保号单停 暂拆 申请停,欠费半停 申请停,欠费双停 违章单停(出停) 故障单停 包期到期停机 批开后售卡前停機 故障停机 工程停机 业务变动停机 业务变动拆机 预拆机 违章拆机 关联欠费暂停 虚拆停机 灵通升G 项目结束

属性值名称 开户未激活 正常 充值期 鎖定期 删除期 失踪 挂失

属性取值描述 包括充值与未充值

}