Get Started¶

API Environments¶

Environment	Host	Country
Production	https://api.ginee.com	ID

API Security¶

Request¶

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.

Signature

Code example

Java

/**
* 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");
        mac.init(key);
        signature = base64Encoder.encodeToString(mac.doFinal(signatureHeaderInfo.getBytes(StandardCharsets.UTF_8)));
    } catch (NoSuchAlgorithmException | InvalidKeyException | InvalidKeySpecException var6) {
        throw new RuntimeException(var6);
    }
    System.out.println(signature);
}

Python

import base64
import hmac
from hashlib import sha256

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

PHP

<?php

$request_host = 'https://api.ginee.com';
$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'
);

var_dump($header_array);

$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);

C#

public void buildSign() {
    string HttpMethod = "{Api Method}";
    string RequestUri = "${Api Path}";
    string secretKey = "{Your Secret Key}";
    string signatureHeaderInfo = HttpMethod + "$" + RequestUri + "$";
    String signature;
    try
    {
        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);
    }
    Console.WriteLine(signature);
}

Curl

curl -XPOST -H "X-Advai-Country: ID" \
-H "Authorization: d20254aee13cc156:{signature}" \
-H 'Content-Type: application/json' \
-d '{"channel":"JD_ID"}' \
"https://genie-sandbox.advai.net/openapi/shop/v1/list"

Response¶

Response Structure

Ginee API will give response in JSON format:

Example

{
    "code":"SUCCESS",
    "message":"OK",
    "data":null,
    "extra":null,
    "transactionId":"9dc6227f08731388"
}

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`.

Note

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
`SUCCESS`	OK	`FREE`
`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`

Note

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.