Технический протокол

Запросы к API выполняются по защищенному HTTPS протоколу используя URL: https://ssl-api.giftery.ru.

Параметры запроса

В общем виде полный URL для выполнения запросов выглядит следующим образом:

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

Параметр	Описание
id	Обязательный. ID клиента, выдаваемое каждому клиенту
cmd	Обязательный. Название вызываемого метода
sig	Обязательный. Подпись, удостоверяющая валидность запроса
data	Параметры запроса в выбранном формате
in	Формат параметров запроса (json / url), влияет только на интерпретацию параметра data. По умолчанию: url
out	Формат ответа (json / url), влияет на всё тело ответа. По уполчанию: json

Алгоритм формирования подписи sig

Подпись представляет собой хеш-сумму от трёх параметров, передаваемых при запросах к API.

Параметр	Описание
cmd	Название вызываемого метода
data	Параметры запроса в выбранном формате
secret	Секретная сторка, выдаваемая каждому клиенту

Рассчитывается sha256-хеш от конкатенации строк:

sig = sha256(cmd + data + secret) // sha256 хэш от склеенной строки, 64 символа

Параметр data может быть пустой строкой.

Доступные методы

• checkCertificate
• redeemCertificate
• cancelOperation
• test

Пример

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

Скрипт для Postman

Этот pre-script поможет настроить рабочее окружение в Postman для удобной работы с API Giftery

/**
* GET https://{{host}}?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 "";
}

Статус запроса и обработка ошибок

В случае успешного выполнения ответ будет иметь вид (на примере JSON):

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

В случае ошибки (на примере JSON):

{
    "status": "error",
    "error": {
        "code": 1,
        "text": "Недостаточно данных для выполнения запроса (cmd)"
    }
}