> ## 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 API guide - Ace Data Cloud

AceDataCloud には現在、`/api/v1/distribution/` 集約エンドポイントはありません。紹介報酬データは、ステータス、履歴、レベル、交換の4組のインターフェースで構成されています。必要なリソースに応じて呼び出し、存在しない集約レスポンスに依存しないでください。

## 準備作業

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)

## サブサイト上乗せ注文

新ルールが適用されるサブサイト注文では、紹介コミッションは割引後の基本価格に基づいて計算され、割引後の上乗せ差額は全額、注文作成時点のサイト運営者に帰属します。同一受益者への2つの報酬部分は元の分配記録に統合され、分配履歴にはその内訳が表示されます。上乗せのない注文および過去の注文は従来ルールを維持します。

例えば、基本価格が100、上乗せ後が120で、サイト運営者が唯一の紹介者でもあり、比率が10%の場合、この注文の報酬は 10 + 20 = 30 です。サイト運営者と紹介者が異なる場合、両者はそれぞれ対応する報酬を受け取ります。

現金精算は引き続きプラットフォームが手動で行います。プラットフォームは元の報酬アカウントから今回利用可能な金額を差し引いた後、手動で支払いを行います。すでにポイントへ交換された部分は、現金として重複して支払うことはできません。返金後に報酬の不足額が発生した場合は、後続の報酬から先に相殺されます。


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