> ## 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/`. Дані про реферальні винагороди складаються з чотирьох груп API: статус, історія, рівні та обмін; викликайте відповідно до потрібного ресурсу, не покладайтеся на неіснуючу зведену відповідь.

## Підготовка

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'
```

## Доступні API

| Метод | 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` та інші, які в старій документації не повертаються API.

> Ініціалізація та обмін є операціями запису. Виробничі скрипти повинні спочатку викликати API лише для читання, щоб перевірити статус, і зберігати унікальний `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.