post-bank-point-mall/docs/服务开放平台工程接口设计规范-高端客户权益积分V1.18.md

服务开放平台工程接口设计规范-高端客户权益积分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 2. Content-Type 不是 application/json;charset=UTF-8 3. 请求参数有问题
2	401	未认证	1.未进行身份认证
3	403	禁止访问	1. api对应的产品合约有问题（没合约，或者合约状态有问题） 2. 没有对应资源的访问权限 3. 请求路径有问题，取不到商户号 4. accessToken 信息为空(一般h5 accessToken失效会出此问题) 5. 报文里的商户号和请求地址的商户号不一致（h5时，可能报文里的商户号和accessToken的不一致） 6. 合约校验失败
4	429	请求太多	1.单位时间内请求，超过限流次数
5	500	服务器内部错误	1.请求报文格式有问题 2.加解密签名有问题（使用了和商户平台密钥配对以外的密钥） 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	默认全部； 0-全部，1-已获得，2-已使用
5	积分类型	pointType	String	2	C	默认普通积分； 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	客户编号和客户三要素二选一（仅限电话银行渠道） 客户信息和兑换权益码二选一（仅限电话银行渠道预约）
5	客户编号	cstmId	String	32	C
6	证件类型	personalCertTypeCode	String	2	C
7	证件号码	personalCertNo	String	30	C
8	兑换预约码	rightsCode	String	32	C/M	预约类型：客户信息和兑换权益码二选一（仅限电话银行渠道，其他渠道必输） 取消、完成类型：输入项必输 接口返回：输出项必输 例： 16800G-VN4724-NX874-30VHR
9	操作类型	optType	String	32	M	200-预约，300-完成，400-取消
10	服务类型	ServiceType	String	6	M	210001-口腔护理 210002-三个月血糖管理 210003-三个月血压管理 210004-三个月体重管理 220001-高铁贵宾厅 220002-机场贵宾厅 220003-洗车 1200-机场快速通道 1400-专车服务（舒适型30公里） 1410-专车服务（商务型30公里） 1420-专车服务（舒适型50公里） 1430-专车服务（商务型50公里） 1500-代驾服务（20公里及以内）
11	服务厂商编号	providerCode	String	4	M	示例： A101-盛大 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-服务未预约 200-服务已预约 300-服务已完成 400-服务已取消 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-服务未预约 200-服务已预约 300-服务已完成 400-服务已取消 500-服务已过期
4	服务商编号	eqtyServProvrNo	String	4	M	例如 A101
5	权益服务编号	equityServNo	String	6	M	喜马拉雅VIP巅峰会员季卡-310001 知乎会员季卡-310002口腔护理-210001 三个月血糖管理-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-未出账 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	已兑换未预约取消：客户三要素和客户编号二选一必输 已预约取消场景：客户三要素和客户编号为非必输
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	交易总幸福点 返回码为：000000，该字段不为空
5	已过期的幸福点	ovdueIntglNum	int	9	C	已过期的幸福点，非0时，前端展示提醒 返回码为：000000，该字段不为空
6	提醒信息文本	noticeMsg	String	999	C	提醒信息文本 返回码为：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	原交易流水号格式不正确