团购券核销

仅提供已授权的门店数据服务：调用时通过门店标识定位收钱吧门店，平台校验该门店已完成授权（平台资质与应用配置、门店映射、平台授权）；未授权门店的券业务无法执行，授权流程见开通流程。

1. 接口说明

本接口面向外部业务系统，提供各平台团购券的查券、核销、撤销与结果查询能力。对接方通过本平台开放接口，将券核销能力嵌入自有系统，无需自行对接各团购平台的核销接口。

能力一览

2. 智能接口与手动接口的选择

查券、核销各提供智能与手动两个版本，两者能力一致，区别仅在于平台识别方式：

接入建议：开放平台建议开发者优先选择手动查券、手动核销（显式指定 platform）。部分平台的二维码解析后不含平台识别特征，智能接口无法判断券码归属，将导致核销失败；显式指定平台可规避该问题。

券码是否可识别，取决于券码中是否包含平台特征：

识别规则可能随平台策略调整，实际以系统识别结果为准。

无识别特征的券码（如纯数字券码 1234567890）无法自动识别，调用智能接口将返回 52002（券码不存在或无法识别）。该类券码多属于美团（MEI_TUAN）或支付宝神券（如数字券码 0009 9040 8042）等平台，请改用手动查券、手动核销接口并显式指定 platform。

3. 智能查券（自动识别平台）

系统基于券码格式特征自动识别所属团购平台并路由到对应平台完成查券。券码未包含平台识别特征时识别会失败（返回 52002），开放平台建议优先使用手动查券，选择依据见智能接口与手动接口的选择。

查券前置：核销前必须先调用查券接口；查券调用成功后 30 分钟内支持核销，超过 30 分钟需重新查券——查券过期后直接核销将返回 52005（券查券状态失效，不可核销）。

3.1 请求参数

请求示例

{
  "clientStoreSn": "SH001",
  "sqbStoreSn": "1580000003443730",
  "couponCode": "ABC123",
  "requestId": "req_001"
}

3.2 响应参数

响应示例

{
  "code": 0,
  "message": "成功",
  "data": {
    "couponCode": "ABC123",
    "platform": "MEI_TUAN",
    "platformDesc": "美团餐饮",
    "name": "满50减10元代金券",
    "count": 1,
    "couponBuyPrice": 4000,
    "couponMarketPrice": 5000,
    "status": "INIT",
    "couponStatusDesc": "未使用",
    "bizType": "2",
    "couponEndTime": 1735660799000
  }
}

4. 手动查券（指定平台）

显式指定三方平台进行查券。适用于券码不具备识别特征的场景，选择依据见智能接口与手动接口的选择。

4.1 请求参数

请求示例

{
  "clientStoreSn": "SH001",
  "sqbStoreSn": "1580000003443730",
  "platform": "MEI_TUAN",
  "couponCode": "ABC123",
  "requestId": "req_001"
}

4.2 响应参数

响应字段与响应示例同智能查券。

5. 智能核销（自动识别平台）

将已查券的团购券标记为已使用。系统基于券码特征自动识别平台并路由核销。

核销前必须先查券：未查券直接核销将返回 52005（券未查券，不可核销）；查券后超过 30 分钟再核销需重新查券，否则同样返回 52005（查券已过期）。

5.1 请求参数

请求示例

{
  "clientStoreSn": "SH001",
  "sqbStoreSn": "1580000003443730",
  "couponCode": "ABC123",
  "count": 1,
  "requestId": "req_001"
}

5.2 响应参数

响应示例

{
  "code": 0,
  "message": "成功",
  "data": {
    "requestId": "req_001",
    "sqbOrderId": "sqb_consume_001",
    "couponCode": "ABC123",
    "platform": "MEI_TUAN",
    "platformDesc": "美团餐饮",
    "couponName": "满50减10元代金券",
    "couponBuyPrice": 4000,
    "couponMarketPrice": 5000,
    "count": 1,
    "exOrderId": "mt_ext_001",
    "exStoreId": "mt_store_001",
    "bizType": "2",
    "status": "CONSUMED"
  }
}

核销结果说明：核销成功时返回上述字段；核销失败（如券已核销 52003、券已过期 52004、未查券 52005、三方平台异常 41501）时直接返回对应错误码，data 为 null，不返回核销数据。

注意：sqbOrderId 为收钱吧核销订单号，后续撤销核销时必须使用此字段，请妥善保存。若核销调用后无法确定最终结果（如网络超时、返回异常或处理中），可使用查询核销结果按 requestId 查询核销最终处理结果。

6. 手动核销（指定平台）

显式指定三方平台进行核销。适用于券码不具备识别特征的场景，选择依据见智能接口与手动接口的选择。

核销前必须先查券（同智能核销）：未查券直接核销将返回 52005；查券后超过 30 分钟再核销需重新查券，否则同样返回 52005（查券已过期）。

6.1 请求参数

请求示例

{
  "clientStoreSn": "SH001",
  "sqbStoreSn": "1580000003443730",
  "platform": "MEI_TUAN",
  "couponCode": "ABC123",
  "count": 1,
  "requestId": "req_001"
}

6.2 响应参数

响应字段与响应示例同智能核销。

7. 撤销核销

根据收钱吧核销订单号撤销已核销的券，将券恢复到"未使用"状态。团购平台由系统自动反查。

支持部分撤销：一次核销多份券时，可只撤销其中部分份数（如核销 2 张、只撤销 1 张）。单次请求可撤销的份数上限因平台而异，见单次撤销张数限制；累计撤销份数不能超过该核销订单的已核销份数。

7.1 请求参数

请求示例

{
  "clientStoreSn": "SH001",
  "sqbStoreSn": "1580000003443730",
  "sqbOrderId": "sqb_consume_001",
  "count": 1,
  "requestId": "req_001"
}

7.2 响应参数

响应示例（成功）

{
  "code": 0,
  "message": "成功",
  "data": {
    "requestId": "req_001",
    "sqbOrderId": "sqb_consume_001",
    "platform": "MEI_TUAN",
    "totalSuccessCount": 1,
    "totalFailedCount": 0,
    "nowSuccessCount": 1,
    "nowFailedCount": 0,
    "nowStatus": "CANCELLED",
    "status": "CANCELLED",
    "cancelErrorReasonList": []
  }
}

响应示例（部分成功）

{
  "code": 0,
  "message": "成功",
  "data": {
    "requestId": "req_001",
    "sqbOrderId": "sqb_consume_001",
    "platform": "MEI_TUAN",
    "totalSuccessCount": 2,
    "totalFailedCount": 1,
    "nowSuccessCount": 2,
    "nowFailedCount": 1,
    "nowStatus": "PART_CANCELLED",
    "status": "PART_CANCELLED",
    "cancelErrorReasonList": [
      {
        "couponCode": "CERT_003",
        "failReason": "该券码已失效"
      }
    ]
  }
}

部分撤销注意事项：单次请求含多份券时可能出现部分成功、部分失败（nowStatus = PART_CANCELLED）；cancelErrorReasonList 仅包含失败的券码及原因，请据此判断是否需要人工介入。若撤销调用后无法确定最终结果（如网络超时、返回异常或处理中），可使用查询撤销结果按 requestId 查询撤销最终处理结果。

撤销时效：各平台对核销后可撤销的时间窗口不同，超出时效后撤销将被平台拒绝，各平台时效与开发建议见团购券枚举附录。

8. 查询核销/撤销结果（按 requestId）

核销、撤销为写操作，若调用时出现网络超时或返回"处理中"（如 52011）等无法确定最终结果的情况，可按操作时使用的 requestId 查询最终处理结果，用于结果确认与对账闭环。核销与撤销的结果结构不同，分为两个接口：

两个接口均为查询类接口，请求参数中的 requestId 即待查询操作（核销/撤销）发起时使用的 requestId，本次查询请求不再单独生成请求标识；requestId 仅用于查询定位，不参与去重。

门店归属校验：查询请求的门店（clientStoreSn，如传 sqbStoreSn 同此）须与待查询操作发起时一致，平台按门店维度校验归属；跨门店查询返回 52010（核销单不属于当前门店），requestId 无对应记录返回 52014（请求记录不存在）。

8.1 查询核销结果

8.1.1 请求参数

请求示例

{
  "clientStoreSn": "SH001",
  "sqbStoreSn": "1580000003443730",
  "requestId": "req_002"
}

8.1.2 响应参数

响应示例（核销成功）

{
  "code": 0,
  "message": "成功",
  "data": {
    "requestId": "req_002",
    "status": "CONSUMED",
    "sqbOrderId": "sqb_consume_001",
    "couponCode": "ABC123",
    "couponName": "满50减10元代金券",
    "platform": "MEI_TUAN",
    "platformDesc": "美团餐饮",
    "count": 1,
    "couponBuyPrice": 4000,
    "couponMarketPrice": 5000,
    "bizType": "2",
    "exOrderId": "mt_ext_001",
    "exStoreId": "mt_store_001"
  }
}

查询说明：本接口适用于核销调用后无法确定最终结果的场景——如核销接口网络超时/返回异常、或返回"处理中"（PROCESSING）等，使用核销时的 requestId 查询核销最终处理结果，用于结果确认与对账。查询时的门店须与核销时一致，跨门店查询返回 52010；requestId 无对应记录返回 52014（请求记录不存在）。status = PROCESSING 表示核销仍在处理中，请稍后使用相同 requestId 重新查询。

8.2 查询撤销结果

8.2.1 请求参数

请求示例

{
  "clientStoreSn": "SH001",
  "sqbStoreSn": "1580000003443730",
  "requestId": "req_003"
}

8.2.2 响应参数

响应示例（撤销成功）

{
  "code": 0,
  "message": "成功",
  "data": {
    "requestId": "req_003",
    "status": "CANCELLED",
    "sqbOrderId": "sqb_consume_001",
    "platform": "MEI_TUAN",
    "nowSuccessCount": 1,
    "nowFailedCount": 0,
    "totalSuccessCount": 1,
    "totalFailedCount": 0,
    "cancelErrorReasonList": []
  }
}

查询说明：本接口适用于撤销调用后无法确定最终结果的场景——如撤销接口网络超时/返回异常、或返回 52011（撤销超时/处理中）等，使用撤销时的 requestId 查询撤销最终处理结果，用于结果确认与对账。查询时的门店须与撤销时一致，跨门店查询返回 52010；requestId 无对应记录返回 52014（请求记录不存在）。status = PROCESSING 表示撤销仍在处理中，请稍后使用相同 requestId 重新查询。

9. 完整调用流程示例

场景：外部系统自有门店 SH001 对应收钱吧门店 1580000003443730，顾客持美团券 ABC123 到店消费。

第一步：智能查券

{
  "clientStoreSn": "SH001",
  "sqbStoreSn": "1580000003443730",
  "couponCode": "ABC123",
  "requestId": "req_001"
}

券有效（status = INIT），进入核销。

第二步：智能核销

{
  "clientStoreSn": "SH001",
  "sqbStoreSn": "1580000003443730",
  "couponCode": "ABC123",
  "count": 1,
  "requestId": "req_002"
}

核销成功，保存 sqbOrderId = sqb_consume_001，后续撤销时使用。

第三步：撤销核销（顾客临时取消消费）

{
  "clientStoreSn": "SH001",
  "sqbStoreSn": "1580000003443730",
  "sqbOrderId": "sqb_consume_001",
  "count": 1,
  "requestId": "req_003"
}

若该核销订单核销了多份券，此处 count 可小于核销份数，实现部分撤销；单次可撤销份数上限见单次撤销张数限制。

10. 错误码

业务错误码使用团购券独立段位 52xxx，与订单（50xxx）、商品（51xxx）段位相互独立、互不重叠；公共错误码（鉴权、频率限制、权限、下游服务等）见错误码。

本接口业务错误码（52xxx 段）

参数校验失败等公共业务错误见错误码（41109）。接口响应中的 code 为统一包装结果码，业务数据在 data 中体现。

11. AI 快速接入提示词

将下方提示词连同当前项目代码库提供给任意 AI 编程工具，即可快速完成团购券业务（查券、核销、撤销、查询核销/撤销结果）的接入。AI 会先识别项目所用语言、框架与既有规范，再依据收钱吧官方接口及签名文档实现请求、签名、配置和测试；适用于不同技术栈，无需预设 Java 或固定项目目录。使用前请在安全的配置渠道提供脱敏后的必要参数，切勿将真实密钥写入提示词、代码或日志。

你是一名经验丰富的后端集成工程师。请在"当前项目"的既有技术栈、代码规范和部署方式下，接入并验证收钱吧智慧开放平台的团购券业务接口（智能查券、手动查券、智能核销、手动核销、撤销核销）。不要假定编程语言、框架、HTTP 客户端、配置系统或目录结构；先调研当前项目，再选择与项目一致的实现方式。

## 业务目标
将团购券核销能力嵌入自有系统：根据门店与券码查券、核销、撤销，并按 `requestId` 查询操作最终结果，交付一个可安全配置、可自动验证、可供业务代码复用的接口适配能力。

## 接口信息
- 网关：`https://gateway-smart.shouqianba.com`
- 接口路径前缀：`/open-api/v1/coupon/`
  - 智能查券：`POST /open-api/v1/coupon/query`
  - 手动查券：`POST /open-api/v1/coupon/manual/query`
  - 智能核销：`POST /open-api/v1/coupon/consume`
  - 手动核销：`POST /open-api/v1/coupon/manual/consume`
  - 撤销核销：`POST /open-api/v1/coupon/cancel`
  - 查询核销结果：`POST /open-api/v1/coupon/consume/result`
  - 查询撤销结果：`POST /open-api/v1/coupon/cancel/result`
- 官方文档：
  - 鉴权与签名：`https://doc.shouqianba.com/docs-for-smart/公共定义/鉴权与签名.html`
  - 团购券核销：`https://doc.shouqianba.com/docs-for-smart/接口说明/团购券/团购券核销.html`

## 工作步骤
1. 先阅读当前项目中与 OpenAPI、HTTP 请求、配置加载、密钥管理、日志、错误处理和测试有关的现有代码；复用已有约定，不要为了本接口引入无必要的新框架或重构无关代码。
2. 阅读上述官方文档，先在实施说明中写清"待签名字符串/字节的构造规则、签名算法、编码和请求头含义"。不要凭经验推断签名格式；文档与旧代码冲突时，以官方文档为准并说明差异。
3. 实现券业务客户端/适配层，将业务参数、认证参数、序列化、签名、网络调用和响应解析合理分离，便于后续复用与测试。

## 请求与签名硬性要求
- 请求体使用 JSON。各接口公共参数：`clientStoreSn`（客户门店号）、`sqbStoreSn`（收钱吧门店号，可不传）、`requestId`（请求标识）。
- 查券（智能/手动）至少传入 `clientStoreSn`、`couponCode`、`requestId`；手动接口需额外传入 `platform`（三方平台代码）。
- 核销（智能/手动）另需 `count`（1-99）；手动核销需额外传入 `platform`。
- 撤销需 `sqbOrderId`（核销响应返回）、`count`；支持部分撤销，单次可撤份数上限因平台而异。
- 查询核销结果：传入核销时使用的 `requestId`，返回核销最终 `status` 与核销数据。
- 查询撤销结果：传入撤销时使用的 `requestId`，返回撤销最终 `status` 与撤销数据。
- 核销前必须先查券，查券成功后 30 分钟内支持核销，超出需重新查券。
- 核销/撤销为写操作，`requestId` 为幂等键，超时重试时必须使用相同 `requestId`。
- 按官方规范生成并发送 `X-AccessKey`、`X-Timestamp`（毫秒级）、`X-Nonce`（8 位字母数字随机串）和 `X-Signature`（小写十六进制）。
- 使用官方规定的 HMAC-SHA256 签名规则。参与签名的原始 JSON 请求体必须与最终实际发送的字节完全一致；签名完成后不得重新格式化、排序或序列化请求体。

## 配置与安全
- 所有敏感和环境相关值必须由当前项目的标准安全配置机制注入（例如环境变量、密钥服务、部署平台 Secret 或本地忽略的配置文件），不得硬编码。
- 至少支持以下逻辑配置项：AccessKey、AccessSecret、clientStoreSn、sqbStoreSn；并按需支持券码、count 等测试数据。
- 配置示例、日志、异常、测试输出、提交记录和文档中都不得出现真实 AccessSecret、令牌、门店号或券码。
- 必填配置缺失时，应给出可操作的报错/跳过信息，绝不能使用任何默认真实凭据。

## 验收与测试
1. 增加不依赖网络的签名单元测试，使用固定测试向量验证 HMAC-SHA256 和小写十六进制编码。
2. 增加可选的集成测试或可执行调用示例；只有在必填配置齐全时才实际请求平台，缺失时安全跳过或明确提示。
3. 成功响应至少校验 `code == 0`，并按官方响应结构校验：查券返回券详情含券状态；核销返回 `sqbOrderId`；撤销返回撤销份数与状态；结果查询（核销/撤销）返回最终 `status` 与对应结果数据。
4. 对网络超时、非成功状态、签名/鉴权失败、响应 JSON 异常和业务错误码（如 52005 未查券、52009 撤销份数超限）提供与当前项目一致的错误处理。
5. 执行当前项目可用的相关检查和测试。

## 最终交付格式
请输出：
1. 采用的技术栈与复用的项目既有组件；
2. 修改/新增的文件及各自职责；
3. 脱敏的配置项说明和调用示例；
4. 签名构造规则摘要；
5. 已执行的验证命令与结果，以及因现有项目问题无法验证的部分；
6. 任何需要人工补充的非敏感配置或权限。

实施范围仅限团购券查券/核销/撤销/结果查询能力及其必要测试，不修改无关业务逻辑。