포인트 | 잼쿠봇 개발자센터

채널 시청자의 포인트를 목록으로, 또는 한 명씩 조회합니다. 이 개발자 API의 포인트 기능은 조회만 지원합니다.

포인트 목록 조회

채널에 포인트 기록이 있는 시청자를 페이지 단위로 돌려줍니다. 포인트가 0인 시청자도 들어 있습니다.

GET/api/v1/developer/points권한: points:read

요청

이름	위치	타입	필수	설명
`page`	query	integer	아니요	페이지 번호. 1부터 시작하며 기본값은 1입니다
`size`	query	integer	아니요	한 페이지의 시청자 수. 1~200, 기본값은 50입니다

GET /api/v1/developer/points?page=1&size=50
Authorization: Bearer ACCESS_TOKEN

응답

필드	타입	설명
`total_page`	integer	전체 페이지 수
`page`	integer	요청한 페이지 번호
`size`	integer	요청한 페이지 크기
`total`	integer	전체 시청자 수
`has_next`	boolean	다음 페이지가 있으면 `true`
`has_prev`	boolean	이전 페이지가 있으면(`page`가 2 이상이면) `true`
`data`	array	시청자 목록. 시청자 UID 내림차순이며 포인트 순이 아닙니다. 범위 밖 페이지나 포인트 기록이 없는 채널은 `[]`
`data[].user_uid`	string	시청자 UID
`data[].nickname`	string	시청자 닉네임. 잼쿠봇에 저장된 마지막 닉네임입니다
`data[].point`	integer	보유 포인트. 아직 저장되지 않은 자동 적립분까지 더한 현재 잔액입니다

범위를 벗어난 페이지를 요청하거나 채널에 포인트 기록이 하나도 없어도 null이 아니라 data가 빈 배열인 페이지 객체를 돌려줍니다(2026-10-05 부터, 이전에는 null). 마지막 페이지는 has_next로 판단합니다. 공통 규칙은 페이지네이션을 참고하세요.

{
  "total_page": 4,
  "page": 1,
  "size": 50,
  "total": 187,
  "has_next": true,
  "has_prev": false,
  "data": [
    {
      "user_uid": "fedcba9876543210fedcba9876543210",
      "nickname": "시청자닉네임",
      "point": 12500
    },
    {
      "user_uid": "fe01dcba9876543210fedcba98765432",
      "nickname": "다른시청자",
      "point": 0
    }
  ]
}

오류

상태	응답	원인
422	`{"detail": [...]}`	`page`가 1보다 작거나, `size`가 1~200을 벗어났거나, 둘 중 하나가 정수가 아닙니다
401, 403	공통 오류	토큰이 유효하지 않거나 `points:read` 권한이 없습니다

시청자 포인트 조회

시청자 UID나 닉네임으로 한 명의 포인트를 조회합니다.

GET/api/v1/developer/points/lookup권한: points:read

요청

이름	위치	타입	필수	설명
`type`	query	string	예	찾는 방법. `uid` 또는 `nickname`
`data`	query	string	예	찾을 값. `type=uid`면 시청자 UID, `type=nickname`이면 닉네임. 1자 이상

type=nickname이면 data에 URL 인코딩한 닉네임을 넣습니다.
닉네임은 잼쿠봇에 저장된 마지막 닉네임과 정확히 같아야 합니다. 대소문자는 구분하지 않습니다.
닉네임은 이 채널이 아니라 잼쿠봇 전체 사용자에서 찾습니다. 같은 닉네임을 쓰는 사람이 여럿이면 먼저 찾은 한 명만 보므로, 그 사람이 이 채널에 포인트 기록이 없으면 404가 될 수 있습니다. 정확히 조회하려면 type=uid를 쓰세요.

GET /api/v1/developer/points/lookup?type=uid&data=fedcba9876543210fedcba9876543210
Authorization: Bearer ACCESS_TOKEN

응답

필드	타입	설명
`user_uid`	string	시청자 UID
`nickname`	string	시청자 닉네임. 잼쿠봇에 저장된 마지막 닉네임입니다
`point`	integer	보유 포인트. 아직 저장되지 않은 자동 적립분까지 더한 현재 잔액입니다

{
  "user_uid": "fedcba9876543210fedcba9876543210",
  "nickname": "시청자닉네임",
  "point": 12500
}

오류

상태	응답	원인
404	`{"detail": "시청자를 찾을 수 없습니다"}`	그 UID·닉네임의 시청자가 없거나, 이 채널에 그 시청자의 포인트 기록이 없습니다
409	`{"detail": "같은 닉네임의 시청자가 여러 명입니다. uid 로 조회하세요"}`	`type=nickname` 인데 글자 그대로 같은 닉네임이 여럿이고 이 채널 포인트 기록으로도 한 명을 고를 수 없습니다. 닉네임은 대소문자·띄어쓰기까지 같아야 맞습니다
422	`{"detail": [...]}`	`type`이 `uid`·`nickname`이 아니거나, `type`이나 `data`가 없거나, `data`가 빈 문자열입니다
401, 403	공통 오류	토큰이 유효하지 않거나 `points:read` 권한이 없습니다

이 가이드로 해결이 안 됐나요?

디스코드로 문의하기