> ## Documentation Index
> Fetch the complete documentation index at: https://playcamp.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API 레퍼런스

> SDK API 엔드포인트 빠른 참조

## 에러 응답 형식

```json theme={null}
{
  "error": "에러 메시지",
  "code": "ERROR_CODE"
}
```

## 공통 에러 코드

| HTTP | 코드                 | 설명               |
| ---- | ------------------ | ---------------- |
| 400  | `VALIDATION_ERROR` | 요청 파라미터 검증 실패    |
| 400  | `BAD_REQUEST`      | 잘못된 요청           |
| 401  | `UNAUTHORIZED`     | 인증 실패 (API 키 오류) |
| 403  | `FORBIDDEN`        | 권한 없음            |
| 404  | `NOT_FOUND`        | 리소스를 찾을 수 없음     |
| 409  | `CONFLICT`         | 중복 리소스           |
| 500  | `INTERNAL_ERROR`   | 서버 내부 오류         |

## 날짜/시간 형식

모든 날짜/시간 값은 **ISO 8601** 형식의 **UTC** 시간으로 전송해야 합니다.

**형식**

```
YYYY-MM-DDTHH:mm:ss.sssZ
```

**예시**

```json theme={null}
{
  "purchasedAt": "2024-01-15T10:30:00.000Z"
}
```

| 구성 요소        | 설명         | 예시           |
| ------------ | ---------- | ------------ |
| `YYYY-MM-DD` | 날짜 (년-월-일) | `2024-01-15` |
| `T`          | 날짜와 시간 구분자 | `T`          |
| `HH:mm:ss`   | 시간 (시:분:초) | `10:30:00`   |
| `.sss`       | 밀리초 (선택)   | `.000`       |
| `Z`          | UTC 타임존    | `Z`          |

<Warning>
  로컬 타임존이 아닌 **UTC 시간**으로 전송해야 합니다. 한국 시간(KST)은 UTC+9이므로, KST 오후 7시 30분은 UTC 오전 10시 30분(`10:30:00Z`)입니다.
</Warning>

**언어별 변환 예시**

```javascript theme={null}
// JavaScript
const now = new Date();
const isoString = now.toISOString();
// "2024-01-15T10:30:00.000Z"
```

```python theme={null}
# Python
from datetime import datetime, timezone

now = datetime.now(timezone.utc)
iso_string = now.isoformat(timespec='milliseconds').replace('+00:00', 'Z')
# "2024-01-15T10:30:00.000Z"
```

```java theme={null}
// Java
import java.time.Instant;

String isoString = Instant.now().toString();
// "2024-01-15T10:30:00.000Z"
```

## Server API 엔드포인트

| 기능                        | Method | Endpoint                                    |
| ------------------------- | ------ | ------------------------------------------- |
| **부스트 (Sponsor)**         |        |                                             |
| 부스트 등록/변경                 | POST   | `/v1/server/sponsors`                       |
| 부스트 상태 조회                 | GET    | `/v1/server/sponsors/user/:userId`          |
| 부스트 해제                    | DELETE | `/v1/server/sponsors/user/:userId`          |
| **결제**                    |        |                                             |
| 결제 등록                     | POST   | `/v1/server/payments`                       |
| 결제 일괄 등록 (최대 1000건)       | POST   | `/v1/server/payments/bulk`                  |
| 결제 조회                     | GET    | `/v1/server/payments/:transactionId`        |
| 유저 결제 내역                  | GET    | `/v1/server/payments/user/:userId`          |
| 결제 환불                     | POST   | `/v1/server/payments/:transactionId/refund` |
| **쿠폰**                    |        |                                             |
| 쿠폰 검증                     | POST   | `/v1/server/coupons/validate`               |
| 쿠폰 사용                     | POST   | `/v1/server/coupons/redeem`                 |
| 유저 쿠폰 내역                  | GET    | `/v1/server/coupons/user/:userId`           |
| **조회**                    |        |                                             |
| 캠페인 목록                    | GET    | `/v1/server/campaigns`                      |
| 캠페인 상세                    | GET    | `/v1/server/campaigns/:id`                  |
| 크리에이터 검색                  | GET    | `/v1/server/creators/search`                |
| 크리에이터 상세                  | GET    | `/v1/server/creators/:creatorKey`           |
| 크리에이터 쿠폰 목록               | GET    | `/v1/server/creators/:creatorKey/coupons`   |
| **플레이타임**                 |        |                                             |
| 플레이타임 세션 기록               | POST   | `/v1/server/playtime/sessions`              |
| 플레이타임 세션 일괄 기록 (최대 1000건) | POST   | `/v1/server/playtime/sessions/bulk`         |
| **웹뷰**                    |        |                                             |
| 웹뷰 일회용 토큰(OTT) 발급         | POST   | `/v1/server/webview/ott`                    |
| **웹훅**                    |        |                                             |
| 웹훅 목록                     | GET    | `/v1/server/webhooks`                       |
| 웹훅 등록                     | POST   | `/v1/server/webhooks`                       |
| 웹훅 수정                     | PUT    | `/v1/server/webhooks/:id`                   |
| 웹훅 삭제                     | DELETE | `/v1/server/webhooks/:id`                   |
| 웹훅 로그                     | GET    | `/v1/server/webhooks/:id/logs`              |
| 웹훅 테스트                    | POST   | `/v1/server/webhooks/:id/test`              |

## Client API 엔드포인트

| 기능                | Method | Endpoint                            |
| ----------------- | ------ | ----------------------------------- |
| **캠페인**           |        |                                     |
| 캠페인 목록            | GET    | `/v1/client/campaigns`              |
| 캠페인 상세            | GET    | `/v1/client/campaigns/:id`          |
| 캠페인 크리에이터 목록      | GET    | `/v1/client/campaigns/:id/creators` |
| 캠페인 패키지 목록        | GET    | `/v1/client/campaigns/:id/packages` |
| **크리에이터**         |        |                                     |
| 크리에이터 검색          | GET    | `/v1/client/creators/search`        |
| 크리에이터 상세          | GET    | `/v1/client/creators/:creatorKey`   |
| **쿠폰**            |        |                                     |
| 쿠폰 검증             | POST   | `/v1/client/coupons/validate`       |
| **부스트 (Sponsor)** |        |                                     |
| 부스트 상태 조회         | GET    | `/v1/client/sponsors`               |