接口文档

doc/建行生活API接口文档.md

@@ -0,0 +1,568 @@
+# 建行生活API接口文档
+
+> 文档版本: v1.1.6
+> 生成时间: 2025-01-21
+> 来源: 建行生活输入通讯报文v1.1.6【最新】.xlsx
+
+---
+
+## 📑 目录
+
+- [1. 修订记录](#1-修订记录)
+- [2. 接口规范](#2-接口规范)
+  - [2.1 公共报文头](#21-公共报文头)
+  - [2.2 通讯地址](#22-通讯地址)
+  - [2.3 接口索引](#23-接口索引)
+- [3. 核心接口](#3-核心接口)
+  - [3.1 A3341TP01 - 服务方订单推送](#31-a3341tp01---服务方订单推送)
+  - [3.2 A3341TP02 - 服务方订单更新](#32-a3341tp02---服务方订单更新)
+  - [3.3 A3341TP03 - 服务方订单查询](#33-a3341tp03---服务方订单查询)
+  - [3.4 A3341TP04 - 服务方订单退款](#34-a3341tp04---服务方订单退款)
+  - [3.5 A3341TP05 - 订单支付权益查询](#35-a3341tp05---订单支付权益查询)
+  - [3.6 A3341TP13 - 服务方订单补充信息](#36-a3341tp13---服务方订单补充信息)
+
+---
+
+## 1. 修订记录
+
+| 修订日期 | 修订内容 | 上线状态 |
+|---------|---------|----------|
+| 2021-11-22 | 接口增加字段PLAT_MCT_ID、增加退款和订单查询接口 | 已上线 |
+| 2022-11-11 | 增加订单子系统新接口 | 已上线 |
+| 2023-03-28 | 订单推送新增GOODS_NM/PLATFORM_POINT两个字段 | 已上线 |
+| 2024-01-24 | 修改报文顺序、内容 | 已上线 |
+| 2024-02-23 | 订单更新新增PLATFORM_POINT、PAY_MODE、GOODS_NM字段 | 已上线 |
+| 2024-02-26 | 增加权益信息查询接口 | 已上线 |
+| 2025-06-09 | 增加SKU_LIST字段 | 待上线 |
+
+---
+
+## 2. 接口规范
+
+### 2.1 公共报文头
+
+#### 请求体（CLD_HEADER）
+
+| 栏位项目名称 | 中文名称 | 栏位属性 | 必须 | 数据项说明 |
+|------------|---------|---------|------|------------|
+| CLD_TX_CHNL | 通讯渠道号 | C | Y | 跟svcid相同，YS44开头的字符串 |
+| CLD_TX_TIME | 通讯时间 | C | Y | yyyyMMddHHmmss（请求通讯时间） |
+| CLD_TX_CODE | 服务ID | C | Y | 如A3341TP01 |
+| CLD_TX_SEQ | 全局事件流水号 | C | Y | 唯一流水号 |
+
+#### 响应体（CLD_HEADER）
+
+| 栏位项目名称 | 中文名称 | 栏位属性 | 必须 | 数据项说明 |
+|------------|---------|---------|------|------------|
+| CLD_TX_CHNL | 通讯渠道号 | C | Y | 跟svcid相同，YS44开头的字符串 |
+| CLD_TX_TIME | 通讯时间 | C | Y | yyyyMMddHHmmss（响应通讯时间） |
+| CLD_TX_CODE | 服务ID | C | Y | 如A3341TP01 |
+| CLD_TX_SEQ | 全局事件流水号 | C | Y | 唯一流水号 |
+| CLD_CODE | 响应码 | C | Y | 详见响应字典 |
+| CLD_DESC | 响应描述 | C | N | 响应描述信息 |
+
+### 2.2 通讯地址
+
+#### UAT 测试环境
+```
+http://128.192.179.60/uat_new/tp_service/txCtrl/server?txcode=XX
+```
+
+#### 生产环境
+```
+https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=XX
+```
+
+> **注意**: XX 为服务ID，每个接口不同
+
+#### 接口地址示例
+
+| 接口 | 服务ID | 完整URL |
+|------|--------|---------|
+| 订单推送 | A3341TP01 | https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP01 |
+| 订单更新 | A3341TP02 | https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP02 |
+| 订单查询 | A3341TP03 | https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP03 |
+| 订单退款 | A3341TP04 | https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP04 |
+| 权益查询 | A3341TP05 | https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP05 |
+| 订单补充信息 | A3341TP13 | https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP13 |
+
+> **提示**: 当调用接口出现404时，请求头中加上：
+> - `Accept: application/json`
+> - `Content-Type: application/json`
+
+### 2.3 接口索引
+
+| 服务码 | 服务名称 | 服务类型 | 版本 | 备注 |
+|--------|---------|---------|------|------|
+| A3341TP01 | 服务方订单推送 | 直接调用 | 01 | 新接口 |
+| A3341TP02 | 服务方订单更新 | 直接调用 | 01 | 新接口 |
+| A3341TP03 | 服务方订单查询 | 直接调用 | 01 | 新接口 |
+| A3341TP04 | 服务方订单退款 | 直接调用 | 01 | 新接口 |
+| A3341TP05 | 订单支付权益查询 | 直接调用 | 01 | 新接口 |
+| A3341TP13 | 服务方订单补充信息 | 直接调用 | 01 | 新接口 |
+
+---
+
+## 3. 核心接口
+
+### 3.1 A3341TP01 - 服务方订单推送
+
+#### 接口说明
+
+| 项目 | 说明 |
+|------|------|
+| **服务码** | A3341TP01 |
+| **服务名称** | 服务方订单推送 |
+| **服务类型** | 直接调用 |
+| **功能描述** | 用户在服务方下单成功后推送，支付时会校验订单信息 |
+| **URL** | https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP01 |
+
+#### 请求参数（CLD_BODY）
+
+| 字段名 | 中文名称 | 数据类型 | 必须 | 说明 |
+|--------|---------|----------|------|------|
+| USER_ID | 客户编号 | varChar(30) | Y | 建行生活的会员编号 |
+| ORDER_ID | 订单编号 | varChar(30) | Y | 用户订单号，建行生活订单列表展示的订单订单号（对应收银台USER_ORDERID字段，支付时会校验订单信息） |
+| ORDER_DT | 订单日期 | Char(14) | Y | yyyyMMddHHmmss |
+| TOTAL_AMT | 订单原金额 | number(15,2) | Y | 第三方原始金额 |
+| PAY_AMT | 订单实际支付金额 | number(15,2) | N | 支付网关支付金额。此处如果为空必须在状态变更时推送 |
+| DISCOUNT_AMT | 第三方平台优惠金额 | number(15,2) | N | 第三方平台优惠金额。此处如果为空必须在状态变更时推送 |
+| DISCOUNT_AMT_DESC | 第三方平台优惠定义 | varChar(1000) | N | 各金额之和等于第三方平台优惠金额，格式：名称=金额\|@\|名称=金额 |
+| ORDER_STATUS | 订单状态 | Char(1) | Y | 0-待支付 1-支付成功 2-已过期 3-支付失败 4-取消 |
+| REFUND_STATUS | 退款状态 | Char(1) | Y | 0-无退款 1-退款申请 2-已退款 3-部分退款 |
+| INV_DT | 订单过期日期 | Char(14) | N | yyyyMMddHHmmss |
+| MCT_NM | 商户名称 | varChar(218) | Y | 商户名称 |
+| CUS_ORDER_URL | 自定义订单链接 | varChar(256) | N | 订单详情地址(需要推送完整的订单详情URL) |
+| OCC_MCT_LOGO_URL | 服务方商户logo图片地址 | varChar(512) | N | 必须以http://或https://开头 |
+| PAY_FLOW_ID | 支付流水号 | varChar(30) | Y | 支付流水号，调用收银台时上送的支付流水号（对应收银台ORDERID字段） |
+| PAY_USER_ID | 支付客户编号 | varChar(30) | N | 支付客户编号 |
+| TOTAL_REFUND_AMT | 累计退款金额 | number(15,2) | N | 若支持多次退款，此次推送的金额为多次退款累计已退金额 |
+| PREFTL_MRCH_ID | 门店商户号 | varChar(50) | N | 999的门店商户号，商户终端对应的建行生活门店编号 |
+| PAY_MRCH_ID | 支付商户号 | Char(15) | Y | 调用收银台时上送的商户号 |
+| PLAT_MCT_ID | 服务商门店编号 | varChar(21) | N | 外部平台商户号，不为空以这个字段为准 |
+| OCCCOUP_DISCOUNT_AMT | 建行专属优惠金额 | number(15,2) | N | 第三方平台的建行专属优惠金额 |
+| OCCCOUP_DISCOUNT_AMT_DESC | 建行专属优惠定义 | varChar(1000) | N | 格式：券实例号=金额\|@\|券实例号=金额 |
+| SPECIAL_STATUS | 特殊附加状态 | Char(5) | N | P0000-正常状态 P0001-待使用 P0002-待审核 P0003-已支付 P0004-待退款 P0005-退款中 P0006-待发货 P0007-已发货 P0008-进行中 P0009-预定中 P0010-预定成功 P0011-预定失败 P0012-已入住 P0013-已离店 P0014-未入住 P0015-配送中 P0016-出券中 |
+| PLAT_ORDER_TYPE | 服务方订单类型 | Char(5) | N | T0000-普通类型 T0001-洗车 T0002-加油 T0003-停车 T0004-修车 T0005-充电 T0006-年检代办 T0007-道路救援 T0008-云南中石油充值 |
+| GOODS_NM | 商品名称 | varChar(200) | N | 用户购买商品名称 |
+| PLATFORM_POINT | 积分值 | number(15,2) | N | 订单使用积分抵扣积分值 |
+| PAY_MODE | 支付方式 | varChar(8) | N | STSL-刷脸 STSK-刷卡 |
+| PLATFORM | 下单场景 | Char(2) | N | 99-建行生活APP 98-微应用 |
+| **SKU_LIST** | **商品信息** | **varchar(3000)** | **N** | **商品信息列表(JSON字符串)，商品售价SKU_SELL_PRICE不能大于商品定价SKU_REF_PRICE** |
+
+#### SKU_LIST 字段说明（JSON数组）
+
+```json
+[
+  {
+    "SKU_NAME": "商品名称",
+    "SKU_REF_PRICE": 15.01,
+    "SKU_NUM": 1,
+    "SKU_SELL_PRICE": 10.01
+  },
+  {
+    "SKU_NAME": "商品名称2",
+    "SKU_REF_PRICE": 15.01,
+    "SKU_NUM": 2,
+    "SKU_SELL_PRICE": 10.01
+  }
+]
+```
+
+| 字段名 | 中文名称 | 数据类型 | 必须 | 说明 |
+|--------|---------|----------|------|------|
+| SKU_NAME | 商品名称 | varChar | Y | 商品名称 |
+| SKU_REF_PRICE | 商品参考价 | number(15,2) | Y | 商品参考价，支持两位小数 |
+| SKU_NUM | 商品数量 | number(11,2) | Y | 商品数量 |
+| SKU_SELL_PRICE | 商品单价 | number(15,2) | Y | 商品单价，支持两位小数 |
+
+#### 响应参数
+
+| 字段名 | 中文名称 | 数据类型 | 必须 | 说明 |
+|--------|---------|----------|------|------|
+| CCB_DISCOUNT_AMT | 建行支付侧优惠金额 | number(15,2) | N | 因业务调整，后续下线字段 |
+| CCB_DISCOUNT_AMT_DESC | 建行支付侧优惠定义 | varChar(1000) | N | 因业务调整，后续下线字段 |
+
+---
+
+### 3.2 A3341TP02 - 服务方订单更新
+
+#### 接口说明
+
+| 项目 | 说明 |
+|------|------|
+| **服务码** | A3341TP02 |
+| **服务名称** | 服务方订单更新 |
+| **服务类型** | 直接调用 |
+| **功能描述** | 在用户订单状态有变动时调用，比如电影出票成功、外卖配送中等 |
+| **URL** | https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP02 |
+| **重要说明** | 通知类型为"支付状态修改"时，支付状态不能为空，退款状态为空；通知类型为"退款状态修改"时，退款状态不能为空，支付状态为空 |
+
+#### 请求参数
+
+| 字段名 | 中文名称 | 数据类型 | 必须 | 说明 |
+|--------|---------|----------|------|------|
+| ORDER_ID | 订单编号 | varChar(30) | Y | 用户订单号（对应收银台USER_ORDERID字段） |
+| INFORM_ID | 通知类型 | Char(1) | Y | 0-支付状态修改 1-退款状态修改 |
+| PAY_STATUS | 支付状态 | Char(1) | N | 0-待支付 1-支付成功 2-已过期 3-支付失败 4-取消 |
+| REFUND_STATUS | 退款状态 | Char(1) | N | 0-无退款 1-退款申请 2-已退款 3-部分退款 |
+| PAY_AMT | 订单实际支付金额 | number(15,2) | N | 订单实际支付金额 |
+| DISCOUNT_AMT | 第三方平台优惠金额 | number(15,2) | N | 第三方平台优惠金额 |
+| DISCOUNT_AMT_DESC | 第三方平台优惠定义 | varChar(1000) | N | 格式：名称=金额\|@\|名称=金额 |
+| CUS_ORDER_URL | 自定义订单链接 | varChar(256) | N | 订单详情地址(需要推送完整的订单详情URL) |
+| OCC_MCT_LOGO_URL | 服务方商户logo图片地址 | varChar(512) | N | http:// 或 https:// 为起始 |
+| PAY_FLOW_ID | 支付流水号 | varChar(30) | Y | 调用收银台时上送的支付流水号（对应收银台ORDERID字段） |
+| PAY_USER_ID | 支付客户编号 | varChar(150) | N | 支付客户编号 |
+| TOTAL_REFUND_AMT | 累计退款金额 | number(15,2) | N | 若支持多次退款，此次推送的金额为多次退款累计已退金额 |
+| PREFTL_MRCH_ID | 门店商户号 | varChar(50) | N | 999的门店商户号 |
+| PAY_MRCH_ID | 支付商户号 | Char(15) | Y | 调用收银台时上送的商户号 |
+| PLAT_MCT_ID | 服务商门店编号 | varChar(21) | N | 外部平台商户号，不为空以这个字段为准 |
+| OCCCOUP_DISCOUNT_AMT | 建行专属优惠金额 | number(15,2) | N | 第三方平台的建行专属优惠金额 |
+| OCCCOUP_DISCOUNT_AMT_DESC | 建行专属优惠定义 | varChar(1000) | N | 格式：券实例号=金额\|@\|券实例号=金额 |
+| SPECIAL_STATUS | 特殊附加状态 | Char(5) | N | 同订单推送 |
+| PLAT_ORDER_TYPE | 服务方订单类型 | Char(5) | N | 同订单推送 |
+| GOODS_NM | 商品名称 | varChar(200) | N | 用户购买商品名称 |
+| PLATFORM_POINT | 积分值 | number(15,2) | N | 订单使用积分抵扣积分值 |
+| PAY_MODE | 支付方式 | varChar(8) | N | STSL-刷脸 STSK-刷卡 |
+| PLATFORM | 下单场景 | Char(2) | N | 99-建行生活APP 98-微应用 |
+| SKU_LIST | 商品信息 | varchar(3000) | N | 商品信息列表(JSON字符串)，格式同订单推送 |
+
+#### 响应参数
+
+| 字段名 | 中文名称 | 数据类型 | 必须 | 说明 |
+|--------|---------|----------|------|------|
+| IS_SUCCESS | 是否更新成功 | Char(1) | Y | 0-否 1-是 |
+| CCB_DISCOUNT_AMT | 建行支付侧优惠金额 | number(15,2) | N | 因业务调整，后续下线字段 |
+| CCB_DISCOUNT_AMT_DESC | 建行支付侧优惠定义 | varChar(1000) | N | 因业务调整，后续下线字段 |
+
+---
+
+### 3.3 A3341TP03 - 服务方订单查询
+
+#### 接口说明
+
+| 项目 | 说明 |
+|------|------|
+| **服务码** | A3341TP03 |
+| **服务名称** | 服务方订单查询 |
+| **服务类型** | 直接调用 |
+| **功能描述** | 订单主动查询，在未收到支付结果通知时使用。查询结果存在延时情况，接口返回未查到可以适当重复查询 |
+| **URL** | https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP03 |
+| **流控限制** | 默认流控值为 100/TPM |
+
+#### 请求参数
+
+| 字段名 | 中文名称 | 数据类型 | 必须 | 说明 |
+|--------|---------|----------|------|------|
+| TX_TYPE | 交易类型 | varChar(1) | Y | 0-支付交易 1-退款交易 a-查询可退款的订单 |
+| TXN_PRD_TPCD | 查询时间范围类型 | varChar(2) | Y | 99-自定义时间段查询 |
+| STDT_TM | 开始日期时间 | Char(14) | N | 查询时间范围类型为99时必输，格式yyyyMMddhhmiss |
+| EDDT_TM | 结束日期时间 | Char(14) | N | 查询时间范围类型为99时必输，格式yyyyMMddhhmiss |
+| ONLN_PY_TXN_ORDR_ID | 订单编号 | varChar(60) | N | 调用收银台时支付流水号，对应字段ORDERID |
+| SCN_IDR | 场景标识 | varChar(3) | N | BHK-本行卡 THK-他行卡 ZFB-支付宝 CFT-微信 |
+| PLAT_MCT_ID | 服务商门店编号 | varChar(21) | N | 外部平台商户号，不为空以这个字段为准 |
+| CUSTOMERID | 商户号 | varChar(21) | N | 建行商户编号，与外部平台商户号不能同时为空 |
+| BRANCHID | 一级分行号 | varChar(9) | N | 商户一级分行号，用建行商户编号时不能为空 |
+| POS_CODE | 柜台号 | varChar(9) | N | 柜台号 |
+| POS_ID | POS终端编号 | varChar(19) | N | POS终端编号 |
+| TXN_STATUS | 交易状态 | varChar(2) | Y | 00-交易成功 01-交易失败 02-不确定 |
+| MSGRP_JRNL_NO | 商户的流水号 | varChar(60) | N | 商户支付流水号或者退款流水号 |
+| PAGE | 当前页次 | number(10) | Y | 当前页次 |
+
+#### 响应参数（摘要）
+
+| 字段名 | 中文名称 | 数据类型 | 必须 | 说明 |
+|--------|---------|----------|------|------|
+| CUR_PAGE | 当前页次 | number(10) | N | 每页最多返回10条记录 |
+| PAGE_COUNT | 总页次 | number(10) | N | 总页次 |
+| ED_CRD_PRTY_IDR_CD | 商户号 | varChar(15) | N | 商户号 |
+| PY_AMT | 支付金额 | number(16,2) | N | 单位：元 |
+| MRCH_RFND_AMT | 商户退款金额 | number(16,2) | N | 单位：元 |
+| LIST | 订单列表 | Array | N | 订单详情列表（见下表） |
+
+#### LIST 数组字段（订单列表）
+
+| 字段名 | 中文名称 | 数据类型 | 说明 |
+|--------|---------|----------|------|
+| ONLN_PY_TXN_ORDR_ID | 订单编号 | varChar(120) | 订单编号 |
+| CLRG_STM_DT_TM | 交易时间 | varChar(14) | 格式yyyyMMddhhmiss |
+| ACQ_FNDS_CLRG_DT | 记账日期 | varChar(8) | 格式yyyyMMdd |
+| ORDR_TM | 原支付订单时间 | varChar(42) | 格式yyyyMMddhhmiss |
+| AHN_TXNAMT | 交易金额 | number(16,2) | 单位：元 |
+| ORDR_PYRFD_AMT | 退款总额 | number(16,2) | 单位：元 |
+| TXN_CLRGAMT | 结算金额 | number(16,2) | 单位：元 |
+| MRCHCMSN_AMT | 手续费金额 | number(16,2) | 单位：元 |
+| ORIG_AMT | 订单金额 | number(16,2) | 单位：元 |
+| DISCOUNT_AMT | 优惠金额 | number(16,2) | 订单金额-交易金额=优惠金额 |
+| RETGDS_ORIG_TXNAMT | 原支付金额 | number(16,2) | 单位：元 |
+| CST_ACCNO | 支付卡号 | varChar(32) | 支付卡号 |
+| CCYCD | 币种 | varChar(3) | 币种 |
+| TXN_STATUS | 交易状态 | varChar(2) | 00-成功 01-失败 02/04-不确定 TO-超时 |
+| ORIOVRLSTTNEV_TRCK_NO | 银行流水号 | varChar(25) | 银行流水号 |
+| MSGRP_JRNL_NO | 商户流水号 | varChar(240) | 退款时商户上送的退款流水号 |
+| PAY_MODE | 支付方式 | Char(3) | BHK-建行 THK-他行 ZFB-支付宝 CFT-微信 |
+
+> **更多字段请参考Excel原文档**
+
+---
+
+### 3.4 A3341TP04 - 服务方订单退款
+
+#### 接口说明
+
+| 项目 | 说明 |
+|------|------|
+| **服务码** | A3341TP04 |
+| **服务名称** | 服务方订单退款 |
+| **服务类型** | 直接调用 |
+| **功能描述** | 订单退款时使用。在退款结果未返回结果时，建议先查询退款结果再做后续处理 |
+| **URL** | https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP04 |
+
+#### 请求参数
+
+| 字段名 | 中文名称 | 数据类型 | 必须 | 说明 |
+|--------|---------|----------|------|------|
+| PLAT_MCT_ID | 服务商门店编号 | varChar(21) | N | 外部平台商户号，不为空以这个字段为准 |
+| CUSTOMERID | 商户号 | varChar(21) | N | 建行商户编号，与外部平台商户号不能同时为空 |
+| BRANCHID | 一级分行号 | varChar(9) | N | 商户一级分行号，用建行商户编号时不能为空 |
+| MONEY | 退款金额 | number(16,2) | Y | 单位：元 |
+| ORDER | 订单号 | varChar(30) | Y | 调用收银台时支付流水号，对应字段ORDERID |
+| STDT_TM | 开始日期时间 | Char(14) | Y | 根据支付时间往前加4小时，格式yyyyMMddhhmiss |
+| EDDT_TM | 结束日期时间 | Char(14) | Y | 根据支付时间往后加4小时，但日期不能超过当前日期，格式yyyyMMddhhmiss |
+| REFUND_CODE | 退款流水号 | varChar(30) | N | 可不填，商户可根据需要填写，退款流水号由商户的系统生成（在未收到退款接口返回时，可用此字段查询退款结果） |
+
+#### 响应参数
+
+| 字段名 | 中文名称 | 数据类型 | 必须 | 说明 |
+|--------|---------|----------|------|------|
+| ORDER_NUM | 订单号 | varChar(30) | Y | 订单号 |
+| PAY_AMOUNT | 支付金额 | number(16,2) | Y | 单位：元 |
+| AMOUNT | 退款金额 | number(16,2) | Y | 单位：元 |
+| Cst_AccNo | 客户账户 | varChar(32) | N | 脱敏后客户退款账号 |
+
+---
+
+### 3.5 A3341TP05 - 订单支付权益查询
+
+#### 接口说明
+
+| 项目 | 说明 |
+|------|------|
+| **服务码** | A3341TP05 |
+| **服务名称** | 订单支付权益查询 |
+| **服务类型** | 直接调用 |
+| **功能描述** | 查询订单支付时使用的权益信息。此接口跟订单支付结果一起计算流控TPM |
+| **URL** | https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP05 |
+
+#### 请求参数
+
+| 字段名 | 中文名称 | 数据类型 | 必须 | 说明 |
+|--------|---------|----------|------|------|
+| PLAT_MCT_ID | 服务商门店编号 | varChar(21) | N | 外部平台商户号（暂不支持） |
+| CUSTOMERID | 商户号 | varChar(21) | N | 建行商户编号，与外部平台商户号不能同时为空 |
+| BRANCHID | 一级分行号 | varChar(9) | N | 商户一级分行号，用建行商户编号时不能为空 |
+| TX_SPECIAL_EC | 交易类型 | varChar(1) | Y | 0-支付交易 1-退款交易 |
+| ORDER_ID | 订单号 | varChar(30) | Y | 调用收银台时支付流水号，对应字段ORDERID |
+| OriOvrlsttnEV_Trck_No | 原银行流水号 | varChar(25) | N | 原银行流水号 |
+| Txn_Prd_TpCd | 交易期间类型代码 | varChar(2) | N | 08-1个小时内，送空则为08 |
+| POS_ID | 终端号 | varChar(19) | N | 终端号 |
+| Jrnl_TpCd | 流水类型代码 | varChar(2) | N | XM-数字人民币 PT-普通收单 YH-单纯查券优惠 AL-全部，送空则为YH |
+
+#### 响应参数（摘要）
+
+| 字段名 | 中文名称 | 数据类型 | 说明 |
+|--------|---------|----------|------|
+| Py_Amt | 总支付金额 | varChar(19) | 总支付金额 |
+| Mrch_Rfnd_Amt | 总退款金额 | varChar(10) | 总退款金额 |
+| Py_Ordr_Amt | 总支付订单金额 | varChar(18) | 总支付订单金额 |
+| Rght_Cgy_Inf | 权益类信息 | varChar(3000) | 权益信息（见下方说明） |
+| LIST | 订单列表 | Array | 订单详情列表 |
+
+#### Rght_Cgy_Inf 权益类信息说明
+
+权益位图格式示例：
+```
+P6:{FL3:有价折扣券,AM1:30.00,AM2:30.00},P3:{FL2:02,FL3:满减活动,AM1:30.00,AM2:30.00}
+```
+
+**字段说明**:
+- P6: 商户券
+- FL1: 优惠度量（如积分数、券数量）
+- FL2: 清算方式（01-后结算 02-在线一笔清算 03-在线异步清算）
+- FL3: 优惠类型（如满减活动、满减券、有价券等）
+- FL4: 优惠名称（如活动描述或券名称）
+- AM1: 优惠金额
+- AM2: 清算金额
+- AM3: 银行出资金额
+- AM4: 商户出资金额
+- AM5: 优惠券面额
+- AM6: 客户实付金额
+- AM7: 积分抵扣金额
+
+**P6 优惠券类型**:
+- 免费折扣券
+- 免费代金券
+- 免费实物券
+- 免费定额券
+- 有价折扣券
+- 有价代金券
+- 有价实物券
+- 有价定额券
+
+---
+
+### 3.6 A3341TP13 - 服务方订单补充信息
+
+#### 接口说明
+
+| 项目 | 说明 |
+|------|------|
+| **服务码** | A3341TP13 |
+| **服务名称** | 服务方订单补充信息 |
+| **服务类型** | 直接调用 |
+| **功能描述** | 补充订单的商品信息（SKU_LIST） |
+| **URL** | https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=A3341TP13 |
+
+#### 请求参数
+
+| 字段名 | 中文名称 | 数据类型 | 必须 | 说明 |
+|--------|---------|----------|------|------|
+| USER_ID | 会员编号 | varChar(40) | Y | 会员编号 |
+| ORDER_ID | 订单编号 | varChar(40) | Y | 订单编号 |
+| SKU_LIST | 商品信息列表 | varChar(3000) | N | 商品信息列表(JSON字符串)，格式同订单推送接口 |
+
+#### SKU_LIST 字段说明
+
+同订单推送接口的 SKU_LIST 字段，包含：
+- SKU_NAME：商品名称
+- SKU_REF_PRICE：商品参考价
+- SKU_NUM：商品数量
+- SKU_SELL_PRICE：商品单价
+
+⚠️ **重要提示**：商品售价 SKU_SELL_PRICE 不能大于商品定价 SKU_REF_PRICE，字段长度为字节，注意中文字段长度。
+
+---
+
+## 附录
+
+### A. 订单状态枚举
+
+#### 订单状态（ORDER_STATUS / PAY_STATUS）
+- `0` - 待支付
+- `1` - 支付成功
+- `2` - 已过期
+- `3` - 支付失败
+- `4` - 取消
+
+#### 退款状态（REFUND_STATUS）
+- `0` - 无退款
+- `1` - 退款申请
+- `2` - 已退款
+- `3` - 部分退款
+
+#### 特殊附加状态（SPECIAL_STATUS）
+- `P0000` - 正常状态
+- `P0001` - 待使用
+- `P0002` - 待审核
+- `P0003` - 已支付
+- `P0004` - 待退款
+- `P0005` - 退款中
+- `P0006` - 待发货
+- `P0007` - 已发货
+- `P0008` - 进行中
+- `P0009` - 预定中
+- `P0010` - 预定成功
+- `P0011` - 预定失败
+- `P0012` - 已入住
+- `P0013` - 已离店
+- `P0014` - 未入住
+- `P0015` - 配送中
+- `P0016` - 出券中
+
+### B. 服务方订单类型（PLAT_ORDER_TYPE）
+- `T0000` - 普通类型
+- `T0001` - 洗车
+- `T0002` - 加油
+- `T0003` - 停车
+- `T0004` - 修车
+- `T0005` - 充电
+- `T0006` - 年检代办
+- `T0007` - 道路救援
+- `T0008` - 云南中石油充值
+
+### C. 支付方式（PAY_MODE / Scn_Idr）
+- `STSL` - 刷脸
+- `STSK` - 刷卡
+- `BHK` - 本行卡
+- `THK` - 他行卡
+- `ZFB` - 支付宝
+- `CFT` - 微信
+
+### D. 交易状态（TXN_STATUS / Txn_Status）
+- `00` - 交易成功
+- `01` - 交易失败
+- `02` - 不确定
+- `04` - 不确定（前端无须发冲正）
+- `TO` - 交易超时
+
+---
+
+## 开发指南
+
+### 1. 接口调用流程
+
+```
+1. 构建公共报文头（CLD_HEADER）
+   ├── CLD_TX_CHNL：服务方ID（如YS44000009001853）
+   ├── CLD_TX_TIME：当前时间（YmdHis格式）
+   ├── CLD_TX_CODE：服务码（如A3341TP01）
+   └── CLD_TX_SEQ：唯一流水号
+
+2. 构建业务参数（CLD_BODY）
+   └── 根据具体接口填充业务参数
+
+3. 整体报文加密
+   ├── 将CLD_HEADER + CLD_BODY转JSON
+   ├── 使用建行公钥RSA加密
+   └── 生成MD5签名（mac字段）
+
+4. 发送HTTP POST请求
+   ├── URL：基础地址 + ?txcode=服务码
+   ├── 参数：cnt（加密内容）、mac（签名）
+   └── 请求头：Content-Type: application/x-www-form-urlencoded
+
+5. 处理响应
+   ├── 使用商户私钥解密响应cnt字段
+   ├── 验证响应mac签名
+   └── 解析CLD_HEADER和CLD_BODY
+```
+
+### 2. 重要提示
+
+⚠️ **密钥管理**
+- 商户私钥：用于解密建行返回的数据
+- 商户公钥：参与支付串的MD5签名计算
+- 建行公钥：用于加密发送给建行的数据
+
+⚠️ **字段校验**
+- SKU_SELL_PRICE（商品售价）不能大于 SKU_REF_PRICE（商品定价）
+- 通知类型为"支付状态修改"时，PAY_STATUS 必填，REFUND_STATUS 为空
+- 通知类型为"退款状态修改"时，REFUND_STATUS 必填，PAY_STATUS 为空
+
+⚠️ **流控限制**
+- 订单查询接口（A3341TP03）：默认流控值为 100/TPM
+- 权益查询接口（A3341TP05）：与订单支付结果一起计算流控TPM
+
+⚠️ **时间格式**
+- 所有时间字段统一使用：`yyyyMMddHHmmss` 格式
+- 示例：`20250121120000`
+
+### 3. 错误处理
+
+- 接口返回404：请在请求头中添加 `Accept: application/json` 和 `Content-Type: application/json`
+- 查询结果延时：订单查询接口存在延时，返回未查到时可适当重复查询
+- 退款未返回：建议先调用订单查询接口查询退款结果，再做后续处理
+
+---
+
+**文档结束**