크리에이터 부스트

유저가 응원하는 크리에이터를 설정합니다. 부스트 설정 후 해당 유저의 결제는 자동으로 크리에이터에게 귀속됩니다.

POST /sponsors 동작

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

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

POST /sponsors는 부스트 생성과 변경을 하나의 API로 처리합니다. 변경만 명시적으로 처리하려면 부스트 크리에이터 변경의 PUT 엔드포인트를 사용하세요.

흐름

1. 크리에이터 검색/선택  →  2. 부스트 등록 (POST /sponsors)  →  3. 이후 결제 자동 귀속

부스트 등록

campaignId를 지정하지 않으면 현재 활성화된 캠페인으로 자동 귀속됩니다.

한 게임에서 여러 캠페인을 운영하는 경우, 반드시 campaignId를 명시하여 캠페인을 구분해야 합니다.

요청

cURL
Node SDK
Go SDK

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": "user_12345",
    "creatorKey": "ABC12",
    "callbackId": "game-session-abc123"
  }'

const sponsor = await server.sponsors.create({
  userId: 'user_12345',
  creatorKey: 'ABC12',
  callbackId: 'game-session-abc123', // optional
});

sponsor, err := server.Sponsors.Create(ctx, playcamp.CreateSponsorParams{
    UserID:     "user_12345",
    CreatorKey: "ABC12",
    CallbackID: "game-session-abc123", // optional
})

응답 (201 Created)

{
  "data": {
    "userId": "user_12345",
    "campaignId": "campaign_001",
    "creatorKey": "ABC12",
    "creatorName": "홍길동",
    "isActive": true,
    "sponsoredAt": "2024-01-15T10:30:00.000Z"
  }
}

creatorName은 표시용 필드입니다. 크리에이터 이름을 조회할 수 없는 경우 creatorKey 값이 그대로 들어갑니다.

부스트 크리에이터 변경

기존 부스트를 다른 크리에이터로 변경합니다. 부스트 등록(또는 최근 변경) 시점으로부터 30일이 지난 후에만 변경할 수 있습니다.

변경 시 30일 쿨다운이 초기화되고 sponsor.changed 웹훅이 발송됩니다. 변경 내역은 부스트 변경 이력에 CHANGED 액션으로 기록됩니다.

요청

cURL
Node SDK
Go SDK

curl -X PUT "https://sandbox-sdk-api.playcamp.io/v1/server/sponsors/user/user_12345" \
  -H "Authorization: Bearer ak_server_xxx:secret" \
  -H "Content-Type: application/json" \
  -d '{
    "newCreatorKey": "XYZ99",
    "callbackId": "game-session-abc123"
  }'

const sponsor = await server.sponsors.update('user_12345', {
  newCreatorKey: 'XYZ99',
  callbackId: 'game-session-abc123', // optional
});

sponsor, err := server.Sponsors.Update(ctx, "user_12345", playcamp.UpdateSponsorParams{
    NewCreatorKey: "XYZ99",
    CallbackID:    "game-session-abc123", // optional
})

응답 (200 OK)

{
  "data": {
    "userId": "user_12345",
    "campaignId": "campaign_001",
    "creatorKey": "XYZ99",
    "creatorName": "김철수",
    "isActive": true,
    "sponsoredAt": "2024-02-20T09:00:00.000Z"
  }
}

부스트 해제

campaignId를 지정하지 않으면 활성 캠페인의 부스트가 해제됩니다. 요청

cURL
Node SDK
Go SDK

curl -X DELETE "https://sandbox-sdk-api.playcamp.io/v1/server/sponsors/user/user_12345" \
  -H "Authorization: Bearer ak_server_xxx:secret"

await server.sponsors.remove('user_12345');

err := server.Sponsors.Delete(ctx, "user_12345", nil)

부스트 변경 이력

유저의 부스트 등록·변경·해제 이력을 최신순으로 조회합니다. 요청

cURL
Node SDK
Go SDK

curl "https://sandbox-sdk-api.playcamp.io/v1/server/sponsors/user/user_12345/history?page=1&limit=20" \
  -H "Authorization: Bearer ak_server_xxx:secret"

const history = await server.sponsors.getHistory('user_12345', {
  page: 1,
  limit: 20,
});

// 전체 이력을 순회
for await (const entry of server.sponsors.listAllHistory('user_12345')) {
  console.log(entry.action, entry.creatorKey);
}

history, err := server.Sponsors.GetHistory(ctx, "user_12345", &playcamp.GetSponsorHistoryOptions{
    Page:  playcamp.Int(1),
    Limit: playcamp.Int(20),
})

응답 (200 OK)

{
  "data": [
    {
      "userId": "user_12345",
      "campaignId": "campaign_001",
      "creatorKey": "XYZ99",
      "creatorName": "김철수",
      "action": "CHANGED",
      "previousCreatorKey": "ABC12",
      "previousCreatorName": "홍길동",
      "createdAt": "2024-02-20T09:00:00.000Z"
    },
    {
      "userId": "user_12345",
      "campaignId": "campaign_001",
      "creatorKey": "ABC12",
      "creatorName": "홍길동",
      "action": "CREATED",
      "previousCreatorKey": null,
      "previousCreatorName": null,
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 2, "totalPages": 1 }
}

`action`	설명
`CREATED`	부스트 최초 등록
`CHANGED`	다른 크리에이터로 부스트 변경
`ENDED`	부스트 해제

previousCreatorKey와 previousCreatorName은 CHANGED일 때만 값이 있습니다.

선택 파라미터

필드	타입	설명
`campaignId`	string	캠페인 ID (미지정 시 활성 캠페인 자동 귀속)
`callbackId`	string	웹훅 추적용 ID (웹훅 이벤트에 포함됨)
`isTest`	boolean	테스트 모드 (실제 데이터 생성 안 함)

에러 처리

HTTP	코드	설명	대응
400	`BAD_REQUEST`	30일 쿨다운 기간 내 또는 크리에이터가 캠페인에 미참여	쿨다운 대기, 캠페인 참여 여부 확인
400	`NO_ACTIVE_CAMPAIGN`	활성 캠페인 없음 (`campaignId` 미지정)	`campaignId` 명시 또는 캠페인 상태 확인
404	`NOT_FOUND`	크리에이터 없음	creatorKey 확인

플랫폼

개발사 가이드

크리에이터 가이드

크리에이터 부스트

POST /sponsors 동작

흐름

부스트 등록

부스트 크리에이터 변경

부스트 해제

부스트 변경 이력

선택 파라미터

에러 처리

​POST /sponsors 동작

​흐름

​부스트 등록

​부스트 크리에이터 변경

​부스트 해제

​부스트 변경 이력

​선택 파라미터

​에러 처리

POST /sponsors 동작

흐름

부스트 등록

부스트 크리에이터 변경

부스트 해제

부스트 변경 이력

선택 파라미터

에러 처리