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/js-api/open/payment/sign.md.

sign

使用三方纯签约的签约单号拉起用户签约页面。

支持版本

前端库版本不低于 0.0.28。

支持平台

平台支持情况
Android支持
iOS支持
PC不支持
HarmonyOS不支持

支持场景

场景支持情况
页面支持
卡片支持

接入准备

前置条件

  • Android:需用户已登录并完成抖音账号绑定,且当前处于前台可见页面
  • iOS:需用户已登录并完成抖音账号绑定

使用说明

如果用户尚未绑定抖音账号,豆包可能先拉起账号绑定流程,再继续展示签约页面。

用户的最终签约状态必须以业务服务端查询签约单详情或收到的签约结果回调为准。 业务服务端还需要维护业务用户与签约 ID 的对应关系。

  • 调用会拉起签约 UI 并需要用户交互,请在用户明确触发签约的交互场景中调用;请勿在无用户操作的后台逻辑中调用。

调用方式

异步 API

sign(params: SignParams): Promise<SignResult>

入参

名称类型必填默认值约束说明
orderIdstring是--平台签约订单号。

传入 `createSignOrder` 成功后返回的 `authOrderId`,不要使用业务侧订单号或自行构造的值。

调用示例

import {
  createSignOrder,
  sign,
  type CreateSignOrderParams
} from '@doubao-dev/framework/api';

// 业务方自行实现:从业务服务端获取签约订单参数和签名;该函数不是 SDK API。
declare function getSignOrderParamsFromBusinessServer():
  Promise<CreateSignOrderParams>;
// 业务方自行实现:通过业务服务端确认最终签约状态;该函数不是 SDK API。
declare function refreshSignStatusFromBusinessServer(authOrderId: string): Promise<void>;

const orderParams = await getSignOrderParamsFromBusinessServer();
const orderResult = await createSignOrder(orderParams);

if ('authOrderId' in orderResult) {
  await sign({ orderId: orderResult.authOrderId });
  await refreshSignStatusFromBusinessServer(orderResult.authOrderId);
}

成功返回

名称类型必返说明
codenumber否错误码。
errLogIdstring否用于服务端排查问题的错误日志 ID。
errMsgstring否错误信息。
errNostring否错误编号。

返回示例

{}

错误处理

错误对象和通用错误码见 通用错误处理。

失败示例

{
  "errNo": 114,
  "errMsg": "operation cancelled"
}

错误码

errNoerrMsg平台触发条件处理建议
114operation cancelledAndroid用户在签约收银台中取消了签约操作用户需要时可再次调用 `sign` 重新发起签约。

通用错误码

errNoerrMsg说明平台
102internal error内部错误Android、iOS
103feature not support当前环境不支持该能力Android、iOS

平台差异

  • Android:需在前台可见的 Activity 中调用,应用退至后台或无有效页面时会返回失败。
  • Android:用户主动取消签约时返回顶层 errNo 114(operation cancelled);iOS 在该场景不返回顶层专属 errNo。

已知限制与注意事项

  • 失败结果不会作为 await 的返回值,需通过 catch 捕获并从错误对象的 data 字段读取 code、errNo、errMsg、errLogId。