App Notice

This guide explains how to use the app notice inquiry API.

Prerequisites¶

Before calling the app notice inquiry API, you must register the notices to be displayed in the app from the Hive Console.

How it works¶

The app notice inquiry API is called directly from the app via server-to-server communication and supports the following two interfaces depending on the query method.

• Get all notices: Retrieves all notices for a specific app (game_index) at once.
• Get paginated notices: Retrieves notices for a specific app (game_index) in pages (pagination).

When calling the API, the X-Access-Token request header must include an authentication token (JWT Access Token; see OAuth Token issuance). The response includes basic notice information, language-specific details, app server ID list, and country code list.

Notices can be retrieved only when the following conditions are met.

• status = 1: active state
• start_time <= current time: The current time is after the display start time.
• end_time >= current time: The current time is before the display end time.

Common response specification¶

Provides examples of success and failure response data returned when calling the app notice inquiry API, along with status codes.

Success response example¶

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

Error response example¶

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

JWT validation failure example¶

{
  "result_code": 1203,
  "result_msg": "Unauthorized",
  "token_validation": {
    "result_code": 2408,
    "result_msg": "JWT token expired"
  }
}

Status codes¶

Get all notices¶

Returns the complete list of notices for a specific app (game_index).

Request information¶

Request data¶

Describes the data sent when calling 'Get all notices'.

Request headers¶

Request header example¶

X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0...

Path parameters¶

Request body¶

None (GET request)

Request example¶

The following is an example of calling 'Get all notices'.

curl -X GET "https://sandbox-social-api.qpyou.cn/v2/games/539/notices" \
  -H "X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0..."

Response data¶

Describes the data received when calling 'Get all notices'.

Response body¶

Response example¶

The following is an example response for calling 'Get all notices'.

{
  "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"]
      }
    ]
  }
}

Get paginated notices¶

Returns the notice list for a specific app (game_index) in pages.

The Get all notices endpoint switches to paginated mode when either page or per_page is included as a query parameter.

Request information¶

Request data¶

Describes the data sent when calling 'Get paginated notices'.

Request headers¶

Request header example¶

X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0...

Path parameters¶

Query parameters¶

Request body¶

None (GET request)

Request example¶

The following is an example of calling 'Get paginated notices'.

curl -X GET "https://sandbox-social-api.qpyou.cn/v2/games/539/notices?page=1&per_page=20" \
  -H "X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0..."

Response data¶

Describes the data received when calling 'Get paginated notices'.

Response body¶

Response example¶

The following is an example response for calling 'Get paginated notices'.

{
  "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"]
      }
    ]
  }
}

Response data details¶

Describes the details of all response data supported by the app notice inquiry API.

Basic notice information¶

type codes¶

country_expose_type codes¶

details¶

details is an object keyed by language code. Only languages registered for the notice are included; returns an empty object ({}) if no details exist.

Supported language codes¶

game_servers¶

• List of app server IDs. Returns an empty array ([]) if no data is available.
• Example: ["server1", "server2", "server3"]

country_codes¶

• List of country codes. Returns an empty array ([]) if no data is available.
• Example: ["KR", "US", "JP"]
• Reference: ISO 3166 standard