Tokoku API Documentation

A Comprehensive Guide to Tokoku API

Introduction
Welcome to the Tokoku API Documentation. Whether you are a developer looking to
integrate our services into your application, a business seeking to streamline operations, or
simply curious about what Tokoku can offer, this documentation will provide you with the
resources and information you need.

Getting Started
To begin using the Tokoku Open API, please follow these steps:
1. Get credentials: After your access request was approved, check your email and
obtain your API credentials.
2. Authentication: Learn how to authenticate your requests to the API securely.
3. Endpoints: Explore our API endpoints and discover what features and data you can
access.
4. Testing: Learn how to test our API in development server before using real data.
5. Troubleshooting: Learn how to fix common issues that may arise.

Please note that this documentation is subject to updates and improvements as we strive to
provide you with the best experience.
1. Get Credentials
Updated: Dec 14, 2023
To get your credentials, check your email after your access request has been approved. Your
credentials will consist of an API Key and a Secret Key. The credentials should look
something like this:

Do not share this key with anyone. Your credentials, including the API Key and Secret Key,
are vital components of your account's security. Sharing these credentials with anyone
poses a significant risk to the integrity and privacy of your data and account.
2. Authentication
Updated: Dec 14, 2023

Request Headers
To authenticate your request, your request headers must include the following headers.

HTTP Headers Description Sample

X-Api-Key API Key provided by itemku. X-Api-Key: abcdefg123456abcde

To see your API key look at the

instruction from Get Credentials
section.

Authorization Bearer token. Authorization: Bearer

To learn how to generate token eyJYLUFwaS1LZXkiOiJZb3VyQXBp
look at the Authorization Token S2V5UHJvdmlkZWRCeUl0ZW1rdSIs
section. Ik5vbmNlIjoiMTYxMTgzMDg0NSIsI
mFsZyI6IkhTMjU2In0.eyJwcm9kdW
N0X2lkIjoxMjM0LCJwcmljZSI6MTA
wMCwicXVhbnRpdHkiOjEsInJlZmVy
ZW5jZV9pZCI6IlgxMjM0NSJ9.9wb
M9eYu6GiKttczFb7jTwQUh0jAoXgE
x5s6B2elUgo

Content-Type application/json Content-Type: application/json

Nonce Current Timestamp string Nonce: 16738647785

Authorization Token
JSON Web Token generated based on header, payload, and signature.
For more info check https://jwt.io/

JSON Web Token consists of three parts separated by dots(.) which are:
header.payload.signature

For header part, please use X-Api-Key and Nonce only, and also the alg : “HS256”
Example :

itemku will provide you with API Key and API Secret
API Key : “YourApiKeyProvidedByItemku”
API Secret : “YourApiSecretProvidedByItemku”

Sample Header Value:

{"X-Api-Key":"YourApiKeyProvidedByItemku","Nonce":"1611830845","alg":”HS256”}

Sample Payload Value:

{"order_id":1234,"date_start_at":"2023-11-01"}

How to generate signature :

1. header and payload are in JSON format, and should strip “\t”, “\r”, or “\n”
2. Make sure all parameters and values in both header and payload should be trimmed
(no whitespaces in both ends).
{"order_id":"X12345"} ✅
Instead of
{"order_id":"X12345 "} ❌
3. Base64encode the header
4. Base64encode the payload
5. Combine the base64encoded header and base64encoded payload with a “.” in
between
6. Hashed the combined string with HMAC SHA256 with the API Secret as the key, this
will create the signature
7. Combine the step 5 and 6 result with a “.” in between as your Authorization Token

In code it should look like this:

key = 'YourApiSecretProvidedByItemku'
unsignedToken = encodeBase64Url(header) + '.' +
encodeBase64Url(payload)
signature = HMAC-SHA256(key, unsignedToken)
authToken = unsignedToken + '.' + signature
3. Endpoints
Updated: Dec 14, 2023

Get Order
Use this API to get a list of Orders from respective seller.

Endpoint

https://tokoku-gateway.itemku.com/api/order/list

Request Method

POST

Request Parameters

Parameter Name Data Type Required / Notes

Optional

date_start String Required Format: YYYY-MM-DD

Filter date of the order greater than
equals date_start. Max 2 months ago.
(Default sort by date_start desc)

order_id Number Optional Order ID

order_status String Optional Order Status (REQUIRE_PROCESS,

DELIVERED, REFUNDED).

See Order Status section for detail

limit Number Optional Number between 1 and 30 (defaults

to 10 if not passed)

Order Status

Order Status Description

REQUIRE_PROCESS Order needs to be processed.

DELIVERED Order has been delivered

REFUNDED Order has been canceled and the balance has been
refunded
Response Example for Get Order
{
"success": true,
"statusCode": "SUCCESS",
"message": "Success",
"data": [
{
"order_id": 454634,
"order_number": "OD00000454634",
"product_id": 235634,
"price": 10000,
"quantity": 2,
"order_income": 18000,
"game_name": "Mobile Legends",
"product_name": "Voucher 1000",
"status": "DELIVERED",
"required_information": "{\"player_id\":\"12345567\",\"zone_id\"
:\"1234\",\"username\":\"testing1\"}",
"using_delivery_info": true,
"delivery_info_field": [
{
"field_name": "Email",
"validation_pattern": "^[\w()-|'.+,#%^&*!$\/\\]+$",

},
{
"field_name": "Password",
"validation_pattern": "^[a-z\\d\\-_\\s]+$",
}

],
"delivery_info": [
"QWERTYUIOP",
"ASDFGHJKLK"
]
}
]
}
Error Code

Error Code Description

ORDER_NOT_FOUND We cannot find order with this ID that

belongs to you

MAXIMUM_DATE_RANGE_EXCEEDED Maximum date range exceeded

(Max: 60 days from today)

Order Action
Use this API to deliver or reject an order. Make sure that you input the data correctly.

Endpoint

https://tokoku-gateway.itemku.com/api/order/action

Request Method

POST

Request Parameters

Parameter Name Data Type Required / Notes

Optional

order_id Number Required Order ID

action String Required DELIVER/REJECT

refund_reason String Required / Required on REJECT action.

Optional
See Details in Refund Reason section.

delivery_info Array Required / Required on DELIVER action.

Optional
See Details in Delivery Info section.
Refund Reason

Refund Reason Description

NO_STOCK Product have no stock

WRONG_BUYER_INFORMATION Buyer have wrong required information

SERVER_ERROR Web/Server error

PRICE_CHANGED Price of the product changed

Delivery Info
Delivery info is the account data (username, password, etc) or voucher code for product to
be sent to buyer.

When delivering order, the delivery_info depends on the order data using_delivery_info and
delivery_info_field.

Product Type Order Info Delivery Info

Topup using_delivery_info: false No need to sent delivery_info

delivery_info_field: null

Example category:
Topup Mobile Legends, Topup
Garena Free Fire, etc

Voucher using_delivery_info: true, delivery_info (Array) – length based

delivery_info_field: null on order_quantity

Example category: Example:

Voucher (Except “Pengiriman ["X12345", "X12346", "X12345"]
Otomatis” feature)

Account using_delivery_info: true, delivery_info (Array) – length based

delivery_info_field: not null on order_quantity

Example category: Example:

Netflix Account, WeTV Account, [{"email":"ndk@email.com","passwor
d":"X12345"}]
etc. (Except “Pengiriman Otomatis”
feature)
Example:

Case 1
{
"order_id": 454633,
"using_delivery_info": false,
"delivery_info_field": null
}

delivery_info: undefined

Case 2
{
"order_id": 454634,
"using_delivery_info": true,
"delivery_info_field": null
}

delivery_info: ["X12345", "X12346", "X12345"]

Case 3
{
"order_id": 454635,
"using_delivery_info": true,
"delivery_info_field": [
{
"field_name": "Email",
"validation_pattern": "^[\w()-|'.+,#%^&*!$\/\\]+$",

},
{
"field_name": "Password",
"validation_pattern": "^[a-z\\d\\-_\\s]+$",
}
]
}

delivery_info: [{"Email":"test@email.com","Password":"X12345"}]

Optional: You can use the validation_pattern for regex to make sure the input use the correct
format
Response Example for Order Action
{
"success": true,
"statusCode": "SUCCESS",
"message": "Success",
"data": [
{
"order_id": 454634,
"order_number": "OD00000454634",
"product_id": 235634,
"price": 10000,
"quantity": 2,
"order_income": 18000,
"game_name": "Mobile Legends",
"product_name": "Voucher 1000",
"status": "DELIVERED",
"required_information": "{\"player_id\":\"12345567\",\"zone_id\"
:\"1234\",\"username\":\"testing1\"}",
"using_delivery_info": true,
"delivery_info_field": [
{
"field_name": "Email",
"validation_pattern": "^[\w()-|'.+,#%^&*!$\/\\]+$",
},
{
"field_name": "Password",
"validation_pattern": "^[a-z\\d\\-_\\s]+$",
}

],
"delivery_info": [
"QWERTYUIOP",
"ASDFGHJKLK"
]
}
]
}
Error Code

Error Code Description

DELIVER_ORDER_IN_PROGRESS Your deliver/reject order request is currently in

progress

ORDER_DELIVERED Order status already DELIVERED (on action

DELIVER)

ORDER_REJECTED Order status already REJECTED (on action

REJECT)

MISSMATCH_STATUS Status of the order is not REQUIRE_PROCESS to

do the action

INVALID_ORDER_INFO Delivery Info provided is not valid

INVALID_ACTION Action provided is not valid. Available actions

are DELIVER or REJECT

REFUND_FAILED Failed to create refund for order

Order Callback (Notification on Order)

● itemku will send a JSON when the order is paid by the buyer.
● Header will be filled with X-itemku: {shop_id}
● To verify the request is from itemku, seller can use endpoint
https://tokoku-gateway.itemku.com/api/order/list and validate
if the order is exists in itemku and the status is REQUIRE_PROCESS
● Sellers require the DNS TXT “v-api-itemku-{SHOPNAME}=1” to verify the domain
ownership. If the verify process is failed, itemku will not accept the callback API
requests. Example:

Note for callback response from seller partner:

● itemku will ignore all the payload responses from the callback, no expected return
result.
 ● If the seller callback API returns an error, itemku will not retry the process, seller
partners need to check order on API
https://tokoku-gateway.itemku.com/api/order/list for the order.
● Order Callback is not available in the sandbox environment.

Endpoint
{URL_PROVIDED_BY_SELLER}

Request Method

POST

Body Request Example

{
"data": [
{
"order_id": 454634,
"order_number": "OD00000454634",
"product_id": 235634,
"price": 10000,
"quantity": 2,
"order_income": 18000,
"game_name": "Mobile Legends",
"product_name": "Voucher 1000",
"status": "REQUIRE_PROCESS",
"required_information": "{\"player_id\":\"12345567\",\"zone_id\"
:\"1234\",\"username\":\"testing1\"}",
"using_delivery_info": true,
"delivery_info_field": [
{
"field_name": "Email",
"validation_pattern": "^[\w()-|'.+,#%^&*!$\/\\]+$",
},
{
"field_name": "Password",
"validation_pattern": "^[a-z\\d\\-_\\s]+$",
}
],
"delivery_info": null
}
]
}
Generate Order (Sandbox)
Use this API to simulate an order for your shop. The order will be in status
REQUIRE_PROCESS.

Endpoint

https://sandbox-api-tokoku.itemku.com/dev/api/order/generate

Request Method

POST

Request Parameters

Parameter Name Data Type Required / Notes

Optional

quantity Number Required The quantity of item for the created order

game_id Number Required ID of the game. See Available Category for

Order Generate section for details

item_type_id Number Required ID of the item type. See Available Category

for Order Generate section for details

Available Category for Order Generate

Category Parameter

Akun, Netflix "game_id":161,

"item_type_id":422

Item, Roblox "game_id":65,

"item_type_id":130

Steam Wallet, Steam "game_id":43,

"item_type_id":39

Top Up, Mobile Legends "game_id":51,

"item_type_id":95
Response Example
{
"success": true,
"data": {
"order_id": 28,
"product_id": 12345,
"price": 4000,
"quantity": 2,
"product_name": "test product",
"delivery_info_field": null,
"status": "REQUIRE_PROCESS",
"delivery_info": null
},
"message": "Success",
"statusCode": "SUCCESS"
}

Error Code

Error Code Description

SERVER_ERROR Failed to generate order. Please retry in a few

minutes. If issue persist, contact itemku.

ORDER_CATEGORY_NOT_ALLOWED Combination of game_id and item_type_id is not

available. Please refer to Available Category for
Order Generate section
4. Testing
Updated: Dec 14, 2023

Environment
We offer two distinct environments for the Tokoku API:

Sandbox: This is intended for testing purposes.

Production: This environment is used for actual production use.

The API Key you receive when requesting access through the Seller Dashboard at
https://tokoku.itemku.com/ is a production key. If you wish to access the testing
environment, you will need to register for a sandbox account with itemku. It's important to
note that sandbox accounts have a limited lifespan, typically expiring after a certain number
of months. Additionally, they come with a separate testing key.

Registration for Sandbox

Please contact itemku discord at https://discord.gg/itemku-lapak-juragan for registration
details. You will be given:
1. API key for testing
2. Secret key for testing
3. Access for your IP to our testing server
5. Troubleshooting
Updated: Dec 14, 2023
Case Suggested Solution

Cannot reach the server Please make sure you’re accessing the server with the
registered IPs

Method not allowed Please check one of these things:

1. Make sure the HTTP method is `POST`
2. If you got redirected, please follow the original HTTP
Method. For example, in Postman, please enable this
setting

HTTP 401 Check your header, this could mean :

- Unregistered X-API-Key
- Nonce is too far from current time
- Content type is not “application/json”
- Invalid Authorization Token
- Request body is not the same as the one you encoded
in the token

HTTP 422 Input payload failed to pass validation, please check your
payload.

HTTP 5xx There's a problem with our server, please retry in a few
minutes.
Or if it’s sandbox, make sure it’s during our server uptime.
(Mon - Fri 6 AM - 9 PM WIB UTC +7)
Appendix

I. Description of response example

Updated: Dec 14, 2023

Response Parameter Description Data Type

order_id Order ID of Orders, unique Number

identifier of Orders

order_number Order Number of Orders, unique String

identifier of Orders

product_id Product ID of the seller’s Number

product, unique identifier of
Products

price Price of the product seller inputs Number

per 1 quantity

quantity Quantity of orders that buyer Number

purchase

order_income Income seller get on orders. Number

price x quantity - seller’s fee

game_name Name of the Category Game String

product_name Name of the product String

status Status of the Orders String

See: Order Status

required_information Game information of buyers. JSON string

Example: in Topup Mobile
Legends there are player_id &
zone_id

using_delivery_info Does the product require delivery Boolean

info or not

delivery_info_fields Delivery info fields containing Array of JSON

input format for product delivery
info

delivery_info See: Delivery Info Array of JSON

II. Required Information Lists
Updated: Dec 14, 2023

Game required_information fields

player_id
Ace Racer zone_id
username
Arena of Valor player_id
Bermuda player_id
BIGO Live player_id
Black Clover M user_id
Blood Strike user_id
user_id
Boxing Star
username
Clash of Clans player_id
Clash Royale player_id

player_id

zone_id
Dead by Daylight Mobile
username
Dragon Nest 2 Evolution player_id
Dragon Nest 2 Evolution zone_id
Dragonheir: Silent Gods username
EA FC Mobile player_id
Echocalypse player_id
Echocalypse zone_id
Echocalypse username
Eggy Party player_id
Ensemble Stars Music player_id
Ensemble Stars Music username
Garena Free Fire player_id
Garena Free Fire MAX player_id
Garena Speed Drifters player_id
Garena Undawn player_id
player_id
Genshin Impact
zone_id
 player_id
Girls' Connect: Idle RPG zone_id
username
player_id
GODDESS OF VICTORY: NIKKE zone_id
username
Growtopia player_id
Harry Potter: Magic Awakened player_id
Hay Day player_id
player_id
Heroes Evolved
zone_id
player_id
Honkai: Star Rail
zone_id
League of Legends: Wild Rift player_id
LifeAfter player_id
LifeAfter zone_id
Light of Thel New Era player_id
player_id
MARVEL SNAP
username
Metal Slug Awakening player_id
player_id
Mobile Legends
zone_id
player_id
Modern Strike Online
username
Nex Parabola player_id
Omlet Arcade user_id
Path to Nowhere player_id
Path to Nowhere username
Point Blank Beyond Limits player_id
PUBG Mobile Indonesia player_id
player_id
Ragnarok Eternal Love
zone_id
player_id
Ragnarok Origin Global username
zone_id
player_id
Revelation: New World
 zone_id
username
Rhythm Hive player_id
player_id
Rise of Kingdoms
username
player_id
Seal M
zone_id
player_id
State of Survival: Zombie War zone_id
username
Stumble Guys user_id
player_id
The Return of Condor Heroes zone_id
username
player_id
Time Raiders zone_id
username
Valorant player_id
player_id
Yalla
username