TOP/APIドキュメント | API Documentation/REST API Specification 0.0.2

REST API Specification 0.0.2

2025/2/4 19:282025/3/4 23:31

This document provides specifications for integrating with the Game8 Store API.

By using this API, publishers can perform actions such as:

Checking purchase eligibility for in-game items

Registering purchases and granting items

Retrieving purchase history

Obtaining sales data

We actively consider feedback and feature requests from publishers. If you have any suggestions or additional requirements, please feel free to contact us.

If you already have an existing publisher API, we will adjust our implementation to align with your specifications as much as possible.

Index

API List 1. General Specifications 1.1. Request Specifications Request Headers 1.2. Response Specifications Common Response Headers Common Response Body 2. API Endpoints 2.1. Item Purchase Availability Check (GET /check)Overview Request Specifications Request Headers Request Parameters (Query Parameters)Request Example Response Specifications Response Example (Purchasable)Response Example (Not Purchasable - Age Restriction)Response Example (Not Purchasable - Limit Exceeded)2.2. Item Purchase Record Registration (POST /register)Overview Request Specifications Request Headers Request Body (JSON)Example Request Response Specifications Response Body Example Response (Success)Example Response (Failure - Unknown User)2.3. Retrieve Purchase History (GET /history)Overview Request Specifications Request Headers Request Parameters (Query Parameters)Example Request Response Specifications Response Body Data Structure of the history Array Example Response (Success)2.4. Sales Confirmation (GET /sales)Overview Request Specifications Request Headers Request Parameters (Query Parameters)Request Example Response Specifications Response Body Structure of the transactions Array Response Example (Success)3. Error Handling List 3.1. List of Error Codes 3.2. Recommended Error Handling Flow 3.3. Retry Policy

API List

API Name	Endpoint	Method	Required	Description
Purchase Eligibility Check			Required	Check whether a user can purchase a specified item
Register Purchase			Required	Register a completed purchase and grant the in-game item
Get Purchase History			Optional	Retrieve a user's past purchase history
Get Sales Data			Optional	Retrieve sales data within a specified period

1. General Specifications

Item	Description
Host
Protocol	HTTPS
Character Encoding	UTF-8

1.1. Request Specifications

Request Headers

Key	Value	Description
Authorization	Bearer	Authentication Information
Content-Type	application/json	Content Type

1.2. Response Specifications

Common Response Headers

Key	Value
Content-Type	application/json

Common Response Body

Key	Type	Description
request_id		Unique Request ID
timestamp		Response Timestamp
result_code		Result Code
message		Message

2. API Endpoints

2.1. Item Purchase Availability Check (GET /check)

Overview

Checks whether an in-game item can be purchased, considering age restrictions and purchase limits.

Request Specifications

Item	Description
Method	GET
Endpoint
Protocol	HTTPS
Content Type	application/json

Request Headers

Key	Value	Description
Authorization	Bearer	Authentication Information
Content-Type	application/json	Content Type

Request Parameters (Query Parameters)

Key	Type	Required	Description
game	string	✅	The unique game ID assigned within Game8Store
user	string	✅	The unique user ID assigned within the game
item	string	✅	The unique item ID assigned within the game
price	integer	✅	The item's sale price in Game8Store (in yen)

Request Example

Response Specifications

Key	Type	Description
request_id	string	Unique Request ID
timestamp	string (ISO8601)	Response Timestamp
result_code	string	Result Code
message	string	Message
purchasable	boolean	if purchasable, otherwise
age_category	string	User Age Category ( / / )
monthly_limit	integer	Monthly Purchase Limit (JPY), if no limit
remaining_limit	integer	Remaining Purchase Limit (JPY), if no limit
requested_price	integer	Requested Item Price (JPY)

Response Example (Purchasable)

Response Example (Not Purchasable - Age Restriction)

Response Example (Not Purchasable - Limit Exceeded)

2.2. Item Purchase Record Registration (POST /register)

Overview

Processes the increase of in-game items after purchase completion.

Request Specifications

Item	Details
Method	POST
Endpoint
Protocol	HTTPS
Content Type	application/json

Request Headers

Key	Value	Description
Authorization	Bearer	Authentication information
Content-Type	application/json	Content type

Request Body (JSON)

Key	Type	Required	Description
game	string	✅	The unique game ID assigned within Game8Store
user	string	✅	The unique user ID assigned within the game
item	string	✅	The unique item ID assigned within the game
transaction_id	string	✅	Transaction ID of the purchase
item_name	string	✅	The name of the purchased item (e.g., "100 Gem Pack")
price	integer	✅	Purchase amount (in yen)
quantity	integer	✅	The quantity of purchased items (e.g., 100)

Example Request

Response Specifications

Response Body

Key	Type	Description
request_id	string	Unique request ID
timestamp	string (ISO8601)	Timestamp of the response
result_code	string	Result code
message	string	Message
item_granted	boolean	Whether the in-game item was granted ( / )

Example Response (Success)

Example Response (Failure - Unknown User)

2.3. Retrieve Purchase History (GET /history)

Overview

Retrieves the user's past purchase history.

Request Specifications

Item	Details
Method	GET
Endpoint
Protocol	HTTPS
Content Type	application/json

Request Headers

Key	Value	Description
Authorization	Bearer	Authentication information
Content-Type	application/json	Content type

Request Parameters (Query Parameters)

Key	Type	Required	Description
game	string	✅	The unique game ID assigned within Game8Store
user	string	✅	The unique user ID assigned within the game
limit	integer	❌	Maximum number of records to retrieve (Default: 10)

Example Request

Response Specifications

Response Body

Key	Type	Description
request_id	string	Unique request ID
timestamp	string (ISO8601)	Timestamp of the response
result_code	string	Result code
message	string	Message
history	array	List of purchase history records

Data Structure of the history Array

Key	Type	Description
transaction_id	string	Payment transaction ID
item	string	Item ID
item_name	string	The name of the purchased item (e.g., "100 Gem Pack")
price	integer	Purchase amount (in yen)
quantity	integer	The quantity of purchased items (e.g., 100)
timestamp	string (ISO8601)	Purchase date and time

Example Response (Success)

2.4. Sales Confirmation (GET /sales)

Overview

Retrieves sales information for a specified period.

Request Specifications

Item	Details
Method	GET
Endpoint
Protocol	HTTPS
Content Type	application/json

Request Headers

Key	Value	Description
Authorization	Bearer	Authentication Information
Content-Type	application/json	Content Type

Request Parameters (Query Parameters)

Key	Type	Required	Description
game	string	✅	The unique game ID assigned within Game8Store
start_date	string (YYYY-MM-DD)	✅	Start date of data retrieval
end_date	string (YYYY-MM-DD)	✅	End date of data retrieval

Request Example

Response Specifications

Response Body

Key	Type	Description
request_id	string	Unique request ID
timestamp	string (ISO8601)	Timestamp of the response
result_code	string	Result code
message	string	Message
total_sales	integer	Total sales amount within the period (in JPY)
total_fees	integer	Total fees within the period (in JPY)
net_sales	integer	Net sales amount (sales - fees) within the period
transactions	array	List of sales transactions

Structure of the transactions Array

Key	Type	Description
transaction_id	string	Payment transaction ID
item	string	Item ID
item_name	string	The name of the purchased item (e.g., "100 Gem Pack")
price	integer	Purchase amount (in JPY)
quantity	integer	The quantity of purchased items (e.g., 100)
fee	integer	Fee amount (in JPY)
net_amount	integer	Net sales (purchase amount - fee)
timestamp	string (ISO8601)	Purchase date and time

Response Example (Success)

3. Error Handling List

3.1. List of Error Codes

Error Code	Description	Resolution
	Success	-
	Invalid request format	Check the request structure and required parameters, and send in the correct format.
	Missing authentication information	Ensure the header includes a valid .
	Invalid access token	Check the token's expiration and reissue if necessary.
	Insufficient access permissions	Verify that the API endpoint has the necessary permissions.
	Missing required parameters	Ensure all required parameters are included and correct the request.
	Invalid parameter type	Example: If is sent as a , change it to an integer.
	Invalid parameter value	Ensure values are within the allowed range and are not prohibited.
	No corresponding data found	Verify that a valid or is specified.
	Purchase limit reached	Check the value to ensure the limit is not exceeded.
	Purchase not allowed due to age restrictions	Verify the and ensure compliance with the restriction.
	Invalid transaction ID	Check if the is correct.
	Specified user does not exist	Verify the is correct.
	Specified item does not exist	Ensure the is valid and correct.
	Internal server error	The issue may be on the server side; retry after some time.
	Temporary system failure	Retry after a delay (recommended: retry after 5 seconds).
	Unknown error	Check the detailed error message and contact the development team if necessary.

3.2. Recommended Error Handling Flow

Check

If (Success), process normally.

Otherwise, determine the type of error.

Check if the error can be resolved on the client side

Errors in the and series can usually be resolved by modifying the request.

Errors in the series require verifying data integrity.

Check if the error is retryable

Errors and may be temporary, so retry after a few seconds.

Log and notify errors

For unknown errors (), log the details and report to the development team.

3.3. Retry Policy

Retry Interval	Max Retry Attempts	Notes
After 5 seconds	3 times	Since this is a server-side issue, it may be resolved in a short time.
After 10 seconds	5 times	A temporary system failure; use longer retry intervals.
None	0 times	Immediately report unknown errors.

Refer to this error handling list to implement appropriate error handling in your system.