> ## 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 整合指南 - Ace Data Cloud

「申請（Application）」表示目前帳戶對某個服務的訂閱關係——必須先申請，才能再為這個申請建立 API 憑證、呼叫業務介面。首次申請某個服務時，Application 會獲得該服務目前設定的 `free_amount`；該值可能為 0。

> ℹ️ 本介面屬於 **AceDataCloud 平台管理 API**，統一前綴 `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 憑證** → [建立 AceDataCloud 平台 API 憑證](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。可從[服務列表](https://platform.acedata.cloud/documents/platform-service-list)的 `items[].id` 取得 |

## 請求範例

### 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 | code | 含義 |
| - | - | - |
| 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) — 查看單一申請
* [建立 AceDataCloud 平台 API 憑證](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.