> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# 建立 AceDataCloud 平台儲值訂單

> Platform 整合指南 - Ace Data Cloud

為一個或多個 Application 建立待付款訂單。建立會寫入訂單，但不會自動完成付款；付款前應核對回應中的 `price`、方案和 Application。

## 準備工作

* 建立 [Account Token](https://platform.acedata.cloud/documents/platform-token)。
* 從 [Application 清單](https://platform.acedata.cloud/documents/platform-application-list)取得 `application_id`。
* 從 [服務詳情](https://platform.acedata.cloud/documents/platform-service-detail)的 `packages` 中選擇與 Application 類型相符且可購買的 `package_id`。

```shell theme={null}
export PLATFORM_TOKEN='你的帳戶權杖'
export APPLICATION_ID='你的 Application ID'
export PACKAGE_ID='你的 Package ID'
```

## 介面概覽

| 項目 | 內容 |
| - | - |
| 方法 | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/orders/` |
| 驗證 | Account Token，OAuth token 需 `orders:write` |
| Body | JSON |

## 請求體

單一 Application 訂單使用 `application_id` + `package_id`；批次訂單使用長度對應的 `application_ids` + `package_ids`。一般訂單在後續 `/pay/` 請求中選擇付款方式。iOS 內購訂單建立時傳入 `pay_way: "AppleIAP"`，且只能選擇一個帶有 `metadata.apple_product_id` 和 `metadata.apple_price` 的 Usage 方案。Apple 內購使用獨立的美元預設價格，不疊加會員折扣、付款方式折扣或網站加價；其他地區的本幣扣款金額以 Apple 付款確認頁為準。

```shell theme={null}
curl -X POST 'https://platform.acedata.cloud/api/v1/orders/' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d "{\"application_id\":\"${APPLICATION_ID}\",\"package_id\":\"${PACKAGE_ID}\"}"
```

## 回應說明

成功回傳 `201` 和新建立的 Order 物件。關鍵欄位包括 `id`、`price`、`discount`、`state`、`application_id/application_ids`、`package_id/package_ids`、`expired_at` 與時間欄位。新訂單通常是 `Pending`，接著呼叫[支付訂單](https://platform.acedata.cloud/documents/platform-order-pay)。

* `price` 是伺服器根據方案、網站加價和折扣計算後的應付金額；不要由用戶端自行計算。
* Package 與 Application 服務或類型不相符時回傳 `400`。
* 免費且由系統管理的 Package 不能透過公開訂單介面自行領取。
* 為不屬於目前帳戶的 Application 建立訂單會被拒絕。

## 相關介面

* [取得訂單清單](https://platform.acedata.cloud/documents/platform-order-list)
* [取得訂單詳情](https://platform.acedata.cloud/documents/platform-order-detail)
* [支付訂單](https://platform.acedata.cloud/documents/platform-order-pay)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.