> ## 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 información sobre recompensas por recomendación de AceDataCloud

> Platform API guide - Ace Data Cloud

AceDataCloud actualmente no tiene un endpoint agregado `/api/v1/distribution/`. Los datos de recompensas por recomendación constan de cuatro grupos de interfaces: estado, historial, niveles y canje; llame según el recurso necesario y evite depender de una respuesta resumida que no existe.

## Preparativos

1. Cree y guarde un Account Token en la [consola de Account Token](https://platform.acedata.cloud/console/platform-tokens).
2. Utilice `GET /api/v1/platform-tokens/me/` para obtener el UUID de la cuenta actual.

```shell theme={null}
export PLATFORM_TOKEN='tu token de cuenta'
export USER_ID='tu UUID de cuenta'
```

## Interfaces disponibles

| Método | URL | Uso |
| - | - | - |
| `GET` | `/api/v1/distribution-statuses/?user_id=${USER_ID}` | Importe acumulado de recomendaciones, recompensas y nivel de la cuenta actual |
| `POST` | `/api/v1/distribution-statuses/initialize/` | Inicializa o actualiza por primera vez el nivel de la cuenta actual; escribe datos |
| `GET` | `/api/v1/distribution-histories/?user_id=${USER_ID}` | Historial de recompensas por recomendación |
| `GET` | `/api/v1/distribution-levels/` | Reglas de niveles y proporciones |
| `GET` | `/api/v1/distribution-redemptions/preview/` | Previsualiza las recompensas canjeables actuales; `amount` es opcional |
| `GET` | `/api/v1/distribution-redemptions/` | Registros de canjes completados |
| `POST` | `/api/v1/distribution-redemptions/redeem/` | Confirma el canje; requiere `idempotency_key` y genera un canje irreversible |

## Ejemplos de solicitudes de solo lectura

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

La forma de respuesta validada en línea es:

* status, history, level, redemption list: `{count, items}`;
* redemption preview: un único objeto, que contiene campos como `eligible`, `reason`, `reward_amount`, `credit_amount`, `credits_per_usd`, `currency`, `package`, `global_application`, entre otros.

Los elementos de estado y de historial se ampliarán según el control de riesgos de recomendaciones, las compensaciones y las reglas de recompensas; el cliente debe leer según sea necesario y no depender de campos agregados como `referral_url`, `recent_orders`, `withdrawable_balance`, entre otros, que se mencionan en documentación antigua pero no son devueltos por la interfaz.

> Tanto la inicialización como el canje son operaciones de escritura. Los scripts de producción deben primero llamar a las interfaces de solo lectura para comprobar el estado y persistir un `idempotency_key` único para las solicitudes de canje; no reintente automáticamente canjes con resultados desconocidos.

## Páginas relacionadas

* [Obtener lista de pedidos](https://platform.acedata.cloud/documents/platform-order-list)
* [Gestionar tokens de cuenta](https://platform.acedata.cloud/documents/platform-token)

## Pedidos con sobreprecio de subestaciones

Para los pedidos de subestaciones a los que se aplican las nuevas reglas, la comisión por recomendación se calcula sobre el precio base después del descuento, y la diferencia del sobreprecio después del descuento pertenece íntegramente al webmaster en el momento de creación del pedido. Las dos partes de la recompensa del mismo beneficiario se combinan en el registro de distribución original, y el historial de distribución mostrará su composición; los pedidos sin sobreprecio y los pedidos históricos mantienen las reglas originales.

Por ejemplo, con un precio base de 100 y un precio de 120 después del sobreprecio, si el webmaster es al mismo tiempo el único recomendador y la proporción es del 10 %, la recompensa de este pedido será 10 + 20 = 30. Cuando el webmaster y el recomendador no son la misma persona, ambos reciben respectivamente las recompensas correspondientes.

La liquidación en efectivo sigue siendo gestionada manualmente por la plataforma. La plataforma deducirá el importe disponible de esta vez de la cuenta de recompensas original y luego realizará el pago manual; la parte ya canjeada por créditos no puede volver a pagarse en efectivo. Si después de un reembolso aparece un saldo negativo de recompensas, primero se compensará con recompensas posteriores.


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