NAV Navbar

Úvod dokumentace

Givery disponují velmi jednoduchým REST API postaveným na standardním HTTPS protokolu. Díky němu můžete propojit váš stávající systém s naším a tím na míru naimplementovat prodej a dodání produktů zákazníkům.

V případě dotazů ohledně implementace kontaktujte:
Vojtěch Zikmund
vojtech.zikmund@egit.cz

Prostředí

Vývojářské prostředí - sandbox

Požadavky na tento sandbox nevyvolají žádnou změnu na produkci a vydané produkty se neprojeví ve fakturaci. Sandbox tedy plně slouží pro odzkoušení napsaného kódu.

Produkční

Všechny požadavky jsou zpracovány a vydané produkty jsou promítnuty do fakturace. K produkčním metodám je potřeba přistupovat pouze z povolených IP adres.

HMAC podepisování

Pro podepisování je využita HMAC Autentizace. Podpisem požadavku je kryptograficky silný hash založený na funkci SHA-256, který je obsažen v každém požadavku i odpovědi. Hash je založen na tajném klíči, který je znám pouze příjemci a odesílateli požadavku. Před odesláním požadavku je spočítán jeho podpis, který je následně přidán jako poslední parametr. Při přijetí požadavku je znovu druhou stranou spočítán podpis a je ověřena shoda.

HMAC API klíč od nás získáte během implementačního procesu.

Vytváření podpisu

Vytvoření podpisu v PHP

<?php
$secret_key = "0b8Qpv7MQ8N0FTma4mFWOK5oy";

$data = [
    "parametr_1" => "hodnota",
    "parametr_2" => "",
    "parametr_3" => 420
];

# vysledny rezetec pro vytvoreni podpisu
# ziskame retezec 'hodnota||420'
$string = join("|", $data); 


# pro vytvoreni retezce z multidimensionalniho pole muzeme vyuzit anonymni funkci napr.
$createStringFromNestedArray = function(array $data):string{
    $result = [];
    $cb = function ($value) use (&$result) : void {
        $result[] = $value;
    };
    array_walk_recursive($data, $cb);
    return join("|", $result);
};

# ziskame retezec 'hodnota||420'
$string = $createStringFromNestedArray($data);

# signature muzeme propojit k poli a odeslat
# ziskame podpis '4ac947ef5b196e7fca79427c6035986826858f422f225cd6fa76b394dfc3f931'
$signature = hash_hmac("sha256", $string, $secret_key); 

$data["signature"] = $signature;
?>

Request

{
    "parametr_1": "hodnota",
    "parametr_2": "",
    "parametr_3": 420,
    "signature": "4ac947ef5b196e7fca79427c6035986826858f422f225cd6fa76b394dfc3f931"
}

Hodnoty požadavku jsou spojeny do řetězce, ve kterém je oddělovačem svislítko | (roura). Řetězec je následně zahashován s využítím HMAC API klíče obchodníka a připojen jako poslední parametr původního požadavku s klíčem signature.

Výsledký řetězec po spojení hodnot:
hodnota||420

Výsledný podpis:
4ac947ef5b196e7fca79427c6035986826858f422f225cd6fa76b394dfc3f931

Příklad implementace v PHP je uveden v pravém sloupci. Pro implementaci v ostatních jazycích je možné string podpisu získat podle některého z následujících návodů:
- pro Python
- pro Javu a ostatní jazyky

Kontrola podpisu

Response

{
    "vat": "0.00",
    "cost": {
      "currency": "CZK",
      "cost": "98.00",
      "cost_vat": "0.00"
    },
    "recommended_retail_price": {
      "CZK": "100.00",
      "EUR": ""
    },
    "signature": "b80f12f9cf4903f4072e2bc831e5df39590f5a40c8ac6deb8e49057b22309550"
}

Kontrola podpisu v PHP

<?php

# Priklad odpovedi prevedene do PHP pole
$dataNested = [
    "vat" => "0.00",
    "cost" => [
        "currency"=> "CZK",
        "cost"=>"98.00",
        "cost_vat" => "0.00"
    ],
    "recommended_retail_price" => [
        "CZK" => "100.00",
        "EUR" => ""
    ],
    "signature" => "b80f12f9cf4903f4072e2bc831e5df39590f5a40c8ac6deb8e49057b22309550"
];

# z pole vyjmeme prijaty podpis a uchovame jej v promenne k pozdejsimu uziti
$signatureReceived = $dataNested["signature"];
unset($dataNested["signature"]);


# z pole vytvorime retezec - vyuzijeme vyse definovanou anonymni fci $createStringFromNestedArray
# ziskame retezec '0.00|CZK|98.00|0.00|100.00|' 
$string = $createStringFromNestedArray($dataNested);

# podpis vytvorime stejne jako pri vytvareni noveho pozadavku
# ziskame podpis 'b80f12f9cf4903f4072e2bc831e5df39590f5a40c8ac6deb8e49057b22309550'
$signatureCreated = hash_hmac("sha256", $string, $secret_key);


# podpisy spolu porovname 
if(hash_equals($signatureReceived, $signatureCreated) === FALSE){
  # callback pro pripad, kdy se podpisy nerovnaji
}

U každé přijaté odpovědi je vhodné kontrolovat podpis, aby byla zajištěna pravdivost přijatých informací. Protože odpovědi ve většině případů obsahují multidimensionální pole, je nutné s touto skutečností počítat při vytváření řetězce z přijatých hodnot.

Příklad možné implementace včetně zpracování multidimensionálního pole je uveden opět v pravém sloupci.

Dostupné metody

Nová objednávka

/order

Request

{
  "order_id": "vaseIdObjednavky",
  "product_id": 1001001,
  "value": "",
  "terminal_id": 201240735,
  "retailer_id": 20124,
  "signature": "75e7be12545fa995190131d2261907b5ef4320fc5714e1677ef241528b380072"
}

Response

{
    "error": "",
    "error_code": 0,
    "order_id": "vaseIdObjednavky",
    "product_id": 1001001,
    "vat": "0.00",
    "cost": {
      "currency": "CZK",
      "cost": "100.00",
      "cost_vat": "0.00"
    },
    "recommended_retail_price": {
      "CZK": "100.00",
      "EUR": ""
    },
    "terminal_id": 201240735,
    "retailer_id": 20124,
    "pin": "9999813954920884",
    "serial_number": 1416965695,
    "ean": "",
    "valid_to": "",
    "text": "PIN = hotovost! \nPIN nikdy nesdělujte cizím osobám!\n\nPoužití: Vyberte si internetový obchod a výrobek, zvolte způsob platby paysafecard a zadejte PIN.\n\nV případě dotazů navštivte www.paysafecard.com/help. Tipy pro bezpečné platby na internetu naleznete na www.paysafecard.com/security.\n\nPaysafecard je forma platebního prostředku vydaná společností Paysafe Prepaid Services Ltd. Všeobecné obchodní podmínky naleznete na www.paysafecard.com.",
    "created_at": "2020-05-26 12:34:52",
    "changed_at": "2020-05-26 12:34:53",
    "status": "DELIVERED",
    "order_error_code": 0,
    "order_error_desc": "",
    "signature": "abc..."
}

Metoda pro vytvoření požadavku na novou objednávku. Po jejím zavolání bude vydán nový produkt.

Požadavek

Parametr Datový typ Popis
order_id string (max 50) ID objednávky.Tuto hodnotu si volíte sami. Každá nová objednávka musí mít unikátní ID. Tato hodnota může být u některých produktů předána koncovému zákazníkovi.
product_id int ID objednávaného produktu. Hodnota musí odpovídat ID dostupného produktu. Dostupné produkty lze získat metodou /products nebo v administraci obchodníka.
value string Prázdný string, pokud se jedná o produkt s pevnou cenou. Pokud se jedná o dobíjecí produkt, je vložena dobíjená částka s dvěmi desetinnými místy (odděleny tečkou).
terminal_id int ID terminálu, ze kterého je metoda volána. ID terminálu vám bude přiděleno během implementačního procesu.
retailer_id int ID obchodníka. Hodnota je konstatní pro všechny vaše objednávky. Vaše ID obchodníka vám bude přiděleno během implementačního procesu.
signature string Podpis požadavku.

Odpověď

Odpoveď je objekt typu ResponseReceipt.

Dotaz na jednu objednávku

Request

  /order/78912/2160507358/61069f01b0bf04f4ea4897a2d50c6283e2d60baeb480901866a06df02f9e3cda

Response

{
    "error": "",
    "error_code": 0,
    "order_id": "2160507358",
    "product_id": 2001003,
    "vat": "21.00",
    "cost": {
        "currency": "CZK",
        "cost": "160.00",
        "cost_vat": "33.60"
    },
    "recommended_retail_price": {
        "CZK": "",
        "EUR": ""
    },
    "terminal_id": 789120444,
    "retailer_id": 78912,
    "pin": "abcd-efgh-1234",
    "serial_number": "",
    "ean": "",
    "valid_to": "",
    "text": "",
    "created_at": "2020-05-21 13:37:43",
    "changed_at": "2020-05-22 03:00:02",
    "status": "DELIVERED",
    "order_error_code": 0,
    "order_error_desc": "",
    "signature": "eb7b6e830ce9822c2e48e1b2a032407f82da62706c38707f3baa8ac4115e3b18"
}

Získání informace o jedné objednávce podle ID, které jste jí přidělili voláním metody /order.

Ukázkové hodnoty požadavku

Parametr Datový typ Popis Příklad
retailer_id int ID obchodníka. Vaše ID obchodníka vám bude přiděleno během implementačního procesu. 78912
order_id string ID objednávky, které jste objednávce přidělili vytvořením objednávky metodou /order 2160507358
signature string Podpis požadavku. 61069f01b0bf04f4ea4897a2...

Odpověď

Odpoveď je objekt typu ResponseReceipt.

Dotaz na více objednávek

Request

/orders-list/12345/7/a07d879bd12121a39ecabea681525cdd929c9e157b774fd35c8e6af042c31f95

Response

{
    "error": "",
    "error_code": 0,
    "retailer_id": 12345,
    "days": 7,
    "orders_count": 11,
    "orders": [
        {
            "order_id": "3035096072",
            "product_id": 1001001,
            "vat": "0.00",
            "cost": {
                "currency": "CZK",
                "cost": "100.00",
                "cost_vat": "0.00"
            },
            "recommended_retail_price": {
                "CZK": "100.00",
                "EUR": ""
            },
            "terminal_id": 123450123,
            "pin": "",
            "serial_number": "1416965693",
            "ean": "",
            "valid_to": "",
            "status": "DELIVERED"
        },
        { ... },
        {
            "order_id": "6869467211",
            "product_id": 3001001,
            "vat": "0.00",
            "cost": {
                "currency": "EUR",
                "cost": "19.06",
                "cost_vat": "0.00"
            },
            "recommended_retail_price": {
                "CZK": "519.00",
                "EUR": "20.00"
            },
            "terminal_id": 123450123,
            "pin": "1234567890123456",
            "serial_number": "123420200526143459",
            "ean": "4260497360773",
            "valid_to": "3000-01-01",
            "status": "DELIVERED"
        }
    ],
    "signature": "3eb14a005909640568b1e470a6181f89d6e0d0f1bb6ce24699af49f375f3095b"
}

Metoda umožňuje získat více objednávek za posledních několik dní. Získané objednávky jsou seřazeny od nejstarší po nejnovější. První parametr v dotazu je ID obchodníka, druhý parametr určitě kolik dní do minulosti hledat objednávky a třetí parametr je podpis.

Pro plný detail objednávky je nutné zavolat nový dotaz na konkrétní objednávku podle jejího ID.

Ukázkové hodnoty požadavku

Parametr Datový typ Popis Příklad
retailer_id int ID obchodníka. Vaše ID obchodníka vám bude přiděleno během implementačního procesu. 13245
last_days int Určuje kolik celých dní do minulosti hledat objednávky (např. pokud je dnes 08. 01. 2020 a zadáme hodnotu 7, budou vyhledány objednávky od 01. 01. 2020 do 08. 01. 2020 včetně). 7
signature string Podpis požadavku. a07d879bd12121a3...

Odpověď

Odpoveď je objekt typu ResponseReceiptsList.

Storno objednávky

/order/cancel

Request

{
  "order_id": "vaseIdObjednavky",
  "retailer_id": 78912,
  "signature": "841dd310c0cd1b4657342f3a1ba71a2834e7980f82e9cc9c93f41452cfd6831b"
}

Response HTTP code 200

{
    "error": "",
    "error_code": 0,
    "order_id": "vaseIdObjednavky",
    "product_id": 1001001,
    "vat": "0.00",
    "cost": {
        "currency": "CZK",
        "cost": "99.00",
        "cost_vat": "0.00"
    },
    "recommended_retail_price": {
        "CZK": "100.00",
        "EUR": ""
    },
    "terminal_id": 789120555,
    "retailer_id": 78912,
    "pin": "",
    "serial_number": 1416965696,
    "ean": "",
    "valid_to": "",
    "text": "PIN = hotovost! \nPIN nikdy nesdělujte cizím osobám!\n\nPoužití: Vyberte si internetový obchod a výrobek, zvolte způsob platby paysafecard a zadejte PIN.\n\nV případě dotazů navštivte www.paysafecard.com/help. Tipy pro bezpečné platby na internetu naleznete na www.paysafecard.com/security.\n\nPaysafecard je forma platebního prostředku vydaná společností Paysafe Prepaid Services Ltd. Všeobecné obchodní podmínky naleznete na www.paysafecard.com.",
    "created_at": "2020-05-26 13:35:49",
    "changed_at": "2020-05-26 13:36:18",
    "status": "CANCELLED",
    "order_error_code": 0,
    "order_error_desc": "",
    "signature": "8084939f70f75fff270696d4952178944fce70c8f59956b6e560642c1913d6f5"
}

Response HTTP code 400

{
    "error": "Order id 'vaseIdObjednavky' is already cancelled",
    "error_code": 5
}

Metoda pro stornování objednávky. Pokud je možné objednávku stornovat, vrátí objekt typu ResponseReceipt. Pokud není možné objednávku stornovat, vrací chybový stav. Chybový stav je vrácen, i když je objednávka již stornována.

Ukázkové hodnoty požadavku

Parametr Datový typ Popis Příklad
order_id string ID objednávky, kterou si přejete stornovat. vaseIdObjednavky
retailer_id int ID obchodníka. Vaše ID obchodníka Vám bude přiděleno během implementačního procesu. 78912
signature string Podpis požadavku. 841dd310c0cd1b4657...

Odpověď

Odpoveď je objekt typu ResponseReceipt.

Ping

Request

/ping

Response

[
    "ok"
]

Prostředek pro otestování, zda je API připraveno přijímat požadavky. Tuto metodu můžete volat vždy před prvotním voláním a ověřit tak funkčnost spojení a také funkčnost obou systémů.

Odpověď

V případě navázání spojení je odpovědí jednoprvkové pole s jednoduchým textem ok.

Dostupné produkty

Request - jeden produkt

 /products/78912/2001003/08a7ba3f34c9fe6c1cac620f0e5121df00c9480d66a2901ef3d4ae7c5e9537a9

Request - všechny produkty

  /products/78912/ALL/6c4582dbcdc28a15d3a70a29c089e6b484cdf8a3c8002cf6736beb2d716e9016

Response

{
    "error": "",
    "error_code": 0,
    "products_count": 8,
    "products": [
        {
            "id": 1001001,
            "name": "Paysafecard 100 Kč",
            "text": "PIN = hotovost! \nPIN nikdy nesdělujte cizím osobám!\n\nPoužití: Vyberte si internetový obchod a výrobek, zvolte způsob platby paysafecard a zadejte PIN.\n\nV případě dotazů navštivte www.paysafecard.com/help. Tipy pro bezpečné platby na internetu naleznete na www.paysafecard.com/security.\n\nPaysafecard je forma platebního prostředku vydaná společností Paysafe Prepaid Services Ltd. Všeobecné obchodní podmínky naleznete na www.paysafecard.com.",
            "image_url": "https://media.egit.cz/givery/loga/paysafecard.png",
            "vat": "0.00",
            "cost": {
                "currency": "CZK",
                "cost": "99.00",
                "cost_vat": "0.00"
            },
            "recommended_retail_price": {
                "CZK": "100.00",
                "EUR": ""
            },
            "status": "ENABLED"
        },
        { ... },
        {
            "id": 2001003,
            "name": "PlayStation Plus 1 měsíc",
            "text": "",
            "image_url": "",
            "vat": "21.00",
            "cost": {
                "currency": "CZK",
                "cost": "160.00",
                "cost_vat": "33.60"
            },
            "recommended_retail_price": {
                "CZK": "",
                "EUR": ""
            },
            "status": "ENABLED"
        },
        {
            "id": 3001001,
            "name": "Blizzard Battle.net Digital Code 20 EUR",
            "text": "Kód zadejte na stránce account.blizzard.com. Tím dojde k jeho aktivaci a okamžitému uplatnění.",
            "image_url": "https://media.egit.cz/givery/loga/blizzard.png",
            "vat": "0.00",
            "cost": {
                "currency": "EUR",
                "cost": "520.00",
                "cost_vat": "0.00"
            },
            "recommended_retail_price": {
                "CZK": "519.00",
                "EUR": "20.00"
            },
            "status": "ENABLED"
        }
    ],
    "signature": "0ecb96596e73511f2b978451626290bd12055e0fe9d45289c5876bdfd1aacd6b"
}

Metoda vrací objekt typu ReponseProductsList obsahující jednotlivé produkty, které jsou pro obchodníka dostupné k prodeji. Jednotlivé produkty jsou objektem typu ReponseProduct. Parametrizací API url lze získat informace o jednom produktu nebo všechny produkty.

Ukázkové hodnoty požadavku

Parametr Datový typ Popis Příklad
retailer_id int ID obchodníka. Vaše ID obchodníka vám bude přiděleno během implementačního procesu. 78912
product_id int | string ID produktu, o kterém si přejete získat informace. ID produktu lze získat dotázáním se nejdříve na všechny dostupné produkty. Namísto ID produktu vložte klíčové slovo ALL 2001003 | ALL
signature string Podpis požadavku. -

Odpověď

Odpoveď je objekt typu ReponseProductsList.

Objekty odpovědí

ResponseReceipt

{
    "error": "",
    "error_code": 0,
    "order_id": "2160507358",
    "product_id": 2001003,
    "vat": "21.00",
    "cost": {
        "currency": "CZK",
        "cost": "160.00",
        "cost_vat": "33.60"
    },
    "recommended_retail_price": {
        "CZK": "",
        "EUR": ""
    },
    "terminal_id": 789120444,
    "retailer_id": 78912,
    "pin": "abcd-efgh-1234",
    "serial_number": "",
    "ean": "",
    "valid_to": "",
    "text": "",
    "created_at": "2020-05-21 13:37:43",
    "changed_at": "2020-05-22 03:00:02",
    "status": "DELIVERED",
    "order_error_code": 0,
    "order_error_desc": "",
    "signature": "eb7b6e830ce9822c2e48e1b2a032407f82da62706c38707f3baa8ac4115e3b18"
}

Nejběžnější druh odpovědi. Tento objekt je vrácen jak při vytváření nové objednávky, jejím stornovám, tak i při dotazu na detail jedné objednávky.

Parametr Datový typ Formát hodnoty Popis
error string Prázdný string nebo popis, pokud došlo při požadavku k chybě.
error_code int Nula nebo číslo větší než nula, pokud došlo při požadavku k chybě.
order_id string ID objednávky, které určujete při vytváření nové objednávky.
product_id int ID objednávaného produktu. Detail produktu lze získat voláním metody /products.
vat string číslo s dvěmi desetinnými místy (odděleny tečkou) Sazba DPH v procentech.
cost objekt Cost Objekt typu Cost.
recommended_retail_price objekt RecommandedRetailPrice Objekt typu RecommandedRetailPrice.
terminal_id int ID terminálu, ze kterého byl odeslán požadavek.
retailer_id int Vaše ID obchodníka, které vám bude přiděleno během procesu implementace.
pin string Prázdný string (pokud není znovu možné hodnotu získat - např. u Paysafecard) nebo PIN.
serial_number string Prázdný string (pokud hodnota není poskytnuta dodavatelem) nebo sériové číslo.
ean string Prázdný string (pokud hodnota není známá) nebo EAN produktu.
valid_to date Y-m-d Prázdný string (pokud dodavatel neuvádí konec platnosti) nebo datum konce platnosti PINu.
text string Popis produktu/návod na uplatnění.
created_at dateTime Y-m-d H:i:s Časová známka vytvoření objednávky. Časová zóna je nastavena na UTC timezone +00:00.
changed_at dateTime Y-m-d H:i:s Časová známka, kdy byl změněn stav objednávky. Časová zóna je nastavena na UTC timezone +00:00.
status enum OrderStatus Stav objednávky. Obsahuje jednu z hodnot popsanou v OrderStatus.
order_error_code int Nula nebo číslo chyby, pokud objednávka nebyla úspěšně dokončena.
order_error_desc string Prázdný string nebo popis chyby, pokud objednávka nebyla úspěšně dokončena.
signature string Podpis z výše uvedených hodnot.

ResponseReceiptSimplified

{
    "order_id": "3035096072",
    "product_id": 1001001,
    "vat": "0.00",
    "cost": {
        "currency": "CZK",
        "cost": "100.00",
        "cost_vat": "0.00"
    },
    "recommended_retail_price": {
        "CZK": "100.00",
        "EUR": ""
    },
    "terminal_id": 123450123,
    "pin": "",
    "serial_number": "1416965693",
    "ean": "",
    "valid_to": "",
    "status": "DELIVERED"
}

Jedná se o zjednodušenou variantu objektu ResponseReceipt. V tomto objektu chybí některé méně důležité informace. Objekt je vkládán jako hodnota parametru orders objektu odpovědi ResponseReceiptsList při dotazu na více objednávek.

Parametr Datový typ Formát hodnoty Popis
order_id string ID objednávky, které určujete při vytváření nové objednávky.
product_id int ID objednávaného produktu. Detail produktu lze získat voláním metody /products.
vat string číslo s dvěmi desetinnými místy (odděleny tečkou) Sazba DPH v procentech fakturované částky.
cost objekt Cost Objekt typu Cost.
recommended_retail_price objekt RecommandedRetailPrice Objekt typu RecommandedRetailPrice.
terminal_id int ID terminálu, ze kterého byl odeslán požadavek.
pin string Prázdný string (pokud není znovu možné hodnotu získat - např. u Paysafecard) nebo PIN.
serial_number string Prázdný string (pokud hodnota není poskytnuta dodavatelem) nebo sériové číslo.
ean string Prázdný string (pokud hodnota není známá) nebo EAN produktu.
valid_to date Y-m-d Prázdný string (pokud dodavatel neuvádí konec platnosti) nebo datum konce platnosti PINu.
status enum OrderStatus Stav objednávky. Obsahuje jednu z hodnot popsanou v OrderStatus.

 ResponseReceiptsList

{
    "error": "",
    "error_code": 0,
    "retailer_id": 12345,
    "days": 7,
    "orders_count": 11,
    "orders": [
        {
            "order_id": "3035096072",
            "product_id": 1001001,
            "vat": "0.00",
            "cost": {
                "currency": "CZK",
                "cost": "100.00",
                "cost_vat": "0.00"
            },
            "recommended_retail_price": {
                "CZK": "100.00",
                "EUR": ""
            },
            "terminal_id": 123450123,
            "pin": "",
            "serial_number": "1416965693",
            "ean": "",
            "valid_to": "",
            "status": "DELIVERED"
        },
        { ... },
        {
            "order_id": "6869467211",
            "product_id": 3001001,
            "vat": "0.00",
            "cost": {
                "currency": "EUR",
                "cost": "19.06",
                "cost_vat": "0.00"
            },
            "recommended_retail_price": {
                "CZK": "519.00",
                "EUR": "20.00"
            },
            "terminal_id": 123450123,
            "pin": "1234567890123456",
            "serial_number": "123420200526143459",
            "ean": "4260497360773",
            "valid_to": "3000-01-01",
            "status": "DELIVERED"
        }
    ],
    "signature": "3eb14a005909640568b1e470a6181f89d6e0d0f1bb6ce24699af49f375f3095b"
}

Objekt je vracen při dotazu na více objednávek. Obsahuje všechny objednávky z určitého období podle předaných parametrů. Může sloužit pro rekonsolidaci s vašim systémem.

Parametr Datový typ Formát hodnoty Popis
error string Prázdný string nebo popis, pokud došlo při požadavku k chybě.
error_code int Nula nebo číslo větší než nula, pokud došlo při požadavku k chybě.
retailer_id int Vaše ID obchodníka, které vám bude přiděleno během procesu implementace.
days int Počet dní do minulosti, za které chcete vypsat provedené objednávky. Metoda vybere objednávky, které mají datum vytvoření >= (dnes - n).
orders_count int Počet nalezených objednávek.
orders pole ResponseReceiptSimplified Položkou pole je objekt typu ResponseReceiptSimplified. Pokud nebyla nalezena žádná objednávka, je pole prázdné. Položky jsou řazeny podle data vytvoření od nejstarší po nejnovější.
signature string Podpis z výše uvedených hodnot.

 ReponseProduct

{
    "id": 2001003,
    "name": "PlayStation Plus 1 měsíc",
    "text": "",
    "image_url": "",
    "vat": "21.00",
    "cost": {
        "currency": "CZK",
        "cost": "160.00",
        "cost_vat": "33.60"
    },
    "recommended_retail_price": {
        "CZK": "",
        "EUR": ""
    },
    "status": "ENABLED"
}

Z objektu lze vyčíst různé informace o produktu. Může sloužit pro automatizaci zalistování produktů do vašeho systému. Objekt je vkládán do parametru products výsledného objektu ReponseProductsList, který je odpovědí při dotazu na všechny produkty obchodníka.

Parametr Datový typ Formát hodnoty Popis
id int ID produktu, které se vkládá jako hodnota parametru product_id při vytvářené nové objednávky metodou /order.
name string Obchodní název produktu.
text string Popis produktu/návod na uplatnění.
image_url string URL adresa - odkaz na logo/obrázek v PNG s průhledným pozadí.
vat string číslo s dvěmi desetinnými místy (odděleny tečkou) Sazba DPH v procentech fakturované částky.
cost objekt Cost Objekt typu Cost.
recommended_retail_price objekt RecommandedRetailPrice Objekt typu RecommandedRetailPrice.
status enum ProductStatus Dostupnost produktu. Obsahuje jednu z hodnot popsanou v ProductStatus.

 ReponseProductsList

{
    "error": "",
    "error_code": 0,
    "products_count": 8,
    "products": [
        {
            "id": 1001001,
            "name": "Paysafecard 100 Kč",
            "text": "PIN = hotovost! \nPIN nikdy nesdělujte cizím osobám!\n\nPoužití: Vyberte si internetový obchod a výrobek, zvolte způsob platby paysafecard a zadejte PIN.\n\nV případě dotazů navštivte www.paysafecard.com/help. Tipy pro bezpečné platby na internetu naleznete na www.paysafecard.com/security.\n\nPaysafecard je forma platebního prostředku vydaná společností Paysafe Prepaid Services Ltd. Všeobecné obchodní podmínky naleznete na www.paysafecard.com.",
            "image_url": "https://media.egit.cz/givery/loga/paysafecard.png",
            "vat": "0.00",
            "cost": {
                "currency": "CZK",
                "cost": "99.00",
                "cost_vat": "0.00"
            },
            "recommended_retail_price": {
                "CZK": "100.00",
                "EUR": ""
            },
            "status": "ENABLED"
        },
        { ... },
        {
            "id": 2001003,
            "name": "PlayStation Plus 1 měsíc",
            "text": "",
            "image_url": "",
            "vat": "21.00",
            "cost": {
                "currency": "CZK",
                "cost": "160.00",
                "cost_vat": "33.60"
            },
            "recommended_retail_price": {
                "CZK": "",
                "EUR": ""
            },
            "status": "ENABLED"
        },
        {
            "id": 3001001,
            "name": "Blizzard Battle.net Digital Code 20 EUR",
            "text": "Kód zadejte na stránce account.blizzard.com. Tím dojde k jeho aktivaci a okamžitému uplatnění.",
            "image_url": "https://media.egit.cz/givery/loga/blizzard.png",
            "vat": "0.00",
            "cost": {
                "currency": "EUR",
                "cost": "520.00",
                "cost_vat": "0.00"
            },
            "recommended_retail_price": {
                "CZK": "519.00",
                "EUR": "20.00"
            },
            "status": "ENABLED"
        }
    ],
    "signature": "0ecb96596e73511f2b978451626290bd12055e0fe9d45289c5876bdfd1aacd6b"
}

Objekt přehledně vypisuje produkty obchodníka vč. jejich prodejních cen, obchodních názvů atd. Tento objekt je vrácen při volání metody pro zjištění všech produktů obchodníka.

Parametr Datový typ Formát hodnoty Popis
error string Prázdný string nebo popis, pokud došlo při požadavku k chybě.
error_code int Nula nebo číslo větší než nula, pokud došlo při požadavku k chybě.
products_count int Počet nalezených produktů.
products pole ReponseProduct Položkou pole je objekt typu ReponseProduct. Pokud nebyl nalezen žádný produkt, je pole prázdné.
signature string Podpis z výše uvedených hodnot.

Cost

"cost": {
    "currency": "CZK",
    "cost": "99.00",
    "cost_vat": "0.00"
}

Objekt obsahuje informace o ceně prodaného produktu.

Parametr Datový typ Formát hodnoty Popis
currency string ISO 4217 Lingvistické označení měny podle ISO 4217 (CZK, EUR), ve které bude obj. produkt fakturován.
cost string číslo s dvěmi desetinnými místy (odděleny tečkou) Cena bez DPH, která bude fakturována.
cost_vat string číslo s dvěmi desetinnými místy (odděleny tečkou) Vyčíslené DPH, které bude fakturováno.

RecommandedRetailPrice

"recommended_retail_price": {
    "CZK": "519.00",
    "EUR": "20.00"
}

Objekt obsahuje doporučené maloobchodní ceny prodaného produktu v měnách CZK i EUR. Pokud produkt nemá žádnou doporučenou maloobchodní cenu, je v klíči měny uveden prádzný string.

Parametr Datový typ Formát hodnoty Popis
CZK string číslo s dvěmi desetinnými místy (odděleny tečkou) nebo prázdný string Doporučená maloobchodní cena v CZK.
EUR string číslo s dvěmi desetinnými místy (odděleny tečkou) nebo prázdný string Doporučená maloobchodní cena v EUR.

OrderStatus

Hodnota Popis
CREATED Inicializační stav objednávky. Následně přechází do některého z následných stavů.
DELIVERED Stav označující úspěšné doručení produktu. Produkty v tomto stavu jsou započítávány do fakturace a je s nimi operováno v mechanismech kontrolujících limity objednávek terminálů a obchodníka.
REJECTED Objednávka nebyla úspěšně dokončena. Více informací se zobrazí při získání konkrétní objednávky v parametru order_error_code a order_error_desc.
CANCELLED Objednávka byla stornována metodou /order/cancel

ProductStatus

Hodnota Popis
ENABLED Produkt je dostupný k prodeji.
DISABLED Produkt není dostupný k prodeji.

Návratové HTTP kódy

Kód Popis
200 Úspěšné volání.
400 Neúspěšný požadavek.
403 Neúspěšná autorizace.
404 Neexistující zdroj/metoda/endpoint.
500 Volání skončilo chybou.

Chybové stavy

Chybové stavy jsou vráci s číslem chyby error_code a popisem chyby error. HTTP kód se liší podle druhu chyby.

Objednávka nebyla nalezena

{
    "error": "Order id 504187 was not found",
    "error_code": 4
}

Objednávka neexistujícího produktu

{
    "error": "Invalid parameters supplied. Check retailer_id, terminal_id and product_id.",
    "error_code": 3
}

Objednávku nelze znovu stornovat

{
    "error": "Order id '5599715725' is already cancelled",
    "error_code": 5
}
Kód chyby HTTP kód Hodnota Popis
1 500 Internal error Vnitřní chyba aplikace.
2 400
Invalid request (*)
Product ID '{product_id}' is not valid
Chyba během validace požadavku.
3 400
Invalid request (*)
Product is no longer available for orders
API has to use virtual terminal
Web app cannot use virtual terminal
Chyba během validace požadavku na novou objednávku.
4 404 Order id 'order_id' was not found Zdroj nebyl nalezen.
5 400 Invalid request (*) Zdroj již existuje nebo metodu nelze na zdroj aplikovat.
6 403
Invalid request (*)
Not authorized (*)
Retailer is not allowed to process orders.
Neautorizovaný přístup. Obchodník podle ID nebyl nalezen, podpis není správný, IP adresa není povolena, ...
7 403
Terminal weekly limit has been exceeded
Terminal daily limit has been exceeded
Retailer postpaid limit has been exceeded
Retailer prepaid limit has been exceeded
Překročení limitu pro objednávky obchodníka/terminálu.
8 500 Service provider unavailable Chyba na straně vydavatele produktu.
9 500 Service provider error Chyba na straně vydavatele produktu. Chyba se zobrazí v případě, pokud produkt již nelze stornovat.
10 404 Service endpoint not found Endpoint nebo metoda nebyla nalezena.

(*) hodnoty jsou na produkční instanci z důvodu bezpečnosti obecného charakteru, avšak v testovacím prostředí jsou více specifické.

Konsolidace stavů

Ztracené odpovědi

Implementovat proces zachycující a pracující s nedokončenými objednávkami a ztracenými odpověďmi je důležité pro zachování vzájemné stavové integrity objednávek v našich a vašich systémech a aby bylo zaručeno očekávané vyúčtování.

K jevu ztraceného požadavku nebo odpovědi může docházet z mnoha příčin, zejména však problémy na úrovni síťového připojení. Tyto okolnosti mohou vést k nekonzistenci stavů, kdy v některých případech se do vaší aplikace nemusí promítnout skutečný (finální) stav. Pokud taková situace nastane, doporučujeme POST volání opakovat se stejným order_id jako v prvním neúspěšném pokusu nebo rovnou volat metodu GET na založenou objednávku pro získání PINu.

GET volání lze aplikovat jen u vydavatelů, kteří umožňují předat PIN opakovaně. Vydavatelé, u kterých není možné opakovaně získat PIN metodou GET, je nutné objednávku stornovat a provést zcela nové POST volání s novým order_id.

Rekonsolidační proces

Rekonsolidační proces doporučujeme provádět minimálně na denní bázi, aby byla dlouhodobě zachována vzájemná stavová integrita objednávek v obou systémech. Pro zjištění stavů objednávek provedených za uplynulé dny, využijte metodu Dotaz na více objednávek. V případně zjištěných nekonzistencí volejte Storno objednávky (pokud lze) nebo přiřaďte ztracený PIN k příslušné objednávce.

Proces by měl být z vaší strany implementován následujícím způsobem:

Vlastnosti jednotlivých produktů

Vydavatel Opakované
získání PINu
Stornování
kuponu
paysafecard ne ano
Blizzard ano ano
Steam ano ano
Microsoft ano ne
Sony ano ne
Amazon ano ano
Wargaming ano ano