23 lines
9.8 KiB
Markdown
23 lines
9.8 KiB
Markdown
{
|
||
"doc_type" : "client_sdk",
|
||
"refined_doc" : "## 文档概述\n- 文档类型：client_sdk\n- 接口总数：4个（3个调用接口 + 1个回调通知接口）\n- 说明：本文档描述行内（调用方）调用供应商权益接口的规范，包含下单、查询、充值及回调通知\n\n## 认证与安全\n\n### 前置约定（需双方协商）\n- SM3 salt（盐值）\n- SM4 key（对称加密密钥）\n- 供应商侧测试及生产环境的 IP/域名和接口地址\n- 行方回调通知接口地址\n\n### 签名规则\n1. 将 `timestamp` + `encryptedData` 字符串拼接\n2. 使用 SM3 盐值加密（SmUtil.sm3WithSalt）进行签名\n\n**签名示例（Java Hutool）：**\n```java\nimport cn.hutool.crypto.SmUtil;\nString sign = SmUtil.sm3WithSalt(sm3Salt.getBytes()).digestHex(timestamp + encryptedData);\n```\n\n### 加密规则\n- 业务数据（JSON格式）使用 SM4 加密后放入 `encryptedData` 字段\n- 响应中的 `data` 字段也是 SM4 加密的 JSON 字符串，需解密后使用\n\n### 通用请求参数（所有接口共用）\n\n#### 请求头\n| 参数名 | 必填 | 类型 | 描述 | 取值说明 |\n|--------|------|------|------|----------|\n| timestamp | 是 | String | 时间戳 | 毫秒级时间戳 |\n| sign | 是 | String | 签名 | 见签名规则 |\n\n#### 请求体\n| 参数名 | 必填 | 类型 | 描述 | 取值说明 |\n|--------|------|------|------|----------|\n| encryptedData | 是 | String | 加密数据 | JSON格式业务数据进行SM4加密 |\n\n### 通用响应参数（所有接口共用）\n| 参数名 | 必填 | 类型 | 描述 | 说明 |\n|--------|------|------|------|------|\n| code | 是 | int | 返回状态编码 | 0成功 -1失败 |\n| msg | 是 | String | 返回错误信息 | |\n| data | 否 | Object | 返回数据 | JSON格式业务数据进行SM4加密 |\n\n## 接口列表\n\n### 接口 1：卡券/直充权益下单接口\n- 路径：待供应商提供（测试/生产环境）\n- 方法：POST\n- 描述：适用于卡密、直充商品下单\n- Content-Type：application/json\n\n#### 请求参数（业务数据，加密前）\n| 参数名 | 必填 | 类型 | 描述 | 取值说明 |\n|--------|------|------|------|----------|\n| actCode | 是 | String | 活动code | 可约定为各供应商的项目编号和密钥的拼接加密字符串 |\n| goodsCode | 是 | String | 商品code | 供应商商品编号 |\n| actOrderNum | 是 | String | 活动方订单号 | 唯一，行内活动订单号 |\n| account | 否 | String | 充值账号 | |\n| callbackUrl | 否 | String | 回调地址 | |\n\n#### 响应参数（data解密后）\n| 参数名 | 必填 | 类型 | 描述 | 说明 |\n|--------|------|------|------|------|\n| orderNo | 是 | String | 权益订单号 | 唯一，供应商订单号 |\n| couponNo | 否 | String | 卡号 | 卡券/短链类商品返回 |\n| couponCode | 否 | String | 卡密 | 卡券类商品返回 |\n| status | 是 | Integer | 状态 | -1发放中 0成功 1失败 2已核销 3已过期 |\n| expireTime | 否 | String | 有效期 | 卡券/短链类商品返回，格式：yyyy-MM-dd HH:mm:SS |\n\n#### 示例\n\n**请求示例（原始业务参数，加密前）：**\n```json\n{\n \"actCode\": \"ACT001\",\n \"goodsCode\": \"123456\",\n \"actOrderNum\": \"00001\",\n \"account\": \"19912345678\",\n \"callbackUrl\": \"https://xxx/notice\"\n}\n```\n\n**响应示例（data解密后）：**\n```json\n{\n \"code\": 0,\n \"msg\": \"请求成功\",\n \"data\": \"{\\\"orderNo\\\":\\\"HM17575805323790000127073398f3772c00\\\",\\\"expireTime\\\":\\\"2025-09-12 00:00:00\\\",\\\"couponNo\\\":\\\"27073398f3772c00\\\",\\\"couponCode\\\":\\\"27073398f3772c00\\\",\\\"status\\\":1}\"\n}\n```\n\n### 接口 2：卡券/直充/微信立减金订单查询接口\n- 路径：待供应商提供（测试/生产环境）\n- 方法：POST\n- 描述：行内通过供应商订单号查询订单状态\n- Content-Type：application/json\n\n#### 请求参数（业务数据，加密前）\n| 参数名 | 必填 | 类型 | 描述 | 取值说明 |\n|--------|------|------|------|----------|\n| actCode | 是 | String | 活动code | 可约定为各供应商的项目编号和密钥的拼接加密字符串 |\n| orderNo | 是 | String | 供应商订单号 | |\n\n#### 响应参数（data解密后）\n| 参数名 | 必填 | 类型 | 描述 | 说明 |\n|--------|------|------|------|------|\n| orderNo | 是 | String | 权益订单号 | 唯一，供应商订单号 |\n| status | 是 | Integer | 订单状态 | -1发放中 0成功 1失败 2已核销 3已过期 |\n| account | 否 | String | 充值账号 | 直充类型时存在 |\n| cardInfo | 否 | Object | 卡券信息 | 卡券/短链类型时存在 |\n| - couponNo | 是 | String | 卡号/短链 | |\n| - couponCode | 是 | String | 卡密 | |\n| - expireTime | 是 | String | 过期时间 | 格式：yyyy-MM-dd HH:mm:ss |\n| couponId | 是 | String | 优惠id | 微信立减金类型时存在 |\n\n#### 示例\n\n**请求示例（原始业务参数，加密前）：**\n```json\n{\n \"actCode\": \"FBG6vdYqGE4mGX7EH/woEg==\",\n \"orderNo\": \"HM1757046717684000102707339840b23222\"\n}\n```\n\n**响应示例（data解密后）：**\n```json\n{\n \"code\": 0,\n \"msg\": \"请求成功\",\n \"data\": \"{\\\"orderNo\\\":\\\"HM1757046717684000102707339840b23222\\\",\\\"cardInfo\\\":\\\"{\\\\\\\"couponNo\\\\\\\":\\\\\\\"11111\\\\\\\",\\\\\\\"couponCode\\\\\\\":\\\\\\\"12334\\\\\\\",\\\\\\\"expireTime\\\\\\\":\\\\\\\"2029-03-09 00:00:00\\\\\\\"}\\\",\\\"status\\\":3}\"\n}\n```\n\n### 接口 3：微信立减金订单充值接口\n- 路径：待供应商提供（测试/生产环境）\n- 方法：POST\n- 描述：微信立减金订单充值\n- Content-Type：application/json\n\n#### 请求参数（业务数据，加密前）\n| 参数名 | 必填 | 类型 | 描述 | 取值说明 |\n|--------|------|------|------|----------|\n| actCode | 是 | String | 活动code | 可约定为各供应商的项目编号和密钥的拼接加密字符串 |\n| orderNo | 是 | String | 供应商订单号 | |\n| goodsCode | 是 | String | 商品code | 供应商商品编号 |\n| actOrderNum | 是 | String | 活动方订单号 | 唯一，行内订单号 |\n| appId | 是 | String | 公众账号ID | |\n| openId | 是 | String | 微信用户标识 | 需要与 appId 绑定（同一个 appId 下的 openId） |\n| callbackUrl | 否 | String | 回调地址 | |\n\n#### 响应参数（data解密后）\n| 参数名 | 必填 | 类型 | 描述 | 说明 |\n|--------|------|------|------|------|\n| orderNo | 是 | String | 权益订单号 | 唯一，供应商订单号 |\n| status | 是 | Integer | 订单状态 | -1发放中 0成功 1失败 2已核销 3已过期 |\n| couponId | 是 | String | 微信优惠id | 微信该批次立减金的优惠id |\n\n#### 示例\n\n**请求示例（原始业务参数，加密前）：**\n```json\n{\n \"actCode\": \"FBG6vdYqGE4mGX7EH/woEg==\",\n \"goodsCode\": \"0001\",\n \"actOrderNum\": \"0001\",\n \"openId\": \"0001\",\n \"appId\": \"00001\"\n}\n```\n\n**响应示例（data解密后）：**\n```json\n{\n \"code\": 0,\n \"msg\": \"请求成功\",\n \"data\": \"{\\\"orderNo\\\":\\\"0001\\\",\\\"couponId\\\":\\\"123456\\\",\\\"status\\\":1}\"\n}\n```\n\n**失败响应示例：**\n```json\n{\n \"code\": -1,\n \"msg\": \"库存不足\",\n \"data\": null\n}\n```\n\n## 回调通知\n\n### 接口 4：卡券/直充/微信立减金充值结果通知接口\n- 说明：供应商主动回调行内，通知充值结果\n- 路径：行内提供回调地址\n- 方法：POST\n- Content-Type：application/json\n\n#### 请求参数（业务数据，加密前）\n| 参数名 | 必填 | 类型 | 描述 | 取值说明 |\n|--------|------|------|------|----------|\n| orderNo | 是 | String | 供应商订单号 | 唯一，供应商订单号 |\n| actOrderNum | 是 | String | 活动方订单号 | 唯一，行内订单号 |\n| status | 是 | Integer | 订单状态 | -1发放中 0成功 1失败 2已核销 3已过期 |\n| account | 否 | String | 直充账号 | 直充类型商品时存在 |\n| cardInfo | 否 | Object | 卡券信息 | 卡券/短链类型商品时存在 |\n| - couponNo | 是 | String | 卡号/短链 | |\n| - couponCode | 是 | String | 卡密 | |\n| - expireTime | 是 | String | 卡券过期时间 | |\n| couponId | 否 | String | 微信优惠id | 微信立减金类型商品时存在 |\n\n#### 回调请求示例（原始业务参数，加密前）\n```json\n{\n \"orderNo\": \"HM202509291010001\",\n \"actOrderNum\": \"XY2025092910100001\",\n \"status\": 3,\n \"account\": \"19912345678\"\n}\n```\n\n#### 响应要求\n| 状态码 | 返回内容 | 说明 |\n|--------|----------|------|\n| 200 | ok | 接收成功，系统认为回调已处理成功，不会重试 |\n| 其它 | 任意内容 | 系统认为接收失败，将按重试策略重试，最多3次 |\n\n## 错误码\n| 错误码 | 说明 | 处理建议 |\n|--------|------|----------|\n| 0 | 成功 | - |\n| -1 | 失败 | 根据 msg 字段判断具体错误原因 |\n\n## 订单状态枚举\n| 状态值 | 说明 |\n|--------|------|\n| -1 | 发放中 |\n| 0 | 成功 |\n| 1 | 失败 |\n| 2 | 已核销 |\n| 3 | 已过期 |",
|
||
"has_authentication" : true,
|
||
"interfaces" : [ {
|
||
"method" : "POST",
|
||
"path" : "待供应商提供",
|
||
"summary" : "卡券/直充权益下单接口"
|
||
}, {
|
||
"method" : "POST",
|
||
"path" : "待供应商提供",
|
||
"summary" : "卡券/直充/微信立减金订单查询接口"
|
||
}, {
|
||
"method" : "POST",
|
||
"path" : "待供应商提供",
|
||
"summary" : "微信立减金订单充值接口"
|
||
}, {
|
||
"method" : "POST",
|
||
"path" : "行内提供回调地址",
|
||
"summary" : "卡券/直充/微信立减金充值结果通知接口（回调）"
|
||
} ],
|
||
"reason" : "文档主要描述行内（调用方）如何调用供应商的3个接口（下单、查询、充值），包含请求方式、参数、签名规则、加密方式等调用方所需信息，同时附带一个供应商回调行内的通知接口说明，整体属于 client_sdk 类型。"
|
||
} |