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

# Créer une demande de service de la plateforme AceDataCloud

> Platform API guide - Ace Data Cloud

Une « demande (Application) » représente la relation d’abonnement du compte actuel à un certain service — vous devez d’abord faire une demande, avant de pouvoir créer des identifiants API pour cette demande et appeler les interfaces métier. Lors de la première demande d’un certain service, l’Application obtient la valeur `free_amount` actuellement configurée pour ce service ; cette valeur peut être 0.

> ℹ️ Cette interface appartient à l’**API de gestion de la plateforme AceDataCloud**, avec le préfixe unifié `https://platform.acedata.cloud/api/v1/`. Pour l’index complet des interfaces, consultez [Obtenir la liste de la documentation de la plateforme AceDataCloud](https://platform.acedata.cloud/documents/platform-document-list).

## Processus d’intégration complet

Les nouveaux utilisateurs suivent généralement ces 5 étapes, de l’inscription jusqu’au premier appel d’interface métier :

1. **Obtenir le jeton de compte** → [Gérer les jetons de compte de la plateforme AceDataCloud](https://platform.acedata.cloud/documents/platform-token)
2. **Choisir un service** → [Obtenir la liste des services de la plateforme AceDataCloud](https://platform.acedata.cloud/documents/platform-service-list)
3. **Créer une demande** (ce document) → Obtenir le quota initial selon la configuration du service
4. **Créer des identifiants API** → [Créer des identifiants API de la plateforme AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create)
5. **Appeler l’interface métier** → Utiliser le Token de 32 caractères obtenu pour appeler `https://api.acedata.cloud/<path>`

## Aperçu de l’interface

| Élément | Contenu |
| - | - |
| Méthode | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/applications/` |
| Authentification | ✅ Jeton de compte requis |
| Content-Type | `application/json` |

## Instructions d’authentification (comment obtenir le jeton de compte)

En-tête de requête :

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

Le jeton de compte (Account Token) est une « clé de niveau compte » que les développeurs utilisent via l’API pour gérer les ressources de leur propre compte. Méthodes d’obtention :

1. **Création en un clic depuis la console (recommandée)** : connectez-vous à la [plateforme AceDataCloud](https://platform.acedata.cloud) → [console Account Token](https://platform.acedata.cloud/console/platform-tokens) → cliquez sur « Créer » pour obtenir un jeton commençant par `platform-v1-`.
2. **Création par API** : utilisez un jeton de compte existant ou le JWT de session du navigateur pour appeler `POST /api/v1/platform-tokens/`, voir [Gérer les jetons de compte de la plateforme AceDataCloud](https://platform.acedata.cloud/documents/platform-token).

> ⚠️ Les jetons de compte sont aussi sensibles que les mots de passe ; il est interdit de les écrire dans le code frontend ou dans des dépôts publics. En cas de fuite, supprimez-les immédiatement dans la console et recréez-les.

## Corps de la requête

| Paramètre | Type | Requis | Description |
| - | - | - | - |
| `service_id` | UUID | ✅ | ID du service à demander. Peut être obtenu depuis `items[].id` de la [liste des services](https://platform.acedata.cloud/documents/platform-service-list) |

## Exemples de requête

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

## Exemples de réponse

### Succès (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 structure des champs retournés est identique à celle de [Obtenir les détails d’une demande de service de la plateforme AceDataCloud](https://platform.acedata.cloud/documents/platform-application-detail).

### Déjà demandé (HTTP 400)

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

Il s’agit d’une restriction stricte par conception : **chaque utilisateur ne peut avoir qu’une seule Application pour chaque service**. Si elle existe déjà, recherchez celle existante via [Obtenir la liste des demandes de service de la plateforme AceDataCloud](https://platform.acedata.cloud/documents/platform-application-list).

### Service introuvable (HTTP 404)

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

### Le service nécessite une vérification (HTTP 403)

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

Si le service a `need_verify=true` (ce champ est visible dans la liste des services), vous devez suivre le processus de ticket pour demander l’ajout à la liste blanche.

## Gestion des erreurs

| HTTP | code | Signification |
| - | - | - |
| 400 | `duplication` | Ce service a déjà été demandé par le compte actuel |
| 400 | `invalid` | `service_id` est manquant ou son format est incorrect |
| 401 | `not_authenticated` | Le jeton du compte est manquant ou a été supprimé |
| 403 | `need_verify` | Le service nécessite une vérification, veuillez suivre le processus de ticket |
| 404 | `not_found` | Le service n'existe pas ou a été retiré |

Format unifié de réponse d'erreur :

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

## Conseils pratiques

* **La création elle-même n'entraîne aucun débit** : lors de la première création, le quota initial est défini selon le `free_amount` actuel du service ; cette valeur peut être 0, et créer à nouveau une Application du même type ne garantit pas l'attribution répétée du quota gratuit.
* **Vérifiez le champ `paid` pour savoir si un paiement est requis** : juste après la demande, `paid=false` ; après avoir appelé [Créer une commande de recharge de la plateforme AceDataCloud](https://platform.acedata.cloud/documents/platform-order-create) et terminé le paiement, il devient `true`.
* **`disabled=true` signifie que le service est temporairement désactivé** — par exemple, en cas de déclenchement du contrôle des risques, d'impayé, etc. Lorsqu'il est désactivé, l'interface métier renvoie `403`.
* **Ne créez pas de manière concurrente sans limite** : récupérez d'abord le `service_id` cible depuis la liste paginée des services, puis demandez-les un par un selon les besoins métier ; en cas de `duplication`, réutilisez l'Application existante.

## Interfaces associées

* [Obtenir la liste des services de la plateforme AceDataCloud](https://platform.acedata.cloud/documents/platform-service-list) — choisissez d'abord le service
* [Obtenir la liste des demandes de services de la plateforme AceDataCloud](https://platform.acedata.cloud/documents/platform-application-list) — consultez toutes les demandes déjà effectuées
* [Obtenir les détails d'une demande de service de la plateforme AceDataCloud](https://platform.acedata.cloud/documents/platform-application-detail) — consultez une demande individuelle
* [Créer des identifiants API de la plateforme AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create) — étape suivante après une demande réussie
* [Créer une commande de recharge de la plateforme AceDataCloud](https://platform.acedata.cloud/documents/platform-order-create) — rechargez après épuisement du quota gratuit


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