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

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

## 错误处理

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