# 服务开放平台工程接口设计规范-高端客户权益积分V1.18

**服务开放平台**

**个人综合积分接口设计规范**

2022年03月21日

**文****档修订记录**

| 版本 | 简要说明 | 日期 | 作者 | 审核人 | 批准人 |
| --- | --- | --- | --- | --- | --- |
| 1.0 | 初版 | 2022.03.21 | 黄海贝 | 廖静雅 |  |
| 1.1 | 修改信用卡积分明细查询接口卡号字段名 | 2022.03.23 | 黄海贝 | 廖静雅 |  |
| 1.2 | 修改信用卡积分明细查询接口名 | 2022.03.28 | 黄海贝 | 廖静雅 |  |
| 1.3 | **修改日终文件查询、下载接口名，修改接口地址示例** | 2022.03.30 | 黄海贝 | 廖静雅 |  |
| 1.4 | **增加线下积分批量调整接口请求参数说明** | 2022.04.13 | 黄海贝 | 廖静雅 |  |
| 1.5 | **增加文件查询、下载接口正式环境地址示例，添加线下积分批调接口说明** | 2022.04.19 | 黄海贝 | 廖静雅 |  |
| 1.6 | **增加权益积分服务预约、取消、完成接口以及权益积分预约服务状态查询接口说明** | 2022.04.29 | 梁雅琪 | 廖静雅 |  |
| 1.7 | **修改权益积分服务接口合作方交易流水号生成规则，修改预约服务状态字段大小写** | 2022.5.12 | 梁雅琪 | 廖静雅 |  |
| 1.8 | **增加兑换预约码样例，服务厂商编号枚举值** | 2022.5.18 | 梁雅琪 | 廖静雅 |  |
| 1.9 | **增加服务商对账单文件下载和查询接口说明** | 2022.5.18 | 万聪 | 廖静雅 |  |
| 1.10 | **修改对账文件的流水号规则要求** | 2022.6.23 | 梁雅琪 | 廖静雅 |  |
| 1.11 | **新增业务返回码** | 2023.04.18 | 梁雅琪 | 廖静雅 |  |
| 1.12 | ### 新增6.2.9高端客户权益积分根据权益码订单详情查询接口 | 2024.01.24 | 凌强祥 | 廖静雅 |  |
| 1.13 | ### 6.2.9高端客户权益积分根据权益码订单详情查询接口客户归属机构一分brhLv1InstName备注修改 | 2024.01.26 | 凌强祥 | 廖静雅 |  |
| 1.14 | ### 6.2.9高端客户权益积分根据权益码订单详情查询接口partnerTxSriNo生成规则说明修改 | 2024.02.01 | 凌强祥 | 廖静雅 |  |
| 1.15 | ### 6.2.9 高端客户权益积分根据权益码订单详情查询响应体客户自营代理属性instType、客户归属机构一分brhLv1InstName、客户归属机构二分brhLv2InstName、客户归属机构一支subLv1InstName、客户归属网点机构custInstName、出账月份outGoingDate备注修改 | 2024.02.05 | 凌强祥 | 廖静雅 |  |
| 1.16 | ### 6.2.5高端客户权益积分服务预约、取消、完成、6.2.6高端客户权益积分预约服务状态查询接口接口请求体中渠道标识tranChnl备注更新 | 2024.03.26 | 凌强祥 | 廖静雅 |  |
| 1.17 | ### 修改文件查询、下载接口定版示例地址 | 2024.04.02 | 凌强祥 | 廖静雅 |  |
| 1.18 | ### 新增高端客户权益订单退还时已过期积分查询接口 | 20250422 | 崔广学 | 廖静雅 |  |

说明：1.按修改时间先后顺序排列。

2.版本栏中填入版本编号或者更改记录编号。

3.在简要说明栏中填写变更的内容和变更的范围。

4.表中所有日期格式为：YYYYMMDD。

**目      录**

1. 范围5

2. 参考文档5

3. 术语与定义5

4. 符号与缩略语5

5. 报文结构及使用说明5

5.1. 通信报文协议5

5.2. 数据类型定义5

5.3. 取值符号说明6

5.4. 报文结构说明6

5.4.1 请求报文结构6

5.4.2 请求报文头说明6

5.4.3 响应报文结构7

5.4.4 响应报文头说明7

5.4.5 报文加解密规则7

5.4.6 签名验签8

5.4.7 报文范例8

5.4.8 http状态码说明9

6. 交易定义10

6.1. 接口地址规范10

6.2. 接口报文10

6.2.1 线下积分批量调整交易10

6.2.2 调整结果日终文件查询接口12

6.2.3 调整结果日终文件下载接口13

6.2.4 信用卡积分明细查询（分类）13

6.2.5 高端客户权益积分服务预约、取消、完成接口15

6.2.6 高端客户权益积分预约服务状态查询接口17

6.2.7 服务商对账单文件查询接口18

6.2.8 服务商对账单文件下载接口19

6.2.9 高端客户权益积分根据权益码订单详情查询19

7. 附录A21

7.1. 业务响应码说明21

# 范围

中国邮政储蓄银行服务开放平台工程，开放api部分。

# 参考文档

无。

# 术语与定义

表 3\-1 术语与定义

| 术语 | 描述 |
| --- | --- |
| 报文头 | 即系统参数，对应报文结构中的 head 部分，适用于所有报文类接口，与具体业务无关 |
| 报文体 | 即业务参数，对应报文结构中的 body 部分，根据具体业务进行定义。 |
| 数字签名 | 数据在网络中传输的安全手段之一，用于防篡改、验证数据收发双方身份，具体参见安全规范部分 |
| token | Token, 令牌，代表执行某些操作的权利的对象。 |
| 报文 | 数据传输的载体，由报文头、报文体、数字签名 |
| 参数 | 用于描述传输的数据信息，是报文、文件传输的基础组成部分 |
| 报文组件 | 由一个或多个参数组成，是一个可共用、复用的数据结构 |
| 请求发送方 | 报文或文件发送端 |
| 请求接收方 | 报文或文件接收端 |

# 符号与缩略语

无。

# 报文结构及使用说明

## 通信报文协议

专线连接方式采用HTTP方式。互联网连接方式采用HTTPS方式。

报文组织采用application/json;charset=UTF-8格式。

## 数据类型定义

表 5\-1 数据类型定义

| 序号 | 类型 | 说明 | 分类 | 附加说明 |
| --- | --- | --- | --- | --- |
| 1 | string | 字符串类型 | simpleType(简单类型) | 12345abc |
| 2 | date | 日期，格式为yyyyMMdd | simpleType(简单类型) | 20191211 |
| 3 | datetime | yyyyMMddHHmmssSSS | simpleType(简单类型) | 20191211120856000 |
| 4 | boolean | 布尔类型 | simpleType(简单类型) | true/false |
| 5 | number | 整数类型 | simpleType(简单类型) | 100 |
| 6 | byte\[\] | 字节流 | simpleType(简单类型) | 如文件流 |
| 7 | list | 列表集合，名称对应列表名，集合中的参数单独描述 | complexType(复杂类型) | userList |

## 取值符号说明

表 5\-2 取值符号说明

| 符号 | 含义 | 备注 |
| --- | --- | --- |
| M | 必须出现 |  |
| ME | 必须出现且于应答与请求保持一致 |  |
| C | 条件出现 |  |
| CE | 如果出现，应答与请求保持一致 |  |
| O | 可选出现 | 如不出现，参数名及值都可以不出现 |
| OE | 可选出现，应答与请求保持一致 | 如不出现，参数名及值都可以不出现 |

## 报文结构说明

### 请求报文结构

请 求 报 文 只 支 持 JSON 格 式 ， 报 文 支 持 的 媒 体 类 型 为 ：

application/json;charset=UTF-8

报文分为：请求报文、数字签名、token、报文加密密钥四部分。

表 5\-3 报文结构说明

| 序号 | 中文名称 | 变量名 | 数据类型 | 长度 | 必输 | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | 请求报文 | request | string |  | M | 加密后的请求报文（详见报文加解密规则） |
| 2 | 数字签名 | signature | string | 256 | M | 签名（详见签名规则） |
| 3 | 访问令牌 | accessToken | string | 1000 | M | 请求方的访问令牌 |
| 4 | 报文加密密钥 | encryptKey | string | 200 | M | 报文sm4加密密钥,使用sm2加密后的密文（详见报文加解密规则） |

### 请求报文头说明

表 5\-4 请求报文头说明

| 序号 | 中文名称 | 变量名 | 数据类型 | 长度 | 必输 | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | 合作方交易流水号 | partnerTxSriNo | string | 24 | M | 交易唯一标识,规则日期+时间+10位数字（比如：202007151505101987563766） |
| 2 | 接口代码 | method | string | 32 | M | 详见具体接口名 |
| 3 | 接口版本 | version | string | 8 | M | 默认1 |
| 4 | 合作方编号 | merchantId | string | 20 | M | 合作方在服开门户注册的合作方编号 |
| 5 | 伙伴应用id | appID | string | 21 | M | 门户首页分配给商户的APP\_ID |
| 6 | 报文发起时间 | reqTime | datetime | 14 | M | 格式：yyyyMMddHHmmss（合作方发起时间） |
| 7 | 保留字段 | reserve | string | 256 | O | KV方式 |

### 响应报文结构

**http状态码为200**时的应 答 的 报 文 只 支 持 JSON 格 式 ， 报 文 支 持 的 媒 体 类 型 为 ：

application/json;charset=UTF-8

报文分为：响应报文、数字签名、token、报文加密密钥四部分。

表 5\-5 报文结构说明

| 序号 | 中文名称 | 变量名 | 数据类型 | 长度 | 必输 | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | 响应报文 | response | string |  | M | 加密后的响应报文（详见报文加解密规则） |
| 2 | 数字签名 | signature | string | 256 | M | 签名（详见签名规则） |
| 3 | 访问令牌 | accessToken | string | 1000 | M | 请求方的访问令牌 |
| 4 | 报文加密密钥 | encryptKey | string | 200 | M | 报文sm4加密密钥,使用sm2加密后的密文（详见报文加解密规则） |

### 响应报文头说明

表 5\-6 响应报文头说明

| 序号 | 中文名称 | 变量名 | 数据类型 | 长度 | 必输 | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | 合作方交易流水号 | partnerTxSriNo | string | 24 | M | 交易唯一标识 |
| 2 | 接口代码 | method | string | 32 | M | 详见具体接口名 |
| 3 | 接口版本 | version | string | 8 | M | 默认1 |
| 4 | 合作方编号 | merchantId | string | 10 | M | 合作方在服开门户注册的合作方编号 |
| 5 | 伙伴应用id | appID | string | 32 | M | 门户首页分配给商户的APP\_ID |
| 6 | 报文响应时间 | respTime | datetime | 14 | M | 格式：yyyyMMddHHmmss |
| 7 | 预留字段 | reserve | string | 256 | O | KV方式 |

### 报文加解密规则

合作伙伴调用服务开放平台的api时，需要对报文进行加密，以保证报文网络传输安全。

密钥互换: 合作伙伴根据服务开放平台提供的密钥生成工具，生成公私钥。将公钥public key 1上传给服务开放平台，保留私钥private key1。下载服务开放平台分配给合作伙伴的公钥public key 2服务开放平台持有该商户平台私钥private key2。

加密规则: 合作伙伴发起API调用时，随机生成一个sm4 key，并使用这个key对请求报文做sm4对称加密 得到请求报文密文 request。然后使用public key 2对这个key进行sm2非对称加密得到报文加密密钥密文 encryptKey。

sm4 配置: CBC

服务开放平台收到合作伙伴的请求报文后，使用private key2对encryptKey进行解密。使用解密后的key对request解密。

服务开发平台响应报文加密规则: 随机生成一个sm4 key，并使用这个key对请求报文做sm4对称加密 得到请求报文密文 response。然后使用public key 1对这个key进行sm2非对称加密得到报文加密密钥密文 encryptKey。

### 签名验签

服务开放平台要对合作伙伴的api请求做签名验签，以防止请求参数被篡改。

密钥互换: 参考报文加解密密钥互换部分。

签名规则: 对request + encryptKey + accessToken 组成的字符串使用private key1取sm3签名运算后的值然后通过private key 1 sm2加密后作为签名signature。

服务开放平台做签名验签时，使用sm3 对request + encryptKey + accessToken组成的字符串做签名运算后的值 和用public key 1 对signature 做sm2 解密后的值验签。根据验签结果，判断报文是否被篡改。

说明:accessToken 非必传。为空时取空字符串。

服务开发平台响应报文签名规则:对response + encryptKey + accessToken 组成的字符串使用sm3做签名运算，签名运算的值用private key2 sm2加密后作为签名signature。

### 报文范例

请求报文明文示例：

{"head":{"method":"account.addBankCard","merchantId":"TEST0006","appID":"psbc123456","reserve":"","partnerTxSriNo":"test43543543teew67er4353435","reqTime":"20200109125700","version":"1"},"body":{"validateCode":"165445","reqIp":"0","accountNo":"6210987910013270745","busiMainId":"788678899qwwq4555442278","accType":"2","reqMac":"0","bankCardCode":"403100000004","bankCardNo":"6210987910013270745","bankCardType":"1","mobileNo":"13130475423","custName":"王二娃","deviceInfo":"iphone11","personalCertNo":"14022319831115983X","txAbbr":"0","txAttr":"0","personalCertTypeCode":"01","reqTransTime":"20200314140802"}}

请求报文加密加签名后示例：

{"accessToken":"","encryptKey":"040D01522D88DBD9D76DC0188770E76664D7B9585A9D6AE64F24E965C4485D611F524A963EDA727357AAC2DC0FF8873744382EA3123B2D45007952D1C51E29E79007204DEC4347D615E1970D20CAEBC4D011B4F90367E1177587DA011E3ED1D97991AA55047460428187532FE7A46B9CE1","request":"7/0DxUlf/wvizkfwvHt+xCnhj0fyJKBoZsuHPBuWz6XYTeN1f4xGI1XhyGaVM46xNvNmPf138u0aFXXFG/8rXJdfAy9ZidrReToOtVTO0ElwypeuS9Y2oGhODuxGGtEatiJ7+R40/SKb01dVJmj2d9O5ytRCYFxuet1Twf8FATbV0smrRWJKXqnx7DnAWlKW2mrve+8RJbKp5Xd3eleal+ytZThjmSvc1PekpREfBIxs2EqofGETUKO4o2DYPJGJk3e+MWe/sU5y2Uv3M7/zDCB2ld05fqa4RhhWc1N/mpK659OoSbq/CW4f9o6/Y2FzyDq+faMV5ze71BXTwxxpuVnvE5LxQT0FGRCZNT1j9Y55iDAdkrAzvreEZXch2w0X9zio+mcOWwugXRGwQw6wdMphP5B87YIebfSlBaEfEfHn7zD02Xwwyj7tXeerg6ypRuE5naI9j8n3FoOKVV/jUsxsU0Dc60m9l4rcUPMs/gMGnR73JcdpiAoU+SRXczhW0dk9cs4+fXyY4WEsFNNewrtB3woM1bXoLlm2QxtBPj27GqqL9zeRHlsTBKqLCFK90EuwNTe4Lm2nM3uQhY80Wff9yXkLxyQ5iSAEEaAaYRbg9POfaBJAN2O3+zu4WW0p1QKsVrJZ9EnElYChBwmRgbzCTD/RjJe1XxzcsQZOjuwzQmNiGkmH9H9aMvWVR7HTZXAm/Q7Lkz7ilJZ7Yurphilm+lttoOx8JJuDa9K57zFyKcLy7PL9nZGha1+a7o8O2YID9HvVzQKqn6fNTqDrmtPdK6iFa5d03Zzrie7BK8nuNEYwWerQrnewGC9nx8we","signature":"MEYCIQDXoTlvzsNTJwJKlMWxEcOw9Ic5LHFE4FxTMcf9U2UnhAIhAIvv5suTW+2CQLYg1vXYrTcfHOyWiY1X/pBgoQa2ebAu"}

加密加签名的响应报文示例：

{"encryptKey":"047755F0AEBC7CC4D8F92B8AF8BC76A781F068D641C48956EAF395B3D4E22CF48047CDBAF73DACE994CE1E9277D6A8FE9BD6BDCFA796EAFE7BE5E712ED94E5B18CE14F70F469F79304E17415D10ED63A9F32C64B0BB92EB8E8CB6372A2A2CF6F75E10E1D77073BE02A930BF5A0ADDF74FB","response":"zulRLLrANOut8vZqzbYI04SbAQoV3ZV/qkWtMPDGQWOjjU7HgM+b151/HoA/0TyUA4hLSdbWMDNfhYW8VK5ujr1HEQkgvfS3nkY8pfIGrqLSqr4AnLYEIzxlj9st4cD3+Ty5q0Dc3LJz5zOEcZ4/xmABIUgO1pjYRqhCC7X0P+VzGVE+E8mSDI9uAUSdC5wpJ8+lPT0yQkgFSQOKMd6igKT3M/NwX1gyorbrKd5LdCIxEmopwk15TMi9o/lGGdVh15T4ip8FuSWwZ+3b3xbPb2l2oScv7yifjWnxq1a6Vmjqo5lWJbp8/cUNeE4PanV3A3tMg8OmMMxkk7jLD0iuj8hclEgyjHlfrU/qB9Gl/dI=","signature":"MEYCIQDbdksIwiixYo/8vUzZa4AI4xssnn86MbRvJrItp1lvswIhAMJJRFkbqmZUxV3BV+Fo5LqY5WO/IoHFLKemYavp+y5p"}

响应报文response明文示例：

{"head":{"method":"account.addBankCard","merchantId":"TEST0006","appID":"psbc123456","respTime":"20200914163044","reserve":"","partnerTxSriNo":"test43543543teew67er4353435","version":"1"},"body":{"respMsg":"合作方交易流水号格式错误","respCode":"062025"}}

### http状态码说明

表 5-7 响应报文头说明

| 序号 | 状态码 | 描述 | 一般问题产生原因 |
| --- | --- | --- | --- |
| 1 | 400 | 非法请求 | 1.  http请求方法不是POST<br>    <br>2.  Content-Type 不是 application/json;charset=UTF-8<br>    <br>3.  请求参数有问题 |
| 2 | 401 | 未认证 | 1.未进行身份认证 |
| 3 | 403 | 禁止访问 | 1.  api对应的产品合约有问题（没合约，或者合约状态有问题）<br>    <br>2.  没有对应资源的访问权限<br>    <br>3.  请求路径有问题，取不到商户号<br>    <br>4.  accessToken 信息为空(一般h5 accessToken失效会出此问题)<br>    <br>5.  报文里的商户号和请求地址的商户号不一致（h5时，可能报文里的商户号和accessToken的不一致）<br>    <br>6.  合约校验失败 |
| 4 | 429 | 请求太多 | 1.单位时间内请求，超过限流次数 |
| 5 | 500 | 服务器内部错误 | 1.请求报文格式有问题<br>2.加解密签名有问题（使用了和商户平台密钥配对以外的密钥）<br>3.其他错误 |

# 交易定义

## 接口地址规范

格式: 协议 + 域名 + 网关 + 接口地址业务前缀 + 合作方编号 + 接口地址后缀

正式示例: https://open.psbc.com/gateway/biz/points/{合作方编号}.htm?partnerTxSriNo={流水号} 

正式环境文件查询、下载示例：https://open.psbc.com/gateway/biz/ufile/{合作方编号}.htm?partnerTxSriNo={流水号}

沙箱示例: https://open.psbc.com/gateway/sandbox/biz/points/{合作方编号}.htm?partnerTxSriNo={流水号}

测试定版示例：http://220.248.252.123:8443/sop-h5/biz/points/{合作方编号}.htm?partnerTxSriNo={流水号}

文件查询、下载接口定版示例：http://220.248.252.123:8443/sop-h5/biz/ufile/{合作方编号}.htm?partnerTxSriNo={流水号}

测试预演示例：http://220.248.252.123:8443/sop-h5/biz\_pre/points/{合作方编号}.htm?partnerTxSriNo={流水号}

文件查询、下载接口预演示例：http://220.248.252.123:8443/sop-h5/biz\_pre/ufile/{合作方编号}.htm?partnerTxSriNo={流水号}

## 接口报文

### 线下积分批量调整交易

接口名：points.offlineBatchAdjust

说明：提供北分可批量调整客户线下积分的接口。该接口请求头中的partnerTxSriNo字段生成规则需要单独注意，生成规则为：8位日期+6位时间+4位数字，每次交易确保唯一。

#### 请求报文

表 6\-1 线下积分批量调整交易请求报文

| 序号 | 中文名称 | 变量名 | 类型 | 长度 | 必输 | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | 业务主ID | busiMainId | String | 24 | M | 规则同合作方交易流水号 |
| 2 | 交易时间 | reqTransTime | String | 14 | M | yyyyMMddHHmmss（用户发起时间） |
| 3 | 渠道标识 | tranChnl | String | 14 | M | 46-北京分行 |
| 4 | 机构属性 | instType | String | 32 | M | 01-自营，02-代理 |
| 5 | 发起机构编号 | opInstId | String | 32 | M |  |
| 6 | 本次调整数量 | adjustNum | int | 8 | M | 最少1条，最多20条 |
| 7 | 批次编号 | adjustBatchNo | string | 30 | M | 本次批量调整的批次编号，每次交易保证唯一 |
| 8 | 调整明细集合 | adjustList | arrayList |  | M |  |
| 8.1 | 客户调整序列号 | subTranSq | string | 30 | M | 本次批量调整中具体客户调整明细对应的序列号，保证唯一 |
| 8.2 | 活动号 | activityId | string | 30 | M |  |
| 8.3 | 客户名称 | cstmName | string | 40 | M |  |
| 8.4 | 客户证件类型 | paperType | string | 2 | M |  |
| 8.5 | 客户证件号码 | paperId | string | 30 | M |  |
| 8.6 | 调整积分数 | adjustPoints | int | 10 | M |  |
| 8.7 | 生效日期 | effectiveDate | string | 8 | M | yyyyMMdd |
| 8.8 | 积分归属机构（网点） | instId | string | 9 | M |  |

#### 响应报文

表 6\-2 线下积分批量调整交易响应报文

| 序号 | 中文名称 | 变量名 | 类型 | 长度 | 必输 | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | 返回码 | respCode | String | 6 | M |  |
| 2 | 返回信息 | respMsg | String | 255 | M |  |
| 3 | mac加密串 | mac | String | 24 | M | 交易流水号+系统编号+发起机构编号+本次调整数量 |

### 调整结果日终文件查询接口

接口名：ufile.query.points\_offlineBatchAdjustResult

说明：查询文件。

#### 请求报文

表 6\-3 通用文件查询接口请求报文

| 序号 | 中文名称 | 变量名 | 类型 | 长度 | 必输 | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | 会计日期 | accountingDate | String | 8 | M | YYYYMMDD |

#### 响应报文

表 6\-4 通用文件查询接口响应报文

| 序号 | 中文名称 | 变量名 | 类型 | 长度 | 必输 | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | 返回码 | respCode | String | 6 | M |  |
| 2 | 返回信息 | respMsg | String | 255 | M |  |
| 3 | 文件信息列表 | files | List | \- | M |  |
| 3.1 | 文件id | fileId | String | 32 | M | 文件唯一标识 |
| 3.2 | 文件数据名称 | dataName | String |  | O | 文件数据名称 |
| 3.3 | 区域编码 | areaCode | String | 4 | O | 默认0000 |
| 3.4 | 会计日期 | accountingDate | String | 8 | O | YYYYMMDD |
| 3.5 | 处理类型 | hanType | String | 1 | O | Z-初始数据，A-增量数据，I-全量数据 |
| 3.6 | 批次号 | fileTatchNo | String | 4 | O | 例：0001 |
| 3.7 | 文件序号 | fileNo | String | 4 | O | 例：0001 |
| 3.8 | 文件数据名称扩展 | dataNameExt | String |  | O |  |

### 调整结果日终文件下载接口

接口名：ufile.download.points\_offlineBatchAdjustResult

说明：下载文件。

#### 请求报文

表 6\-5 通用文件查询接口请求报文

| 序号 | 中文名称 | 变量名 | 类型 | 长度 | 必输 | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | 文件id | fileId | String | 32 | M | 文件唯一标识号，查询接口返回 |
| 2 | Sm4加密key | sm4Key | String | 16 | M | 对账文件sm4加密的密钥 |

#### 响应报文

响应体类型：application/octet-stream

签名（signature）：http响应头里，对文件base64编码，sm4加密后的字符串，sm3摘要值。

### 信用卡积分明细查询（分类）

接口名：points.queryTranDetailByType

说明：客户通过积分商城调用该接口，按获得、使用或者全部等分类查询相关积分交易明细信息。

#### 请求报文

表 6\-6 信用卡积分明细查询接口请求报文

| 序号 | 中文名称 | 变量名 | 类型 | 长度 | 必输 | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | 业务主ID | busiMainId | String | 24 | M | 规则同合作方交易流水号 |
| 2 | 交易时间 | reqTransTime | String | 14 | M | yyyyMMddHHmmss（用户发起时间） |
| 3 | 卡号 | cardNo | String | 20 | C | 卡号和客户三要素二选一上送 |
| 4 | 明细类型 | detailType | String | 1 | C | 默认全部；<br>0-全部，1-已获得，2-已使用 |
| 5 | 积分类型 | pointType | String | 2 | C | 默认普通积分；<br>01-普通积分，02-权益积分，03-公益积分，04-里程积分，05-华润通积分，06-美团零花 |
| 6 | 当前页码数 | page | int |  | C | 可选，默认1 |
| 7 | 每页记录行数 | pageSize | int |  | C | 可选，默认10 |
| 8 | 查询起始时间 | begDt | String | 8 | M | yyyyMMdd |
| 9 | 查询结束时间 | endDt | String | 8 | M | yyyyMMdd |
| 10 | 客户姓名 | custName | String | 40 | C | 客户三要素 |
| 11 | 证件类型 | personalCertTypeCode | String | 2 | C | 客户三要素 |
| 12 | 证件号码 | personalCertNo | string | 18 | C | 客户三要素 |

#### 响应报文

表 6\-7 信用卡积分明细查询接口响应报文

| 序号 | 中文名称 | 变量名 | 类型 | 长度 | 必输 | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | 返回码 | respCode | String | 6 | M |  |
| 2 | 返回信息 | respMsg | String | 255 | M |  |
| 3 | 卡号 | cardNo | String | 20 | C |  |
| 4 | 积分类型 | pointType | String | 2 | C |  |
| 5 | 当前页码数 | page | int | 17 | M |  |
| 6 | 每页记录行数 | pageRows | int |  | M |  |
| 7 | 总条目数 | total | long |  | M |  |
| 8 | 明细信息 | tranInfo | list |  | C |  |
| 8.1 | 交易日期 | tranDt | String | 8 | C | yyyyMMdd |
| 8.2 | 交易积分值 | tranPoints | long | 9 | C |  |
| 8.3 | 交易金额 | tranAmt | bigDecimal | 20 | C |  |
| 8.4 | 交易描述 | tranDesc | String | 100 | C |  |
| 8.5 | 卡号后4位 | cardNo | String | 4 | C |  |

### 高端客户权益积分服务预约、取消、完成接口

接口名：points.rightPointsTran

说明：客户可调用权益积分服务接口实现对个人权益积分服务的预约、取消或完成功能。该接口请求头中的partnerTxSriNo字段长度18位，生成规则为：渠道号+交易日期8位+自己定义8位，每次交易确保唯一。

#### 请求报文

表 6\-8 高端客户权益积分服务预约、取消、完成接口请求报文

| 序号 | 中文名称 | 变量名 | 类型 | 长度 | 必输 | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | 业务主ID | busiMainId | String | 24 | M | 规则同合作方交易流水号 |
| 2 | 交易时间 | reqTransTime | String | 14 | M | yyyyMMddHHmmss（用户发起时间） |
| 3 | 渠道标识 | tranChnl | String | 2 | M | 12\-手机银行，17\-电话银行，18\-微信银行（请求头中的partnerTxSriNo生成规则的渠道号和渠道标识相同） |
| 4 | 客户名称 | custName | String | 40 | C | 客户编号和客户三要素二选一（仅限电话银行渠道）<br>客户信息和兑换权益码二选一（仅限电话银行渠道预约） |
| 5 | 客户编号 | cstmId | String | 32 | C |
| 6 | 证件类型 | personalCertTypeCode | String | 2 | C |
| 7 | 证件号码 | personalCertNo | String | 30 | C |
| 8 | 兑换预约码 | rightsCode | String | 32 | C/M | 预约类型：客户信息和兑换权益码二选一（仅限电话银行渠道，其他渠道必输）<br>取消、完成类型：输入项必输<br>接口返回：输出项必输<br>例：<br>16800G-VN4724-NX874-30VHR |
| 9 | 操作类型 | optType | String | 32 | M | 200-预约，300\-完成，400\-取消 |
| 10 | 服务类型 | ServiceType | String | 6 | M | 210001\-口腔护理<br>210002\-三个月血糖管理<br>210003\-三个月血压管理<br>210004\-三个月体重管理<br>220001\-高铁贵宾厅<br>220002\-机场贵宾厅<br>220003\-洗车<br>1200\-机场快速通道<br>1400\-专车服务（舒适型30公里）<br>1410\-专车服务（商务型30公里）<br>1420\-专车服务（舒适型50公里）<br>1430\-专车服务（商务型50公里）<br>1500\-代驾服务（20公里及以内） |
| 11 | 服务厂商编号 | providerCode | String | 4 | M | 示例：<br>A101-盛大<br>B101-元化 |
| 12 | 实际完成时间 | completionTime | String | 14 | C/M | 完成操作时必输。yyyyMMddHHmmss |

#### 响应报文

表 6\-9 高端客户权益积分服务预约、取消、完成接口响应报文

| 序号 | 中文名称 | 变量名 | 类型 | 长度 | 必输 | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | 返回码 | respCode | String | 6 | M |  |
| 2 | 返回信息 | respMsg | String | 255 | M |  |
| 3 | 兑换预约码 | rightsCode | String | 32 | C |  |
| 4 | 业务响应码 | tradeRespCode | String | 6 | M |  |
| 5 | 业务响应码描述 | tradeRespMsg | String | 255 | M |  |

### 高端客户权益积分预约服务状态查询接口

接口名：points.rightPointsTranQueryState

说明：实现了客户通过兑换权益码查询权益积分预约服务状态的功能。该接口请求头中的partnerTxSriNo字段长度18位，生成规则为：渠道号+交易日期8位+自己定义8位，每次交易确保唯一。

#### 请求报文

表 6\-10 高端客户权益积分预约服务状态查询接口请求报文

| 序号 | 中文名称 | 变量名 | 类型 | 长度 | 必输 | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | 业务主ID | busiMainId | String | 24 | M | 规则同合作方交易流水号 |
| 2 | 交易时间 | reqTransTime | String | 14 | M | yyyyMMddHHmmss（用户发起时间） |
| 3 | 渠道标识 | tranChnl | String | 2 | M | 12\-手机银行，17\-电话银行，18\-微信银行，36\-you生活（请求头中的partnerTxSriNo生成规则的渠道号和渠道标识相同） |
| 4 | 兑换权益码 | rightsCode | String | 32 | M |  |

#### 响应报文

表 6\-11 高端客户权益积分预约服务状态查询接口响应报文

| 序号 | 中文名称 | 变量名 | 类型 | 长度 | 必输 | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | 返回码 | respCode | String | 6 | M |  |
| 2 | 返回信息 | respMsg | String | 255 | M |  |
| 3 | 预约服务状态 | serviceStateMsg | String | 12 | M |  |
| 4 | 预约服务状态码 | serviceState | String | 3 | M | 100-服务未预约<br>200\-服务已预约<br>300\-服务已完成<br>400\-服务已取消<br>500\-服务已过期 |
| 5 | 业务响应码 | tradeRespCode | String | 6 | M |  |
| 6 | 业务响应码描述 | tradeRespMsg | String | 255 | M |  |

### 服务商对账单文件查询接口

接口名：ufile.query.commonQuery

说明：实现了客户通过文件接口名和会计日期查询对账单文件功能，其中文件接口名是固定的，每一类文件都对应一个文件接口名，具体值见下表。

#### 请求报文

表 6\-12 通用文件查询接口请求报文

| 序号 | 中文名称 | 变量名 | 类型 | 长度 | 必输 | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | 会计日期 | accountingDate | String | 8 | M | YYYYMMDD |
| 2 | 文件接口名 | fileIntfcName | String | 64 | M | 由积分老师提供 |

#### 响应报文

表 6\-13 通用文件查询接口响应报文

| 序号 | 中文名称 | 变量名 | 类型 | 长度 | 必输 | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | 响应码 | respCode | String | 6 | M | 000000表示成功，其他错误码参考附录A |
| 2 | 响应信息 | respMsg | String | 255 | M |  |
| 3 | 文件信息列表 | files | list | \- | M |  |
| 3.1 | 文件id | fileId | String | 32 | M | 文件唯一标识 |
| 3.2 | 文件数据名称 | dataName | String |  | O | 文件数据名称 |
| 3.3 | 区域编码 | areaCode | String | 4 | O | 默认0000 |
| 3.4 | 会计日期 | accountingDate | String | 8 | O | YYYYMMDD |
| 3.5 | 处理类型 | hanType | String | 1 | O | Z：表示初始数据；A：表示增量数据；I：表示全量数据。 |
| 3.6 | 批次号 | fileTachNo | String | 4 | O | 示例：0001 |
| 3.7 | 文件序号 | fileNo | String | 4 | O | 示例：0001 |
| 3.8 | 文件数据名称扩展 | dataNameExt | String |  | O | 文件数据名称扩展，当一个文件接口包含多个dataName一样，且业务含义不一样的文件使用。 |

### 服务商对账单文件下载接口

接口名：ufile.download.commonDownload

说明：实现了客户通过文件接口名和文件id下载对账单文件功能，其中文件接口名是固定的，每一类文件都对应一个文件接口名，具体值见下表。

#### 请求报文

表 6\-14 通用文件查询接口请求报文

| 序号 | 中文名称 | 变量名 | 类型 | 长度 | 必输 | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | 文件id | fileId | String | 32 | M | 文件唯一标识号，查询接口返回。 |
| 2 | 文件接口名 | fileIntfcName | String | 64 | M | 由积分老师提供 |
| 3 | sm4加密key | sm4Key | String | 16 | M | 对账文件sm4加密的密钥 |

#### 响应报文

响应体类型：application/octet-stream

签名(signature)：http响应头里，对文件base64编码，sm4加密后的字符串，sm3摘要值。

#### 文件内容

表 6\-15 盛大服务商对账单文件内容

| 序号 | 中文名称 | 变量名 | 类型 | 长度 | 必输 | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | 统计月份 | \- | String | 8 | M | YYYYMMDD |
| 2 | 一分机构序号 | \- | String | 8 | M |  |
| 3 | 一分机构名称 | \- | String | 100 | M |  |
| 4 | 网点机构属性 | \- | String | 2 | C | 01-自营 02-代理 |
| 5 | 积分客户服务编码 | \- | String | 6 | C |  |
| 6 | 服务内容 | \- | String | 200 | M |  |
| 7 | 预约时间 | \- | String | 14 | C |  |
| 8 | 实际完成时间 | \- | String | 14 | C |  |
| 9 | 权益兑换码 | \- | String | 14 | O |  |

### 高端客户权益积分根据权益码订单详情查询

接口名：points.queryOrderInfoByRightCode

说明：用于服务商根据权益码查询所属机构、服务信息、服务商信息。该接口请求头中的partnerTxSriNo字段生成规则需要单独注意，生成规则为：渠道号2位+交易日期8位+8位数字，每次交易确保唯一

#### 请求报文

表 6\-15 高端客户权益积分根据权益码订单详情查询请求报文

| 序号 | 中文名称 | 变量名 | 类型 | 长度 | 必输 | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | 业务主ID | busiMainId | String | 24 | M | 规则同合作方交易流水号 |
| 2 | 交易时间 | reqTransTime | String | 14 | M | yyyyMMddHHmmss（用户发起时间） |
| 3 | 服务商编号 | eqtyServProvrNo | String | 4 | M | 例如 A101 |
| 4 | 兑换权益码 | rightsCode | String | 32 | M | 兑换权益码 |

#### 响应报文

表 6\-16 高端客户权益积分根据权益码订单详情查询响应报文

| 序号 | 中文名称 | 变量名 | 类型 | 长度 | 必输 | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | 返回码 | respCode | String | 6 | M |  |
| 2 | 返回信息 | respMsg | String | 255 | M |  |
| 3 | 预约服务状态 | serviceState | String | 3 | M | 100-服务未预约<br>200-服务已预约<br>300-服务已完成<br>400-服务已取消<br>500-服务已过期 |
| 4 | 服务商编号 | eqtyServProvrNo | String | 4 | M | 例如 A101 |
| 5 | 权益服务编号 | equityServNo | String | 6 | M | 喜马拉雅VIP巅峰会员季卡-310001<br>知乎会员季卡-310002口腔护理-210001<br>三个月血糖管理-210002 |
| 6 | 权益服务对内名称 | equityServName | String | 30 | M | 该名称是积分系统内部使用的名称，例如 体检服务-元化 |
| 7 | 兑换时间 | consumerTime | String | 14 | M | 兑换时间:yyyyMMddHHmmss |
| 8 | 预约时间 | appointmentTime | String | 14 | M | 预约时间:yyyyMMddHHmmss |
| 9 | 取消时间 | cancelTime | String | 14 | M | 取消时间:yyyyMMddHHmmss |
| 10 | 完成时间 | finishTime | String | 14 | M | 完成时间:yyyyMMddHHmns |
| 11 | 出账状态 | outGoingState | String | 1 | M | 0-未出账<br>1-已出账 |
| 12 | 客户自营代理属性 | instType | String | 2 | M |  |
| 13 | 客户归属机构一分 | brhLv1InstName | String | 50 | M |  |
| 14 | 客户归属机构二分 | brhLv2InstName | String | 50 | M |  |
| 15 | 客户归属机构一支 | subLv1InstName | String | 50 | M |  |
| 16 | 客户归属网点机构 | custInstName | String | 50 | M |  |
| 17 | 出账月份 | outGoingDate | String | 6 | M | 已出账的情况下这个字段有值，未出账为null，出账月份：yyyyMM |

### 高端客户权益订单退还时已过期积分查询

接口名：points.queryReturnOveDuePoints

接口版本：1

说明：用于客户通过服务商对退还或取消服务时，查询该订单总幸福点，已过期幸福点等，若过期幸福点不为0需要进行提醒。

接口地址：普通接口地址

#### 请求报文

表 6\-17 高端客户权益订单退还时已过期积分查询接口请求报文

| 序号 | 中文名称 | 变量名 | 类型 | 长度 | 必输 | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | 业务主ID | busiMainId | String | 24 | M | 规则同合作方交易流水号 |
| 2 | 交易时间 | reqTransTime | String | 14 | M | yyyyMMddHHmmss（用户发起时间） |
| 3 | 客户名称 | cstmName | String | 40 | C | 已兑换未预约取消：客户三要素和客户编号二选一必输<br>已预约取消场景：客户三要素和客户编号为非必输 |
| 4 | 证件类型 | paperType | String | 2 | C |
| 5 | 证件号码 | paperId | String | 30 | C |
| 6 | 客户编号 | cstmId | String | 32 | C |
| 7 | 原交易流水号 | orgTranSq | String | 18 | C | 已兑换未预约取消场景：原交易流水号必输 |
| 8 | 兑换预约码 | rightsCode | String | 32 | C | 已预约取消场景：兑换预约码必输 |

#### 响应报文

表 6\-18 高端客户权益订单退还时已过期积分查询接口响应报文

| 序号 | 中文名称 | 变量名 | 类型 | 长度 | 必输 | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | 返回码 | respCode | String | 6 | M |  |
| 2 | 返回信息 | respMsg | String | 255 | M |  |
| 3 | 业务主ID | busiMainId | String | 24 | M |  |
| 4 | 交易总幸福点 | tranIntglNum | int | 9 | C | 交易总幸福点<br>返回码为：000000，该字段不为空 |
| 5 | 已过期的幸福点 | ovdueIntglNum | int | 9 | C | 已过期的幸福点，非0时，前端展示提醒<br>返回码为：000000，该字段不为空 |
| 6 | 提醒信息文本 | noticeMsg | String | 999 | C | 提醒信息文本<br>返回码为：000000，该字段不为空 |

# 附录A

## 业务响应码说明

表 7\-1 返回码 

| 业务类型 | 返回码 | 描述 |
| --- | --- | --- |
| 公共响应码 | 000000 | 交易成功（具体交易为准） |
|  | 900000 | 未知系统异常（统一处理） |
|  | 900001 | 非法参数 |
|  | 900002 | 必填参数缺失 |
|  | 900005 | 签名错误 |
|  | 900006 | 请求非法 |
|  | 900008 | 幂等错 |
|  | 900011 | 签名验证失败 |
|  | 063001 | 系统繁忙，请稍后再试（文件） |
|  | 062005 | 查询失败,请稍后再试（文件） |
|  | 990172 | 系统繁忙，请稍后再试 |
|  | 990272 | 系统繁忙，请稍后再试 |
|  | 990772 | 系统繁忙，请稍后再试 |
| 积分相关响应码 | 727102 | 未查询到当前分类的积分信息 |
|  | 727101 | 系统异常，请稍后重试 |
|  | 729928 | 查询起始日期必须在12个月内 |
|  | 729922 | 查询结束时间不得小于查询开始时间 |
|  | 729918 | 不能包含^&<>+^\|?《》... |
|  | 729917 | 长度不符合要求 |
|  | 729910 | 格式不正确 |
|  | 729909 | 不能为空 |
|  | 729904 | 积分账户不存在 |
|  | 721611 | 批调数量错误或超限 |
|  | 721612 | 批调数量与实际数量不一致 |
|  | 729809 | 系统繁忙，请稍后再试 |
|  | 161006 | 交易数据不存在 |
|  | 161008 | 未知渠道错误 |
|  | 161027 | 兑换权益码错误 |
|  | 161026 | 兑换权益码已失效 |
|  | 161024 | 服务未预约，不允许完成或取消操作 |
|  | 161014 | 服务已完成或取消，不允许再操作 |
|  | 161016 | 无权益服务可操作 |
|  | 161033 | 实际完成时间不满足对账规范 |
|  | 729006 | 未找到原交易 |
|  | 729011 | 客户名称不能为空 |
|  | 729012 | 客户证件类型不能为空 |
|  | 729013 | 证件号码不能为空 |
|  | 729024 | 证件号码格式不正确 |
|  | 729033 | 客户编号格式不正确 |
|  | 720502 | 原交易流水号不能为空 |
|  | 720503 | 原交易流水号格式不正确 |