补传挂网协议信息

1. 文档概述

该接口用于接收华通子渠道的挂网协议信息

报文编号 版本号
请求 BNK1-1001-005-01 1.0.0
应答 BNK1-1001-005-01 1.0.0

2. 接口信息

  • 接口名称：补传挂网协议
  • 请求方式：POST
  • Content-Type：application/json
  • 返回类型：Result<ReuploadAgreementResDTO>

3. 业务说明

  1. 调用方传入的 bankType 仍然使用华通子渠道值，例如：
    • HT-MC
  2. 服务端在进入下游前，会通过 BankEnum.getChannel(bankType) 将华通子渠道统一映射为 HT。
  3. 服务端自动生成 merTransNo，并组装 YQT 请求体。
  4. 下游统一使用 serviceName = reuploadAgreement 调用 yqt-trade。
  5. 下游返回结果中：
    • succeeded：成功
    • processing：处理中，原样透传
    • failed：失败，转换为统一业务错误返回

4. 请求参数

4.1 请求示例

{
  "memberId": "M001",
  "balanceAcctId": "BAL-001",
  "accountName": "测试账户",
  "bankType": "HT-MC",
  "entryTime": "2026-05-28 10:00:00",
  "readingDuration": "120",
  "checkboxClickTime": "2026-05-28 10:02:00",
  "clientIp": "127.0.0.1"
}

4.2 字段说明

字段名 类型 必填 最大长度 说明
uid String 是 64 会员号/业务主体标识
balanceAcctId String 是 64 电子账簿ID
accountName String 是 128 账户名称
bankType String 是 - 华通子渠道类型，支持 HT-MC、HT-PAM、HT-DC、HT-EP
entryTime String 是 19 进入页面时间，格式 yyyy-MM-dd HH:mm:ss
readingDuration String 是 3 阅读时长，纯数字字符串
checkboxClickTime String 是 19 勾选时间，格式 yyyy-MM-dd HH:mm:ss
clientIp String 是 32 客户端 IP

4.3 校验规则

  1. 所有字段均不能为空。
  2. bankType 必须是系统支持的华通子渠道。
  3. entryTime 和 checkboxClickTime 必须符合 yyyy-MM-dd HH:mm:ss。
  4. readingDuration 必须是长度不超过 3 的数字字符串。

5. 响应参数

5.1 成功响应示例

{
  "success": true,
  "code": "000000",
  "message": "成功",
  "data": {
    "merTransNo": "MTR-202605280001",
    "orderNo": "ORD-202605280001",
    "status": "processing",
    "ackMsg": "处理中",
    "bankType": "HT"
  }
}

5.2 响应字段说明

字段名 类型 说明
success Boolean 是否成功
code String 返回码
message String 返回信息
data Object 业务结果
data.merTransNo String 商户交易流水号
data.orderNo String 下游订单号
data.status String 下游状态，常见值：succeeded、processing、failed
data.ackMsg String 下游返回说明
data.bankType String 下游返回银行类型，正常为 HT

6. 错误返回说明

6.1 参数校验失败

当请求参数不符合约束时，接口直接返回业务错误，不会调用下游。

示例：

{
  "success": false,
  "code": "INVALID_PARAMETER",
  "message": "进入页面时间格式非法",
  "data": null
}

6.2 银行类型不支持

当 bankType 不是华通支持的子渠道时，返回业务错误：

{
  "success": false,
  "code": "BANK_NOT_SUPPORT",
  "message": "该银行暂未接入补送挂网协议",
  "data": null
}

6.3 下游失败

当 yqt-trade 返回 failed 时，接口将下游失败信息映射为统一错误返回：

{
  "success": false,
  "code": "REMOTE_CALL_RESPONSE_IS_FAILED",
  "message": "渠道拒绝",
  "data": null
}

6.4 系统异常

当出现未预期异常时，接口返回统一系统错误：

{
  "success": false,
  "code": "SYSTEM_ERROR",
  "message": "系统异常",
  "data": null
}