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

# Server API 직접 연동

> 게임 자체 UI로 크리에이터 부스트 + 결제를 직접 연동하는 방식

게임 내 자체 UI로 크리에이터 검색/선택/부스트를 구현하고, Server API를 직접 호출하는 방식입니다. 게임 UX에 완벽히 맞출 수 있지만 UI 개발이 필요합니다.

## 이 방식이 적합한 경우

* 크리에이터 선택 UI를 게임 스타일로 직접 구현하고 싶을 때
* 게임 UX 흐름에 자연스럽게 통합하고 싶을 때
* 부스트 등록/해제 타이밍을 게임 로직으로 제어하고 싶을 때

## 전체 흐름

```mermaid theme={null}
sequenceDiagram
    participant U as 게임 유저
    participant C as 게임 클라이언트
    participant S as 게임 서버
    participant P as PlayCamp SDK API

    rect rgb(40, 40, 60)
    Note over U,P: 1. 크리에이터 선택 (게임 자체 UI)
    U->>C: 크리에이터 목록 화면 열기
    C->>S: 크리에이터 검색 요청
    S->>P: 크리에이터 검색 (GET /creators/search)
    P-->>S: 크리에이터 목록 반환
    S-->>C: 크리에이터 목록 전달
    U->>C: 크리에이터 선택
    end

    rect rgb(40, 60, 40)
    Note over U,P: 2. 부스트 등록 (Server API)
    C->>S: 부스트 등록 요청
    S->>P: 부스트 등록 (POST /sponsors)
    P-->>S: 부스트 결과 반환
    S-->>C: 완료 알림
    end

    rect rgb(60, 40, 40)
    Note over U,P: 3. 결제 등록 (인게임 결제 발생 시)
    U->>C: 인게임 결제
    C->>S: 결제 완료 알림
    S->>P: 결제 등록 (POST /payments)
    P-->>S: 크리에이터 귀속 확인
    end

    rect rgb(60, 60, 40)
    Note over U,P: 4. 정산
    Note over P: 월말 정산 → 크리에이터별 수익 계산
    end
```

## 게임사 개발 작업

| # | 작업              | 담당       | 설명                  |
| - | --------------- | -------- | ------------------- |
| 1 | 크리에이터 검색/선택 UI  | 게임 클라이언트 | 크리에이터 목록, 검색, 선택 화면 |
| 2 | 크리에이터 조회 API 연동 | 게임 서버    | 크리에이터/캠페인 데이터 조회    |
| 3 | 부스트 등록 API 연동   | 게임 서버    | 유저-크리에이터 매칭         |
| 4 | 결제 등록 API 연동    | 게임 서버    | 인게임 결제 발생 시 전송      |
| 5 | (선택) 웹훅 수신      | 게임 서버    | 외부 변경사항 수신          |

***

## Step 1: 크리에이터 조회 (게임 서버)

게임 서버에서 크리에이터 정보를 조회하여 게임 클라이언트에 표시합니다.

### 크리에이터 검색

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    # 키워드로 검색
    curl "https://sandbox-sdk-api.playcamp.io/v1/server/creators/search?q=크리에이터이름" \
      -H "Authorization: Bearer ak_server_xxx:secret"

    # 특정 크리에이터 상세 조회
    curl "https://sandbox-sdk-api.playcamp.io/v1/server/creators/ABC12" \
      -H "Authorization: Bearer ak_server_xxx:secret"
    ```
  </Tab>

  <Tab title="Node SDK">
    ```typescript theme={null}
    // 키워드로 검색
    const creators = await server.creators.search({ q: '크리에이터이름' });

    // 특정 크리에이터 상세 조회
    const creator = await server.creators.get('ABC12');
    ```
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    // 키워드로 검색
    creators, err := server.Creators.Search(ctx, playcamp.SearchCreatorsParams{
        Q: "크리에이터이름",
    })

    // 특정 크리에이터 상세 조회
    creator, err := server.Creators.Get(ctx, "ABC12")
    ```
  </Tab>
</Tabs>

### 캠페인 크리에이터 목록

특정 캠페인에 참여 중인 크리에이터만 조회할 수도 있습니다.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl "https://sandbox-sdk-api.playcamp.io/v1/server/campaigns/campaign_001" \
      -H "Authorization: Bearer ak_server_xxx:secret"
    ```
  </Tab>

  <Tab title="Node SDK">
    ```typescript theme={null}
    const campaign = await server.campaigns.get('campaign_001');
    ```
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    campaign, err := server.Campaigns.Get(ctx, "campaign_001")
    ```
  </Tab>
</Tabs>

> 상세: [API 레퍼런스 - 조회 엔드포인트](/ko/guides/developers/game-integration/reference#server-api-엔드포인트)

## Step 2: 부스트 등록 (게임 서버)

유저가 크리에이터를 선택하면 게임 서버에서 부스트를 등록합니다.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://sandbox-sdk-api.playcamp.io/v1/server/sponsors" \
      -H "Authorization: Bearer ak_server_xxx:secret" \
      -H "Content-Type: application/json" \
      -d '{
        "userId": "게임_유저_고유번호",
        "creatorKey": "ABC12"
      }'
    ```
  </Tab>

  <Tab title="Node SDK">
    ```typescript theme={null}
    const sponsor = await server.sponsors.create({
      userId: '게임_유저_고유번호',
      creatorKey: 'ABC12',
    });
    ```
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    sponsor, err := server.Sponsors.Create(ctx, playcamp.CreateSponsorParams{
        UserID:     "게임_유저_고유번호",
        CreatorKey: "ABC12",
    })
    ```
  </Tab>
</Tabs>

**응답**

```json theme={null}
{
  "data": {
    "userId": "게임_유저_고유번호",
    "campaignId": "campaign_001",
    "creatorKey": "ABC12",
    "isActive": true,
    "sponsoredAt": "2024-01-15T10:30:00.000Z"
  }
}
```

### 부스트 변경 규칙

`POST /sponsors`는 upsert 방식으로 동작합니다:

| 현재 상태          | 동작           |
| -------------- | ------------ |
| 부스트 없음         | 신규 생성        |
| 같은 크리에이터 부스트 중 | 현재 상태 반환     |
| 다른 크리에이터 부스트 중 | 30일 쿨다운 후 변경 |
| 부스트 종료됨        | 다시 활성화       |

> 상세: [크리에이터 부스트](/ko/guides/developers/game-integration/sponsor)

## Step 3: 결제 등록 (게임 서버)

인게임 결제가 발생하면 PlayCamp로 결제 정보를 전송합니다. 부스트 중인 크리에이터에게 자동 귀속됩니다.

<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": "게임_유저_고유번호",
        "transactionId": "txn_abc123",
        "productId": "gem_pack_100",
        "productName": "100 보석 팩",
        "amount": 9900,
        "currency": "KRW",
        "platform": "Android",
        "distributionType": "MOBILE_STORE",
        "purchasedAt": "2024-01-15T10:30:00.000Z"
      }'
    ```
  </Tab>

  <Tab title="Node SDK">
    ```typescript theme={null}
    const payment = await server.payments.create({
      userId: '게임_유저_고유번호',
      transactionId: 'txn_abc123',
      productId: 'gem_pack_100',
      productName: '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}
    purchasedAt, _ := time.Parse(time.RFC3339, "2024-01-15T10:30:00Z")

    payment, err := server.Payments.Create(ctx, playcamp.CreatePaymentParams{
        UserID:           "게임_유저_고유번호",
        TransactionID:    "txn_abc123",
        ProductID:        "gem_pack_100",
        ProductName:      playcamp.String("100 보석 팩"),
        Amount:           9900,
        Currency:         "KRW",
        Platform:         playcamp.PaymentPlatformAndroid,
        DistributionType: playcamp.String("MOBILE_STORE"),
        PurchasedAt:      purchasedAt,
    })
    ```
  </Tab>
</Tabs>

> 상세: [결제 등록](/ko/guides/developers/game-integration/payment)

## Step 4: (선택) 웹훅 수신

Server API 직접 연동 방식에서는 부스트 등록/해제를 게임 서버가 직접 호출하므로, 결과를 이미 알고 있습니다. 하지만 다음 경우에 웹훅이 유용합니다:

* PlayCamp 관리자가 부스트를 수동 변경한 경우
* 결제 등록 결과를 비동기로 확인하고 싶은 경우
* 쿠폰 사용 이벤트를 수신하고 싶은 경우

> 상세: [웹훅 이벤트](/ko/guides/developers/game-integration/webhook)

## Step 5: 정산

결제 데이터를 기반으로 월 단위 정산이 진행됩니다.

1. **매출 마감** — 매월 말 기준으로 결제 데이터 집계
2. **매출 대사** — PlayCamp에서 제공하는 정산 내역과 게임사 내부 데이터 대사
3. **정산 입금** — 대사 확인 후 정산 금액 입금
4. **크리에이터 정산** — PlayCamp가 크리에이터에게 수익 분배

> 상세: [정산](/ko/guides/developers/settlement)