드롭스 API

인게임 보상 지급에 필요한 씨미 OpenAPI입니다. 전체 흐름은 드롭스 연동 가이드를 먼저 참고해 주세요. 요청 인증은 인증 문서를 참고해 주세요.

캠페인 목록 조회

GET /api/openapi/open/v1/drops/campaigns

본인 애플리케이션이 소유한 드롭스 캠페인 목록을 페이지 단위로 조회합니다.

쿼리 파라미터 (모두 선택)

파라미터	설명
`page`	페이지 번호 (0부터 시작, 기본 0)
`size`	페이지 크기 (기본 20, 최대 100)
`state`	상태 필터 (콤마 구분, 생략 시 모든 상태). 예: `ACTIVE,CLAIMABLE`

응답 예시

{
  "code": 200,
  "message": null,
  "content": {
    "data": [
      {
        "campaignId": "456",
        "state": "ACTIVE",
        "title": "캠페인 이름",
        "description": "캠페인 설명",
        "imageUrl": "https://...",
        "externalUrl": null,
        "startAt": "2026-05-01T00:00:00.000Z",
        "endAt": "2026-05-31T23:59:59.000Z",
        "claimAvailableAt": "2026-06-07T23:59:59.000Z",
        "rewards": [
          {
            "rewardId": "789",
            "title": "보상 이름",
            "imageUrl": "https://...",
            "type": "IN_GAME_REWARD",
            "minWatchTime": 1800
          }
        ]
      }
    ]
  }
}

필드	설명
`campaignId`	캠페인 고유 ID
`state`	캠페인 상태 (`DRAFT` / `PENDING` / `APPROVED` / `ACTIVE` / `PAUSED` / `CLAIMABLE` / `COMPLETED` / `CANCELLED` / `REJECTED`)
`startAt` / `endAt`	캠페인 활성 기간 (RFC3339 UTC)
`claimAvailableAt`	보상 수령 마감 시각 (RFC3339 UTC). 이 시각 이후 미수령 보상은 만료됨
`rewards[].minWatchTime`	보상 수령에 필요한 최소 시청 시간 (초)

청구 내역 조회

GET /api/openapi/open/v1/drops/reward-claims

본인 애플리케이션이 소유한 드롭스 캠페인의 보상 지급 요청 내역을 페이지 단위로 조회합니다.

쿼리 파라미터 (모두 선택)

파라미터	설명
`page`	페이지 번호 (0부터 시작, 기본 0)
`size`	페이지 크기 (기본 20, 최대 1000)
`claimId`	조회할 청구 ID (콤마 구분, 최대 100개)
`channelId`	시청자 채널 ID
`campaignId`	캠페인 ID
`categoryId`	카테고리 코드
`fulfillmentState`	`CLAIMED` / `FULFILLED`

응답 예시

{
  "code": 200,
  "message": null,
  "content": {
    "data": [
      {
        "claimId": "123",
        "campaignId": "456",
        "rewardId": "789",
        "categoryId": "game-code",
        "categoryName": "게임 이름",
        "channelId": "1000",
        "fulfillmentState": "CLAIMED",
        "claimedDate": "2026-04-21T12:34:56.000Z",
        "updatedDate": "2026-04-21T12:34:56.000Z"
      }
    ]
  }
}

필드	설명
`claimId`	지급 요청 고유 ID. `PUT`에 그대로 사용
`campaignId` / `rewardId`	해당 청구가 속한 캠페인·보상 ID
`categoryId` / `categoryName`	캠페인에 할당된 카테고리 코드·이름
`channelId`	요청한 시청자의 채널 ID
`fulfillmentState`	현재 상태 (`CLAIMED` / `FULFILLED`)
`claimedDate`	마지막으로 지급 요청된 시각 (RFC3339 UTC)
`updatedDate`	마지막으로 `fulfillmentState`가 변경된 시각 (RFC3339 UTC)

결과는 claimId 오름차순으로 반환됩니다. 미지급 내역만 주기적으로 확인하시려면 fulfillmentState=CLAIMED 필터와 함께, 마지막으로 처리한 claimId 또는 updatedDate를 기준으로 이어서 조회하시는 것을 권장드립니다.

시청자의 청구는 캠페인이 진행중(ACTIVE) 상태인 동안에도 접수되므로, 방송 중에 CLAIMED 상태의 내역이 실시간으로 생성될 수 있습니다. 폴링 주기를 캠페인 운영 기간 전반에 맞춰 설계해 주세요.

지급 상태 변경

PUT /api/openapi/open/v1/drops/reward-claims

지급 요청 ID 배열을 받아 각 항목의 상태를 변경하고 결과를 상태별로 그룹핑하여 반환합니다.

CLAIMED → FULFILLED: 실제 보상 지급 완료 기록
FULFILLED → CLAIMED: 지급 취소 (재시도·오지급 정정)

요청 본문

{
  "claimIds": ["123", "124"],
  "fulfillmentState": "FULFILLED"
}

claimIds: 최대 100개
fulfillmentState: 전이할 상태 (CLAIMED / FULFILLED)

응답 예시

{
  "code": 200,
  "message": null,
  "content": {
    "data": [
      { "status": "SUCCESS",       "ids": ["123", "124"] },
      { "status": "INVALID_ID",    "ids": ["abc"] },
      { "status": "NOT_FOUND",     "ids": ["999"] },
      { "status": "UNAUTHORIZED",  "ids": ["200"] },
      { "status": "UPDATE_FAILED", "ids": ["300"] }
    ]
  }
}

status	설명
`SUCCESS`	상태 전이에 성공했습니다.
`INVALID_ID`	ID 형식이 올바르지 않습니다.
`NOT_FOUND`	해당 청구가 존재하지 않거나 본인 애플리케이션 소유가 아닙니다.
`UNAUTHORIZED`	해당 시청자의 OAuth 연동이 활성 상태가 아닙니다.
`UPDATE_FAILED`	이미 요청하신 상태와 동일하거나, 캠페인이 수령 마감 구간을 지나 지급을 더 받을 수 없거나, 동시 요청으로 경합이 발생했습니다.

권장 처리 순서

게임 내에서 보상 지급을 멱등하게 먼저 처리합니다.
지급에 성공한 청구만 모아 PUT으로 일괄 전송합니다.
UPDATE_FAILED는 재시도가 필요 없으며, INVALID_ID / NOT_FOUND / UNAUTHORIZED는 로그만 남기고 폐기하시면 됩니다.

쿼타

드롭스 OpenAPI 호출에는 일일 쿼타가 부여됩니다. 개발자센터 애플리케이션 상세에서 남은 한도를 확인하실 수 있습니다.

매일 한국 시간 자정(KST)에 초기화됩니다.
한도를 초과한 호출은 거부됩니다.
조회(GET)와 상태 변경(PUT)의 쿼타가 각각 집계됩니다.
한도 증액이 필요하시면 씨미에 문의 부탁드립니다.