# 发送服务通知

## 基本信息

| 名称 | 描述 |
| --- | --- |
| HTTP Path | `/api/miniapp_notify/v1/developer/push_send` |
| HTTP Method | POST |
| Content-Type | `application/json` |
| 鉴权 | `X-DB-AccessToken` |

服务端使用 `business-templates.yaml.notice_templates[].template_id` 选择模板，使用 `biz_data` 提供模板变量。通知摘要 `brief` 在模板中必填并随首次通知发送，调用方不能在发送请求中临时覆盖；`brief` 中引用的变量同样由 `biz_data` 提供。不要传下游数字模板 ID 或 SupplierID。

## 请求头

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `X-DB-AccessToken` | 是 | 使用 AppID/AppSecret 获取的应用级 Token |
| `Content-Type` | 是 | 固定为 `application/json` |

## 请求体

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `open_id` | 是 | 当前应用下目标用户的 OpenID |
| `template_id` | 是 | `business-templates.yaml` 中开发者声明的通知模板 ID |
| `channel_info_list` | 是 | JSON 字符串；服务通知使用 `["service_notice"]` |
| `biz_data` | 是 | JSON 字符串；内容为 `map<string,string>`，变量与模板声明精确匹配 |
| `out_msg_id` | 建议 | 开发者侧稳定消息幂等键；同一业务事件重试时复用 |
| `jump_data` | 否 | JSON 字符串；通知点击后的智能服务内部页面信息，其中 `path` 必须以 `/` 开头 |
| `ext_data` | 否 | JSON 字符串；只有平台当前协议明确需要时才传，不自由透传敏感数据 |

请求示例：

```bash
curl -X POST 'https://hello.doubao-dev.com/api/miniapp_notify/v1/developer/push_send' \
  -H 'X-DB-AccessToken: <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "open_id": "<user_open_id>",
    "template_id": "milk_tea_ready",
    "channel_info_list": "[\"service_notice\"]",
    "biz_data": "{\"name\":\"珍珠奶茶\",\"pickup_code\":\"A018\",\"store_name\":\"中关村店\"}",
    "out_msg_id": "milk-tea-order-20260722-001-ready"
  }'
```

不要手工拼接 `biz_data`；使用语言 JSON 库序列化 `map<string,string>`，再把结果放入外层请求。

## 响应

通用响应字段：

| 字段 | 说明 |
| --- | --- |
| `code` | `0` 表示业务成功 |
| `msg` | 结果说明 |
| `log_id` | 平台排障 ID，日志中可保留 |
| `data.notice_id` | 平台服务通知 ID |
| `data.success_channel_list` | 成功渠道列表 |
| `data.fail_channel_list` | 失败渠道列表 |

示例：

```json
{
  "code": 0,
  "msg": "success",
  "log_id": "202607220001",
  "data": {
    "notice_id": "1234567890",
    "success_channel_list": ["service_notice"],
    "fail_channel_list": []
  }
}
```

只有 `code == 0` 且 `data.notice_id` 非空时标记发送成功。HTTP 200 但业务码非 0 时按业务失败处理。

## 运行时校验

- AccessToken 必须属于模板所在应用。
- `open_id` 必须属于同一应用下的目标用户。
- 模板必须存在，并在当前正式/预览环境中可用。
- `biz_data` 必须是字符串到字符串的 JSON 对象。
- 所有模板变量都必须提供，包括仅在 `brief` 中使用的变量；不允许额外变量或平台保留变量。
- `channel_info_list` 至少包含一个受支持渠道；服务通知使用 `service_notice`。
- `out_msg_id` 应在当前应用和业务事件范围内稳定唯一。

记录错误时保留脱敏模板 ID、幂等键、结果码和 `log_id`，不要记录 AccessToken、完整 OpenID 或完整 `biz_data`。