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

# Erstellen einer AceDataCloud-Plattformdienstanwendung

> Platform API guide - Ace Data Cloud

„Anwendung (Application)“ bezeichnet die Abonnementbeziehung des aktuellen Kontos zu einem bestimmten Dienst — Sie müssen zuerst eine Anwendung erstellen, bevor Sie für diese Anwendung API-Anmeldedaten erstellen und Geschäftsschnittstellen aufrufen können. Bei der erstmaligen Beantragung eines Dienstes erhält die Application den aktuell für diesen Dienst konfigurierten `free_amount`; dieser Wert kann 0 sein.

> ℹ️ Diese Schnittstelle gehört zur **AceDataCloud-Plattformverwaltungs-API** mit dem einheitlichen Präfix `https://platform.acedata.cloud/api/v1/`. Den vollständigen Schnittstellenindex finden Sie unter [Abrufen der AceDataCloud-Plattformdokumentenliste](https://platform.acedata.cloud/documents/platform-document-list).

## Vollständiger Integrationsprozess

Neue Benutzer durchlaufen von der Registrierung bis zum erfolgreichen Aufruf der ersten Geschäftsschnittstelle üblicherweise diese 5 Schritte:

1. **Kontotoken erhalten** → [AceDataCloud-Plattformkontotoken verwalten](https://platform.acedata.cloud/documents/platform-token)
2. **Dienst auswählen** → [AceDataCloud-Plattformdienstliste abrufen](https://platform.acedata.cloud/documents/platform-service-list)
3. **Anwendung erstellen** (dieses Dokument) → Anfangskontingent gemäß Dienstkonfiguration erhalten
4. **API-Anmeldedaten erstellen** → [AceDataCloud-Plattform-API-Anmeldedaten erstellen](https://platform.acedata.cloud/documents/platform-credential-create)
5. **Geschäftsschnittstelle aufrufen** → Das erhaltene 32-stellige Token für `https://api.acedata.cloud/<path>` verwenden

## Schnittstellenübersicht

| Element | Inhalt |
| - | - |
| Methode | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/applications/` |
| Authentifizierung | ✅ Kontotoken erforderlich |
| Content-Type | `application/json` |

## Hinweise zur Authentifizierung (wie Sie ein Kontotoken erhalten)

Request-Header:

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

Das Kontotoken (Account Token) ist der „Schlüssel auf Kontoebene“, über den Entwickler ihre eigenen Kontoressourcen per API verwalten. So erhalten Sie es:

1. **Erstellung mit einem Klick in der Konsole (empfohlen)**: Melden Sie sich bei der [AceDataCloud-Plattform](https://platform.acedata.cloud) an → [Account-Token-Konsole](https://platform.acedata.cloud/console/platform-tokens) → Klicken Sie auf „Erstellen“, um ein mit `platform-v1-` beginnendes Token zu erhalten.
2. **Erstellung per API**: Rufen Sie mit einem vorhandenen Kontotoken oder einem JWT aus der Browser-Anmeldesitzung `POST /api/v1/platform-tokens/` auf. Details finden Sie unter [AceDataCloud-Plattformkontotoken verwalten](https://platform.acedata.cloud/documents/platform-token).

> ⚠️ Kontotoken sind genauso vertraulich wie Passwörter und dürfen nicht in Frontend-Code oder öffentliche Repositorys geschrieben werden. Löschen Sie sie bei einer Offenlegung sofort in der Konsole und erstellen Sie sie neu.

## Request-Body

| Parameter | Typ | Erforderlich | Beschreibung |
| - | - | - | - |
| `service_id` | UUID | ✅ | Die ID des zu beantragenden Dienstes. Sie kann aus `items[].id` der [Dienstliste](https://platform.acedata.cloud/documents/platform-service-list) abgerufen werden |

## Request-Beispiele

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

## Antwortbeispiele

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

Die Struktur der zurückgegebenen Felder entspricht [AceDataCloud-Plattformdienstanwendungsdetails abrufen](https://platform.acedata.cloud/documents/platform-application-detail).

### Bereits beantragt (HTTP 400)

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

Dies ist eine harte Einschränkung im Design: **Jeder Benutzer kann für jeden Dienst nur eine Application haben**. Suchen Sie bei einer bereits bestehenden Anwendung über [AceDataCloud-Plattformdienstanwendungsliste abrufen](https://platform.acedata.cloud/documents/platform-application-list) nach der vorhandenen.

### Dienst nicht vorhanden (HTTP 404)

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

### Dienst erfordert Überprüfung (HTTP 403)

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

Wenn für den Dienst `need_verify=true` gilt (dieses Feld ist in der Dienstliste sichtbar), müssen Sie den Ticketprozess durchlaufen, um eine Whitelist zu beantragen.

## Fehlerbehandlung

| HTTP | Code | Bedeutung |
| - | - | - |
| 400 | `duplication` | Dieser Dienst wurde bereits vom aktuellen Konto beantragt |
| 400 | `invalid` | `service_id` fehlt oder hat ein falsches Format |
| 401 | `not_authenticated` | Kontotoken fehlt oder Token wurde gelöscht |
| 403 | `need_verify` | Der Dienst muss geprüft werden, bitte den Ticketprozess durchlaufen |
| 404 | `not_found` | Der Dienst existiert nicht oder wurde eingestellt |

Einheitliches Format der Fehlerantwort:

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

## Praktische Hinweise

* **Die Erstellung selbst verursacht keine Kosten**: Bei der erstmaligen Erstellung wird das anfängliche Kontingent gemäß dem aktuellen `free_amount` des Dienstes festgelegt; dieser Wert kann 0 sein, und bei einer erneuten Erstellung derselben Art von Application ist eine wiederholte Gewährung nicht garantiert.
* **Ob eine Zahlung erforderlich ist, hängt vom Feld `paid` ab**: Direkt nach der Beantragung gilt `paid=false`; nach dem Aufruf von [AceDataCloud-Plattform-Aufladebestellung erstellen](https://platform.acedata.cloud/documents/platform-order-create) und Abschluss der Zahlung wird es zu `true`.
* **`disabled=true` bedeutet, dass der Dienst vorübergehend deaktiviert wurde** — beispielsweise aufgrund ausgelöster Risikokontrolle, Zahlungsrückständen usw. Bei Deaktivierung geben die Geschäftsschnittstellen `403` zurück.
* **Keine unbegrenzten parallelen Erstellungen durchführen**: Zuerst die Ziel-`service_id` aus der paginierten Dienstliste abrufen und dann je nach Geschäftsbedarf einzeln beantragen; bei `duplication` die vorhandene Application wiederverwenden.

## Zugehörige Schnittstellen

* [AceDataCloud-Plattform-Dienstliste abrufen](https://platform.acedata.cloud/documents/platform-service-list) — Zuerst einen Dienst auswählen
* [AceDataCloud-Plattform-Dienstbeantragungsliste abrufen](https://platform.acedata.cloud/documents/platform-application-list) — Alle bereits beantragten anzeigen
* [Details einer AceDataCloud-Plattform-Dienstbeantragung abrufen](https://platform.acedata.cloud/documents/platform-application-detail) — Eine einzelne Beantragung anzeigen
* [AceDataCloud-Plattform-API-Anmeldedaten erstellen](https://platform.acedata.cloud/documents/platform-credential-create) — Nächster Schritt nach erfolgreicher Beantragung
* [AceDataCloud-Plattform-Aufladebestellung erstellen](https://platform.acedata.cloud/documents/platform-order-create) — Aufladen, nachdem das kostenlose Kontingent aufgebraucht ist


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