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

# Creare una richiesta di servizio sulla piattaforma AceDataCloud

> Platform API guide - Ace Data Cloud

Una "richiesta (Application)" rappresenta la relazione di sottoscrizione dell'account corrente a un determinato servizio: è necessario prima presentare una richiesta, per poi creare credenziali API per questa richiesta e chiamare le interfacce business. Quando si richiede un servizio per la prima volta, l'Application otterrà il `free_amount` attualmente configurato per quel servizio; questo valore può essere 0.

> ℹ️ Questa interfaccia appartiene alle **API di gestione della piattaforma AceDataCloud**, con prefisso unificato `https://platform.acedata.cloud/api/v1/`. Per l'indice completo delle interfacce, vedere [Ottenere l'elenco della documentazione della piattaforma AceDataCloud](https://platform.acedata.cloud/documents/platform-document-list).

## Processo completo di integrazione

I nuovi utenti, dalla registrazione alla prima chiamata riuscita a un'interfaccia business, seguono solitamente questi 5 passaggi:

1. **Ottenere il token dell'account** → [Gestire i token dell'account della piattaforma AceDataCloud](https://platform.acedata.cloud/documents/platform-token)
2. **Selezionare un servizio** → [Ottenere l'elenco dei servizi della piattaforma AceDataCloud](https://platform.acedata.cloud/documents/platform-service-list)
3. **Creare una richiesta** (questo documento) → Ottenere il credito iniziale in base alla configurazione del servizio
4. **Creare credenziali API** → [Creare credenziali API della piattaforma AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create)
5. **Chiamare l'interfaccia business** → Usare il Token di 32 caratteri ottenuto per chiamare `https://api.acedata.cloud/<path>`

## Panoramica dell'interfaccia

| Voce | Contenuto |
| - | - |
| Metodo | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/applications/` |
| Autenticazione | ✅ Richiede il token dell'account |
| Content-Type | `application/json` |

## Istruzioni di autenticazione (come ottenere il token dell'account)

Intestazione della richiesta:

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

Il token dell'account (Account Token) è la "chiave a livello di account" usata dagli sviluppatori per gestire le risorse del proprio account tramite API. Metodi per ottenerlo:

1. **Creazione con un clic dalla console (consigliata)**: accedere alla [piattaforma AceDataCloud](https://platform.acedata.cloud) → [console Account Token](https://platform.acedata.cloud/console/platform-tokens) → fare clic su "Crea" per ottenere un token che inizia con `platform-v1-`.
2. **Creazione tramite API**: usare un token dell'account esistente o il JWT della sessione di accesso del browser per chiamare `POST /api/v1/platform-tokens/`; per i dettagli, vedere [Gestire i token dell'account della piattaforma AceDataCloud](https://platform.acedata.cloud/documents/platform-token).

> ⚠️ Il token dell'account è sensibile quanto una password e non deve essere inserito nel codice frontend o in repository pubblici. In caso di divulgazione, eliminarlo immediatamente dalla console e ricrearlo.

## Corpo della richiesta

| Parametro | Tipo | Obbligatorio | Descrizione |
| - | - | - | - |
| `service_id` | UUID | ✅ | ID del servizio da richiedere. Può essere ottenuto da `items[].id` dell'[elenco dei servizi](https://platform.acedata.cloud/documents/platform-service-list) |

## Esempi di richiesta

### 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())
}
```

## Esempi di risposta

### Successo (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 struttura dei campi restituiti è coerente con [Ottenere i dettagli di una richiesta di servizio della piattaforma AceDataCloud](https://platform.acedata.cloud/documents/platform-application-detail).

### Già richiesto (HTTP 400)

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

Questo è un limite rigido di progettazione: **ogni utente può avere una sola Application per ogni servizio**. Se esiste già, cercare quella esistente tramite [Ottenere l'elenco delle richieste di servizio della piattaforma AceDataCloud](https://platform.acedata.cloud/documents/platform-application-list).

### Il servizio non esiste (HTTP 404)

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

### Il servizio richiede approvazione (HTTP 403)

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

Se il `need_verify=true` del servizio (questo campo è visibile nell'elenco dei servizi), è necessario seguire il processo di ticket per richiedere l'inserimento nella whitelist.

## Gestione degli errori

| HTTP | codice | Significato |
| - | - | - |
| 400 | `duplication` | Il servizio è già stato richiesto dall'account corrente |
| 400 | `invalid` | `service_id` mancante o formato errato |
| 401 | `not_authenticated` | Token dell'account mancante o token eliminato |
| 403 | `need_verify` | Il servizio richiede una revisione, seguire il processo del ticket |
| 404 | `not_found` | Il servizio non esiste o è stato disattivato |

Formato unificato della risposta di errore:

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

## Suggerimenti pratici

* **La creazione stessa non comporta addebiti**: alla prima creazione, il credito iniziale viene impostato in base al `free_amount` corrente del servizio; questo valore può essere 0 e la creazione ripetuta di Application dello stesso tipo non garantisce l'assegnazione ripetuta del credito gratuito.
* **Per verificare se è necessario pagare, consultare il campo `paid`**: subito dopo la richiesta `paid=false`; dopo aver chiamato [Crea ordine di ricarica della piattaforma AceDataCloud](https://platform.acedata.cloud/documents/platform-order-create) per completare il pagamento, diventa `true`.
* **`disabled=true` indica che è temporaneamente disabilitato**—ad esempio, per l'attivazione del controllo del rischio, insolvenza, ecc. Quando è disabilitato, l'interfaccia aziendale restituirà `403`.
* **Non creare con concorrenza illimitata**: prima ottenere il `service_id` di destinazione dall'elenco dei servizi paginato, quindi richiedere gli elementi uno per uno in base alle necessità aziendali; in caso di `duplication`, riutilizzare l'Application esistente.

## Interfacce correlate

* [Ottieni elenco dei servizi della piattaforma AceDataCloud](https://platform.acedata.cloud/documents/platform-service-list) — scegliere prima il servizio
* [Ottieni elenco delle richieste di servizio della piattaforma AceDataCloud](https://platform.acedata.cloud/documents/platform-application-list) — visualizzare tutte le richieste effettuate
* [Ottieni dettagli della richiesta di servizio della piattaforma AceDataCloud](https://platform.acedata.cloud/documents/platform-application-detail) — visualizzare una singola richiesta
* [Crea credenziale API della piattaforma AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create) — passaggio successivo dopo l'esito positivo della richiesta
* [Crea ordine di ricarica della piattaforma AceDataCloud](https://platform.acedata.cloud/documents/platform-order-create) — ricaricare dopo l'esaurimento del credito gratuito


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