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

# Gestión de tokens de cuenta de la plataforma AceDataCloud (Account Token)

> Platform API guide - Ace Data Cloud

**El token de cuenta (Account Token, anteriormente llamado Platform Token)** es una "clave de nivel de cuenta" que los desarrolladores utilizan para gestionar mediante programación los recursos de la plataforma AceDataCloud (solicitudes de servicios, credenciales de API, pedidos, registros de llamadas, saldo, archivos, etc.). Su función es similar al Token de usuario después de iniciar sesión en el frontend y, de forma predeterminada, no tiene fecha de expiración; los usuarios normales solo pueden gestionar sus propios tokens, mientras que los superadministradores pueden gestionar los tokens de otras cuentas según los permisos.

Los tokens de cuenta acceden a las interfaces de la plataforma con los permisos actuales de la cuenta a la que pertenecen: se aplican combinadamente los permisos básicos, los permisos concedidos directamente y los permisos de los grupos de usuarios a los que pertenece; después de unirse a un grupo o ser eliminado de él, la siguiente solicitud se evaluará según los nuevos permisos. El acceso a recursos específicos, como solicitudes y pedidos, aún requiere una verificación de pertenencia. Los tokens de cuenta no expiran de forma predeterminada; utilícelos solo en entornos confiables y consérvelos adecuadamente.

> ℹ️ Esta interfaz pertenece a la **API de administración de la plataforma AceDataCloud**, con el prefijo unificado `https://platform.acedata.cloud/api/v1/`. Para el índice completo de interfaces, consulte [Obtener la lista de documentos de la plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-document-list).

## Token de cuenta vs credenciales de API

Los dos tipos de claves que los principiantes confunden con mayor facilidad; revíselos claramente primero:

| Dimensión | **Token de cuenta** (este documento) | **Credenciales de API (Credential)** |
| - | - | - |
| Uso | Llamar a las interfaces de administración `https://platform.acedata.cloud/**` | Llamar a las interfaces de negocio `https://api.acedata.cloud/**` (OpenAI, Midjourney, Suno, Veo, etc.) |
| Formato | `platform-v1-` + 64 dígitos hexadecimales (76 caracteres en total) | 32 dígitos hexadecimales |
| Una cuenta | Normalmente 1–2 tokens | 1–N tokens por cada solicitud de servicio |
| Punto de creación | [Consola de Account Token](https://platform.acedata.cloud/console/platform-tokens) | [Crear credenciales de API de la plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create) |
| Condiciones de invalidación | Se invalida inmediatamente después de eliminarse; se invalida al vencer cuando `expiration` no es nulo | Se puede establecer un límite de cuota, tiempo de expiración y vincular IP de origen |

Si solo quiere probar GPT-4.1, lo que necesita son **credenciales de API**, no un token de cuenta.
Si desea escribir scripts de automatización para gestionar recargas, ver facturas mensuales o distribuir credenciales en lote a miembros del equipo, entonces use un token de cuenta.

***

## Crear con un clic en la consola (recomendado)

1. Inicie sesión en [https://platform.acedata.cloud](https://platform.acedata.cloud).
2. Vaya a la barra lateral → «Desarrollador» → «[Account Token](https://platform.acedata.cloud/console/platform-tokens)».
3. Haga clic en el botón «Crear» en la esquina superior derecha para obtener inmediatamente un token `platform-v1-...`, **haga clic en el botón de copiar y guárdelo en el gestor de contraseñas**.

![Consola de Account Token](https://cdn.acedata.cloud/6g86oz.png)

> ⚠️ Las respuestas actuales de creación, lista y detalles devuelven el token en texto plano. Trate toda la respuesta como un secreto; no la escriba en registros, plataformas de análisis o almacenamiento persistente del frontend; el cliente tampoco debe depender de que la lista conserve la devolución en texto plano a largo plazo.

***

## Crear un token de cuenta mediante API

### Resumen de la interfaz

| Elemento | Contenido |
| - | - |
| Método | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/` |
| Autenticación | ✅ Cualquier token de cuenta existente o JWT de sesión del navegador |
| Body | `application/json` (se puede pasar un objeto vacío `{}`) |

### Explicación de autenticación (el problema del huevo y la gallina)

> ¿De dónde viene el primer token? La respuesta es **desde la consola**: después de iniciar sesión en el navegador, la consola llama a `POST /platform-tokens/` autenticándose con JWT y le entrega el primer token.
> Después, puede usar cualquier token existente `platform-v1-...` para crear más.

Formato de los encabezados de solicitud:

```http theme={null}
Authorization: Bearer ${PLATFORM_TOKEN}
Content-Type: application/json
```

### Ejemplo de solicitud

```shell theme={null}
curl -X POST 'https://platform.acedata.cloud/api/v1/platform-tokens/' \
  -H 'accept: application/json' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{}'
```

### Respuesta (HTTP 201)

```json theme={null}
{
  "id": "3264f1aa-cbe1-4e2c-a434-95adba4f8304",
  "token": "platform-v1-<REDACTED>",
  "expiration": null,
  "user_id": "89518d07-5560-4b05-92c1-667f3ddf6a4b",
  "created_at": "2026-04-26T15:50:11.123456Z",
  "updated_at": "2026-04-26T15:50:11.123456Z",
  "used_at": null
}
```

### Descripción de campos

| Campo | Tipo | Descripción |
| - | - | - |
| `id` | UUID | Clave primaria del token, utilizada al eliminar / consultar detalles |
| `token` | string | Texto plano del token de cuenta. Formato: `platform-v1-` + 64 dígitos hexadecimales (76 caracteres en total); debe tratarse como secreto |
| `expiration` | int \| null | Tiempo de expiración (marca de tiempo en segundos). `null` indica que no se ha establecido un tiempo de expiración |
| `user_id` | UUID | ID del usuario propietario. También es el valor del parámetro `?user_id=` que debe pasarse en todas las interfaces de lista posteriores |
| `created_at` | datetime (ISO8601) | Hora de creación |
| `updated_at` | datetime (ISO8601) | Hora de actualización |
| `used_at` | datetime \| null | Hora de la última vez que se utilizó para autenticación. Si nunca se ha utilizado, es `null`; puede usarse para detectar "tokens zombis" |

***

## Obtener la lista de tokens de cuenta

### Resumen de la interfaz

| Elemento | Contenido |
| - | - |
| Método | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/` |
| Autenticación | ✅ Se requiere token de cuenta |

### Parámetros de consulta obligatorios

> ⚠️ **Debe incluir `?user_id=<your_user_id>`**. Motivo: la interfaz de lista realiza una verificación de permisos **por objeto** sobre los resultados paginados; si no se incluye `user_id`, el primer objeto que no le pertenezca será rechazado y devolverá `403 permission_denied`.

Cómo obtener `user_id`:

1. Abra [https://auth.acedata.cloud/user/profile](https://auth.acedata.cloud/user/profile) en el navegador; la parte superior de la página muestra el UUID completo.
2. O complete directamente el campo `user_id` del valor devuelto por `POST /platform-tokens/`.

### Parámetros de consulta

| Parámetro | Obligatorio | Tipo | Descripción |
| - | - | - | - |
| `user_id` | ✅ | UUID | ID de usuario de la cuenta actual |
| `limit` | ❌ | int | Número de elementos por página, predeterminado 10, máximo 100 |
| `offset` | ❌ | int | Desplazamiento |
| `ordering` | ❌ | string | Campo de ordenación, predeterminado `-created_at` |

### Ejemplo de solicitud

```shell theme={null}
curl 'https://platform.acedata.cloud/api/v1/platform-tokens/?user_id=89518d07-5560-4b05-92c1-667f3ddf6a4b&limit=5' \
  -H 'accept: application/json' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}"
```

### Respuesta (HTTP 200)

```json theme={null}
{
  "count": 2,
  "items": [
    {
      "id": "51c575a2-801c-4211-bc47-711452a8c8c9",
      "token": "platform-v1-<REDACTED>",
      "expiration": null,
      "user_id": "89518d07-5560-4b05-92c1-667f3ddf6a4b",
      "created_at": "2026-04-26T15:41:32.761705Z",
      "updated_at": "2026-04-26T15:41:32.761726Z",
      "used_at": null
    }
  ]
}
```

> La respuesta paginada de esta interfaz utiliza `count` + `items`. Otras interfaces de plataforma pueden utilizar estructuras diferentes; consulte la documentación correspondiente y la respuesta real.

***

## Obtener detalles del token de cuenta

| Elemento | Contenido |
| - | - |
| Método | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/<id>`（**sin barra al final**） |
| Autorización | ✅ Solo el creador del token o el superadministrador pueden acceder |

```shell theme={null}
curl 'https://platform.acedata.cloud/api/v1/platform-tokens/51c575a2-801c-4211-bc47-711452a8c8c9' \
  -H 'accept: application/json' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}"
```

La estructura devuelta es consistente con el elemento de la lista, `HTTP 200`.

***

## Eliminar token de cuenta

| Elemento | Contenido |
| - | - |
| Método | `DELETE` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/<id>`（**sin barra al final**） |
| Autorización | ✅ Solo el creador del token o el superadministrador pueden eliminar |

```shell theme={null}
curl -X DELETE 'https://platform.acedata.cloud/api/v1/platform-tokens/3264f1aa-cbe1-4e2c-a434-95adba4f8304' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}"
```

* Si tiene éxito, devuelve `HTTP 204 No Content`, sin cuerpo de respuesta.
* Después de eliminarlo, el token queda **inmediatamente invalidado**, y todos los servicios que lo estén utilizando recibirán `401` de inmediato.
* Consultar de nuevo este `id` devolverá `404`.

> ⚠️ La eliminación es irreversible. Si sospecha que el token se ha filtrado, puede **crear primero uno nuevo, cambiar el lado de negocio y luego eliminar el antiguo**.

***

## Operaciones no compatibles

| Operación | HTTP | Descripción |
| - | - | - |
| Modificación `PATCH` | 405 | Después de crear un token de cuenta, **no se admite la modificación de ningún campo**. Para usos como cambiar el nombre, elimínelo y vuelva a crearlo |
| Reemplazo `PUT` | 405 | Igual que arriba |

***

## Referencia rápida de códigos de error

| HTTP | `code` | Causa común |
| - | - | - |
| 401 | `not_authenticated` | No se incluyó el encabezado `Authorization`, o el token ha sido eliminado |
| 403 | `permission_denied` | La interfaz de lista no incluyó `?user_id=`, o se accedió a los detalles del token de otra persona |
| 404 | `not_found` | El `id` no existe o ha sido eliminado |
| 405 | `method_not_allowed` | Se envió `PATCH`/`PUT` a la interfaz de detalles |

Formato unificado de respuesta de error:

```json theme={null}
{
  "detail": "You do not have permission to perform this action.",
  "code": "permission_denied",
  "trace_id": "0a88956213edf6e62b71695ee2df0eff"
}
```

Durante la investigación, proporcione el `trace_id` al servicio de atención al cliente o inclúyalo en el ticket para localizar rápidamente los registros.

***

## Ejemplo de código completo

### Python

```python theme={null}
import os
import requests

BASE = "https://platform.acedata.cloud/api/v1"
PLATFORM_TOKEN = os.environ["PLATFORM_TOKEN"]
USER_ID = "89518d07-5560-4b05-92c1-667f3ddf6a4b"

headers = {
    "accept": "application/json",
    "authorization": f"Bearer {PLATFORM_TOKEN}",
    "content-type": "application/json",
}

# 1. Crear un nuevo token
created = requests.post(f"{BASE}/platform-tokens/", headers=headers, json={}).json()
print("Nuevo token：", created["token"])
print("UserID：", created["user_id"])

# 2. Lista
listing = requests.get(
    f"{BASE}/platform-tokens/",
    headers=headers,
    params={"user_id": USER_ID, "limit": 50},
).json()
print(f"Un total de {listing['count']} tokens")

# 3. Eliminar (tenga en cuenta que no hay barra al final)
resp = requests.delete(f"{BASE}/platform-tokens/{created['id']}", headers=headers)
assert resp.status_code == 204, resp.text
```

### Node.js

```javascript theme={null}
const BASE = 'https://platform.acedata.cloud/api/v1'
const PLATFORM_TOKEN = process.env.PLATFORM_TOKEN
const USER_ID = '89518d07-5560-4b05-92c1-667f3ddf6a4b'

const headers = {
  accept: 'application/json',
  authorization: `Bearer ${PLATFORM_TOKEN}`,
  'content-type': 'application/json',
}

// Crear
const created = await fetch(`${BASE}/platform-tokens/`, {
  method: 'POST',
  headers,
  body: '{}',
}).then((r) => r.json())

// Lista
const url = new URL(`${BASE}/platform-tokens/`)
url.searchParams.set('user_id', USER_ID)
const listing = await fetch(url, { headers }).then((r) => r.json())
console.log(`Un total de ${listing.count} tokens`)

// Eliminar (sin barra al final)
await fetch(`${BASE}/platform-tokens/${created.id}`, { method: 'DELETE', headers })
```

***

## Uso en otras API de plataforma

Coloque directamente `platform-v1-...` en el encabezado `Authorization: Bearer ...` para llamar a cualquier interfaz de plataforma que requiera autorización:

```shell theme={null}
curl 'https://platform.acedata.cloud/api/v1/applications/?user_id=89518d07-5560-4b05-92c1-667f3ddf6a4b' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}"
```

> Es **completamente diferente** de las credenciales API hexadecimales de 32 caracteres utilizadas por las interfaces de negocio `https://api.acedata.cloud/**` (OpenAI, Midjourney, Suno, Veo, etc.). No las mezcle: escribir un token de cuenta en una interfaz de negocio resultará en `401`, y viceversa.

***

## Interfaces relacionadas

* [Obtener la lista de solicitudes de servicios de la plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-application-list) — utilizar el token de la cuenta para ver qué servicios ha solicitado
* [Crear credenciales de API de la plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create) — utilizar el token de la cuenta para emitir credenciales de 32 caracteres para la API empresarial
* [Obtener los registros de llamadas a la API de la plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-usage-list) — consultar cuentas y solucionar errores
* [Obtener la lista de pedidos de la plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-order-list) — consultar el historial de recargas


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