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

主動查詢訂單對應付款方式的最新狀態並同步至平台。該請求可能存取付款服務並變更訂單狀態，僅在回呼延遲或需要立即確認時使用。

## 準備工作

* 使用 [Account Token](https://platform.acedata.cloud/documents/platform-token)。
* 從[訂單列表](https://platform.acedata.cloud/documents/platform-order-list)取得本人訂單 ID。

```shell theme={null}
export PLATFORM_TOKEN='你的帳戶權杖'
export ORDER_ID='你的訂單 ID'
```

## 介面概覽

| 項 | 內容 |
| - | - |
| 方法 | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/orders/{order_id}/refresh/` |
| 驗證 | 訂單擁有者或超級管理員 |
| Body | 通常為空；PayPal 回呼情境可能需要 `payer_id` / `PayerID` |

```shell theme={null}
curl -X POST \
  "https://platform.acedata.cloud/api/v1/orders/${ORDER_ID}/refresh/" \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

成功時回傳重新整理後的完整 Order 物件。使用 `state` 判斷結果，並以 `finished_at` 作為完成時間；目前模型沒有 `paid_at` 欄位。狀態值包括 `Pending`、`Paid`、`Finished`、`Expired`、`Failed`、`Refunded`。

付款截止時間只會將仍處於 `Pending` 的訂單改為 `Expired`。已退款的 `Refunded` 訂單在重新整理或收到延遲付款回呼後仍保持已退款狀態。

## 重試建議

* 正常付款優先依賴平台回呼；只有狀態遲遲未更新時才主動 refresh。
* 不要固定高頻輪詢。建議指數退避，並在明確終態後停止。
* `401` 表示權杖無效；`403` 表示不是訂單擁有者；`404` 表示訂單不存在。
* 付款服務查詢失敗時，保留訂單 ID 和 trace ID，稍後重試；不要建立重複訂單來替代狀態確認。

## 相關介面

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


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