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

AceDataCloud 目前沒有 `/api/v1/distribution/` 聚合端點。推薦獎勵資料由狀態、流水、等級和兌換四組介面組成；請依所需資源呼叫，避免依賴一個不存在的彙總回應。

## 準備工作

1. 在 [Account Token 控制台](https://platform.acedata.cloud/console/platform-tokens)建立並儲存 Account Token。
2. 使用 `GET /api/v1/platform-tokens/me/` 取得目前帳戶 UUID。

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

## 可用介面

| 方法 | URL | 用途 |
| - | - | - |
| `GET` | `/api/v1/distribution-statuses/?user_id=${USER_ID}` | 目前帳戶累計推薦金額、獎勵和等級 |
| `POST` | `/api/v1/distribution-statuses/initialize/` | 首次初始化或重新整理目前帳戶等級；會寫入資料 |
| `GET` | `/api/v1/distribution-histories/?user_id=${USER_ID}` | 推薦獎勵流水 |
| `GET` | `/api/v1/distribution-levels/` | 等級與比例規則 |
| `GET` | `/api/v1/distribution-redemptions/preview/` | 預覽目前可兌換獎勵；可選 `amount` |
| `GET` | `/api/v1/distribution-redemptions/` | 已完成的兌換紀錄 |
| `POST` | `/api/v1/distribution-redemptions/redeem/` | 確認兌換；需要 `idempotency_key`，會產生不可撤回的兌換 |

## 唯讀請求範例

```shell theme={null}
curl --get 'https://platform.acedata.cloud/api/v1/distribution-statuses/' \
  --data-urlencode "user_id=${USER_ID}" \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"

curl --get 'https://platform.acedata.cloud/api/v1/distribution-histories/' \
  --data-urlencode "user_id=${USER_ID}" \
  --data-urlencode 'limit=100' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"

curl 'https://platform.acedata.cloud/api/v1/distribution-levels/' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"

curl 'https://platform.acedata.cloud/api/v1/distribution-redemptions/preview/' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

線上驗證的回應形態為：

* status、history、level、redemption list：`{count, items}`；
* redemption preview：單一物件，包含 `eligible`、`reason`、`reward_amount`、`credit_amount`、`credits_per_usd`、`currency`、`package`、`global_application` 等欄位。

狀態項和流水項會隨推薦風控、補償與獎勵規則擴充；用戶端應依需求讀取，不要依賴舊文件中未由介面回傳的 `referral_url`、`recent_orders`、`withdrawable_balance` 等聚合欄位。

> 初始化和兌換都是寫入操作。生產腳本應先呼叫唯讀介面檢查狀態，並為兌換請求持久化唯一的 `idempotency_key`；不要自動重試結果未知的兌換。

## 相關頁面

* [取得訂單列表](https://platform.acedata.cloud/documents/platform-order-list)
* [管理帳戶權杖](https://platform.acedata.cloud/documents/platform-token)

## 分站加價訂單

適用新規則的分站訂單，推薦佣金按折後基礎價計算，折後加價差額全額歸訂單建立時的站長。同一受益人的兩部分獎勵合併至原分銷紀錄，分銷歷史會展示構成；無加價和歷史訂單維持原規則。

例如基礎價 100、加價後 120，站長同時是唯一推薦人且比例為 10%，本單獎勵為 10 + 20 = 30。站長與推薦人不同時，兩人分別獲得對應獎勵。

現金結算仍由平台人工辦理。平台在原獎勵帳戶扣減本次可用金額後進行人工付款；已經兌換積分的部分不能重複支付現金。退款後如出現獎勵欠額，會先用後續獎勵抵扣。


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