Skip to content

Get Started

API Environments

Environment Host Country
Production ID

API Security


All requests should include some specified headers:

Header Name Allow Values Description
Content-Type application/json The data type of request data payload, except multipart requests.
X-Advai-Country ID/CN/PH/VN/TH/MY A header defined by Ginee for tell us the region information.
Authorization {Access Key} + ":" + {Signature} You need apply access key from Ginee.


Code example

* Construct the signature part of Authorization:
* HttpMethod + "$" + RequestUri + "$"
* Api Method eg: POST、GET、DELETE、PUT
* Api Path eg: /openapi/order/v1/list
* eg:POST$/openapi/order/v1/list$

public void buildSign() {
    String HttpMethod = "{Api Method}";
    String RequestUri = "${Api Path}";
    String secretKey = "{Your Secret Key}";
    Base64.Encoder base64Encoder = Base64.getEncoder();
    String signatureHeaderInfo = HttpMethod + "$" + RequestUri + "$";
    String signature;
    try {
        PBEKeySpec keySpec = new PBEKeySpec(secretKey.toCharArray());
        SecretKeyFactory keyFactory = SecretKeyFactory.getInstance("PBEWithMD5AndDES");
        SecretKey key = keyFactory.generateSecret(keySpec);
        Mac mac = Mac.getInstance("HmacSHA256");
        signature = base64Encoder.encodeToString(mac.doFinal(signatureHeaderInfo.getBytes(StandardCharsets.UTF_8)));
    } catch (NoSuchAlgorithmException | InvalidKeyException | InvalidKeySpecException var6) {
        throw new RuntimeException(var6);
import base64
import hmac
from hashlib import sha256

def sign_request():
    signData = '$'.join(['POST', REQUEST_URI]) + '$'
    authorization = ACCESS_KEY + ':' + base64.b64encode('utf-8'), signData.encode('utf-8'),digestmod=sha256).digest()).decode('ascii')
    print("sign_request authorization: " + authorization)
    return authorization

$request_host = '';
$request_uri = '/openapi/shop/v1/list';
$http_method = 'POST';
$param_json = '{"page":0,"size":2}';

$access_key = '{your access_key}';
$secret_key = '{your secret_key}';

$newline = '$';
$sign_str = $http_method . $newline . $request_uri . $newline;
$authorization = sprintf('%s:%s', $access_key, base64_encode(hash_hmac('sha256', $sign_str, $secret_key, TRUE)));
echo sprintf('signature string is:%s', $sign_str . PHP_EOL);

$header_array = array(
'Authorization: ' . $authorization,
'Content-Type: ' . 'application/json',
'X-Advai-Country: ' . 'ID'


$http_header = array(
'http' => array('method' => $http_method, 'header' => $header_array, 'content' => $param_json)

$context = stream_context_create($http_header);
return file_get_contents($request_host . $request_uri, false, $context, 0);
public void buildSign() {
    string HttpMethod = "{Api Method}";
    string RequestUri = "${Api Path}";
    string secretKey = "{Your Secret Key}";
    string signatureHeaderInfo = HttpMethod + "$" + RequestUri + "$";
    String signature;
        var keyBytes = Encoding.UTF8.GetBytes(secretKey);
        using (var hmac = new HMACSHA256(keyBytes))
            var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(signatureHeaderInfo));
            signature = Convert.ToBase64String(hash);
    catch (Exception ex)
        throw new Exception("Failed to generate signature", ex);
curl -XPOST -H "X-Advai-Country: ID" \
-H "Authorization: d20254aee13cc156:{signature}" \
-H 'Content-Type: application/json' \
-d '{"channel":"JD_ID"}' \


Response Structure

Ginee API will give response in JSON format:


Field Description
code The status code that has been explained beforehand, please see below.
message The status code detailed explanation.
extra An exception message (should be empty most of the time).
transactionId An unique string identifier for each request.
pricingStrategy Shows you whether this api call will be charged by Ginee, currently all APIs are FREE even though this tag is PAY.


  • Every service will have a different data format, therefore please check the related API document.
  • If the response format is very complicated (multiple different JSON object, nested JSON object).

Response Status Code

Status Code Message Pricing Strategy
ERROR Internal server error FREE
IAM_FAILED Identity or access management certification failed FREE
PARAMETER_ERROR Parameter invalid(the detail of parameter error info will be here) FREE
SERVICE_BUSY The service is busy, You have exceeded the QPS limits, please retry later FREE


  • Each one of our API response will have Status Code, that will tell you about the result of the API call, whether its a success, fail or there are some error during the process.
  • Each API will have their own special Status code that can only be found on that API response.
  • Above table are the commonly used Status Codes, these status codes could appear in all of our API responses, so please remember to add a handler for these Status Codes as well.