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

分頁返回帳戶的儲值訂單，適合查找訂單 ID、查看支付狀態和對帳。

## 準備工作

建立 [Account Token](https://platform.acedata.cloud/documents/platform-token)，並從 `GET /api/v1/platform-tokens/me/` 取得目前帳戶 UUID。

```shell theme={null}
export PLATFORM_TOKEN='你的账户令牌'
export USER_ID='你的账户 UUID'
```

## 介面概覽

| 項 | 內容 |
| - | - |
| 方法 | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/orders/` |
| 鑑權 | Account Token，OAuth token 需 `orders:read` |
| 分頁 | `count` + `items` |

一般使用者必須傳入自己的 `user_id`；否則分頁遇到無權物件時可能返回 `403`。

## 查詢參數

| 參數 | 類型 | 必填 | 說明 |
| - | - | - | - |
| `user_id` | UUID | 一般使用者必填 | 訂單所屬帳戶；支援重複參數 |
| `pay_way` | string | 否 | 依支付方式篩選；支援重複或逗號分隔值 |
| `state` | string | 否 | 依狀態篩選；支援重複或逗號分隔值 |
| `created_at_from/to` | datetime | 否 | 建立時間範圍 |
| `finished_at_from/to` | datetime | 否 | 完成時間範圍 |
| `limit` / `offset` | integer | 否 | 分頁 |
| `ordering` | string | 否 | `created_at`、`-created_at`、`finished_at` 或 `-finished_at` |

目前列表不支援 `application_id`、`service_id`、`package_id`、`payment_method` 或 `tag` 篩選；支付方式欄位名稱為 `pay_way`。

```shell theme={null}
curl --get 'https://platform.acedata.cloud/api/v1/orders/' \
  --data-urlencode "user_id=${USER_ID}" \
  --data-urlencode 'state=Paid,Finished' \
  --data-urlencode 'pay_way=Stripe' \
  --data-urlencode 'limit=100' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

## 回應說明

回應為 `{count, items}`。線上列表項目包含 `id`、`user_id`、`application_id/application_ids`、`package_id/package_ids`、`price`、`amount`、`discount`、`remaining_amount`、`state`、`pay_way`、`pay_id`、`pay_url`、`finished_at`、`expired_at`、`invoice`、`metadata` 與時間欄位。

* 狀態實際為 `Pending`、`Paid`、`Finished`、`Expired`、`Failed`、`Refunded`，沒有 `Cancelled`。
* 欄位名稱是 `pay_way`、`finished_at`、`discount` 和 `price`，不是 `payment_method`、`paid_at`、`discount_rate` 或 `final_price`。
* `price` 是訂單記錄的最終價格；幣別和結算細節可能位於受控 metadata，不能僅憑支付方式自行推斷。

## 相關介面

* [建立儲值訂單](https://platform.acedata.cloud/documents/platform-order-create)
* [取得訂單詳情](https://platform.acedata.cloud/documents/platform-order-detail)
* [支付訂單](https://platform.acedata.cloud/documents/platform-order-pay)
* [重新整理訂單狀態](https://platform.acedata.cloud/documents/platform-order-refresh)


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