diff --git a/docs/PSBC_Point_Service.png b/docs/PSBC_Point_Service.png new file mode 100644 index 0000000..db87106 Binary files /dev/null and b/docs/PSBC_Point_Service.png differ diff --git a/docs/sequence-diagrams.puml b/docs/sequence-diagrams.puml new file mode 100644 index 0000000..0df88e2 --- /dev/null +++ b/docs/sequence-diagrams.puml @@ -0,0 +1,481 @@ +@startuml PSBC_Point_Service + +skinparam sequenceMessageAlign center +skinparam responseMessageBelowArrow true +skinparam ParticipantPadding 10 +skinparam BoxPadding 10 + +title 邮储银行幸福点权益服务 - 完整业务流程时序图 + +' ========== 参与者定义 ========== +actor "客户" as Customer +participant "手机银行/\n电话银行" as MobileBank +participant "CRM零售" as CRM +participant "渠道二期" as Channel2 +participant "ESB" as ESB +participant "个人综合\n积分系统" as PointSystem +participant "服务开放\n平台" as OpenPlatform +participant "服务商系统" as ServiceProvider +database "定时任务" as Scheduler +database "对账文件" as ReconFile + +note over PointSystem +权益服务状态码说明 +---- +100 - 服务未预约 +200 - 服务已预约 +300 - 服务已完成 +400 - 服务已取消 +500 - 服务已过期 +end note + +' ==================== 流程1: 服务兑换流程 ==================== +== 流程1: 服务兑换流程 == + +note over Customer, PointSystem +业务说明: 客户通过渠道兑换权益服务，扣除幸福点，获取权益码 +前置条件: 客户为高端客户(AUM>=50W) +end note + +group 链路A: 手机银行/电话银行渠道 + Customer -> MobileBank: 1.选择权益服务发起兑换 + activate MobileBank + + MobileBank -> Channel2: 2.调用渠道二期转发请求 + activate Channel2 + + Channel2 -> ESB: 3.转发至ESB总线 + activate ESB + + ESB -> PointSystem: 4.调用积分系统兑换接口 + activate PointSystem + + PointSystem -> PointSystem: 5.校验客户幸福点余额 + PointSystem -> PointSystem: 6.扣除客户幸福点 + PointSystem -> PointSystem: 7.状态:未预约(100) + + PointSystem --> ESB: 8.返回兑换结果 + deactivate PointSystem + + ESB --> Channel2: 9.返回结果 + deactivate ESB + + Channel2 --> MobileBank: 10.返回结果 + deactivate Channel2 + + MobileBank --> Customer: 11.显示兑换成功 + deactivate MobileBank +end + +group 链路B: CRM零售渠道(不经过渠道二期) + Customer -> CRM: 1.理财经理为客户发起兑换 + activate CRM + + CRM -> ESB: 2.直接调用ESB总线 + activate ESB + + ESB -> PointSystem: 3.调用积分系统兑换接口 + activate PointSystem + + PointSystem -> PointSystem: 4.校验客户幸福点余额 + PointSystem -> PointSystem: 5.扣除客户幸福点 + PointSystem -> PointSystem: 6.状态:未预约(100) + + PointSystem --> ESB: 7.返回兑换结果 + deactivate PointSystem + + ESB --> CRM: 8.返回结果 + deactivate ESB + + CRM -> CRM: 9.生成二维码供客户扫描 + CRM --> Customer: 10.展示二维码 + deactivate CRM +end + +' ==================== 流程2: 服务预约使用流程 ==================== +== 流程2: 服务预约使用流程 == + +note over Customer, ServiceProvider +业务说明: 客户使用权益码预约服务商提供的服务 +关键规则: 权益码20分钟内有效，超时需重新生成 +end note + +group 手机银行渠道预约 + Customer -> MobileBank: 1.进入权益使用页面 + activate MobileBank + + MobileBank -> PointSystem: 2.调用积分系统生成服务使用链接 + activate PointSystem + PointSystem -> PointSystem: 3.生成加密链接\n【权益码+服务类型AES加密】\n【有效期20分钟】 + PointSystem --> MobileBank: 4.返回加密链接 + deactivate PointSystem + + MobileBank --> Customer: 5.跳转服务商页面(携带加密参数) + deactivate MobileBank +end + +group CRM零售渠道预约 + Customer -> CRM: 1.理财经理为客户发起预约 + activate CRM + + CRM -> PointSystem: 2.调用积分系统生成预约链接 + activate PointSystem + PointSystem -> PointSystem: 3.生成加密链接\n【权益码+服务类型AES加密】\n【有效期20分钟】 + PointSystem --> CRM: 4.返回加密链接 + deactivate PointSystem + + CRM -> CRM: 5.将链接转成二维码图片 + CRM --> Customer: 6.展示二维码供客户扫描 + deactivate CRM +end + +group 服务商侧处理 + Customer -> ServiceProvider: 7.点击链接/扫码进入服务商页面\n【request字段携带加密数据】 + activate ServiceProvider + + ServiceProvider -> ServiceProvider: 8.AES解密request字段 + ServiceProvider -> ServiceProvider: 9.获取权益码、服务类型参数 + + Customer -> ServiceProvider: 10.客户点击"使用"按钮 + + ServiceProvider -> OpenPlatform: 11.调用服开平台预约接口 + activate OpenPlatform + + OpenPlatform -> ESB: 12.转发预约请求 + activate ESB + + ESB -> PointSystem: 13.调用积分系统预约接口 + activate PointSystem + + alt 20分钟内完成预约 + PointSystem -> PointSystem: 14.校验权益码有效性 + PointSystem -> PointSystem: 15.更新订单状态\n未预约(100)→已预约(200) + PointSystem --> ESB: 16.返回预约成功 + ESB --> OpenPlatform: 17.返回成功 + OpenPlatform --> ServiceProvider: 18.返回预约成功 + ServiceProvider --> Customer: 19.显示预约成功 + else 超过20分钟权益码失效 + PointSystem --> ESB: 权益码已失效 + ESB --> OpenPlatform: 返回失败 + OpenPlatform --> ServiceProvider: 返回失败 + + alt 手机银行/电话银行渠道 + ServiceProvider --> Customer: 提示"当前页面停留时间过长，\n请您重新进入该页面" + else CRM渠道 + ServiceProvider --> Customer: 提示"二维码20分钟内有效，\n现已超时失效，\n请联系理财经理重新生成二维码！" + end + + note right: 超时后需重新走流程1-6\n生成新的20分钟有效权益码 + end + deactivate PointSystem + deactivate ESB + deactivate OpenPlatform + deactivate ServiceProvider +end + +' ==================== 流程3: 服务取消流程(已预约) ==================== +== 流程3: 服务取消流程(已预约) == + +note over Customer, ServiceProvider +业务说明: 客户取消已预约的服务 +关键规则: 取消前需查询是否有过期幸福点并提示客户 +状态变更: 已预约(200) → 已取消(400) +end note + +Customer -> MobileBank: 1.发起服务取消 +activate MobileBank + +MobileBank -> PointSystem: 2.调用积分系统生成取消链接 +activate PointSystem +PointSystem -> PointSystem: 3.生成加密链接\n【权益码+服务类型AES加密放入request】 +PointSystem --> MobileBank: 4.返回加密链接 +deactivate PointSystem + +MobileBank --> Customer: 5.跳转服务商取消页面 +deactivate MobileBank + +Customer -> ServiceProvider: 6.进入服务商取消页面 +activate ServiceProvider + +ServiceProvider -> ServiceProvider: 7.AES解密request字段\n获取权益码、服务类型 + +ServiceProvider -> OpenPlatform: 8.查询订单过期幸福点情况 +activate OpenPlatform + +OpenPlatform -> ESB: 9.转发查询请求 +activate ESB + +ESB -> PointSystem: 10.查询订单幸福点过期情况 +activate PointSystem +PointSystem --> ESB: 11.返回过期幸福点信息 +deactivate PointSystem + +ESB --> OpenPlatform: 12.返回查询结果 +deactivate ESB + +OpenPlatform --> ServiceProvider: 13.返回过期信息 +deactivate OpenPlatform + +alt 存在过期幸福点 + ServiceProvider --> Customer: 14.提示"存在已过期幸福点，\n取消后只退还未过期部分，\n是否继续取消？" + + alt 客户放弃取消 + Customer -> ServiceProvider: 放弃取消 + ServiceProvider --> Customer: 返回服务详情页 + else 客户坚持取消 + Customer -> ServiceProvider: 确认取消 + + ServiceProvider -> OpenPlatform: 15.调用积分系统取消接口 + activate OpenPlatform + + OpenPlatform -> ESB: 16.转发取消请求 + activate ESB + + ESB -> PointSystem: 17.调用取消接口 + activate PointSystem + + PointSystem -> PointSystem: 18.返还未过期幸福点给客户 + PointSystem -> PointSystem: 19.更新订单状态\n已预约(200)→已取消(400) + PointSystem --> ESB: 20.返回取消成功 + deactivate PointSystem + + ESB --> OpenPlatform: 21.返回结果 + deactivate ESB + + OpenPlatform --> ServiceProvider: 22.返回取消成功 + deactivate OpenPlatform + + ServiceProvider --> Customer: 23.显示取消成功\n已退还XX幸福点 + end +else 不存在过期幸福点 + ServiceProvider -> OpenPlatform: 14.直接调用取消接口 + activate OpenPlatform + + OpenPlatform -> ESB: 15.转发取消请求 + activate ESB + + ESB -> PointSystem: 16.调用取消接口 + activate PointSystem + + PointSystem -> PointSystem: 17.返还全部幸福点给客户 + PointSystem -> PointSystem: 18.更新订单状态\n已预约(200)→已取消(400) + PointSystem --> ESB: 19.返回取消成功 + deactivate PointSystem + + ESB --> OpenPlatform: 20.返回结果 + deactivate ESB + + OpenPlatform --> ServiceProvider: 21.返回取消成功 + deactivate OpenPlatform + + ServiceProvider --> Customer: 22.显示取消成功\n已退还全部幸福点 +end +deactivate ServiceProvider + +' ==================== 流程4: 服务退还流程(未预约使用) - 行内实现 ==================== +== 流程4: 服务退还流程(未预约使用) 【行内实现】 == + +note over Customer, PointSystem +业务说明: 客户退还未预约使用的权益服务 +关键规则: 存在过期幸福点时只退还未过期部分 +状态变更: 未预约(100) → 已取消(400) +---- +【行内实现】不经过服务商，直接在手机银行/CRM完成 +end note + +Customer -> MobileBank: 1.发起服务退还申请 +activate MobileBank + +MobileBank -> PointSystem: 2.查询订单是否有过期幸福点 +activate PointSystem +PointSystem --> MobileBank: 3.返回过期幸福点信息 +deactivate PointSystem + +alt 存在过期幸福点 + MobileBank --> Customer: 4.提示"存在已过期幸福点XX，\n只能退还未过期幸福点YY，\n是否继续？" + + alt 客户确认退还 + Customer -> MobileBank: 确认退还 + else 客户取消操作 + Customer -> MobileBank: 取消操作 + MobileBank --> Customer: 返回服务详情页 + end +end + +MobileBank -> PointSystem: 5.调用积分系统退还接口 +activate PointSystem + +PointSystem -> PointSystem: 6.退还幸福点给客户\n(只退还未过期部分) +PointSystem -> PointSystem: 7.更新订单状态\n未预约(100)→已取消(400) +PointSystem --> MobileBank: 8.返回退还成功(退还数量) +deactivate PointSystem + +MobileBank --> Customer: 9.显示退还成功\n已退还XX幸福点 +deactivate MobileBank + +' ==================== 流程5: 服务完成流程 ==================== +== 流程5: 服务完成流程 == + +note over ServiceProvider, PointSystem +业务说明: 服务商完成服务后通知银行系统 +关键规则: +1. 服务完成状态更新要求T+2日时效 +2. 完成状态不支持取消，取消状态不支持完成 +状态变更: 已预约(200) → 已完成(300) +end note + +ServiceProvider -> ServiceProvider: 1.服务商为客户完成服务 +activate ServiceProvider + +ServiceProvider -> OpenPlatform: 2.后台调用服开平台\n请求服务完成 +activate OpenPlatform + +OpenPlatform -> ESB: 3.转发完成请求 +activate ESB + +ESB -> PointSystem: 4.调用积分系统服务完成接口 +activate PointSystem + +alt 订单状态为已预约(200) + PointSystem -> PointSystem: 5.校验订单状态 + PointSystem -> PointSystem: 6.更新订单状态\n已预约(200)→已完成(300) + PointSystem --> ESB: 7.返回完成成功 +else 订单状态为已取消(400) + PointSystem --> ESB: 返回失败\n"订单已取消，不支持完成操作" +else 订单状态为已完成(300) + PointSystem --> ESB: 返回失败\n"订单已完成，请勿重复操作" +end +deactivate PointSystem + +ESB --> OpenPlatform: 8.返回结果 +deactivate ESB + +OpenPlatform --> ServiceProvider: 9.返回完成结果 +deactivate OpenPlatform + +ServiceProvider -> ServiceProvider: 10.记录完成状态 +deactivate ServiceProvider + +note right +重要提醒 +---- +1. 服务完成后订单进入对账阶段 +2. 完成状态不可逆，无法取消 +3. 需在T+2日内完成状态更新 +end note + +' ==================== 流程6: 服务兑换过期处理流程 ==================== +== 流程6: 服务兑换过期处理流程 == + +note over Scheduler, PointSystem +业务说明: 系统自动处理超过90天未预约使用的订单 +关键规则: +1. 超过90天未预约自动过期 +2. 只返还未过期的幸福点 +3. 服务一旦预约，权益码永久有效(不会过期) +状态变更: 未预约(100) → 已过期(500) +end note + +Scheduler -> Scheduler: 1.定时任务触发\n(检测超过90天未预约订单) +activate Scheduler + +Scheduler -> PointSystem: 2.扫描过期订单 +activate PointSystem + +PointSystem -> PointSystem: 3.查询兑换超过90天\n且状态为未预约(100)的订单 + +loop 遍历每笔过期订单 + PointSystem -> PointSystem: 4.判断订单幸福点过期情况 + + alt 存在幸福点已过期 + PointSystem -> PointSystem: 5.计算未过期幸福点数量 + PointSystem -> PointSystem: 6.返还未过期幸福点给客户 + PointSystem -> PointSystem: 7.更新订单状态\n未预约(100)→已过期(500) + PointSystem -> PointSystem: 8.记录已过期幸福点数量(不退还) + else 幸福点全部未过期 + PointSystem -> PointSystem: 5.返还全部幸福点给客户 + PointSystem -> PointSystem: 6.更新订单状态\n未预约(100)→已过期(500) + end +end + +PointSystem --> Scheduler: 9.返回处理结果 +deactivate PointSystem + +Scheduler -> Scheduler: 10.记录处理日志 +deactivate Scheduler + +note right +特别说明 +---- +服务一旦预约(状态200)，权益码永久有效 +过期处理只针对"未预约(100)"状态的订单 +end note + +' ==================== 流程7: 服务对账流程 ==================== +== 流程7: 服务对账流程 == + +note over PointSystem, ServiceProvider +业务说明: 每月生成对账文件供服务商下载核对 +规则: +1. 每月3号生成上月对账文件 +2. 只包含服务完成(300)状态的订单 +示例: 服务完成时间202512210000 → 对账月份2025年12月 → 2026年1月3日推送 +end note + +Scheduler -> Scheduler: 1.每月3号定时任务触发 +activate Scheduler + +Scheduler -> PointSystem: 2.触发生成对账文件 +activate PointSystem + +PointSystem -> PointSystem: 3.筛选上月服务完成(300)\n状态的权益订单 + +PointSystem -> PointSystem: 4.汇总订单数据\n(权益码、服务类型、完成时间、金额等) + +PointSystem -> ReconFile: 5.生成对账文件 +activate ReconFile + +PointSystem --> Scheduler: 6.返回生成成功 +deactivate PointSystem +deactivate Scheduler + +note over ReconFile: 对账文件已生成\n等待服务商下载 + +ServiceProvider -> OpenPlatform: 7.调用服开查询文件接口 +activate ServiceProvider +activate OpenPlatform + +OpenPlatform -> ReconFile: 8.查询对账文件列表 + +ReconFile --> OpenPlatform: 9.返回文件列表\n(文件名、生成时间、文件大小) + +OpenPlatform --> ServiceProvider: 10.返回文件列表 +deactivate OpenPlatform + +ServiceProvider -> OpenPlatform: 11.调用文件下载接口\n(指定文件名) +activate OpenPlatform + +OpenPlatform -> ReconFile: 12.下载指定对账文件 + +ReconFile --> OpenPlatform: 13.返回文件内容 +deactivate ReconFile + +OpenPlatform --> ServiceProvider: 14.返回对账文件 +deactivate OpenPlatform + +ServiceProvider -> ServiceProvider: 15.解析对账文件 +ServiceProvider -> ServiceProvider: 16.与本地订单数据核对 +ServiceProvider -> ServiceProvider: 17.生成对账结果报告 +deactivate ServiceProvider + +note right +对账文件内容 +---- +- 权益码 +- 服务类型 +- 服务完成时间 +- 结算金额 +- 客户信息(脱敏) +end note + +@enduml diff --git a/docs/服务开放平台工程接口设计规范-高端客户权益积分V1.18.docx b/docs/服务开放平台工程接口设计规范-高端客户权益积分V1.18.docx new file mode 100644 index 0000000..38d779e Binary files /dev/null and b/docs/服务开放平台工程接口设计规范-高端客户权益积分V1.18.docx differ diff --git a/docs/服务开放平台工程接口设计规范-高端客户权益积分V1.18.md b/docs/服务开放平台工程接口设计规范-高端客户权益积分V1.18.md new file mode 100644 index 0000000..e09d909 --- /dev/null +++ b/docs/服务开放平台工程接口设计规范-高端客户权益积分V1.18.md @@ -0,0 +1,714 @@ +# 服务开放平台工程接口设计规范-高端客户权益积分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 | 原交易流水号格式不正确 | \ No newline at end of file diff --git a/docs/蓝色兄弟营销开放API.md b/docs/蓝色兄弟营销开放API.md new file mode 100644 index 0000000..dcacdb8 --- /dev/null +++ b/docs/蓝色兄弟营销开放API.md @@ -0,0 +1,410 @@ +# 蓝色兄弟营销开放API + +## 接入流程 + +1.  **注册开发应用账号**：联系平台商务或技术支持，提交接入申请。 + +2.  **获取API密钥**：创建应用成功后，可以在应用详情页获取到API密钥，密钥生成sdk中有集成。 + +3.  **阅读接口文档**：仔细阅读本文档中的API接口说明，了解如何使用API。 + +4.  **集成API**：根据接口文档，将API集成到你的应用中。 + +5.  **测试与验证**：在正式使用前，进行充分的测试以确保API的正确性和稳定性。 + +### 环境配置 + +测试环境地址：https://gateway.dev.cdlsxd.cn + +正式环境地址：https://market.api.86698.cn + +### 测试参数 + +```YAML +#客户应用id +app_id: "OP001" +#应用客户私钥，正式使用请客户自行保存好私钥，将公钥给到平台 +private_key: "xxx" +#应用平台公钥，用于回调验签等 +public_key: "xxx" +#业务参数加密key +key: "xxxx" +#活动编号 串码-1734342908 链接-1742884852 +activity_no: "xxxx" +#签名类型RSA/SM，目前只开放RSA +sign_type: "RSA" +``` + +## 概述 + +### 业务参数 + +```Plain +将业务参数去掉“零”值的参数再由小到大按照字母排序再转成json字符串得到plaintext +再使用应用key将plaintext字符串加密[aes/sm4]得到加密业务参数ciphertext +``` + +### 签名规则 + +```Plain +拼接签名字符串：分配给开发者的应用ID + 发送请求的时间 + 加密业务参数 +使用私钥将拼接待签名字符串生成签名字符串 +``` + +### 回调验签 + +```Plain +获取header头里面的签名信息 +获取body里面的业务参数data +将业务参数data去掉“零”值的参数再由小到大按照字母排序再转成json字符串得到plaintext +再使用应用key将plaintext字符串加密[aes/sm4]得到加密得到ciphertext +拼接签名字符串：分配给开发者的应用ID + 发送请求的时间 + ciphertext +使用应用公钥验签 +``` + +备注：相关业务参数加密规则，验签demo等请联系平台技术人员 + +### SDK + +开发者可参考该sdk + +```markdown +// go +gitee.com/lansexiongdi/ymt +// Java +https://codeup.aliyun.com/lsxd/marketing/ymt-openapi-java-sdk.git +``` + +### 公共headers请求参数 + +| **字段名称** | **类型** | **描述** | **示例值** | +| --- | --- | --- | --- | +| Appid | string | 分配给开发者的应用ID | 123456 | +| Sign-type | string | 签名类型RSA/SM目前暂支持RSA | RSA | +| Timestamp | string | 发送请求的时间，格式"yyyy-MM-dd HH:mm:ss" | 2014-07-24 03:07:50 | +| Sign | string | 商户请求参数的签名串 | 详见sdk示例 | + +#### 公共headers请求参数示例 + +```json +{ + "Sign": ["签名字符串"], + "Appid": ["应用ID"], + "Sign-Type": ["签名类型"], + "Timestamp": ["请求时间"], + "Content-Type": ["请求数据格式"] +} +``` + +### 公共请求参数 + +| ciphertext | string | 请求参数的集合加密字符串 | 详见sdk示例 | +| --- | --- | --- | --- | + +### 公共响应参数 + +| **字段名称** | **类型** | **描述** | +| --- | --- | --- | +| code | int32 | 200成功 | +| message | string | 请求描述 | +| reason | string | 错误原因，错误是返回 | +| data | object | 业务响应参数，成功时返回 | + +### 公共错误码 + +| code**状态码** | **reason** | **错误原因** | **解决** | +| --- | --- | --- | --- | +| 500 | PANIC/其它 | 系统错误 | 联系平台处理 | +| 400 | SIGNATURE\_FAIL | 签名错误 | 请检查应用签名密钥是否正确 | +| | SDK\_INI\_FAIL | sdk错误 | 请检查应用配置信息是否完整 | +| | PARAM\_FAIL | 参数错误 | 请检查业务参数是否正确 | +| | PARAM\_DECRYPT\_FAIL | 参数错误 | 请检查业务参数加密是否正确 | + +### 业务错误码\[汇总\] + +备注：若出现其它未知状态码，请联系平台技术人员 + +| code**状态码** | **reason** | **错误原因** | **解决** | +| --- | --- | --- | --- | +| 503 | KEY\_CREATE\_FAIL | 服务端异常 | 联系平台处理 | +| | MERCHANT\_ORDER\_CREATE\_FAIL | 服务端异常 | 联系平台处理 | +| | MERCHANT\_ORDER\_DISCARD\_FAIL | 服务端异常 | 联系平台处理 | +| | MERCHANT\_ORDER\_DISCARD\_MQ\_FAIL | 服务端异常 | 联系平台处理 | +| 401 | ACTIVITY\_NOT\_AUTH | 活动未授权 | 请检查活动授权状态 | +| | MERCHANT\_NOT\_EXIST | 客户不存在 | 请检查客户是否存在 | +| | MERCHANT\_NOT\_AUTH | 客户冻结 | 请检查客户授权状态 | +| | MERCHANT\_APP\_INCOMPLETE | 客户应用配置未完善 | 请检查客户应用配置 | +| | MERCHANT\_APP\_NOT\_AUTH | 应用不存在 | 请检查客户应用授权状态 | +| 403 | ACTIVITY\_EXPIRE | 活动已结束 | 请检查活动是否有效 | +| | ACTIVITY\_NOT\_AUTH | 1、活动已作废
2、活动待审核
3、活动已驳回
4、活动暂停中
5、活动已失效
6、活动编辑中 | 请检查活动状态 | +| | ACTIVITY\_OUT\_OF\_STOCK | 活动Key码剩余量已不足 | 请检查活动key码总量 | +| 404 | KEY\_NOT\_EXIST | key码不存在 | 请检查key码订单是否有误 | +| | ACTIVITY\_NOT\_EXIST | 活动不存在 | 请检查活动编号是否有误 | +| | MERCHANT\_NOT\_EXIST | 客户不存在 | 请检查客户应用app\_id是否有误 | +| | MERCHANT\_APP\_NOT\_EXIST | 客户应用不存在 | 请检查客户应用app\_id是否有误 | +| | MERCHANT\_ORDER\_NOT\_EXIST | 客户key码记录不存在 | 请检查交易号/外部交易号是否有误 | +| | MERCHANT\_APP\_INCOMPLETE | 客户应用信息未完善 | 请检查客户应用信息是否完善 | +| | MERCHANT\_ORDER\_NOT\_EXIST | 1、交易号不存在
2、外部业务号不存在
3、appId不匹配 | 请检查入参请求交易号/业务号 | + +### 获取券码 + +* 请求方式：`POST` + +* Content-Type: application/json + +* 请求路由：/openapi/v1/key/order + + +#### 业务请求参数 + +| **字段名称** | **类型** | **描述** | 是否必填 | **示例值** | +| --- | --- | --- | --- | --- | +| out\_biz\_no | string | 外部业务号 长度2~32位，幂等 | M | 123456 | +| activity\_no | string | 活动编号 长度32位内 | M | 123456 | +| number | int | 数量，只支持1 | M | 1 | +| account | string | 账号，手机号需短信验证才能兑换,卡密/直充账号领取为该账号 | N | 18666666666 | +| notify\_url | string | 回调通知地址 | N | http://notify.com | + +#### 业务响应参数 + +| **字段名称** | **类型** | 是否必填 | **描述** | +| --- | --- | --- | --- | +| out\_biz\_no | string | M | 外部业务号 | +| trade\_no | string | M | 交易号 | +| key | string | N | key码 | +| usable\_num | uint32 | M | 总兑换次数 | +| status | uint8 | M | 状态 1:正常 2:已核销 3:已作废 | +| url | string | N | 短链接，key/url 不会同时为空 | +| valid\_begin\_time | string | M | key码有效期 | +| valid\_end\_time | string | M | key码有效期 | +| usage\_time | string | N | 核销时间，已核销时返回 | +| discard\_time | string | N | 作废时间，作废时返回 | +| usable\_num | uint32 | M | 可兑换次数 | +| account | string | N | 获取券码上报账号 | + +```json +{ + "ciphertext": "HJYByD2RVGJgqaXInWUr3QOWukCwT9x8M6hv0wbRBHs+K1WDZ3axg8/lRubhA==" +} +``` + +#### 响应示例 + +异常 + +```JSON +{ + "code": 404, + "message": "应用不存在", + "reason": "MERCHANT_APP_NOT_EXIST" +} +``` + +成功 + +```JSON +{ + "code": 200, + "data": { + "out_biz_no": "lzm1", + "key": "aZKdU9BymzR6qGRzJM", + "trade_no": "7251449503000383488", + "url": "https://gateway.dev.cdlsxd.cn/yxh5/aZKdU9BymzR6qGRzJM", + "valid_begin_time": "2024-10-14 11:20:01", + "valid_end_time": "2026-04-30 23:59:59", + "status": 1, + "usable_num": 10, + }, + "message": "成功" +} +``` + +#### 接口调用流程 + +![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/1wvqr76d5BB8Oako/img/d0be4d4d-e0da-465e-b250-aa6fd4b295e3.png) + +### 券码查询 + +* 请求方式：`POST` + +* Content-Type: application/json + +* 请求路由：/openapi/v1/key/query + + +#### 业务请求参数 + +| **字段名称** | **类型** | **描述** | 是否必填 | **示例值** | +| --- | --- | --- | --- | --- | +| out\_biz\_no | string | 外部业务号 out\_biz\_no/trade\_no二选一 | N | 123456 | +| trade\_no | string | 交易号 out\_biz\_no/trade\_no二选一, 若不为空则优先使用 | N | 123456 | + +#### 业务响应参数 + +| **字段名称** | **类型** | 是否必填 | **描述** | +| --- | --- | --- | --- | +| out\_biz\_no | string | M | 外部业务号 | +| trade\_no | string | M | 交易号 | +| key | string | N | key码 | +| usable\_num | uint32 | M | 总兑换次数 | +| usage\_num | uint32 | M | 已兑换次数 key码使用后返回 | +| status | uint8 | M | 状态 1:正常 2:已核销 3:已作废4:已过期 | +| url | string | N | 短链接 key/url 不会同时为空 | +| valid\_begin\_time | string | M | key码有效期 | +| valid\_end\_time | string | M | key码有效期 | +| usage\_time | string | N | 最后一次核销时间 | +| discard\_time | string | N | 作废时间 | +| account | string | N | 获取券码上报账号 | + +#### 请求示例 + +```JSON +{ + "ciphertext": "U4EiooGkfS+XqnUPQ/1ZDAxjgCAJap4/vDqRiyfLCdU0Xu1fekAGq8tEPuTtjKyEw==" +} +``` + +#### 响应示例 + +异常 + +```JSON +{ + "code": 404, + "message": "应用不存在", + "reason": "MERCHANT_APP_NOT_EXIST" +} +``` + +成功 + +```JSON +{ + "code": 200, + "data": { + "out_biz_no": "lzm1", + "key": "aZKdU9BymzR6qGRzJM", + "trade_no": "7251449503000383488", + "url": "https://gateway.dev.cdlsxd.cn/yxh5/aZKdU9BymzR6qGRzJM", + "valid_begin_time": "2024-10-14 11:20:01", + "valid_end_time": "2026-04-30 23:59:59", + "status": 1, + "usable_num": 10, + "usage_num": 5, + }, + "message": "成功" +} +``` + +#### 接口调用流程 + +![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/eYVOLw201deRqpz2/img/51fb1bfc-135c-4487-8471-525b62dda557.png) + +### 券码作废 + +* 请求方式：`POST` + +* Content-Type: application/json + +* 请求路由：/openapi/v1/key/discard + +* 只能作废：待使用、已过期券码 + + +#### 业务参数 + +| **字段名称** | **类型** | **描述** | 是否必填 | **示例值** | +| --- | --- | --- | --- | --- | +| out\_biz\_no | string | 外部业务号 out\_biz\_no/trade\_no二选一 | N | 123456 | +| trade\_no | string | 交易号 out\_biz\_no/trade\_no二选一 若不为空，则优先使用 | N | 123456 | + +#### 请求示例 + +```JSON +{ + "ciphertext": "U4EiooGkfS+XqnUPQ/1ZDAxjgCAJap4/vDqRiyfLCdU0Xu1fekAGq8tEPuTtjKyEw==" +} +``` + +#### 响应示例 + +异常 + +```JSON +{ + "code": 404, + "message": "应用不存在", + "reason": "MERCHANT_APP_NOT_EXIST" +} +``` + +成功 + +```JSON +{ + "code": 200, + "data": {}, + "message": "成功" +} +``` + +#### 接口调用流程 + +![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/MAeqxoXVVrPdn8j9/img/ae4e738e-82a9-41e7-b961-3b514c6e2608.png) + +### 券码状态通知 + +* 请求方式：`POST` + +* Content-Type: application/json + +* 通知地址：客户获取券码上报地址，未上报则使用应用设置回调通知地址 + + +#### 公共参数 + +| **字段名称** | **类型** | **描述** | 是否必填 | **示例值** | +| --- | --- | --- | --- | --- | +| data | object | 请求业务参数 | M | 详见请求业务参数 | + +#### 业务参数data + +| **字段名称** | **类型** | 是否必填 | **描述** | +| --- | --- | --- | --- | +| notify\_id | string | M | 回调通知id | +| out\_biz\_no | string | M | 外部业务号 | +| trade\_no | string | M | 交易号 | +| key | string | N | key码 | +| usable\_num | uint32 | M | 总兑换次数 | +| usage\_num | uint32 | M | 已兑换次数 当usable\_num=usage\_num时即为key码次数已使用完 | +| status | uint8 | M | 状态 1:正常 2:已核销 3:已作废 | +| url | string | N | 短链接，key/url 不会同时为空 | +| valid\_begin\_time | string | M | key码有效期 | +| valid\_end\_time | string | M | key码有效期 | +| usage\_time | string | N | 最后一次核销时间，有核销时会返回 | +| discard\_time | string | N | 作废时间，status=3时返回 | +| account | string | N | 获取券码上报账号 | +| order\_info | object | N | 格式{"order\_no":"123456","account":"1866666666","name":"张三"} | + +#### 请求示例 + +```JSON +{ + "data": { + "notify_id": "202603030015", + "out_biz_no": "883382742152257537", + "trade_no": "https://gateway.dev.cdlsxd.cn/yxh5/war3PPmrQzDVKv8M", + ... + } +} +``` + +#### 响应示例 + +#### 响应重试策略 + +```Plain +非成功响应会进行重试，首次间隔120s，第二次后间隔240s，第三次间隔360s，大于5分钟后间隔5分钟，大于10分钟后间隔10分钟,超过120分钟后不再重试通知 +``` + +* 商家/客户收到回调通知后需返回httpCode=200并且字符串"ok"作为响应 \ No newline at end of file