# 退货通知接收指南（给 AI 看的实施说明）

本文档面向**接入了 RedeemShip 兑换码核销能力的另一个项目**（下称「接入方」）。

背景：接入方通过 `POST https://redeem.zzz.sarl/api/open/redeem` 核销兑换码后，兑换码的发放方（RedeemShip 平台上的商户）**有可能对该码发起退货**。退货成功时，RedeemShip 会向接入方配置的**退货通知地址**发送一条 HTTP 请求，接入方收到后应**撤回/扣减**该码对应的业务会员权益（积分、时长等）。

请按本文档在接入方项目里新增一个接收通知的接口，并完成开发对接。

---

## 一、如何配置退货通知地址

有两种方式（任选其一）：

1. **RedeemShip 控制台**：登录后进入 `API Keys` 页面，点击对应 Key 的「设置」，填入退货通知地址（`return_notify_url`），保存即可。
2. **开放接口**：调用下面的接口更新（`Authorization` 使用对应的 API Key）：

- 方法：`POST`
- 地址：`https://redeem.zzz.sarl/api/open/notify-url`
- 请求头：`Content-Type: application/json`、`Authorization: Bearer ${REDEEMSHIP_API_KEY}`
- 请求体：`{ "url": "https://notify.your-domain.com/redeem/callback" }`（传空字符串表示清除，不再推送）
- 成功响应：`{ "success": true, "message": "退货通知地址已更新" }`

---

## 二、通知请求格式

- 方法：`POST`
- Content-Type: `application/json`
- 请求体：

```json
{
  "payload": "<base64(iv).base64(ciphertext)>"
}
```

**`payload` 是加密的**，加密方式：AES-256-GCM，密钥为接入方 API Key 明文做 SHA-256 派生（32 字节），IV 12 字节。最终格式为 `base64(iv) + "." + base64(ciphertext+tag)`（与 Node.js `crypto.createCipheriv("aes-256-gcm")` 的 GCM tag 附在密文尾部一致）。

> 为什么加密：通知里包含兑换码等业务信息，用只有双方知道的 API Key 加密可以同时完成**身份校验**（解不开 = 假通知）和**内容保密**。请务必先校验 API Key 明文能成功解密，再执行业务逻辑。

### 解密后的 JSON 内容

```json
{
  "event": "code.returned",
  "code": "d3f0c1a2-4b7e-4f2a-9c1d-7e3b5a8c0f12",
  "points": 100,
  "duration": "1_month",
  "remark": "客户申请退单",
  "usedAt": "2026-11-14T08:30:00.000Z",
  "returnedAt": "2026-11-15T02:11:22.345Z"
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `event` | string | 固定 `code.returned`，表示兑换码退货 |
| `code` | string | 被退货的兑换码（UUID） |
| `points` | number | 该码发放的积分数（时长券为 0） |
| `duration` | string \| null | 该码发放的时长：`1_day / 3_day / 1_week / 1_month / 3_month / 1_year` 之一（积分券为 null） |
| `remark` | string \| null | 退货备注（可能为空） |
| `usedAt` | string | 该码当初被核销的时间（ISO 8601） |
| `returnedAt` | string | 本次退货时间（ISO 8601） |

接入方应按 `code` 找到当初核销记录，把对应发放的积分/时长**扣回**（或按自己的业务规则回滚权益）。

---

## 三、参考实现

以 Next.js App Router（Node.js 运行时）为例：

```ts
// app/api/redeem/notify/route.ts
import crypto from "crypto";

export async function POST(req: Request) {
  const body = (await req.json()) as { payload?: string };
  if (!body.payload) return Response.json({ message: "缺少 payload" }, { status: 400 });

  // 1. 用自己的 API Key 派生密钥并解密（解密失败 = 非法通知，直接拒绝）
  const [ivB64, ctB64] = body.payload.split(".");
  if (!ivB64 || !ctB64) return Response.json({ message: "payload 格式错误" }, { status: 400 });

  const key = crypto.createHash("sha256").update(process.env.REDEEMSHIP_API_KEY!).digest();
  let event: {
    event: string; code: string; points: number; duration: string | null;
    remark: string | null; usedAt: string; returnedAt: string;
  };
  try {
    const decipher = crypto.createDecipheriv("aes-256-gcm", key, Buffer.from(ivB64, "base64"));
    decipher.setAuthTag(Buffer.from(ctB64, "base64").subarray(-16));
    const plain = Buffer.concat([
      decipher.update(Buffer.from(ctB64, "base64").subarray(0, -16)),
      decipher.final(),
    ]);
    event = JSON.parse(plain.toString("utf8"));
  } catch {
    return Response.json({ message: "解密失败：API Key 不匹配或数据被篡改" }, { status: 401 });
  }

  // 2. 校验业务：按 event.code 找到当初核销记录
  //    - 找不到 → 返回 404（不要返回 200，避免假装处理成功）
  //    - 找到 → 扣回 event.points 积分 / event.duration 时长（按你的业务表结构实现）
  // 3. 返回 200 表示已处理；非 200 时 RedeemShip 会在退货结果里标记通知发送失败
  await rollbackEntitlement(event.code, event.points, event.duration);
  return Response.json({ success: true });
}
```

Python 示例（解密部分）：

```python
import base64, hashlib, json
from cryptography.hazmat.primitives.ciphers.aead import AESGCM

key = hashlib.sha256(REDEEMSHIP_API_KEY.encode()).digest()
iv, ct = payload.split(".")
data = AESGCM(key).decrypt(
    base64.b64decode(iv), base64.b64decode(ct), None
)
event = json.loads(data)
```

---

## 四、安全要求（必须）

1. **必须用 API Key 解密成功才处理**，解密失败的请求一律拒绝（401），这是唯一的身份校验手段。
2. **不要相信未加密的明文字段**——RedeemShip 的通知里只有 `payload` 一个字段，任何明文声称"退货"的请求都不可信。
3. **幂等**：同一条退货通知理论上可能重试，按 `code` 回滚权益前先检查是否已回滚过（例如给核销记录加 `returned` 标记）。
4. 通知地址必须是公网可访问的 `http/https` 地址；`localhost` / 内网地址收不到通知。

## 五、验收清单

- [ ] 配置了 `return_notify_url` 后，在 RedeemShip「兑换记录」页对一条**已使用**的码点「退货」。
- [ ] 接入方接口收到请求，用 `REDEEMSHIP_API_KEY` 解密成功，拿到 `code / points / duration`。
- [ ] 接入方业务侧权益已扣回（积分减少或时长到期）。
- [ ] 用错误的 API Key 模拟请求 → 接入方拒绝（解密失败）。
- [ ] 未配置退货地址或码未使用时退货 → 不触发通知请求（未使用的码只会被作废）。
