@doubao-dev/plugin-app-dev 0.0.0-stage → 0.0.40-canary-dea0ddc73-20261026073950

package/dist/skills/doubao-plugin-app/references/frontend/doubao-agentic-service-api/14-/346/224/257/344/273/230.md

@@ -0,0 +1,943 @@
+# 豆包应用插件的端能力 API: 支付
+
+订单创建、普通支付、平台免密支付、纯签约和支付并签约能力。
+
+[返回目录](./groups.md) | [返回速查](./quick-reference.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [createSignOrder](#createsignorder) | 创建三方纯签约流程所需的签约单。 |
+| [dypay](#dypay) | 发起抖音支付流程。 |
+| [getOrderPaymentWithSign](#getorderpaymentwithsign) | 使用预下单号和签约参数拉起支付并签约收银台。 |
+| [getOrderPayment](#getorderpayment) | 使用预下单返回的平台交易订单号拉起用户收银台。 |
+| [requestOrder](#requestorder) | 交易预下单，获取拉起收银台所需的平台交易订单号。 |
+| [sign](#sign) | 使用三方纯签约的签约单号拉起用户签约页面。 |
+
+## API 详情
+
+<a id="createsignorder"></a>
+### createSignOrder()
+
+# createSignOrder
+
+创建三方纯签约流程所需的签约单。
+
+## 支持版本
+
+前端库版本不低于 `0.0.28`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>支持</td></tr>
+</tbody>
+</table>
+
+## 使用说明
+
+这是纯签约流程的第一步。创建成功后，将返回的 `authOrderId` 传给 `sign` 拉起用户签约页面。
+此流程与支付按钮组件使用的豆包平台免密签约状态不是同一类签约关系。
+
+`data` 和 `dbAuthorization` 必须由业务服务端生成，不能在前端自行构造。
+用户的最终签约状态必须以业务服务端查询签约单详情或收到的签约结果回调为准。
+
+- 仅创建签约订单、不拉起签约 UI；请在服务端下发合法的 data 与 dbAuthorization 后调用。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+createSignOrder(params: CreateSignOrderParams): Promise<CreateSignOrderResult>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>data</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>三方纯签约的签约单请求数据。<br><br>该字段必须由业务服务端按签约能力的接入协议生成并返回，前端应原样透传。</td></tr>
+<tr><td><code>dbAuthorization</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>`data` 对应的请求签名。<br><br>该字段必须由业务服务端生成并返回，前端应原样透传。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import {
+  createSignOrder,
+  type CreateSignOrderParams
+} from '@doubao-dev/framework/api';
+
+// 业务方自行实现：从业务服务端获取签约订单参数和签名；该函数不是 SDK API。
+declare function getSignOrderParamsFromBusinessServer():
+  Promise<CreateSignOrderParams>;
+
+const orderParams = await getSignOrderParamsFromBusinessServer();
+const result = await createSignOrder(orderParams);
+
+console.log(authOrderId, logId);
+```
+
+## 成功返回
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>authOrderId</code></td><td><code>string</code></td><td>否</td><td>平台返回的签约单号，用于调用 `sign` 拉起签约页面。<br><br>该字段不是用户签约成功后产生的签约 ID。</td></tr>
+<tr><td><code>logId</code></td><td><code>string</code></td><td>否</td><td>用于服务端排查问题的日志 ID。</td></tr>
+<tr><td><code>errLogId</code></td><td><code>string</code></td><td>否</td><td>用于服务端排查问题的错误日志 ID。</td></tr>
+<tr><td><code>errMsg</code></td><td><code>string</code></td><td>否</td><td>错误信息。</td></tr>
+<tr><td><code>errNo</code></td><td><code>string</code></td><td>否</td><td>错误码。</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "authOrderId": "auth_order_123",
+  "logId": "20260519xxxx"
+}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 错误码
+
+#### 通用错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
+</thead>
+<tbody>
+<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
+</tbody>
+</table>
+
+## 已知限制与注意事项
+
+- 失败结果不会作为 await 的返回值，需通过 catch 捕获并从错误对象的 data 字段读取 errNo、errMsg、errLogId。
+
+<a id="dypay"></a>
+### dypay()
+
+# dypay
+
+发起抖音支付流程。
+
+## 扫码预览
+![扫码预览 dypay](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fpayment%252Fdypay%252Findex)
+
+## 支持版本
+
+前端库版本不低于 `0.1.0`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 前置条件
+
+- 调用前需由业务服务端生成合法的支付请求 data
+
+## 使用说明
+
+`data` 应由业务服务端生成，前端不要自行拼装或修改。
+
+支付流程返回不代表最终支付状态，最终结果应以业务服务端查询结果或支付回调为准。
+
+- 调用会进入支付流程，请在用户明确触发支付的交互场景中调用；不要在后台逻辑中自动调用。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+dypay(params: DypayParams): Promise<object>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>data</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>支付请求数据。<br><br>该字段应由业务服务端按支付接入协议生成，前端需原样透传。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { dypay } from '@doubao-dev/framework/api';
+
+// 业务方自行实现：从业务服务端获取支付请求数据；该函数不是 SDK API。
+declare function getDypayDataFromBusinessServer(): Promise<string>;
+
+const data = await getDypayDataFromBusinessServer();
+await dypay({ data });
+```
+
+## 成功返回
+
+无返回字段。
+
+<a id="getorderpaymentwithsign"></a>
+### getOrderPaymentWithSign()
+
+# getOrderPaymentWithSign
+
+使用预下单号和签约参数拉起支付并签约收银台。
+
+## 支持版本
+
+前端库版本不低于 `0.0.28`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 前置条件
+
+- **Android**：需用户已登录并完成抖音账号绑定，且当前处于前台可见页面
+- **iOS**：需用户已登录并完成抖音账号绑定
+
+## 使用说明
+
+此 API 属于三方支付并签约流程，与支付按钮组件根据平台签约状态发起的豆包平台免密支付不是同一流程。
+
+支付是主流程，签约是附带流程。如果签约参数无效，收银台会降级为仅支付。
+
+`signData` 和 `signDbAuthorization` 必须由业务服务端生成，不能在前端自行构造。
+此 API 成功不代表支付或签约成功，最终状态必须由业务服务端分别通过查询接口或结果回调确认。
+
+- 调用会拉起收银台并需要用户交互，请在用户明确触发支付的交互场景中调用；请勿在无用户操作的后台逻辑中调用。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+getOrderPaymentWithSign(params: GetOrderPaymentWithSignParams): Promise<GetOrderPaymentResult>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>orderId</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>平台交易订单号。<br><br>应使用 `requestOrder` 返回的真实预下单结果，不要传入业务侧订单号或自行构造的值。</td></tr>
+<tr><td><code>signData</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>支付并签约所需的签约参数。<br><br>该字段必须由业务服务端按支付并签约接入协议生成并返回，前端应原样透传。</td></tr>
+<tr><td><code>signDbAuthorization</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>`signData` 对应的请求签名。<br><br>该字段必须由业务服务端生成并与 `signData` 一并返回，前端应原样透传。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import {
+  getOrderPaymentWithSign,
+  type GetOrderPaymentWithSignParams
+} from '@doubao-dev/framework/api';
+
+// 业务方自行实现：从业务服务端获取支付并签约参数；该函数不是 SDK API。
+declare function getPaymentAndSignParamsFromBusinessServer():
+  Promise<GetOrderPaymentWithSignParams>;
+// 业务方自行实现：通过业务服务端分别确认支付与签约状态；该函数不是 SDK API。
+declare function refreshPaymentAndSignStatusFromBusinessServer(orderId: string): Promise<void>;
+
+const paymentParams = await getPaymentAndSignParamsFromBusinessServer();
+const result = await getOrderPaymentWithSign(paymentParams);
+console.log(result.orderId);
+await refreshPaymentAndSignStatusFromBusinessServer(result.orderId);
+```
+
+## 成功返回
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>logId</code></td><td><code>string</code></td><td>是</td><td>用于服务端排查问题的日志 ID。</td></tr>
+<tr><td><code>orderId</code></td><td><code>string</code></td><td>是</td><td>本次拉起收银台所使用的平台交易订单号。</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "orderId": "order-id",
+  "logId": "20260519xxxx"
+}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errNo": 114,
+  "errMsg": "operation cancelled"
+}
+```
+
+### 错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>114</code></td><td><code>operation cancelled</code></td><td>Android</td><td>用户在收银台中取消了支付操作</td><td>用户需要时可再次调用 `getOrderPaymentWithSign` 重新拉起收银台。</td></tr>
+</tbody>
+</table>
+
+#### 通用错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
+</thead>
+<tbody>
+<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
+<tr><td><code>103</code></td><td><code>feature not support</code></td><td>当前环境不支持该能力</td><td>Android、iOS</td></tr>
+</tbody>
+</table>
+
+## 平台差异
+
+- **Android**：需在前台可见的 Activity 中调用，应用退至后台或无有效页面时会返回失败。
+- **Android**：用户主动取消支付时返回顶层 errNo 114（operation cancelled）；iOS 在该场景不返回顶层专属 errNo。
+
+<a id="getorderpayment"></a>
+### getOrderPayment()
+
+# getOrderPayment
+
+使用预下单返回的平台交易订单号拉起用户收银台。
+
+## 支持版本
+
+前端库版本不低于 `0.0.28`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 前置条件
+
+- **Android**：需用户已登录并完成抖音账号绑定，且当前处于前台可见页面
+- **iOS**：需用户已登录并完成抖音账号绑定
+
+## 使用说明
+
+直接调用此 API 时，业务只传入 `orderId`，用于普通支付收银台流程。
+豆包平台免密支付应使用 `DoubaoPaymentButton`，由组件查询当前用户的免密可用状态，
+并在用户选择免密支付时携带平台返回的免密支付方式参数；业务不能自行构造该参数。
+当账号未绑定、发生换绑或平台判断免密不可用时，应以组件展示的普通支付路径为准。
+
+此 API 成功仅表示收银台已正常拉起并完成前端交互，不代表订单支付成功。
+最终支付状态必须以业务服务端查询订单详情的结果或业务服务端收到的支付结果回调为准。
+
+- 调用会拉起收银台并需要用户交互，请在用户明确触发支付的交互场景中调用；请勿在无用户操作的后台逻辑中调用。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+getOrderPayment(params: GetOrderPaymentParams): Promise<GetOrderPaymentResult>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>orderId</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>平台交易订单号，长度不超过 64 字节。<br><br>传入 `requestOrder` 预下单成功后返回的 `orderId`，不要使用业务侧订单号或自行构造的值。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import {
+  getOrderPayment,
+  requestOrder,
+  type RequestOrderParams
+} from '@doubao-dev/framework/api';
+
+// 业务方自行实现：从业务服务端获取预下单参数和签名；该函数不是 SDK API。
+declare function getOrderParamsFromBusinessServer(): Promise<RequestOrderParams>;
+// 业务方自行实现：通过业务服务端确认并刷新最终支付状态；该函数不是 SDK API。
+declare function refreshOrderStatusFromBusinessServer(orderId: string): Promise<void>;
+
+const orderParams = await getOrderParamsFromBusinessServer();
+const { orderId } = await requestOrder(orderParams);
+const { logId } = await getOrderPayment({ orderId });
+
+console.log(orderId, logId);
+await refreshOrderStatusFromBusinessServer(orderId);
+```
+
+## 成功返回
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>logId</code></td><td><code>string</code></td><td>是</td><td>用于服务端排查问题的日志 ID。</td></tr>
+<tr><td><code>orderId</code></td><td><code>string</code></td><td>是</td><td>本次拉起收银台所使用的平台交易订单号。</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "orderId": "order-id",
+  "logId": "20260519xxxx"
+}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errNo": 114,
+  "errMsg": "operation cancelled"
+}
+```
+
+### 错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>114</code></td><td><code>operation cancelled</code></td><td>Android</td><td>用户在收银台中取消了支付操作</td><td>用户需要时可再次调用 `getOrderPayment` 重新拉起收银台。</td></tr>
+</tbody>
+</table>
+
+#### 通用错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
+</thead>
+<tbody>
+<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
+<tr><td><code>103</code></td><td><code>feature not support</code></td><td>当前环境不支持该能力</td><td>Android、iOS</td></tr>
+</tbody>
+</table>
+
+## 平台差异
+
+- **Android**：需在前台可见的 Activity 中调用，应用退至后台或无有效页面时会返回失败。
+- **Android**：用户主动取消支付时返回顶层 errNo 114（operation cancelled）；iOS 在该场景不返回顶层专属 errNo。
+
+<a id="requestorder"></a>
+### requestOrder()
+
+# requestOrder
+
+交易预下单，获取拉起收银台所需的平台交易订单号。
+
+## 支持版本
+
+前端库版本不低于 `0.0.28`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>支持</td></tr>
+</tbody>
+</table>
+
+## 使用说明
+
+调用前，前端应先请求业务服务端，由业务服务端构造下单参数并完成签名。
+不要在前端生成 `data` 或 `dbAuthorization`，也不要把证书或私钥下发到前端。
+
+使用 `DoubaoPaymentButton` 时，应在组件请求订单号的回调中获取或创建预下单，
+再将本 API 返回的 `orderId` 交给组件继续普通支付或平台免密支付流程。
+
+- 请在服务端下发合法的 data 与 dbAuthorization 后调用。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+requestOrder(params: RequestOrderParams): Promise<RequestOrderResult>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>data</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>下单参数 JSON 字符串。<br><br>该字段必须由业务服务端按支付接入协议构造并返回，前端应原样透传，不要在客户端自行拼装。<br>JSON 必填字段包括 `skuList`、`outOrderNo`、`merchantUid`、`totalAmount`、`orderName` 和<br>`orderDesc`；可选字段包括 `currency`、`payExpireSeconds` 和 `payNotifyUrl`。<br><br>`skuList` 每项必填 `skuId`、`price`、`quantity`、`title` 和 `totalAmount`。<br>金额单位由 `currency` 决定；当前 `CNY` 使用分。`outOrderNo` 不超过 64 字节，<br>`quantity` 取值范围为 1 到 100，`title` 不超过 256 字节。<br>`payExpireSeconds` 不传或传 0 时使用 300 秒，最长不超过 48 小时；<br>`payNotifyUrl` 必须是 HTTPS 地址。</td></tr>
+<tr><td><code>dbAuthorization</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>`data` 对应的请求签名。<br><br>该字段必须由业务服务端使用已配置的证书生成并返回，前端应原样透传。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import {
+  requestOrder,
+  type RequestOrderParams
+} from '@doubao-dev/framework/api';
+
+// 业务方自行实现：从业务服务端获取预下单参数和签名；该函数不是 SDK API。
+declare function getOrderParamsFromBusinessServer(): Promise<RequestOrderParams>;
+
+const orderParams = await getOrderParamsFromBusinessServer();
+const { orderId, logId } = await requestOrder(orderParams);
+
+console.log(orderId, logId);
+```
+
+## 成功返回
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>logId</code></td><td><code>string</code></td><td>是</td><td>用于服务端排查问题的日志 ID。</td></tr>
+<tr><td><code>orderId</code></td><td><code>string</code></td><td>是</td><td>平台交易订单号，用于调用 `getOrderPayment` 拉起收银台。</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "orderId": "order-id",
+  "logId": "20260519xxxx"
+}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 错误码
+
+#### 通用错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
+</thead>
+<tbody>
+<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
+</tbody>
+</table>
+
+## 已知限制与注意事项
+
+- 失败结果不会作为 await 的返回值，需通过 catch 捕获并从错误对象的 data 字段读取 errNo、errMsg、errLogId。
+
+<a id="sign"></a>
+### sign()
+
+# sign
+
+使用三方纯签约的签约单号拉起用户签约页面。
+
+## 支持版本
+
+前端库版本不低于 `0.0.28`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 前置条件
+
+- **Android**：需用户已登录并完成抖音账号绑定，且当前处于前台可见页面
+- **iOS**：需用户已登录并完成抖音账号绑定
+
+## 使用说明
+
+如果用户尚未绑定抖音账号，豆包可能先拉起账号绑定流程，再继续展示签约页面。
+
+用户的最终签约状态必须以业务服务端查询签约单详情或收到的签约结果回调为准。
+业务服务端还需要维护业务用户与签约 ID 的对应关系。
+
+- 调用会拉起签约 UI 并需要用户交互，请在用户明确触发签约的交互场景中调用；请勿在无用户操作的后台逻辑中调用。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+sign(params: SignParams): Promise<SignResult>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>orderId</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>平台签约订单号。<br><br>传入 `createSignOrder` 成功后返回的 `authOrderId`，不要使用业务侧订单号或自行构造的值。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+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);
+}
+```
+
+## 成功返回
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>code</code></td><td><code>number</code></td><td>否</td><td>错误码。</td></tr>
+<tr><td><code>errLogId</code></td><td><code>string</code></td><td>否</td><td>用于服务端排查问题的错误日志 ID。</td></tr>
+<tr><td><code>errMsg</code></td><td><code>string</code></td><td>否</td><td>错误信息。</td></tr>
+<tr><td><code>errNo</code></td><td><code>string</code></td><td>否</td><td>错误编号。</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errNo": 114,
+  "errMsg": "operation cancelled"
+}
+```
+
+### 错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>114</code></td><td><code>operation cancelled</code></td><td>Android</td><td>用户在签约收银台中取消了签约操作</td><td>用户需要时可再次调用 `sign` 重新发起签约。</td></tr>
+</tbody>
+</table>
+
+#### 通用错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
+</thead>
+<tbody>
+<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
+<tr><td><code>103</code></td><td><code>feature not support</code></td><td>当前环境不支持该能力</td><td>Android、iOS</td></tr>
+</tbody>
+</table>
+
+## 平台差异
+
+- **Android**：需在前台可见的 Activity 中调用，应用退至后台或无有效页面时会返回失败。
+- **Android**：用户主动取消签约时返回顶层 errNo 114（operation cancelled）；iOS 在该场景不返回顶层专属 errNo。
+
+## 已知限制与注意事项
+
+- 失败结果不会作为 await 的返回值，需通过 catch 捕获并从错误对象的 data 字段读取 code、errNo、errMsg、errLogId。
+
+## 相关类型
+
+<a id="createsignorderparams"></a>
+### CreateSignOrderParams
+
+#### Properties
+
+• **data**: `string` - 三方纯签约的签约单请求数据。 该字段必须由业务服务端按签约能力的接入协议生成并返回，前端应原样透传
+• **dbAuthorization**: `string` - data 对应的请求签名。 该字段必须由业务服务端生成并返回，前端应原样透传
+
+<a id="createsignorderresult"></a>
+### CreateSignOrderResult
+
+#### Type
+
+`CreateSignOrderSuccessResult | CreateSignOrderFailResult`
+
+<a id="createsignordersuccessresult"></a>
+### CreateSignOrderSuccessResult
+
+#### Properties
+
+• **authOrderId**: `string` - 平台返回的签约单号，用于调用 sign 拉起签约页面。 该字段不是用户签约成功后产生的签约 ID
+• **logId**: `string` - 用于服务端排查问题的日志 ID
+
+<a id="createsignorderfailresult"></a>
+### CreateSignOrderFailResult
+
+#### Properties
+
+• **errNo**: `string` - 错误码
+• **errMsg**: `string` - 错误信息
+• **errLogId?**: `string` - 用于服务端排查问题的错误日志 ID
+
+<a id="dypayparams"></a>
+### DypayParams
+
+#### Properties
+
+• **data**: `string` - 支付请求数据。 该字段应由业务服务端按支付接入协议生成，前端需原样透传
+
+<a id="getorderpaymentwithsignparams"></a>
+### GetOrderPaymentWithSignParams
+
+#### Properties
+
+• **orderId**: `string` - 平台交易订单号。 应使用 requestOrder 返回的真实预下单结果，不要传入业务侧订单号或自行构造的值
+• **signData**: `string` - 支付并签约所需的签约参数。 该字段必须由业务服务端按支付并签约接入协议生成并返回，前端应原样透传
+• **signDbAuthorization**: `string` - signData 对应的请求签名。 该字段必须由业务服务端生成并与 signData 一并返回，前端应原样透传
+
+<a id="getorderpaymentresult"></a>
+### GetOrderPaymentResult
+
+#### Properties
+
+• **orderId**: `string` - 本次拉起收银台所使用的平台交易订单号
+• **logId**: `string` - 用于服务端排查问题的日志 ID
+
+<a id="getorderpaymentparams"></a>
+### GetOrderPaymentParams
+
+#### Properties
+
+• **orderId**: `string` - 平台交易订单号，长度不超过 64 字节。 传入 requestOrder 预下单成功后返回的 orderId，不要使用业务侧订单号或自行构造的值
+
+<a id="requestorderparams"></a>
+### RequestOrderParams
+
+#### Properties
+
+• **data**: `string` - 下单参数 JSON 字符串。 该字段必须由业务服务端按支付接入协议构造并返回，前端应原样透传，不要在客户端自行拼装。 JSON 必填字段包括 skuList、outOrderNo、merchantUid、totalAmount、orderName 和 orderDesc；可选字段包括 currency、payExpireSeconds 和 payNotifyUrl。 skuList 每项必填 skuId、price、quantity、title 和 totalAmount。 金额单位由 currency 决定；当前 CNY 使用分。outOrderNo 不超过 64 字节， quantity 取值范围为 1 到 100，title 不超过 256 字节。 payExpireSeconds 不传或传 0 时使用 300 秒，最长不超过 48 小时； payNotifyUrl 必须是 HTTPS 地址
+• **dbAuthorization**: `string` - data 对应的请求签名。 该字段必须由业务服务端使用已配置的证书生成并返回，前端应原样透传
+
+<a id="requestorderresult"></a>
+### RequestOrderResult
+
+#### Properties
+
+• **orderId**: `string` - 平台交易订单号，用于调用 getOrderPayment 拉起收银台
+• **logId**: `string` - 用于服务端排查问题的日志 ID
+
+<a id="signparams"></a>
+### SignParams
+
+#### Properties
+
+• **orderId**: `string` - 平台签约订单号。 传入 createSignOrder 成功后返回的 authOrderId，不要使用业务侧订单号或自行构造的值
+
+<a id="signresult"></a>
+### SignResult
+
+#### Type
+
+`SignSuccessResult | SignFailResult`
+
+<a id="signsuccessresult"></a>
+### SignSuccessResult
+
+签约页面流程正常返回时无业务字段。 该结果不代表用户已经签约成功，最终签约状态必须由业务服务端确认。
+
+#### Type
+
+`Record<string, never>`
+
+<a id="signfailresult"></a>
+### SignFailResult
+
+#### Properties
+
+• **code**: `number` - 错误码
+• **errNo**: `string` - 错误编号
+• **errMsg**: `string` - 错误信息
+• **errLogId?**: `string` - 用于服务端排查问题的错误日志 ID