REST API Specification 0.0.2
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 List1. General Specifications1.1. Request SpecificationsRequest Headers1.2. Response SpecificationsCommon Response HeadersCommon Response Body2. API Endpoints2.1. Item Purchase Availability Check (GET /check)OverviewRequest SpecificationsRequest HeadersRequest Parameters (Query Parameters)Request ExampleResponse SpecificationsResponse Example (Purchasable)Response Example (Not Purchasable - Age Restriction)Response Example (Not Purchasable - Limit Exceeded)2.2. Item Purchase Record Registration (POST /register)OverviewRequest SpecificationsRequest HeadersRequest Body (JSON)Example RequestResponse SpecificationsResponse BodyExample Response (Success)Example Response (Failure - Unknown User)2.3. Retrieve Purchase History (GET /history)OverviewRequest SpecificationsRequest HeadersRequest Parameters (Query Parameters)Example RequestResponse SpecificationsResponse BodyData Structure of the history ArrayExample Response (Success)2.4. Sales Confirmation (GET /sales)OverviewRequest SpecificationsRequest HeadersRequest Parameters (Query Parameters)Request ExampleResponse SpecificationsResponse BodyStructure of the transactions ArrayResponse Example (Success)3. Error Handling List3.1. List of Error Codes3.2. Recommended Error Handling Flow3.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
Error Code | 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.