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

# Consultar informações de recompensas de indicação da AceDataCloud

> Platform API guide - Ace Data Cloud

Atualmente, a AceDataCloud não possui um endpoint agregado `/api/v1/distribution/`. Os dados de recompensas de indicação são compostos por quatro grupos de interfaces: status, histórico, níveis e resgates; chame conforme o recurso necessário e evite depender de uma resposta consolidada inexistente.

## Preparação

1. Crie e salve um Account Token no [console de Account Token](https://platform.acedata.cloud/console/platform-tokens).
2. Use `GET /api/v1/platform-tokens/me/` para obter o UUID da conta atual.

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

## Interfaces disponíveis

| Método | URL | Finalidade |
| - | - | - |
| `GET` | `/api/v1/distribution-statuses/?user_id=${USER_ID}` | Valor acumulado de indicações, recompensas e nível da conta atual |
| `POST` | `/api/v1/distribution-statuses/initialize/` | Inicializar ou atualizar o nível da conta atual pela primeira vez; gravará dados |
| `GET` | `/api/v1/distribution-histories/?user_id=${USER_ID}` | Histórico de recompensas de indicação |
| `GET` | `/api/v1/distribution-levels/` | Regras de níveis e proporções |
| `GET` | `/api/v1/distribution-redemptions/preview/` | Visualizar as recompensas atualmente resgatáveis; `amount` é opcional |
| `GET` | `/api/v1/distribution-redemptions/` | Registros de resgates concluídos |
| `POST` | `/api/v1/distribution-redemptions/redeem/` | Confirmar o resgate; requer `idempotency_key` e produzirá um resgate irreversível |

## Exemplos de solicitações somente leitura

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

O formato de resposta validado em produção é:

* status, history, level, redemption list: `{count, items}`;
* redemption preview: um único objeto, contendo campos como `eligible`, `reason`, `reward_amount`, `credit_amount`, `credits_per_usd`, `currency`, `package`, `global_application` etc.

Itens de status e de histórico serão ampliados conforme controles de risco de indicação, compensações e regras de recompensa; o cliente deve lê-los conforme necessário e não deve depender de campos agregados como `referral_url`, `recent_orders`, `withdrawable_balance` etc., que não são retornados pela interface nos documentos antigos.

> Tanto a inicialização quanto o resgate são operações de escrita. Scripts de produção devem primeiro chamar interfaces somente leitura para verificar o status e persistir uma `idempotency_key` única para solicitações de resgate; não repita automaticamente resgates com resultado desconhecido.

## Páginas relacionadas

* [Obter lista de pedidos](https://platform.acedata.cloud/documents/platform-order-list)
* [Gerenciar tokens da conta](https://platform.acedata.cloud/documents/platform-token)

## Pedidos com acréscimo de preço em subestações

Para pedidos de subestações aos quais se aplicam as novas regras, a comissão de indicação é calculada com base no preço-base após o desconto, e a diferença integral do acréscimo após o desconto pertence ao administrador da estação no momento da criação do pedido. As duas partes da recompensa do mesmo beneficiário são combinadas no registro original de distribuição, e o histórico de distribuição exibirá sua composição; pedidos sem acréscimo de preço e pedidos históricos mantêm as regras originais.

Por exemplo, se o preço-base for 100 e o preço após o acréscimo for 120, o administrador da estação também for o único indicado e a proporção for 10%, a recompensa deste pedido será 10 + 20 = 30. Quando o administrador da estação e o indicado não forem a mesma pessoa, cada um receberá a recompensa correspondente.

A liquidação em dinheiro continua a ser processada manualmente pela plataforma. A plataforma deduzirá o valor disponível deste resgate na conta de recompensas original antes de realizar o pagamento manual; as partes já resgatadas em créditos não podem receber pagamento em dinheiro novamente. Se houver déficit de recompensas após um reembolso, ele será primeiro compensado com recompensas futuras.


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