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, and this page is available as Markdown at /apps-plugin/docs/server-api/overview.md.

服务端 API 总览

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

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

开始前

调用服务端 API 前,请先完成以下准备:

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

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

请求域名

服务端 API 的请求域名为:

https://api.doubao-dev.com

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

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

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

获取应用级 Access Token

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

你的服务端
  → 使用 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 和手机号授权码都具有明确的用途,不能混用。它们通常有效时间较短,服务端收到后应尽快调用对应接口。

完整流程和参数说明见《登录接入(服务端)》和《登录相关 API》。

支付签名与服务端 API 鉴权

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

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

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

支付签名不能替代应用级 Access Token,应用级 Access Token 也不能用于验证支付回调。完整的支付流程见《支付接入(服务端)》,签名和验签规则见《支付相关 API》。

API 列表

访问令牌

接口方法路径调用凭证
获取应用级 Access TokenPOST/api/token/v1/developer/get_client_tokenAppID、AppSecret

完整的请求参数、响应字段和错误码见《登录相关 API》。

登录

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

完整的请求参数、手机号解密方式、授权范围和错误码见《登录相关 API》。

支付

接口方法路径调用凭证
查询订单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》。

进行中任务

接口方法路径调用凭证
创建进行中任务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 的响应通常包含以下字段:

{
  "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、请求耗时,以及脱敏后的业务单号。
  • 支付签名使用时间戳时,确保服务器时间准确。
  • 更新凭据或证书后,确认所有服务实例均已使用新配置。

相关文档