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