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

Запросы к 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 / xml / url), влияет только на интерпретацию параметра data. По умолчанию: url
out	Формат ответа (json / xml / url), влияет на всё тело ответа. По уполчанию: json

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

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

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

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

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

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

Пример

sig = sha256("makeOrderproduct_id=2111&face=500&testmode=1SecretString")
sig == "4f573f234c0acec7289e9933407452e8d6f37b4dd011b84662e8213eb99d75d7" // true

sig = sha256("makeOrder{"product_id":2111,"face":500,"testmode":1}SecretString")
sig == "e00d9e2f5d5a44f7121a73ef4d6cd5db18a4e5e1bbbe290ee930c6a306afb442" // true

Запрос

https://ssl-api.giftery.ru/?id=11725&cmd=makeOrder&data=product_id%3D2111%26face%3D500%26testmode%3D1&sig=4f573f234c0acec7289e9933407452e8d6f37b4dd011b84662e8213eb99d75d7&out=json

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

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

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

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

{
    "status": "error",
    "error": {
        "code": 3601,
        "text": "Некорректно заполнены поля: face"
    }
}

Скрипт для 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 "";
}