API Specification

Requests to the API are made over the secure HTTPS protocol using the URL: https://api.giftery.es/v1.

Request Parameters

In general, the full URL for executing requests is as follows:

https://api.giftery.es/v1/?id={ID}&cmd={CMD}&data={DATA}&sig={SIG}&in={IN}&out={OUT}

Parameter	Description
id	Mandatory. Client ID issued to each client
cmd	Mandatory. Name of the method to be called
sig	Mandatory. Signature certifying the validity of the request
data	Request parameters in the selected format
in	The format of the request parameters (json / url), affects only the interpretation of the data parameter. Default: url
out	Response format (json / url), affects the entire response body. Default: json

Algorithm of sig signature formation

The signature is a hash sum of three parameters passed in API requests.

Parameter	Description
cmd	name of the method to be called
data	query parameters in the selected format
secret	secret

Calculates sha256 hash from string concatenation:

sig = sha256(cmd + data + secret) // sha256 hash from concatenated string, 64 characters.

The data parameter can be an empty string.

Available methods

• checkCertificate
• redeemCertificate
• cancelOperation
• test

Example

sig = sha256("checkCertificatecode=99999-999-999-999&pin=9999SecretString")
sig == "f353246c1cf7e1577bd6e965511163f2f0c538777215cd930b9b7424812653cc" // true

sig = sha256("checkCertificate{"code":"99999-999-999-999","pin":"9999"}SecretString")
sig == "9bc89da97e5886f2c6aa1dfa2b97086d4bb5e2c1a1fc1082634e314d1ef83d7b" // true

Request Status and Error Handling

If successful, the response will be of the form (using JSON as an example):

{
    "status": "ok",
    "data": {
        ...
    }
}

In case of an error (using JSON as an example):

{
    "status": "error",
    "error": {
        "code": 1,
        "text": "Not enough data to execute the request (cmd)"
    }
}

Script for Postman

This pre-script will help configure the working environment in Postman for convenient interaction with the Giftery API.

/**
* GET https://{{host}}/v1?cmd=Test&data=[]&sig={{sig}}&id={{id}}    
**/


const clientID = 'YOUR_ID';
const secretKey = 'YOUR_SECRET';
const apiHost = 'API_HOST';

let url = pm.request.url.toString();

let _cmd = getQueryParameter(url, 'cmd');
let _data = getQueryParameter(url, 'data');

let concatenatedString = _cmd + _data + secretKey;
let signature = CryptoJS.SHA256(concatenatedString).toString(CryptoJS.enc.Hex);

pm.environment.set('sig', signature);
pm.environment.set('id', clientID);
pm.environment.set('host', apiHost);

function getQueryParameter(url, parameterName) {
    const queryString = url.split('?')[1];
    if (!queryString) return "";

    const paramPairs = queryString.split('&');
    for (const pair of paramPairs) {
        const [key, ...rest] = pair.split('=');
        if (key === parameterName) {
            return decodeURIComponent(rest.join('='));
        }
    }
    return "";
}