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

# Tworzenie wniosku o usługę platformy AceDataCloud

> Platform API guide - Ace Data Cloud

„Wniosek (Application)” oznacza relację subskrypcji bieżącego konta dla określonej usługi — należy najpierw złożyć wniosek, aby następnie utworzyć dla tego wniosku poświadczenia API i wywoływać interfejsy biznesowe. Przy pierwszym złożeniu wniosku o daną usługę Application otrzyma aktualnie skonfigurowaną dla tej usługi wartość `free_amount`; wartość ta może wynosić 0.

> ℹ️ Ten interfejs należy do **API zarządzania platformą AceDataCloud**, ze wspólnym prefiksem `https://platform.acedata.cloud/api/v1/`. Pełny indeks interfejsów znajduje się w dokumencie [Pobieranie listy dokumentów platformy AceDataCloud](https://platform.acedata.cloud/documents/platform-document-list).

## Pełny proces integracji

Nowi użytkownicy, od rejestracji do uruchomienia pierwszego interfejsu biznesowego, zazwyczaj przechodzą przez tych 5 kroków:

1. **Uzyskanie tokenu konta** → [Zarządzanie tokenami konta platformy AceDataCloud](https://platform.acedata.cloud/documents/platform-token)
2. **Wybór usługi** → [Pobieranie listy usług platformy AceDataCloud](https://platform.acedata.cloud/documents/platform-service-list)
3. **Tworzenie wniosku** (ten dokument) → uzyskanie początkowego limitu zgodnie z konfiguracją usługi
4. **Tworzenie poświadczeń API** → [Tworzenie poświadczeń API platformy AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create)
5. **Wywoływanie interfejsu biznesowego** → użycie uzyskanego 32-znakowego Tokena do wywołania `https://api.acedata.cloud/<path>`

## Przegląd interfejsu

| Element | Treść |
| - | - |
| Metoda | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/applications/` |
| Uwierzytelnianie | ✅ Wymagany token konta |
| Content-Type | `application/json` |

## Opis uwierzytelniania (jak uzyskać token konta)

Nagłówek żądania:

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

Token konta (Account Token) to „klucz na poziomie konta”, za pomocą którego deweloper zarządza przez API zasobami własnego konta. Sposoby uzyskania:

1. **Tworzenie jednym kliknięciem w konsoli (zalecane)**: zaloguj się do [platformy AceDataCloud](https://platform.acedata.cloud) → [konsoli Account Token](https://platform.acedata.cloud/console/platform-tokens) → kliknij „Utwórz”, aby uzyskać token rozpoczynający się od `platform-v1-`.
2. **Tworzenie przez API**: użyj istniejącego tokenu konta albo JWT sesji logowania w przeglądarce, aby wywołać `POST /api/v1/platform-tokens/`; szczegóły znajdują się w [Zarządzaniu tokenami konta platformy AceDataCloud](https://platform.acedata.cloud/documents/platform-token).

> ⚠️ Token konta jest równie wrażliwy jak hasło; nie wolno umieszczać go w kodzie frontendowym ani publicznych repozytoriach. W przypadku wycieku natychmiast usuń go w konsoli i utwórz ponownie.

## Treść żądania

| Parametr | Typ | Wymagany | Opis |
| - | - | - | - |
| `service_id` | UUID | ✅ | ID usługi, o którą składany jest wniosek. Można je uzyskać z `items[].id` na [liście usług](https://platform.acedata.cloud/documents/platform-service-list) |

## Przykłady żądań

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

## Przykład odpowiedzi

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

Struktura zwracanych pól jest zgodna z [Pobieraniem szczegółów wniosku o usługę platformy AceDataCloud](https://platform.acedata.cloud/documents/platform-application-detail).

### Wniosek został już złożony (HTTP 400)

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

Jest to twarde ograniczenie projektowe: **każdy użytkownik może mieć tylko jeden Application dla każdej usługi**. Jeśli już istnieje, znajdź istniejący za pomocą [Pobierania listy wniosków o usługi platformy AceDataCloud](https://platform.acedata.cloud/documents/platform-application-list).

### Usługa nie istnieje (HTTP 404)

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

### Usługa wymaga weryfikacji (HTTP 403)

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

Jeśli usługa ma `need_verify=true` (to pole jest widoczne na liście usług), należy przejść przez proces zgłoszenia, aby wnioskować o dodanie do białej listy.

## Obsługa błędów

| HTTP | kod | Znaczenie |
| - | - | - |
| 400 | `duplication` | Usługa została już zamówiona przez bieżące konto |
| 400 | `invalid` | Brak `service_id` lub nieprawidłowy format |
| 401 | `not_authenticated` | Brak tokenu konta lub token został usunięty |
| 403 | `need_verify` | Usługa wymaga weryfikacji, proszę przejść przez proces zgłoszenia |
| 404 | `not_found` | Usługa nie istnieje lub została wyłączona |

Ujednolicony format odpowiedzi błędu:

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

## Praktyczne wskazówki

* **Samo utworzenie nie powoduje opłaty**: przy pierwszym utworzeniu początkowy limit jest ustawiany zgodnie z aktualnym `free_amount` usługi; wartość ta może wynosić 0, a ponowne utworzenie Application tego samego typu nie gwarantuje ponownego przyznania darmowego limitu.
* **To, czy wymagana jest płatność, sprawdza się w polu `paid`**: bezpośrednio po złożeniu wniosku `paid=false`, po wywołaniu [Utwórz zlecenie doładowania na platformie AceDataCloud](https://platform.acedata.cloud/documents/platform-order-create) i zakończeniu płatności zmienia się na `true`.
* **`disabled=true` oznacza tymczasowe wyłączenie** — na przykład z powodu uruchomienia kontroli ryzyka, zaległości w płatności itd. Gdy usługa jest wyłączona, interfejs biznesowy zwróci `403`.
* **Nie twórz bezgranicznie równolegle**: najpierw pobierz docelowe `service_id` z paginowanej listy usług, a następnie składaj wnioski pojedynczo zgodnie z potrzebami biznesowymi; w przypadku `duplication` użyj istniejącego Application.

## Powiązane interfejsy

* [Pobierz listę usług platformy AceDataCloud](https://platform.acedata.cloud/documents/platform-service-list) — najpierw wybierz usługę
* [Pobierz listę wniosków o usługi platformy AceDataCloud](https://platform.acedata.cloud/documents/platform-application-list) — zobacz wszystkie złożone wnioski
* [Pobierz szczegóły wniosku o usługę platformy AceDataCloud](https://platform.acedata.cloud/documents/platform-application-detail) — zobacz pojedynczy wniosek
* [Utwórz poświadczenia API platformy AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create) — następny krok po pomyślnym złożeniu wniosku
* [Utwórz zlecenie doładowania na platformie AceDataCloud](https://platform.acedata.cloud/documents/platform-order-create) — doładuj po wykorzystaniu darmowego limitu


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