> ## 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일 수 있습니다.

> ℹ️ 이 인터페이스는 **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 | 코드 | 의미 |
| - | - | - |
| 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.