> ## 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 в [консоли Account Token](https://platform.acedata.cloud/console/platform-tokens).
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.