> 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.

# 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"
}
```

## 错误处理

错误对象和通用错误码见 [通用错误处理](/apps-plugin/docs/js-api/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。
