룰렛 API
룰렛 목록과 결과 기록을 조회할 수 있는 API입니다.
이 API를 사용하려면 read.roulette 권한이 필요합니다.
룰렛 목록 조회
GET
/api/v1/roulette채널에 등록된 모든 룰렛 목록을 조회합니다.
응답 필드
| 필드 | 타입 | 설명 |
|---|---|---|
roulettes | array | 룰렛 목록 |
roulettes[].uuid | string | 룰렛 고유 ID (UUID) |
roulettes[].name | string | 룰렛 이름 |
roulettes[].price | number | 룰렛 가격 (포인트) |
roulettes[].items | array | 룰렛 항목 목록 |
roulettes[].items[].name | string | 항목 이름 |
roulettes[].items[].chance | number | 당첨 확률 (%) |
요청
curl -X GET "https://chzzk-bot.ddutto.com/api/v1/roulette" \
-H "Authorization: DDUBOT_API YOUR_API_KEY"응답
{
"success": true,
"roulettes": [
{
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"name": "일반 룰렛",
"price": 1000,
"items": [
{ "name": "1등 - 치킨", "chance": 5.0 },
{ "name": "2등 - 커피", "chance": 15.0 },
{ "name": "꽝", "chance": 80.0 }
]
},
{
"uuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"name": "VIP 룰렛",
"price": 5000,
"items": [
{ "name": "대박", "chance": 10.0 },
{ "name": "중박", "chance": 30.0 },
{ "name": "소박", "chance": 60.0 }
]
}
]
}응답
{
"success": false,
"error": "인증에 실패했습니다."
}룰렛 로그 조회
GET
/api/v1/roulette/logs특정 룰렛의 결과 기록을 페이지네이션으로 조회합니다.
Query Parameters
uuidstring필수조회할 룰렛의 UUID
pagenumber기본값: 1페이지 번호
limitnumber기본값: 50페이지당 개수 (최대 50)
응답 필드
| 필드 | 타입 | 설명 |
|---|---|---|
data | array | 로그 목록 |
data[].user.name | string | 참여자 닉네임 (익명 시 "익명의 후원자") |
data[].user.uid | string | 참여자 UID (익명 시 "anonymous") |
data[].meta.isCompleted | boolean | 보상 지급 완료 여부 |
data[].meta.isTest | boolean | 테스트 여부 |
data[].meta.isAnonymous | boolean | 익명 참여 여부 |
data[].result | string | 룰렛 결과 |
pagination.page | number | 현재 페이지 |
pagination.total | number | 전체 로그 수 |
pagination.totalPages | number | 전체 페이지 수 |
요청
curl -X GET "https://chzzk-bot.ddutto.com/api/v1/roulette/logs?uuid=550e8400-e29b-41d4-a716-446655440000&page=1&limit=20" \
-H "Authorization: DDUBOT_API YOUR_API_KEY"응답
{
"success": true,
"data": [
{
"user": {
"name": "열혈시청자",
"uid": "4c3a50fe635854036b4dcf15c9a4d0a2"
},
"meta": {
"isCompleted": true,
"isTest": false,
"isAnonymous": false
},
"result": "2등 - 커피"
},
{
"user": {
"name": "익명의 후원자",
"uid": "anonymous"
},
"meta": {
"isCompleted": false,
"isTest": false,
"isAnonymous": true
},
"result": "꽝"
}
],
"pagination": {
"page": 1,
"total": 150,
"totalPages": 8
}
}응답
{
"success": false,
"error": "잘못된 룰렛 UUID 형식입니다."
}오류 코드
| 오류 메시지 | HTTP 상태 | 설명 |
|---|---|---|
| 잘못된 룰렛 UUID 형식입니다. | 400 | UUID 형식이 올바르지 않음 |
| page는 1 이상의 정수여야 합니다. | 400 | 페이지 번호 오류 |
| limit는 최대 50까지 가능합니다. | 400 | limit 값 초과 |
| page가 범위를 초과했습니다. | 400 | 존재하지 않는 페이지 |
| 인증에 실패했습니다. | 401 | API 키 인증 실패 |
| 권한이 없습니다. | 403 | read.roulette 권한 없음 |