콘텐츠로 이동

게임 공지사항 조회

본 가이드에서는 게임 공지사항 조회 API 사용 방법을 안내합니다.

API 호출에 앞서 하이브 콘솔에서 게임에 노출할 공지 사항을 등록해야 합니다.

개요

게임 공지사항 조회 API는 게임에서 서버 대 서버 통신으로 직접 호출하며, 조회 방식에 따라 아래와 같은 두 가지 형태의 인터페이스를 지원합니다.

API 호출 시 요청 헤더인 Authorization에 인증 토큰 (Hive 인증키)을 반드시 포함해야 합니다. 또한 응답값으로 조회 결과에는 공지사항 기본 정보, 언어별 상세 정보, 게임 서버 ID 목록, 국가 코드 목록이 포함됩니다.

응답값 중에서 아래의 조건을 만족하는 경우에만 공지사항을 조회할 수 있습니다.

  • status = 1: 활성 상태
  • start_time <= 현재시간: 현재 시간이 노출 시작 시간 이후
  • end_time >= 현재시간: 현재 시간이 노출 종료 시간 이전
Note

모든 시간은 KST (UTC+9) 기준입니다.

공통 응답 명세

게임 공지사항 조회 API의 호출 시 공통으로 적용되는 응답 예시 및 응답 코드를 설명합니다.

성공 응답 예시

{
  "result_code": 0,
  "result_msg": "Success",
  "data": { ... }
}

에러 응답 예시

{
  "result_code": 1100,
  "result_msg": "Unknown error"
}

응답 코드

HTTP 상태 코드 코드 메시지 설명
200 0 Success 정상 처리
500 1100 Unknown error 원인 불명 에러
500 1101 Internal server error 서버 내부 에러
400 1201 상세 메시지
(예: Missing required parameter: game_index)		 요청 형식 오류
400 1202 상세 메시지
(예: `game_index` must be a positive integer)		 파라미터 값 오류
401 1203 Unauthorized 권한 오류
405 1204 Method not allowed HTTP 요청 메서드 오류


전체 공지사항 조회

특정 게임 (game_index)에 해당하는 공지사항 전체 목록을 반환합니다.

요청 정보

구분 정보
상용 URL https://social-api.qpyou.cn/games/{game_index}/notices
샌드박스 URL https://sandbox-social-api.qpyou.cn/games/{game_index}/notices
HTTP Method GET
Response Format JSON

요청 데이터

요청 헤더

필드 타입 필수 여부 설명 비고
Authorization string Y Bearer 토큰
(Hive 인증키)		 앱센터 > 프로젝트 관리 > 게임 상세 > 기본 정보 > Hive 인증키

요청 헤더 예제

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30

경로 파라미터

필드 타입 필수 여부 설명
game_index int Y 게임 인덱스 (양의 정수)

요청 본문

없음 (GET 요청)

요청 예제

curl -X GET "https://sandbox-social-api.qpyou.cn/games/313/notices" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30"

응답 데이터

응답 본문

필드 타입 설명
result_code int 응답 결과 코드
result_msg string 결과 메시지
data object 응답 데이터
ㄴ list array 공지사항 목록 (공지사항 기본 정보 객체 배열, 결과 없으면 [])

응답 예제

{
  "result_code": 0,
  "result_msg": "Success",
  "data": {
    "list": [
      {
        "notice_id": 123,
        "status": 1,
        "type": "N",
        "view_count": 500,
        "registrant": "admin",
        "top_placed": 1,
        "start_time": "2026-03-01 00:00:00",
        "end_time": "2026-03-31 23:59:59",
        "company_index": 1,
        "game_index": 313,
        "country_expose_type": "W",
        "details": {
          "ko": {
            "game_name": "테스트게임",
            "title": "공지사항 제목",
            "content": "공지사항 내용",
            "crop_image": "https://example.com/img/123_kor.png"
          },
          "en": {
            "game_name": "TestGame",
            "title": "Notice Title",
            "content": "Notice Content",
            "crop_image": "https://example.com/img/123_eng.png"
          }
        },
        "game_servers": ["server1", "server2"],
        "country_codes": ["KR", "US"]
      }
    ]
  }
}

페이지 단위 공지사항 조회

특정 게임 (game_index)에 해당하는 공지사항 목록을 페이징하여 반환합니다.

전체 공지사항 조회하기에서 쿼리 파라미터로 page 또는 per_page가 하나라도 존재하면 페이지 단위 공지사항 조회 모드로 동작합니다.

요청 정보

구분 정보
상용 URL https://social-api.qpyou.cn/games/{game_index}/notices?page={page}&per_page={per_page}
샌드박스 URL https://sandbox-social-api.qpyou.cn/games/{game_index}/notices?page={page}&per_page={per_page}
HTTP Method GET
Response Format JSON

요청 데이터

요청 헤더

필드 타입 필수 여부 설명 비고
Authorization string Y Bearer 토큰
(Hive 인증키)		 앱센터 > 프로젝트 관리 > 게임 상세 > 기본 정보 > Hive 인증키

요청 헤더 예제

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30

경로 파라미터

필드 타입 필수 여부 설명
game_index int Y 게임 인덱스 (양의 정수)

쿼리 파라미터

Note

page 또는 per_page 값이 양의 정수가 아닌 경우는 기본값으로 대체됩니다.

파라미터 타입 필수 여부 기본값 설명
page int N 1 페이지 번호 (1부터 시작)
per_page int N 20 페이지당 건수

요청 본문

없음 (GET 요청)

요청 예제

curl -X GET "https://sandbox-social-api.qpyou.cn/games/313/notices?page=1&per_page=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30"

응답 데이터

응답 본문

필드 타입 설명
result_code int 응답 결과 코드
result_msg string 결과 메시지
data object 응답 데이터
ㄴ pagination object 페이징 메타 정보
  ㄴ page int 현재 페이지 번호
  ㄴ per_page int 페이지당 건수
  ㄴ total_count int 전체 데이터 건수
  ㄴ total_pages int 전체 페이지 수 (ceil(total_count / per_page), total_count = 0이면 0)
ㄴ list array 공지사항 목록 (공지사항 기본 정보 객체 배열, 결과 없으면 [])

응답 예제

{
  "result_code": 0,
  "result_msg": "Success",
  "data": {
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total_count": 50,
      "total_pages": 3
    },
    "list": [
      {
        "notice_id": 123,
        "status": 1,
        "type": "N",
        "view_count": 500,
        "registrant": "admin",
        "top_placed": 1,
        "start_time": "2026-03-01 00:00:00",
        "end_time": "2026-03-31 23:59:59",
        "company_index": 1,
        "game_index": 313,
        "country_expose_type": "W",
        "details": {
          "ko": {
            "game_name": "테스트게임",
            "title": "공지사항 제목",
            "content": "공지사항 내용",
            "crop_image": "https://example.com/img/123_kor.png"
          },
          "en": {
            "game_name": "TestGame",
            "title": "Notice Title",
            "content": "Notice Content",
            "crop_image": "https://example.com/img/123_eng.png"
          }
        },
        "game_servers": ["server1", "server2"],
        "country_codes": ["KR", "US"]
      }
    ]
  }
}

응답 데이터 상세

공지사항 기본 정보

필드 타입 설명
notice_id int 공지사항 고유 ID
status int 상태 (1: 활성, 항상 활성 상태의 공지만 반환)
type string 공지 유형 (type 코드 참고)
view_count int 조회수
registrant string 등록자
top_placed int|null 상단 고정 여부 (1 이상의 값: 고정, null: 비고정)
start_time string 노출 시작 시간 (yyyy-MM-dd HH:mm:ss, KST)
end_time string 노출 종료 시간 (yyyy-MM-dd HH:mm:ss, KST)
company_index int 회사 인덱스
game_index int 게임 인덱스
country_expose_type string|null 국가 노출 타입 (country_expose_type 코드 참고, 기본값: null)
details object 언어별 상세 정보 (details 참고)
game_servers array 게임 서버 ID 목록 (game_servers 참고)
country_codes array 국가 코드 목록 (country_codes 참고)

type 코드

코드 설명
I Info (안내)
C Maintenance (점검)
U Update (업데이트)
N Notices (공지사항)
A Announcement (발표)
E Event (이벤트)
D Error (장애)

country_expose_type 코드

코드 설명
null 제한 없음 (전체 국가 노출)
W Whitelist (country_codes에 포함된 국가만 노출)
B Blacklist (country_codes에 포함된 국가를 차단)

details

details는 언어 코드 값으로 구성된 객체입니다. 해당 공지사항에 등록된 언어만 포함되며, 상세 데이터가 없으면 빈 객체({})를 반환합니다.

필드 타입 설명
game_name string 게임명
title string 공지 제목
content string 공지 내용
crop_image string 크롭 이미지 URL

지원 언어 코드

코드 언어
ko 한국어
en 영어
ja 일본어
zh-hans 중국어 (간체)
zh-hant 중국어 (번체)
de 독일어
fr 프랑스어
ru 러시아어
es 스페인어
pt 포르투갈어
id 인도네시아어
th 태국어
vi 베트남어
it 이탈리아어
tr 튀르키예어
ar 아랍어

game_servers

  • 게임 서버 ID 목록입니다. 데이터가 없으면 빈 배열([])을 반환합니다.
  • 예: ["server1", "server2", "server3"]

country_codes

  • 국가 코드 목록입니다. 데이터가 없으면 빈 배열([])을 반환합니다.
  • 예: ["KR", "US", "JP"]
  • 참고: ISO 3166 표준