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

# Створення заявки на сервіс платформи AceDataCloud

> Platform API guide - Ace Data Cloud

«Заявка (Application)» означає відносини підписки поточного облікового запису на певний сервіс — спочатку необхідно подати заявку, і лише потім можна створити для цієї заявки API-облікові дані та викликати бізнес-інтерфейси. Під час першої заявки на певний сервіс Application отримає поточне значення `free_amount`, налаштоване для цього сервісу; це значення може дорівнювати 0.

> ℹ️ Цей інтерфейс належить до **API керування платформою AceDataCloud** з єдиним префіксом `https://platform.acedata.cloud/api/v1/`. Повний індекс інтерфейсів див. у [Отримання списку документації платформи AceDataCloud](https://platform.acedata.cloud/documents/platform-document-list).

## Повний процес інтеграції

Нові користувачі зазвичай проходять ці 5 кроків від реєстрації до успішного виклику першого бізнес-інтерфейсу:

1. **Отримати токен облікового запису** → [Керування токенами облікового запису платформи AceDataCloud](https://platform.acedata.cloud/documents/platform-token)
2. **Вибрати сервіс** → [Отримання списку сервісів платформи AceDataCloud](https://platform.acedata.cloud/documents/platform-service-list)
3. **Створити заявку** (цей документ) → отримати початкову квоту відповідно до конфігурації сервісу
4. **Створити API-облікові дані** → [Створення API-облікових даних платформи AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create)
5. **Викликати бізнес-інтерфейс** → використати отриманий 32-символьний Token для виклику `https://api.acedata.cloud/<path>`

## Огляд інтерфейсу

| Параметр | Вміст |
| - | - |
| Метод | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/applications/` |
| Авторизація | ✅ Потрібен токен облікового запису |
| Content-Type | `application/json` |

## Пояснення авторизації (як отримати токен облікового запису)

Заголовок запиту:

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

Токен облікового запису (Account Token) — це «ключ рівня облікового запису», який розробник використовує для керування ресурсами свого облікового запису через API. Способи отримання:

1. **Створення одним кліком у консолі (рекомендовано)**: увійдіть до [платформи AceDataCloud](https://platform.acedata.cloud) → [консолі Account Token](https://platform.acedata.cloud/console/platform-tokens) → натисніть «Створити», щоб отримати токен, який починається з `platform-v1-`.
2. **Створення через API**: використайте наявний токен облікового запису або JWT стану входу браузера для виклику `POST /api/v1/platform-tokens/`; докладніше див. у [Керування токенами облікового запису платформи AceDataCloud](https://platform.acedata.cloud/documents/platform-token).

> ⚠️ Токен облікового запису є настільки ж конфіденційним, як і пароль; заборонено записувати його у фронтенд-код або публічні репозиторії. У разі витоку негайно видаліть його в консолі та створіть заново.

## Тіло запиту

| Параметр | Тип | Обов’язковий | Опис |
| - | - | - | - |
| `service_id` | UUID | ✅ | ID сервісу, на який потрібно подати заявку. Його можна отримати з `items[].id` у [списку сервісів](https://platform.acedata.cloud/documents/platform-service-list) |

## Приклади запитів

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

## Приклади відповідей

### Успіх (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"
}
```

Структура полів відповіді узгоджується з [Отриманням деталей заявки на сервіс платформи AceDataCloud](https://platform.acedata.cloud/documents/platform-application-detail).

### Заявку вже подано (HTTP 400)

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

Це жорстке обмеження в дизайні: **кожен користувач може мати лише один Application для кожного сервісу**. Якщо він уже існує, знайдіть наявний через [Отримання списку заявок на сервіси платформи AceDataCloud](https://platform.acedata.cloud/documents/platform-application-list).

### Сервіс не існує (HTTP 404)

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

### Сервіс потребує перевірки (HTTP 403)

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

Якщо для сервісу встановлено `need_verify=true` (це поле можна побачити у списку сервісів), необхідно пройти процес подання заявки через тікет для додавання до білого списку.

## Обробка помилок

| HTTP | код | Значення |
| - | - | - |
| 400 | `duplication` | Цю послугу вже було замовлено поточним обліковим записом |
| 400 | `invalid` | `service_id` відсутній або має неправильний формат |
| 401 | `not_authenticated` | Відсутній токен облікового запису або токен було видалено |
| 403 | `need_verify` | Послуга потребує перевірки, будь ласка, скористайтеся процесом тікетів |
| 404 | `not_found` | Послуга не існує або була знята з обслуговування |

Єдиний формат відповіді про помилку:

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

## Практичні поради

* **Саме створення не списує кошти**: під час першого створення початковий ліміт встановлюється відповідно до поточного `free_amount` послуги; це значення може бути 0, а повторне створення Application того ж типу не гарантує повторного надання.
* **Чи потрібна оплата, дивіться за полем `paid`**: щойно після подання заявки `paid=false`, після виклику [Створити замовлення на поповнення платформи AceDataCloud](https://platform.acedata.cloud/documents/platform-order-create) для завершення оплати воно стає `true`.
* **`disabled=true` означає тимчасове вимкнення** — наприклад, через спрацювання контролю ризиків, заборгованість тощо. Якщо вимкнено, бізнес-інтерфейси повертатимуть `403`.
* **Не створюйте необмежену кількість заявок паралельно**: спочатку отримайте цільовий `service_id` зі списку послуг із пагінацією, а потім подавайте заявки по черзі відповідно до бізнес-потреб; у разі `duplication` повторно використовуйте наявний Application.

## Пов’язані інтерфейси

* [Отримати список послуг платформи AceDataCloud](https://platform.acedata.cloud/documents/platform-service-list) — спочатку виберіть послугу
* [Отримати список заявок на послуги платформи AceDataCloud](https://platform.acedata.cloud/documents/platform-application-list) — переглянути всі вже подані заявки
* [Отримати деталі заявки на послугу платформи AceDataCloud](https://platform.acedata.cloud/documents/platform-application-detail) — переглянути окрему заявку
* [Створити облікові дані API платформи AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create) — наступний крок після успішного подання заявки
* [Створити замовлення на поповнення платформи AceDataCloud](https://platform.acedata.cloud/documents/platform-order-create) — поповнення після вичерпання безкоштовного ліміту


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