> ## 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/` 집계 엔드포인트가 없습니다. 추천 보상 데이터는 상태, 내역, 등급 및 교환의 네 그룹 인터페이스로 구성됩니다. 필요한 리소스에 따라 호출하고, 존재하지 않는 집계 응답에 의존하지 마십시오.

## 준비 작업

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.