服务端 API 总览
当豆包应用插件需要识别用户、处理支付订单、更新进行中任务或发送服务通知时,你的服务端可以调用豆包开放平台提供的服务端 API。
这些 API 应由你的后端服务调用,不应由应用插件前端直接调用。AppSecret、访问令牌、刷新令牌和支付私钥等敏感信息只能保存在服务端,不要写入前端源码、Manifest、Skill 或公开的代码仓库。
开始前
调用服务端 API 前,请先完成以下准备:
- 在豆包开发者平台创建应用插件。
- 在应用的开发设置中获取 AppID 和 AppSecret。
- 准备一套可以向豆包开放平台发起 HTTPS 请求的后端服务。
- 将 AppSecret 等敏感信息保存到服务端的密钥管理系统或受保护的环境变量中。
AppID 用于标识你的应用插件;AppSecret 用于证明调用方是该应用的开发者。AppSecret 不应发送给应用插件前端,也不应随普通业务接口重复传递。
请求域名
服务端 API 的请求域名为:
调用接口时,将请求域名与接口路径拼接为完整 URL。例如,“获取应用级 Access Token”接口的完整请求地址为:
每个接口的 HTTP 方法和路径见下方 API 列表;请求参数和完整示例见对应的接口文档。
获取应用级 Access Token
支付、手机号、进行中任务和服务通知等接口,需要使用应用级 Access Token 验证应用身份。你的服务端需要先使用 AppID 和 AppSecret 调用“获取应用级 Access Token”接口,再携带返回的令牌调用这些业务接口。
应用级 Access Token 的响应字段名为 access_token。请按照响应中的 expires_in 缓存和更新令牌,不要在每次业务请求前重新获取。多个服务实例共用同一应用凭证时,应避免同时刷新令牌。
了解不同的身份凭证
不同接口需要的凭证不同。调用前,请先确认接口需要使用哪种凭证。
用户登录与授权
- 如果你只需要识别当前用户,使用应用插件获得的
login_code换取该用户在当前应用下的open_id。 - 如果你需要获取用户手机号,先在应用插件中获得一次性的手机号授权码,再由服务端调用手机号接口。
login_code、auth_code 和手机号授权码都具有明确的用途,不能混用。它们通常有效时间较短,服务端收到后应尽快调用对应接口。
完整流程和参数说明见《登录接入(服务端)》和《登录相关 API》。
支付签名与服务端 API 鉴权
查询订单、创建退款、查询退款、履约通知和协议支付等服务端支付 API,使用应用级 Access Token 鉴权。
支付证书和签名用于以下两类场景:
- 你的服务端为应用插件前端生成预下单参数和
dbAuthorization,前端将其传给支付 API。 - 豆包开放平台向你的回调地址发送支付、退款、签约或代扣结果时,在
X-DB-Authorization请求头中携带签名;你的服务端需要使用平台证书验签。
支付签名不能替代应用级 Access Token,应用级 Access Token 也不能用于验证支付回调。完整的支付流程见《支付接入(服务端)》,签名和验签规则见《支付相关 API》。
API 列表
访问令牌
完整的请求参数、响应字段和错误码见《登录相关 API》。
登录
完整的请求参数、手机号解密方式、授权范围和错误码见《登录相关 API》。
支付
上表列出的是由你的服务端主动调用的接口。支付结果、退款结果、签约结果和代扣结果由豆包开放平台发送到你配置的回调地址,因此不在上表中。回调地址配置、请求字段、验签方式和重试规则见《支付相关 API》。
进行中任务
创建任务成功后,接口会返回用于后续更新该任务的凭证。请妥善保存该凭证,并按照《进行中任务 API》更新任务上下文和状态。
服务通知
发送通知前,需要先在豆包开发者平台完成通知模板等相关配置。接口参数和使用限制见《服务通知 API》。
卡片
通过 refresh_key 批量刷新已下发给用户的应用插件卡片数据,无需用户重新发起对话。接口参数、刷新结果和错误码见《卡片相关 API》。
处理接口响应
服务端 API 的响应通常包含以下字段:
收到响应后,应同时检查 HTTP 状态和响应中的 code:
- 网络错误或非成功的 HTTP 状态表示请求没有正常完成。
- HTTP 请求完成后,只有
code为0才表示业务处理成功。 - 保存失败响应中的
log_id,用于日志关联和问题排查。
重试请求
只有在确认接口支持安全重试后,才能自动重试请求。
- 参数错误、凭证无效、权限不足和签名失败不会通过原样重试恢复,应先修正请求。
- 网络中断、连接超时或服务暂时不可用时,可以根据接口的幂等要求进行有限次数的重试,并使用递增的等待时间。
- 创建订单、退款等请求超时后,结果可能已经生效。再次提交前,应先调用对应的查询接口确认当前状态。
- 使用开发者订单号、退款单号或接口指定的幂等字段防止重复处理。
安全与问题排查
- 不要在前端、Manifest、Skill、代码仓库或普通日志中保存 AppSecret、Access Token、Refresh Token、支付私钥和完整签名。
- 日志中不要记录完整手机号、支付参数或其他用户敏感信息。
- 为服务端请求设置连接超时和响应超时,避免请求长时间占用服务资源。
- 记录接口路径、HTTP 状态、业务
code、log_id、请求耗时,以及脱敏后的业务单号。 - 支付签名使用时间戳时,确保服务器时间准确。
- 更新凭据或证书后,确认所有服务实例均已使用新配置。
相关文档
- 《登录接入(服务端)》:从应用插件获取登录码,到服务端识别用户的完整流程。
- 《登录相关 API》:访问令牌、OpenID、手机号的接口说明。
- 《支付接入(服务端)》:商户开户、证书配置、支付、回调、退款和履约流程。
- 《支付相关 API》:支付接口、回调协议、签名和支付错误码。
- 《卡片相关 API》:卡片刷新接口、刷新结果和错误码。