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

# 개요

> PlayCamp SDK API 연동 아키텍처 및 시작하기

## 아키텍처

PlayCamp SDK API는 게임 서버를 통해 연동됩니다.

```mermaid theme={null}
flowchart LR
  subgraph 클라이언트
    A[게임 클라이언트]
  end
  subgraph 게임사
    B[게임 서버]
  end
  subgraph PlayCamp
    C[SDK API 서버]
  end
  A <-->|UI 인터랙션| B
  B -->|API 호출| C
  C -.->|웹훅 이벤트| B
```

### 역할 분담

| 구성 요소                | 역할                                 |
| -------------------- | ---------------------------------- |
| **게임 클라이언트**         | 유저 인터페이스 (크리에이터 선택 UI, 쿠폰 입력 화면 등) |
| **게임 서버**            | API 호출, 비즈니스 로직 처리, Server Key 보관  |
| **PlayCamp SDK API** | 데이터 저장, 정산 계산, 통계 집계, 웹훅 발송        |

### 데이터 흐름 예시

<Steps>
  <Step title="크리에이터 선택">
    유저가 게임에서 크리에이터를 선택
  </Step>

  <Step title="부스트 등록">
    게임 서버가 `POST /v1/server/sponsors` 호출
  </Step>

  <Step title="인게임 결제">
    유저가 인게임 결제 진행
  </Step>

  <Step title="결제 등록">
    게임 서버가 `POST /v1/server/payments` 호출
  </Step>

  <Step title="자동 귀속">
    SDK API가 해당 결제를 크리에이터에게 자동 귀속
  </Step>

  <Step title="정산">
    월말 정산 시 크리에이터별 수익 계산
  </Step>
</Steps>

## 시작하기

### 필수 연동 API

캠페인 진행을 위해 **반드시 연동해야 하는** Server API 3개입니다.

| 기능         | API                      | 설명                        |
| ---------- | ------------------------ | ------------------------- |
| **부스트 등록** | `POST /sponsors`         | 유저가 크리에이터를 부스트. 결제 귀속의 핵심 |
| **쿠폰 검증**  | `POST /coupons/validate` | 쿠폰 코드 유효성 검사              |
| **결제 등록**  | `POST /payments`         | 인게임 결제 등록. 정산의 기초 데이터     |

<Warning>
  **캠페인 게시를 위해 연동 검증이 필요합니다.** 위 3개 API를 각각 최소 1번 이상 **Live** 환경에서 호출해야 캠페인을 게시할 수 있습니다. 이 검증이 완료되지 않으면 캠페인 승인 화면에 다음 메시지가 표시됩니다:

  *"게임과 PlayCamp가 연동되어 있지 않습니다. API를 통해 연동이 필요합니다."*

  검증 호출 시 `isTest: true`를 사용할 수 있습니다. 테스트 모드 요청도 연동 검증으로 인정되며, 실제 데이터는 저장되지 않습니다.
</Warning>

**연동 검증 흐름:**

<Steps>
  <Step title="API 연동">
    게임 서버에 필수 API 3개를 구현합니다
  </Step>

  <Step title="Live 환경에서 호출">
    각 API를 **Live** 환경(`https://sdk-api.playcamp.io`)에서 최소 1번씩 호출합니다. `isTest: true` 사용이 가능합니다.
  </Step>

  <Step title="캠페인 승인 요청">
    3개 API 검증이 완료되면 PlayCamp 관리자에게 승인을 요청합니다
  </Step>

  <Step title="캠페인 게시">
    승인 후 연동 경고 메시지가 사라지고 캠페인이 최종 게시 상태로 전환됩니다
  </Step>
</Steps>

<Note>
  캠페인/크리에이터 조회, 웹훅 등은 선택적으로 연동하면 됩니다.
</Note>

### API 키 발급

PlayCamp 플랫폼에서 프로젝트 생성 후 API 키를 발급받습니다.

| 키 타입           | 용도                | 보관 위치             |
| -------------- | ----------------- | ----------------- |
| **Server Key** | 모든 API 호출 (읽기/쓰기) | 게임 서버 (안전하게 보관)   |
| **Client Key** | 조회 API만 (읽기 전용)   | 게임 클라이언트 (선택적 사용) |

<Warning>
  Server Key는 절대 클라이언트에 노출하지 마세요.
</Warning>

### 인증 방식

모든 API 요청에 Bearer Token 인증을 사용합니다.

```bash theme={null}
Authorization: Bearer {keyId}:{secret}
```

예시:

```bash theme={null}
Authorization: Bearer ak_server_abc123def456:xyz789secretkey
```

### 서버 환경

| 환경          | URL                                   | 용도     |
| ----------- | ------------------------------------- | ------ |
| **Sandbox** | `https://sandbox-sdk-api.playcamp.io` | 개발/테스트 |
| **Live**    | `https://sdk-api.playcamp.io`         | 실제 서비스 |

<Info>
  개발 중에는 Sandbox 환경을 사용하세요. Sandbox는 Live와 완전히 격리되어 있습니다.
</Info>

### 연동 순서

```
1. POST /sponsors          → 유저가 크리에이터 선택 (부스트)
2. POST /coupons/validate  → 쿠폰 코드 검증
3. POST /payments          → 인게임 결제 발생 시 등록
```

## SDK

타입 안전한 연동을 위해 HTTP 직접 호출 대신 공식 SDK를 사용할 수 있습니다:

<Tabs>
  <Tab title="Node SDK">
    ```bash theme={null}
    npm install @playcamp/node-sdk
    ```

    ```typescript theme={null}
    import { PlayCampServer } from '@playcamp/node-sdk';

    const server = new PlayCampServer('your_server_key:your_secret', {
      environment: 'sandbox',
    });
    ```

    자세한 내용은 [Node SDK 가이드](/ko/guides/developers/game-integration/node-sdk)를 참조하세요.
  </Tab>

  <Tab title="Go SDK">
    ```bash theme={null}
    go get github.com/playcamp/playcamp-go-sdk
    ```

    ```go theme={null}
    import playcamp "github.com/playcamp/playcamp-go-sdk"

    server, err := playcamp.NewServer("your_server_key:your_secret",
        playcamp.WithEnvironment(playcamp.EnvironmentSandbox),
    )
    ```

    자세한 내용은 [Go SDK 가이드](/ko/guides/developers/game-integration/go-sdk)를 참조하세요.
  </Tab>
</Tabs>

## 테스트 모드

캠페인 시작 전 `isTest: true` 파라미터를 사용하여 API 연동을 테스트할 수 있습니다.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://sandbox-sdk-api.playcamp.io/v1/server/payments" \
      -H "Authorization: Bearer ak_server_xxx:secret" \
      -H "Content-Type: application/json" \
      -d '{
        "userId": "test_user",
        "transactionId": "test_txn_001",
        "productId": "gem_pack_100",
        "amount": 9900,
        "currency": "KRW",
        "platform": "Android",
        "distributionType": "MOBILE_STORE",
        "purchasedAt": "2024-01-15T10:30:00.000Z",
        "isTest": true
      }'
    ```
  </Tab>

  <Tab title="Node SDK">
    ```typescript theme={null}
    const server = new PlayCampServer('your_server_key:your_secret', {
      environment: 'sandbox',
      isTest: true,
    });

    const payment = await server.payments.create({
      userId: 'test_user',
      transactionId: 'test_txn_001',
      productId: 'gem_pack_100',
      amount: 9900,
      currency: 'KRW',
      platform: 'Android',
      distributionType: 'MOBILE_STORE',
      purchasedAt: new Date('2024-01-15T10:30:00Z'),
    });
    ```
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    server, err := playcamp.NewServer("your_server_key:your_secret",
        playcamp.WithEnvironment(playcamp.EnvironmentSandbox),
        playcamp.WithTestMode(true),
    )

    purchasedAt, _ := time.Parse(time.RFC3339, "2024-01-15T10:30:00Z")

    payment, err := server.Payments.Create(ctx, playcamp.CreatePaymentParams{
        UserID:           "test_user",
        TransactionID:    "test_txn_001",
        ProductID:        "gem_pack_100",
        Amount:           9900,
        Currency:         "KRW",
        Platform:         playcamp.PaymentPlatformAndroid,
        DistributionType: playcamp.String("MOBILE_STORE"),
        PurchasedAt:      purchasedAt,
    })
    ```
  </Tab>
</Tabs>

**테스트 모드 특징:**

* 요청 파라미터 검증은 실제와 동일하게 수행
* 데이터는 DB에 저장되지 않음
* Mock 응답 반환

<Note>
  **권장**: 캠페인 시작 전 연동 시에는 `isTest: true`를 사용하여 테스트하세요. `isTest`는 Sandbox와 Live 환경 모두에서 사용 가능합니다. 실제 캠페인 운영 시에는 `isTest` 파라미터를 제거하세요.
</Note>

자세한 내용은 [테스트 모드](/ko/guides/developers/game-integration/test-mode)를 참조하세요.