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