앱 공지사항 조회
본 가이드에서는 앱 공지사항 조회 API 사용 방법을 안내합니다.
사전 준비¶
앱 공지사항 조회 API 호출에 앞서 Hive 콘솔에서 앱에 노출할 공지 사항을 등록해야 합니다.
동작 방식¶
앱 공지사항 조회 API는 앱에서 서버 대 서버 통신으로 직접 호출하며, 조회 방식에 따라 아래와 같은 두 가지 형태의 인터페이스를 지원합니다.
- 전체 공지사항 조회: 특정 게임(game_index)에 해당하는 모든 공지사항 목록을 일괄 조회합니다.
- 페이지 단위 공지사항 조회: 특정 게임(game_index)에 해당하는 공지사항 목록을 페이지 단위(Pagination)로 분할하여 조회합니다.
Note
앱 공지사항 조회 API는 JWT 인증 방식으로 동작합니다.
API 호출 시 요청 헤더인 X-Access-Token에 인증 토큰(JWT Access Token, OAuth Token 발급 참고)을 반드시 포함해야 합니다. 또한 응답값으로 조회 결과에는 공지사항 기본 정보, 언어별 상세 정보, 앱 서버 ID 목록, 국가 코드 목록이 포함됩니다.
응답값 중에서 아래의 조건을 만족하는 경우에만 공지사항을 조회할 수 있습니다.
status = 1: 활성 상태start_time <= 현재시간: 현재 시간이 노출 시작 시간 이후end_time >= 현재시간: 현재 시간이 노출 종료 시간 이전
Note
모든 시간은 KST (UTC+9) 기준입니다.
공통 응답 명세¶
앱 공지사항 조회 API 호출 시, 반횐되는 성공 및 실패 응답 데이터 예시와 상태 코드를 안내합니다.
성공 응답 예시¶
{
"result_code": 0,
"result_msg": "Success",
"token_validation": {
"result_code": 0,
"result_msg": "Success"
},
"data": { ... }
}
에러 응답 예시¶
JWT 검증 실패 예시¶
{
"result_code": 1203,
"result_msg": "Unauthorized",
"token_validation": {
"result_code": 2408,
"result_msg": "JWT token expired"
}
}
싱테 코드¶
| 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 | JWT 검증 실패 (상세는 token_validation 참고) |
| 405 | 1204 | Method not allowed | HTTP 요청 메서드 오류 |
Note
JWT 검증 실패 시, token_validation 필드로 상세한 에러 정보를 확인할 수 있습니다. 자세한 내용은 JWT 검증 에러 코드를 참고하세요.
전체 공지사항 조회¶
특정 앱 (game_index)에 해당하는 공지사항 전체 목록을 반환합니다.
요청 정보¶
| 구분 | 정보 |
|---|---|
| 상용 URL | https://social-api.qpyou.cn/v2/games/{game_index}/notices |
| 샌드박스 URL | https://sandbox-social-api.qpyou.cn/v2/games/{game_index}/notices |
| HTTP Method | GET |
| Response Format | JSON |
요청 데이터¶
'전체 공지사항 조회' 호출 시 전송하는 데이터를 설명합니다.
요청 헤더¶
| 필드 | 타입 | 필수 여부 | 설명 | 비고 |
|---|---|---|---|---|
| X-Access-Token | string | Y | JWT Access Token | 발급 방법은 OAuth Token 발급 참고 |
요청 헤더 예제¶
경로 파라미터¶
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| game_index | int | Y | 게임 인덱스 (양의 정수) |
요청 본문¶
없음 (GET 요청)
요청 예제¶
'전체 공지사항 조회' 호출 예시는 아래와 같습니다.
curl -X GET "https://sandbox-social-api.qpyou.cn/v2/games/539/notices" \
-H "X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0..."
응답 데이터¶
'전체 공지사항 조회' 호출 시 응답받는 데이터를 설명합니다.
응답 본문¶
| 필드 | 타입 | 설명 |
|---|---|---|
| result_code | int | 응답 결과 코드 |
| result_msg | string | 결과 메시지 |
| token_validation | object | JWT 검증 결과 |
| ㄴ result_code | int | JWT 검증 결과 코드 (0 = 성공, 상세는 JWT 검증 에러 코드 참고) |
| ㄴ result_msg | string | JWT 검증 결과 메시지 |
| data | object | 응답 데이터 (JWT 검증 실패 시에는 포함되지 않음) |
| ㄴ list | array | 공지사항 목록 (공지사항 기본 정보 객체 배열, 결과 없으면 []) |
응답 예제¶
'전체 공지사항 조회' 호출 시 응답 예시는 아래와 같습니다.
{
"result_code": 0,
"result_msg": "Success",
"token_validation": {
"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": 4,
"game_index": 539,
"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/v2/games/{game_index}/notices?page={page}&per_page={per_page} |
| 샌드박스 URL | https://sandbox-social-api.qpyou.cn/v2/games/{game_index}/notices?page={page}&per_page={per_page} |
| HTTP Method | GET |
| Response Format | JSON |
요청 데이터¶
'페이지 단위 공지사항 조회' 호출 시 전송하는 데이터를 설명합니다.
요청 헤더¶
| 필드 | 타입 | 필수 여부 | 설명 | 비고 |
|---|---|---|---|---|
| X-Access-Token | string | Y | JWT Access Token | 발급 방법은 OAuth Token 발급 참고 |
요청 헤더 예제¶
경로 파라미터¶
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| 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/v2/games/539/notices?page=1&per_page=20" \
-H "X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0..."
응답 데이터¶
'페이지 단위 공지사항 조회' 호출 시 응답받는 데이터를 설명합니다.
응답 본문¶
| 필드 | 타입 | 설명 |
|---|---|---|
| result_code | int | 응답 결과 코드 |
| result_msg | string | 결과 메시지 |
| token_validation | object | JWT 검증 결과 |
| ㄴ result_code | int | JWT 검증 결과 코드 (0 = 성공, 상세는 JWT 검증 에러 코드 참고) |
| ㄴ result_msg | string | JWT 검증 결과 메시지 |
| data | object | 응답 데이터 (JWT 검증 실패 시에는 포함되지 않음) |
| ㄴ 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",
"token_validation": {
"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": 4,
"game_index": 539,
"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"]
}
]
}
}
응답 데이터 상세¶
앱 공지사항 조회 API에서 지원하는 전체 응답 데이터의 상세 내역을 설명합니다.
공지사항 기본 정보¶
| 필드 | 타입 | 설명 |
|---|---|---|
| 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 표준