> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waffo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 移除收件人

> 从门店的商户通知收件人列表中移除一个地址

从门店的收件人列表中移除一个地址。该地址之后可以再次添加。

```
POST /v1/actions/store-notification-recipient/remove-recipient
```

**认证方式：** API Key（需 owner 或 admin 角色）

## 请求体

| 字段            | 类型     | 必填 | 说明                             |
| ------------- | ------ | -- | ------------------------------ |
| `storeId`     | string | 是  | 门店 ID（Short ID 格式 `STO_xxx`）   |
| `recipientId` | string | 是  | 真实收件人的 UUID。兜底条目的哨兵 id 会返回 404 |

## 请求示例

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -X POST https://api.waffo.com/v1/actions/store-notification-recipient/remove-recipient \
    -H "Content-Type: application/json" \
    -H "X-Merchant-Id: $WAFFO_MERCHANT_ID" \
    -H "X-Signature: ..." \
    -d '{
      "storeId": "STO_2aUyqjCzEIiEcYMKj7TZtw",
      "recipientId": "11111111-2222-3333-4444-555555555555"
    }'
  ```

  ```javascript JavaScript theme={"system"}
  const response = await fetch(
    "https://api.waffo.com/v1/actions/store-notification-recipient/remove-recipient",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Merchant-Id": process.env.WAFFO_MERCHANT_ID,
        "X-Signature": signature,
      },
      body: JSON.stringify({
        storeId: "STO_2aUyqjCzEIiEcYMKj7TZtw",
        recipientId: "11111111-2222-3333-4444-555555555555",
      }),
    },
  );

  const { data } = await response.json();
  ```
</CodeGroup>

## 成功响应 (200)

```json theme={"system"}
{
  "data": {
    "recipientId": "11111111-2222-3333-4444-555555555555",
    "removed": true
  }
}
```

<Warning>
  移除最后一个收件人返回 200 —— 服务端没有「至少保留一个」的守卫。此后该门店回退到 owner 的账号邮箱，开关取门店级的 `notify*`。
  兜底条目本身**不可移除**：它不是存储里的一行，传它的 `OWNER_<storeId>` 哨兵 id 会返回 404。要取代它，添加一个真实收件人即可。面向消费者的交易邮件是另一条链路，照常工作。
</Warning>

## 响应字段

| 字段            | 类型      | 说明                                       |
| ------------- | ------- | ---------------------------------------- |
| `recipientId` | string  | 被移除的收件人 UUID                             |
| `removed`     | boolean | 恒为 `true`；未命中返回 404，而不是 `removed: false` |

## 错误

> **重试策略：** 4xx 一律不要重试 —— 修正请求后重新提交。5xx 用指数退避重试（起始 5 秒，最多 3 次）。

| 状态码 | `errors[0].message`                                               | 含义                                 | 建议处理                                  |
| --- | ----------------------------------------------------------------- | ---------------------------------- | ------------------------------------- |
| 400 | `Missing required field: recipientId`                             | 未提供 `recipientId`                  | 修正请求体后重新提交                            |
| 400 | `Invalid recipient id format: expected UUID, got "..."`           | `recipientId` 既非 UUID 也非本店哨兵值      | 原样回传 add-recipient 或 GraphQL 返回的 `id` |
| 401 | `Missing merchantId in request context`                           | API Key 认证未解析出商户                   | 检查 API Key 请求头与签名                     |
| 403 | `Not authorized to manage notification recipients for this store` | 商户不是该门店的 `owner` 或 `admin`         | 确认商户在该门店的角色                           |
| 404 | `Notification recipient not found`                                | 该门店下没有这个 id 的收件人，或该 id 是不可删除的兜底哨兵值 | 重新拉取列表                                |
| 409 | `Notification recipients changed concurrently, please retry`      | 读与写之间有并发写入改动了列表                    | 重新拉取列表后重试                             |
| 500 | `Internal server error`                                           | 服务端未预期故障                           | 用指数退避重试（起始 5 秒，最多 3 次）                |