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

# Consultare le informazioni sulle ricompense di referral di AceDataCloud

> Platform API guide - Ace Data Cloud

AceDataCloud attualmente non dispone di un endpoint aggregato `/api/v1/distribution/`. I dati delle ricompense di referral sono costituiti da quattro gruppi di interfacce: stato, cronologia, livelli e riscatti; chiama le risorse necessarie ed evita di dipendere da una risposta di riepilogo inesistente.

## Preparazione

1. Crea e salva un Account Token nella [console Account Token](https://platform.acedata.cloud/console/platform-tokens).
2. Usa `GET /api/v1/platform-tokens/me/` per ottenere l'UUID dell'account corrente.

```shell theme={null}
export PLATFORM_TOKEN='你的账户令牌'
export USER_ID='你的账户 UUID'
```

## Interfacce disponibili

| Metodo | URL | Scopo |
| - | - | - |
| `GET` | `/api/v1/distribution-statuses/?user_id=${USER_ID}` | Importo cumulativo dei referral, ricompense e livello dell'account corrente |
| `POST` | `/api/v1/distribution-statuses/initialize/` | Inizializza o aggiorna per la prima volta il livello dell'account corrente; scrive dati |
| `GET` | `/api/v1/distribution-histories/?user_id=${USER_ID}` | Cronologia delle ricompense di referral |
| `GET` | `/api/v1/distribution-levels/` | Regole relative a livelli e percentuali |
| `GET` | `/api/v1/distribution-redemptions/preview/` | Anteprima delle ricompense attualmente riscattabili; `amount` facoltativo |
| `GET` | `/api/v1/distribution-redemptions/` | Registri dei riscatti completati |
| `POST` | `/api/v1/distribution-redemptions/redeem/` | Conferma il riscatto; richiede `idempotency_key` e genera un riscatto irreversibile |

## Esempi di richieste in sola lettura

```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}"
```

Il formato delle risposte verificato online è:

* status, history, level, redemption list: `{count, items}`;
* redemption preview: singolo oggetto, contenente campi quali `eligible`, `reason`, `reward_amount`, `credit_amount`, `credits_per_usd`, `currency`, `package`, `global_application` e altri.

Le voci di stato e di cronologia possono essere estese in base al controllo del rischio dei referral, alle compensazioni e alle regole delle ricompense; il client deve leggerle secondo necessità e non dipendere da campi aggregati come `referral_url`, `recent_orders`, `withdrawable_balance` e altri, non restituiti dall'interfaccia nei vecchi documenti.

> L'inizializzazione e il riscatto sono entrambi operazioni di scrittura. Gli script di produzione devono prima chiamare le interfacce in sola lettura per controllare lo stato e mantenere un `idempotency_key` univoco per le richieste di riscatto; non riprovare automaticamente i riscatti con risultato sconosciuto.

## Pagine correlate

* [Ottenere l'elenco degli ordini](https://platform.acedata.cloud/documents/platform-order-list)
* [Gestire gli Account Token](https://platform.acedata.cloud/documents/platform-token)

## Ordini con sovrapprezzo delle sottostazioni

Per gli ordini delle sottostazioni a cui si applicano le nuove regole, la commissione di referral viene calcolata sul prezzo base scontato, mentre l'intera differenza del sovrapprezzo dopo lo sconto appartiene al gestore della sottostazione al momento della creazione dell'ordine. Le due parti della ricompensa dello stesso beneficiario vengono unite nel record di distribuzione originale e la cronologia della distribuzione ne mostrerà la composizione; gli ordini senza sovrapprezzo e gli ordini storici mantengono le regole originali.

Ad esempio, con un prezzo base di 100 e un prezzo di 120 dopo il sovrapprezzo, se il gestore della sottostazione è anche l'unico referente e la percentuale è del 10%, la ricompensa dell'ordine è 10 + 20 = 30. Quando il gestore della sottostazione e il referente non sono la stessa persona, i due ricevono rispettivamente le ricompense corrispondenti.

Il regolamento in contanti continua a essere gestito manualmente dalla piattaforma. Dopo che la piattaforma ha detratto dall'account delle ricompense originale l'importo disponibile per questa volta, effettua il pagamento manuale; la parte già riscattata in crediti non può essere pagata nuovamente in contanti. Se dopo un rimborso si verifica un saldo negativo di ricompense, questo verrà prima compensato con le ricompense successive.


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