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

# Crear una solicitud de servicio de la plataforma AceDataCloud

> Platform API guide - Ace Data Cloud

«Solicitud (Application)» representa la relación de suscripción de la cuenta actual a un servicio determinado; primero debe solicitarse, para luego poder crear credenciales de API para esta solicitud y llamar a las interfaces de negocio. Al solicitar un servicio por primera vez, Application obtendrá el `free_amount` configurado actualmente para ese servicio; este valor puede ser 0.

> ℹ️ 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).

## Flujo completo de integración

Los nuevos usuarios, desde el registro hasta lograr conectar la primera interfaz de negocio, normalmente siguen estos 5 pasos:

1. **Obtener el token de cuenta** → [Administrar tokens de cuenta de la plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-token)
2. **Elegir un servicio** → [Obtener la lista de servicios de la plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-service-list)
3. **Crear una solicitud**（este documento） → Obtener la cuota inicial según la configuración del servicio
4. **Crear credenciales de API** → [Crear credenciales de API de la plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create)
5. **Llamar a la interfaz de negocio** → Usar el Token de 32 caracteres obtenido para llamar a `https://api.acedata.cloud/<path>`

## Resumen de la interfaz

| Elemento | Contenido |
| - | - |
| Método | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/applications/` |
| Autenticación | ✅ Requiere token de cuenta |
| Content-Type | `application/json` |

## Instrucciones de autenticación（cómo obtener el token de cuenta）

Encabezado de la solicitud:

```http theme={null}
Authorization: Bearer ${PLATFORM_TOKEN}
```

El token de cuenta (Account Token) es la «clave a nivel de cuenta» que los desarrolladores usan para administrar los recursos de su propia cuenta mediante la API. Formas de obtenerlo:

1. **Creación con un clic en la consola（recomendado）**: Inicie sesión en la [plataforma AceDataCloud](https://platform.acedata.cloud) → [Consola de Account Token](https://platform.acedata.cloud/console/platform-tokens) → Haga clic en «Crear» para obtener un token que comienza con `platform-v1-`.
2. **Creación mediante API**: Use un token de cuenta existente o el JWT de sesión del navegador para llamar a `POST /api/v1/platform-tokens/`; consulte [Administrar tokens de cuenta de la plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-token) para más detalles.

> ⚠️ El token de cuenta es tan sensible como una contraseña; está prohibido escribirlo en código frontend o repositorios públicos. Si se filtra, elimínelo y vuelva a crearlo inmediatamente en la consola.

## Cuerpo de la solicitud

| Parámetro | Tipo | Obligatorio | Descripción |
| - | - | - | - |
| `service_id` | UUID | ✅ | ID del servicio que se desea solicitar. Puede obtenerse de `items[].id` en la [lista de servicios](https://platform.acedata.cloud/documents/platform-service-list) |

## Ejemplo de solicitud

### cURL

```shell theme={null}
curl -X POST 'https://platform.acedata.cloud/api/v1/applications/' \
  -H 'accept: application/json' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{"service_id": "38ecf158-36f2-42f2-8e7f-6786cdfc2452"}'
```

### Python

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

PLATFORM_TOKEN = os.environ["PLATFORM_TOKEN"]
SERVICE_ID = "38ecf158-36f2-42f2-8e7f-6786cdfc2452"

resp = requests.post(
    "https://platform.acedata.cloud/api/v1/applications/",
    headers={
        "accept": "application/json",
        "authorization": f"Bearer {PLATFORM_TOKEN}",
        "content-type": "application/json",
    },
    json={"service_id": SERVICE_ID},
    timeout=10,
)

if resp.status_code == 201:
    app = resp.json()
    print(f"申请成功！application_id={app['id']}")
    print(f"初始额度：{app['remaining_amount']} {app.get('service', {}).get('unit', '')}")
elif resp.status_code == 400 and resp.json().get("code") == "duplication":
    print("⚠️ 已经申请过此服务，请到 /applications/ 列表里找到现成的 application_id")
else:
    print(f"申请失败：HTTP {resp.status_code} - {resp.text}")
```

### Node.js

```javascript theme={null}
const PLATFORM_TOKEN = process.env.PLATFORM_TOKEN
const SERVICE_ID = '38ecf158-36f2-42f2-8e7f-6786cdfc2452'

const resp = await fetch('https://platform.acedata.cloud/api/v1/applications/', {
  method: 'POST',
  headers: {
    accept: 'application/json',
    authorization: `Bearer ${PLATFORM_TOKEN}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({ service_id: SERVICE_ID }),
})

if (resp.status === 201) {
  const app = await resp.json()
  console.log('application_id =', app.id)
} else {
  console.error(await resp.text())
}
```

## Ejemplo de respuesta

### Éxito（HTTP 201）

```json theme={null}
{
  "id": "82f57141-2323-4453-8730-60f7d833a2da",
  "service_id": "38ecf158-36f2-42f2-8e7f-6786cdfc2452",
  "remaining_amount": 1.0,
  "used_amount": 0.0,
  "paid": false,
  "user_id": "89518d07-5560-4b05-92c1-667f3ddf6a4b",
  "disabled": false,
  "allow_consume_global": false,
  "scope": "Individual",
  "type": "Usage",
  "expired_at": null,
  "tags": null,
  "metadata": null,
  "client_ip": null,
  "client_fingerprint": null,
  "created_at": "2026-04-26T07:52:27.462400Z",
  "updated_at": "2026-04-26T07:52:27.462400Z"
}
```

La estructura de los campos devueltos es coherente con [Obtener los detalles de una solicitud de servicio de la plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-application-detail).

### Ya solicitado（HTTP 400）

```json theme={null}
{
  "detail": "Item already exists.",
  "code": "duplication",
  "trace_id": "1a87524f8cbba0b790b2951e2e43117e"
}
```

Esta es una restricción estricta por diseño: **cada usuario solo puede tener una Application para cada servicio**. Si ya existe, encuentre la existente mediante [Obtener la lista de solicitudes de servicio de la plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-application-list).

### El servicio no existe（HTTP 404）

```json theme={null}
{
  "detail": "Service not found.",
  "code": "not_found",
  "trace_id": "..."
}
```

### El servicio requiere revisión（HTTP 403）

```json theme={null}
{
  "detail": "This service requires manual verification.",
  "code": "need_verify",
  "trace_id": "..."
}
```

Si el servicio tiene `need_verify=true`（este campo puede verse en la lista de servicios）, debe seguir el proceso de ticket para solicitar la inclusión en la lista blanca.

## Manejo de errores

| HTTP | código | significado |
| - | - | - |
| 400 | `duplication` | El servicio ya ha sido solicitado por la cuenta actual |
| 400 | `invalid` | Falta `service_id` o el formato es incorrecto |
| 401 | `not_authenticated` | Falta el token de la cuenta o el token ha sido eliminado |
| 403 | `need_verify` | El servicio requiere revisión, siga el proceso de ticket |
| 404 | `not_found` | El servicio no existe o ha sido desconectado |

Formato unificado de respuesta de error:

```json theme={null}
{
  "detail": "...",
  "code": "...",
  "trace_id": "..."
}
```

## Consejos prácticos

* **La creación en sí no genera cargos**: al crear por primera vez, la cuota inicial se establece según el `free_amount` actual del servicio; este valor puede ser 0, y crear nuevamente una Application del mismo tipo no garantiza que se otorgue el regalo de nuevo.
* **Si se requiere pago depende del campo `paid`**: justo después de la solicitud, `paid=false`; después de llamar a [Crear pedido de recarga de la plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-order-create) y completar el pago, cambia a `true`.
* **`disabled=true` indica que ha sido deshabilitado temporalmente**—por ejemplo, por activación de control de riesgos, pagos pendientes, etc. Cuando está deshabilitado, la interfaz de negocio devolverá `403`.
* **No cree de forma concurrente sin límites**: primero obtenga el `service_id` objetivo de la lista paginada de servicios y luego solicítelos uno por uno según las necesidades del negocio; cuando encuentre `duplication`, reutilice la Application existente.

## Interfaces relacionadas

* [Obtener lista de servicios de la plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-service-list) — primero elija un servicio
* [Obtener lista de solicitudes de servicios de la plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-application-list) — ver todas las solicitudes realizadas
* [Obtener detalles de la solicitud de servicio de la plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-application-detail) — ver una solicitud individual
* [Crear credencial de API de la plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create) — siguiente paso después de solicitar con éxito
* [Crear pedido de recarga de la plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-order-create) — recargar después de agotar la cuota gratuita


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