Drops

치지직에서 인앱보상 유형의 드롭스 이벤트 진행 시 지급 여부 검증을 위한 가이드 문서입니다.

드롭스의 기본적인 설명 및 연동 가이드는 다음 문서를 참고해 주세요.

1.1 리워드 지급 요청 이벤트 받기

치지직에서 사용자가 드롭스 리워드를 획득하는 과정에서, 게임사에 지급 요청을 할 수 있습니다. 이때 치지직에서는 등록된 게임사의 webhook URL로 notification 메시지를 전달합니다.

*Note : 상세 내용은 ‘치지직 Webhook Event 가이드’ 문서를 참고해주세요.

notification 메시지는 별도 callback을 요구하지 않습니다. 따라서 드롭스 리워드 지급 상태를 변경하기 위해서는 드롭스 리워드 지급 API를 호출해야 합니다.

1.2 드롭스 리워드 지급 요청 조회 API

치지직 사용자의 드롭스 리워드 지급 요청을 조회합니다. 드롭스 API를 호출하기 위해서는 드롭스 API Scope 신청이 필요합니다. 해당 API Scope는 개발자 센터에 로그인된 사용자가 단체 ID로 법인 인증된 사용자여야만 신청할 수 있습니다.

드롭스 리워드 지급 요청 API를 호출하려면 애플리케이션 등록 후 Client 인증이 필요합니다. (Client 인증 API 참조)

HTTP Request

Description

GET /open/v1/drops/reward-claims

드롭스 리워드 지급 요청 조회

Request Param

Field

Type

Required

Description

page

Object

Optional

페이징 조회를 위해 사용

from

String

Optional

페이징 조회 시, 조회 첫 기준 식별자

size

Int

Optional

페이징 조회 시, 조회 할 전체 크기. 기본 20

claimId

String

Optional

조회할 지급 요청 ID. 콤마(,)로 구분된 배열로 최대 100개까지 요청 가능합니다.

channelId

String

Optional

조회할 유저의 채널 ID

campaignId or categoryId

String

Optional

특정 캠페인 및 카테고리로 조회할 때 조건으로 사용합니다. 동시에 두가지 조건을 사용할 수 없습니다.

campaignId: 조회할 드롭스 캠페인 ID
category: 치지직 카테고리 기준, 조회할 방송(게임) 카테고리 ID

fulfillmentState

String

Optional

조회할 리워드 상태 조건. 명시되지 않으면 모든 상태에 대해 조회합니다.

CLAIMED: 지급 요청된 리워드
FULFILLED: 지급 완료

Response Body

Field

Type

Required

Description

data

Object[]

응답 정보가 담긴 객체 배열. 조회 결과가 없으면 빈 배열이 응답될 수 있습니다.

claimId

String

드롭스 캠페인 지급 요청 ID

campaignId

String

드롭스 캠페인 ID

rewardId

String

드롭스 캠페인에 포함된 리워드 ID

categoryId

String

드롭스 캠페인에 할당된 카테고리 ID

categoryName

String

드롭스 캠페인에 할당된 노출 가능한 카테고리 이름

channelId

String

사용자의 치지직 채널 ID

fulfillmentState

String

조회할 리워드 상태 조건

CLAIMED: 지급 요청된 리워드

FULFILLED: 지급 완료

claimedDate

String

마지막으로 지급 요청된 시간. RFC3339 형식 UTC 시간

updatedDate

String

마지막으로 fulfillmentState 값이 변경된 시간. RFC3339 형식 UTC 시간

page

Object

페이징 조회를 위해 사용.

cursor

String

Optional

페이징 조회 시, 다음 조회 시 page.from으로 사용. Request Param에서 claimId 항목이 정의된 경우 값이 없거나 빈 문자열일 수 있습니다.

{
    "data": [
        {
            "claimId": "1ce167db-8c58-4a37-8662-48d4e2398503",
            "campaignId": "bb3a5e21-b18a-4b31-851b-adbecd7dfae5",
            "rewardId": "068598a1-36b2-4bb4-ab8b-dd875e621862",
            "categoryId": "CATEGORY_CHZZK",
            "categoryName": "치지직",
            "channelId": "34d7ff19-1b63-4b32-85fb-d44880195533",
            "fulfillmentState": "CLAIMED",
            "claimedDate": "2024-08-01T09:20:26Z",
            "updatedDate": "2024-08-01T09:20:26Z"
        },
        {
            "claimId": "6dd13087-d811-479d-8c4d-52d9f3a54c24",
            "campaignId": "bb3a5e21-b18a-4b31-851b-adbecd7dfae5",
            "rewardId": "13708b6d-e0ba-4180-982b-f16aa3521d15",
            "categoryId": "CATEGORY_CHZZK",
            "categoryName": "치지직",
            "channelId": "34d7ff19-1b63-4b32-85fb-d44880195533",
            "fulfillmentState": "FULFILLED",
            "claimedDate": "2024-08-01T09:21:26Z",
            "updatedDate": "2024-08-01T09:22:26Z"
        },
        {
            "claimId": "477fe295-30c2-4670-a3a6-6ad8305d36ad",
            "campaignId": "bb3a5e21-b18a-4b31-851b-adbecd7dfae5",
            "rewardId": "13708b6d-e0ba-4180-982b-f16aa3521d15",
            "categoryId": "CATEGORY_CHZZK",
            "categoryName": "치지직",
            "channelId": "991cd681-527d-43e5-9758-adae7905a005",
            "fulfillmentState": "FULFILLED",
            "claimedDate": "2024-08-01T09:22:26Z",
            "updatedDate": "2024-08-01T09:23:26Z"
        }
    ],
    "page": {
        "cursor": "2af178e3-a620-43da-b4b6-90fe11fa0737"
    }
}

1.3 드롭스 리워드 지급 API

치지직 사용자의 드롭스 리워드의 지급 상태를 관리합니다. 드롭스 API를 호출하기 위해서는 드롭스 API Scope 신청이 필요합니다. 해당 API Scope는 개발자 센터에 로그인된 사용자가 단체 ID로 법인 인증된 사용자여야만 신청할 수 있습니다.

드롭스 리워드 지급 API는 별도의 헤더가 존재합니다. 드롭스 리워드 지급 API를 호출하려면 애플리케이션 등록 후 Client 인증이 필요합니다. (Client 인증 API 참조)

HTTP Request

Description

PUT /open/v1/drops/reward-claims

드롭스 리워드 지급

Request Body

Field

Type

Required

Description

claimId

String[]

드롭스 캠페인 지급 요청 ID 배열

fulfillmentState

String

조회할 리워드 상태 조건

CLAIMED: 지급 요청된 리워드
FULFILLED: 지급 완료

{
    "claimIds": ["6dd13087-d811-479d-8c4d-52d9f3a54c24"]
    "fulfillmentState": "FULFILLED"
}

Response Body

Field

Type

Required

Description

data

Object[]

결과가 담긴 배열. data[].status의 따라 구분

status

String

지급 상태를 명시

INVALID_ID: 잘못된 지급 요청 ID 입니다.
NOT_FOUND: 해당하는 지급 ID를 찾을 수 없습니다.
SUCCESS: 성공적으로 변경했습니다.
UNAUTHORIZED: 요청한 유저가 계정 연동을 해제한 경우입니다.
UPDATE_FAILED: 에러가 발생하여 상태 변경이 실패했습니다.

ids

String[]

지급 상태에 해당하는 지급 요청 ID 배열

{
    "data": [
        {
            "status": "SUCCESS",
            "ids": ["1ce167db-8c58-4a37-8662-48d4e2398503", "6dd13087-d811-479d-8c4d-52d9f3a54c24", "477fe295-30c2-4670-a3a6-6ad8305d36ad"]
        },
        {
            "status": "UNAUTHORIZED",
            "ids": ["3ff167ah-912g-9112-1001-1k2fmvakppzp", "9avlake5-9z1s-8710-b0ba-1ga99b1123fd", "ab98c1z5-mz21-1219-nex0-akem19am7bb"]
        }
    ]
}

PreviousChat Next드롭스 개요

Last updated 2 months ago