> For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt.

# 服务端 API 总览

当豆包应用插件需要识别用户、处理支付订单、更新进行中任务或发送服务通知时，你的服务端可以调用豆包开放平台提供的服务端 API。

这些 API 应由你的后端服务调用，不应由应用插件前端直接调用。AppSecret、访问令牌、刷新令牌和支付私钥等敏感信息只能保存在服务端，不要写入前端源码、Manifest、Skill 或公开的代码仓库。

## 开始前

调用服务端 API 前，请先完成以下准备：

1. 在豆包开发者平台创建应用插件。
2. 在应用的开发设置中获取 AppID 和 AppSecret。
3. 准备一套可以向豆包开放平台发起 HTTPS 请求的后端服务。
4. 将 AppSecret 等敏感信息保存到服务端的密钥管理系统或受保护的环境变量中。

AppID 用于标识你的应用插件；AppSecret 用于证明调用方是该应用的开发者。AppSecret 不应发送给应用插件前端，也不应随普通业务接口重复传递。

## 请求域名

服务端 API 的请求域名为：

```text
https://api.doubao-dev.com
```

调用接口时，将请求域名与接口路径拼接为完整 URL。例如，“获取应用级 Access Token”接口的完整请求地址为：

```text
https://api.doubao-dev.com/api/token/v1/developer/get_client_token
```

每个接口的 HTTP 方法和路径见下方 API 列表；请求参数和完整示例见对应的接口文档。

## 获取应用级 Access Token

支付、手机号、进行中任务和服务通知等接口，需要使用应用级 Access Token 验证应用身份。你的服务端需要先使用 AppID 和 AppSecret 调用“获取应用级 Access Token”接口，再携带返回的令牌调用这些业务接口。

```text
你的服务端
  → 使用 AppID 和 AppSecret 获取应用级 Access Token
  → 缓存 Access Token
  → 在 X-DB-AccessToken 请求头中携带 Access Token
  → 调用所需的业务接口
```

应用级 Access Token 的响应字段名为 `access_token`。请按照响应中的 `expires_in` 缓存和更新令牌，不要在每次业务请求前重新获取。多个服务实例共用同一应用凭证时，应避免同时刷新令牌。

## 了解不同的身份凭证

不同接口需要的凭证不同。调用前，请先确认接口需要使用哪种凭证。

| 凭证                | 用途                     | 如何获得                                                  | 如何传递                    |
| ----------------- | ---------------------- | ----------------------------------------------------- | ----------------------- |
| AppID 和 AppSecret | 验证应用身份，并换取访问令牌或用户标识    | 在豆包开发者平台的应用开发设置中获取                                    | 按接口要求放入请求体              |
| 应用级 Access Token  | 调用支付、手机号、任务和服务通知等应用级接口 | 使用 AppID 和 AppSecret 调用 `get_client_token`            | 请求头 `X-DB-AccessToken`  |
| 用户会话 Token        | 将进行中任务等操作关联到当前豆包用户会话   | 豆包调用你的应用插件 MCP 工具时，通过 `X-DB-SESSION-TOKEN` 请求头传给你的服务端 | 请求头 `X-DB-SessionToken` |

## 用户登录与授权

- 如果你只需要识别当前用户，使用应用插件获得的 `login_code` 换取该用户在当前应用下的 `open_id`。
- 如果你需要获取用户手机号，先在应用插件中获得一次性的手机号授权码，再由服务端调用手机号接口。

`login_code`、`auth_code` 和手机号授权码都具有明确的用途，不能混用。它们通常有效时间较短，服务端收到后应尽快调用对应接口。

完整流程和参数说明见[《登录接入（服务端）》](/apps-plugin/docs/backend-development/login.md)和[《登录相关 API》](/apps-plugin/docs/server-api/login.md)。

## 支付签名与服务端 API 鉴权

查询订单、创建退款、查询退款、履约通知和协议支付等服务端支付 API，使用应用级 Access Token 鉴权。

支付证书和签名用于以下两类场景：

- 你的服务端为应用插件前端生成预下单参数和 `dbAuthorization`，前端将其传给支付 API。
- 豆包开放平台向你的回调地址发送支付、退款、签约或代扣结果时，在 `X-DB-Authorization` 请求头中携带签名；你的服务端需要使用平台证书验签。

支付签名不能替代应用级 Access Token，应用级 Access Token 也不能用于验证支付回调。完整的支付流程见[《支付接入（服务端）》](/apps-plugin/docs/backend-development/payment.md)，签名和验签规则见[《支付相关 API》](/apps-plugin/docs/server-api/payment.md)。

## API 列表

### 访问令牌

| 接口                 | 方法   | 路径                                         | 调用凭证            |
| ------------------ | ---- | ------------------------------------------ | --------------- |
| 获取应用级 Access Token | POST | `/api/token/v1/developer/get_client_token` | AppID、AppSecret |

完整的请求参数、响应字段和错误码见[《登录相关 API》](/apps-plugin/docs/server-api/login.md)。

### 登录

| 接口          | 方法   | 路径                                             | 调用凭证                         |
| ----------- | ---- | ---------------------------------------------- | ---------------------------- |
| 获取用户 OpenID | POST | `/api/login/v1/developer/get_openid`           | AppID、AppSecret、`login_code` |
| 获取用户加密手机号   | POST | `/api/login/v1/developer/get_user_phonenumber` | 应用级 Access Token             |

完整的请求参数、手机号解密方式、授权范围和错误码见[《登录相关 API》](/apps-plugin/docs/server-api/login.md)。

### 支付

| 接口       | 方法   | 路径                                                  | 调用凭证             |
| -------- | ---- | --------------------------------------------------- | ---------------- |
| 查询订单     | POST | `/api/trade_basic/v1/developer/order_query`         | 应用级 Access Token |
| 创建退款     | POST | `/api/trade_basic/v1/developer/refund_create`       | 应用级 Access Token |
| 查询退款     | POST | `/api/trade_basic/v1/developer/refund_query`        | 应用级 Access Token |
| 通知履约完成   | POST | `/api/trade_basic/v1/developer/fulfill_push_finish` | 应用级 Access Token |
| 查询签约订单   | POST | `/api/trade_basic/v1/developer/query_sign_order`    | 应用级 Access Token |
| 解除签约     | POST | `/api/trade_basic/v1/developer/terminate_sign`      | 应用级 Access Token |
| 创建协议支付订单 | POST | `/api/trade_basic/v1/developer/create_sign_pay`     | 应用级 Access Token |
| 查询协议支付订单 | POST | `/api/trade_basic/v1/developer/query_sign_pay`      | 应用级 Access Token |
| 关闭协议支付订单 | POST | `/api/trade_basic/v1/developer/close_sign_pay`      | 应用级 Access Token |

上表列出的是由你的服务端主动调用的接口。支付结果、退款结果、签约结果和代扣结果由豆包开放平台发送到你配置的回调地址，因此不在上表中。回调地址配置、请求字段、验签方式和重试规则见[《支付相关 API》](/apps-plugin/docs/server-api/payment.md)。

### 进行中任务

| 接口      | 方法   | 路径                                                | 调用凭证                        |
| ------- | ---- | ------------------------------------------------- | --------------------------- |
| 创建进行中任务 | POST | `/api/task/v1/developer/create_remote_task`       | 应用级 Access Token、用户会话 Token |
| 推送任务上下文 | POST | `/api/task/v1/developer/push_remote_task_context` | 应用级 Access Token            |
| 更新进行中任务 | POST | `/api/task/v1/developer/update_remote_task`       | 应用级 Access Token            |

创建任务成功后，接口会返回用于后续更新该任务的凭证。请妥善保存该凭证，并按照《进行中任务 API》更新任务上下文和状态。

### 服务通知

| 接口     | 方法   | 路径                                           | 调用凭证             |
| ------ | ---- | -------------------------------------------- | ---------------- |
| 发送服务通知 | POST | `/api/miniapp_notify/v1/developer/push_send` | 应用级 Access Token |

发送通知前，需要先在豆包开发者平台完成通知模板等相关配置。接口参数和使用限制见《服务通知 API》。

### 卡片

| 接口     | 方法   | 路径                               | 调用凭证             |
| ------ | ---- | -------------------------------- | ---------------- |
| 刷新卡片实例 | POST | `/api/card/v1/developer/refresh` | 应用级 Access Token |

通过 `refresh_key` 批量刷新已下发给用户的应用插件卡片数据，无需用户重新发起对话。接口参数、刷新结果和错误码见《卡片相关 API》。

## 处理接口响应

服务端 API 的响应通常包含以下字段：

```json
{
  "code": 0,
  "msg": "success",
  "data": {},
  "log_id": "20260716120000ABCDEF123456"
}
```

| 字段       | 说明                           |
| -------- | ---------------------------- |
| `code`   | 业务处理结果。`0` 表示成功，非 `0` 表示调用失败 |
| `msg`    | 结果说明，可用于排查问题，不建议作为程序分支判断条件   |
| `data`   | 接口返回的业务数据；结构因接口而异            |
| `log_id` | 本次请求的唯一标识，联系技术支持时需要提供        |

收到响应后，应同时检查 HTTP 状态和响应中的 `code`：

1. 网络错误或非成功的 HTTP 状态表示请求没有正常完成。
2. HTTP 请求完成后，只有 `code` 为 `0` 才表示业务处理成功。
3. 保存失败响应中的 `log_id`，用于日志关联和问题排查。

## 重试请求

只有在确认接口支持安全重试后，才能自动重试请求。

- 参数错误、凭证无效、权限不足和签名失败不会通过原样重试恢复，应先修正请求。
- 网络中断、连接超时或服务暂时不可用时，可以根据接口的幂等要求进行有限次数的重试，并使用递增的等待时间。
- 创建订单、退款等请求超时后，结果可能已经生效。再次提交前，应先调用对应的查询接口确认当前状态。
- 使用开发者订单号、退款单号或接口指定的幂等字段防止重复处理。

## 安全与问题排查

- 不要在前端、Manifest、Skill、代码仓库或普通日志中保存 AppSecret、Access Token、Refresh Token、支付私钥和完整签名。
- 日志中不要记录完整手机号、支付参数或其他用户敏感信息。
- 为服务端请求设置连接超时和响应超时，避免请求长时间占用服务资源。
- 记录接口路径、HTTP 状态、业务 `code`、`log_id`、请求耗时，以及脱敏后的业务单号。
- 支付签名使用时间戳时，确保服务器时间准确。
- 更新凭据或证书后，确认所有服务实例均已使用新配置。

## 相关文档

- [《登录接入（服务端）》](/apps-plugin/docs/backend-development/login.md)：从应用插件获取登录码，到服务端识别用户的完整流程。
- [《登录相关 API》](/apps-plugin/docs/server-api/login.md)：访问令牌、OpenID、手机号的接口说明。
- [《支付接入（服务端）》](/apps-plugin/docs/backend-development/payment.md)：商户开户、证书配置、支付、回调、退款和履约流程。
- [《支付相关 API》](/apps-plugin/docs/server-api/payment.md)：支付接口、回调协议、签名和支付错误码。
- [《卡片相关 API》](/apps-plugin/docs/server-api/card.md)：卡片刷新接口、刷新结果和错误码。
