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

V celé dokumentaci je využita britská angličtina (viz např. CANCELLED).

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

# tajny klic obchodnika
$secret_key = "0b8Qpv7MQ8N0FTma4mFWOK5oy";

$data = [
    "parametr_1" => "hodnota",
    "parametr_2" => null,
    "parametr_3" => 42000,
    "parametr_4" => false,
    "parametr_5" => true
];

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


# pro vytvoreni retezce z multidimensionalniho pole muzeme vyuzit napr. tuto anonymni funkci
$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||42000||1'
$string = $createStringFromNestedArray($data);

# retezec spolu s tajnym klicem vlozime do kryptografické hasovaci funkce hash_hmac() a ziskame podpis
# ziskany podpis 'c8e2693ea2cd7dd23ae20ec049fd1819b0420c4efb57d334b39d1310e65f1ec4'
$signature = hash_hmac("sha256", $string, $secret_key); 

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

Request

{
    "parametr_1": "hodnota",
    "parametr_2": null,
    "parametr_3": 42000,
    "parametr_4": false,
    "parametr_5": true,
    "signature": "c8e2693ea2cd7dd23ae20ec049fd1819b0420c4efb57d334b39d1310e65f1ec4"
}

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||42000||1

Výsledný podpis:
c8e2693ea2cd7dd23ae20ec049fd1819b0420c4efb57d334b39d1310e65f1ec4

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,
    "cost": {
      "currency": "CZK",
      "cost": 9800,
      "cost_vat": 0
    },
    "recommended_retail_price": {
      "CZK": 10000,
      "EUR": null
    },
    "signature": "70c3a21c590fb7c6854761f2ada0c2b8affd8e5b22e59089ab18135e709b369e"
}

Kontrola podpisu v PHP

<?php

# tajny klic obchodnika
$secret_key = "0b8Qpv7MQ8N0FTma4mFWOK5oy";

# Priklad odpovedi prevedene do PHP pole
$dataNested = [
    "vat" => 0,
    "cost" => [
        "currency"=> "CZK",
        "cost"=> 9800,
        "cost_vat" => 0
    ],
    "recommended_retail_price" => [
        "CZK" => 10000,
        "EUR" => null
    ],
    "signature" => "70c3a21c590fb7c6854761f2ada0c2b8affd8e5b22e59089ab18135e709b369e"
];

# 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|CZK|9800|0|10000|' 
$string = $createStringFromNestedArray($dataNested);

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


# podpisy spolu porovname 
if(hash_equals($signatureReceived, $signatureCreated) === FALSE){
  # fallback 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

{
    "type": "PIN",
    "order_id": "moje_objednavka",
    "product_id": 1001001,
    "account_id": null,
    "activation_id": null,
    "pos_id": 1234,
    "value": null,
    "terminal_id": 789120555,
    "retailer_id": 78912,
    "signature": "925adeaf5a1db77e1baa47356c1f54a8dad67ea0247635bbdc4b220b6bfa939a"
}

Response

{
    "error": null,
    "error_code": 0,
    "order_id": "moje_objednavka",
    "product_id": 1001001,
    "vat": 0,
    "cost": {
        "currency": "CZK",
        "cost": 9850,
        "cost_vat": 0
    },
    "recommended_retail_price": {
        "CZK": 10000,
        "EUR": null
    },
    "terminal_id": 789120555,
    "retailer_id": 78912,
    "pin": "9999818580216628",
    "serial_number": "1416965707",
    "ean": null,
    "valid_to": null,
    "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-06-10T09:49:50+00:00",
    "changed_at": "2020-06-10T09:49:51+00:00",
    "status": "DELIVERED",
    "order_error_code": 0,
    "order_error_desc": null,
    "signature": "7d89e491274b50b6b62b94c1af36c9d0dd715a2f46702512264cc49619b1ff10"
}

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
type enum Typ požadavku obsahující jednu z hodnot PIN, ACCOUNT nebo ACTIVATION
order_id string (max 50) ID objednávky. Tuto hodnotu si volíte sami. Využijte pouze alfanumerické znaky (možné je i podtržítko). 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.
account_id int|null
activation_id int|null
pos_id int
value int|null Hodnota NULL, pokud se jedná o produkt s pevnou cenou. Pokud se jedná o dobíjecí produkt, je vložena dobíjená částka v setinách měny.
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/moje_objednavka/a5b909308f813537e1243d55d63d1e83781b2a26e66c2aa93d81e9c48372e726

Response

{
    "error": null,
    "error_code": 0,
    "order_id": "moje_objednavka",
    "product_id": 1001001,
    "vat": 0,
    "cost": {
        "currency": "CZK",
        "cost": 9850,
        "cost_vat": 0
    },
    "recommended_retail_price": {
        "CZK": 10000,
        "EUR": null
    },
    "terminal_id": 789120555,
    "retailer_id": 78912,
    "pin": null,
    "serial_number": "1416965707",
    "ean": null,
    "valid_to": null,
    "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-06-10T09:49:50+00:00",
    "changed_at": "2020-06-10T09:49:51+00:00",
    "status": "DELIVERED",
    "order_error_code": 0,
    "order_error_desc": null,
    "signature": "9664287836278072bd5c7abe97f029e9794592f366b1c9e6a26c2da8ac79c5cd"
}

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 moje_objednavka
signature string Podpis požadavku. a5b909308f813537...

Odpověď

Odpoveď je objekt typu ResponseReceipt.

Dotaz na více objednávek za poslední dny

Request

/orders-list/78912/7/3b46b7af4579a14005848282543bd016118eb390ed5b891c0e8bfc0f25c8dea2

Response

{
    "error": null,
    "error_code": 0,
    "retailer_id": 78912,
    "date_start": "2020-06-03",
    "date_end": "2020-06-10",
    "days": 7,
    "orders_count": 6,
    "orders": [
        {
            "order_id": "2211863191",
            "product_id": 2001002,
            "vat": 21,
            "cost": {
                "currency": "CZK",
                "cost": 115000,
                "cost_vat": 24150
            },
            "recommended_retail_price": {
                "CZK": null,
                "EUR": null
            },
            "terminal_id": 789120444,
            "pin": "abcd-efgh-1234",
            "serial_number": null,
            "ean": "8595149006324",
            "valid_to": null,
            "status": "DELIVERED"
        },
        { ... },
        {
            "order_id": "moje_objednavka",
            "product_id": 1001001,
            "vat": 0,
            "cost": {
                "currency": "CZK",
                "cost": 9850,
                "cost_vat": 0
            },
            "recommended_retail_price": {
                "CZK": 10000,
                "EUR": null
            },
            "terminal_id": 789120555,
            "pin": null,
            "serial_number": "1416965707",
            "ean": null,
            "valid_to": null,
            "status": "DELIVERED"
        }
    ],
    "signature": "9332a19a3a86243cc3b694f385354b324a2fa629632daa79d4a3f74abfec527e"
}

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. 78912
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. 3b46b7af4579a14005848282543bd0161...

Odpověď

Odpoveď je objekt typu ResponseReceiptsList.

Dotaz na více objednávek v intervalu

Request

/orders-interval/78912/2020-01-01/2020-01-31/7abe6c86cd080551d154839eda80c1aa6b034f74375fcb0c21350cd5e1d6a7a7

Response

{
    "error": null,
    "error_code": 0,
    "retailer_id": 78912,
    "date_start": "2020-01-01",
    "date_end": "2020-01-31",
    "days": 30,
    "orders_count": 2,
    "orders": [
        {
            "order_id": "5215889594",
            "product_id": 1001001,
            "vat": 0,
            "cost": {
                "currency": "CZK",
                "cost": 9900,
                "cost_vat": 0
            },
            "recommended_retail_price": {
                "CZK": 10000,
                "EUR": null
            },
            "terminal_id": 789120444,
            "pin": null,
            "serial_number": "1416966337",
            "ean": null,
            "valid_to": null,
            "status": "CANCELLED"
        },
        {
            "order_id": "test1",
            "product_id": 1001001,
            "vat": 0,
            "cost": {
                "currency": "CZK",
                "cost": 9900,
                "cost_vat": 0
            },
            "recommended_retail_price": {
                "CZK": 10000,
                "EUR": null
            },
            "terminal_id": 789120151,
            "pin": null,
            "serial_number": "1416966338",
            "ean": null,
            "valid_to": null,
            "status": "DELIVERED"
        }
    ],
    "signature": "e62cc0b15b70d324f5e24f588d8f5912e1d51d0b89a132edb3de16e5afb2f5ce"
}

Metoda umožňuje získat objednávky provedené v určitém časovém internvalu. Získané objednávky jsou seřazeny od nejstarší po nejnovější.

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. 78912
date_start date Y-m-d 2020-01-01
last_days date_end Y-m-d 2020-01-31
signature string Podpis požadavku. 7abe6c86cd080551d15483...

Odpověď

Odpoveď je objekt typu ResponseReceiptsList.

Storno objednávky

/order/cancel

Request

{
  "order_id": "moje_dalsi_objednavka",
  "retailer_id": 78912,
  "signature": "1de919de92e65568b8a33dfe01d039f8a000d66d3bfe3a0a52e86d8c63a9b005"
}

Response HTTP code 200

{
    "error": null,
    "error_code": 0,
    "order_id": "moje_dalsi_objednavka",
    "product_id": 1001001,
    "vat": 0,
    "cost": {
        "currency": "CZK",
        "cost": 9850,
        "cost_vat": 0
    },
    "recommended_retail_price": {
        "CZK": 10000,
        "EUR": null
    },
    "terminal_id": 789120555,
    "retailer_id": 78912,
    "pin": null,
    "serial_number": "1416965710",
    "ean": null,
    "valid_to": null,
    "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-06-10T10:35:37+00:00",
    "changed_at": "2020-06-10T10:35:43+00:00",
    "status": "CANCELLED",
    "order_error_code": 0,
    "order_error_desc": null,
    "signature": "5aff8af60d10e09dff91c682d46301b426297bbf9e02e0a7d2e625d7b8e3aa91"
}

Response HTTP code 400

{
    "error": "Order id 'moje_dalsi_objednavka' 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. moje_dalsi_objednavka
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. 1de919de92e65568b8a3...

Odpověď

Odpoveď je objekt typu ResponseReceipt.

Ping

Request

/ping

Response

{
    "status": "ok",
    "ip": "127.0.0.1",
    "timestamp": "2020-06-19T13:40:37+00:00"
}

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í pole s informací o stavu systému, vaše IP adresa a časová známka. Pokud spojení nebylo navázáno, je vrácen některý z chybových stavů.

Parametr Datový typ Formát hodnoty Popis
status string Jednoduché ok v případě funkčnosti systému.
ip string ipv4 IP adresa, ze které byl požadavek odeslán.
timestamp dateTime RFC 3339 Aktuální časová známka. Časová zóna je nastavena na UTC timezone +00:00.

Dostupné produkty

Request - jeden produkt

 /products/78912/2001003/08a7ba3f34c9fe6c1cac620f0e5121df00c9480d66a2901ef3d4ae7c5e9537a9

Request - všechny produkty

  /products/78912/ALL/6c4582dbcdc28a15d3a70a29c089e6b484cdf8a3c8002cf6736beb2d716e9016

Response

{
    "error": null,
    "error_code": 0,
    "products_count": 9,
    "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,
            "cost": {
                "currency": "CZK",
                "cost": 9850,
                "cost_vat": 0
            },
            "recommended_retail_price": {
                "CZK": 10000,
                "EUR": null
            },
            "status": "ENABLED",
            "can_be_cancelled": true
        },
        { ... },
        {
            "id": 2001003,
            "name": "PlayStation Plus 1 měsíc",
            "text": null,
            "image_url": null,
            "vat": 21,
            "cost": {
                "currency": "CZK",
                "cost": 16000,
                "cost_vat": 3360
            },
            "recommended_retail_price": {
                "CZK": 19000,
                "EUR": null
            },
            "status": "ENABLED",
            "can_be_cancelled": true
        },
        {
            "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,
            "cost": {
                "currency": "EUR",
                "cost": 1900,
                "cost_vat": 0
            },
            "recommended_retail_price": {
                "CZK": 51900,
                "EUR": 2000
            },
            "status": "ENABLED",
            "can_be_cancelled": false
        }
    ],
    "signature": "e72be0cce08e54bb0cfc4bd509147588fcdf13f9fe2ac0890fa2eb8dda886d50"
}

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": null,
    "error_code": 0,
    "order_id": "2211863191",
    "product_id": 2001002,
    "vat": 21,
    "cost": {
        "currency": "CZK",
        "cost": 115000,
        "cost_vat": 24150
    },
    "recommended_retail_price": {
        "CZK": null,
        "EUR": null
    },
    "terminal_id": 789120444,
    "retailer_id": 78912,
    "pin": "abcd-efgh-1234",
    "serial_number": null,
    "ean": "8595149006324",
    "valid_to": null,
    "text": null,
    "created_at": "2020-06-04T09:54:55+00:00",
    "changed_at": "2020-06-05T00:18:48+00:00",
    "status": "DELIVERED",
    "order_error_code": 0,
    "order_error_desc": null,
    "signature": "0a7bd67be417b20900a7590ee8e3e6ad2a3d338a4ad4b25e90253eab58599486"
}

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|null 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 int 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.
retailer_id int Vaše ID obchodníka, které vám bude přiděleno během procesu implementace.
pin string|null Hodnota NULL (pokud není znovu možné hodnotu získat - např. u Paysafecard) nebo PIN.
serial_number string|null NULL (pokud hodnota není poskytnuta dodavatelem) nebo sériové číslo.
ean string|null NULL (pokud hodnota není známá) nebo EAN produktu.
valid_to date|null Y-m-d NULL (pokud dodavatel neuvádí konec platnosti) nebo datum konce platnosti PINu.
text string|null Popis produktu/návod na uplatnění. Plain text. Nový řádek oddělený znakem \n.
created_at dateTime RFC 3339 Časová známka vytvoření objednávky. Časová zóna je nastavena na UTC timezone +00:00.
changed_at dateTime RFC 3339 Č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|null Popis chyby, pokud objednávka nebyla úspěšně dokončena.
signature string Podpis z výše uvedených hodnot.

ResponseReceiptSimplified

{
    "order_id": "2211863191",
    "product_id": 2001002,
    "vat": 21,
    "cost": {
        "currency": "CZK",
        "cost": 115000,
        "cost_vat": 24150
    },
    "recommended_retail_price": {
        "CZK": null,
        "EUR": null
    },
    "terminal_id": 789120444,
    "pin": "abcd-efgh-1234",
    "serial_number": null,
    "ean": "8595149006324",
    "valid_to": null,
    "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 int 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|null Hodnota NULL (pokud není znovu možné hodnotu získat - např. u Paysafecard) nebo PIN.
serial_number string|null NULL (pokud hodnota není poskytnuta dodavatelem) nebo sériové číslo.
ean string|null NULL (pokud hodnota není známá) nebo EAN produktu.
valid_to date|null Y-m-d NULL (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": null,
    "error_code": 0,
    "retailer_id": 78912,
    "date_start": "2020-06-03",
    "date_end": "2020-06-10",
    "days": 7,
    "orders_count": 6,
    "orders": [
        {
            "order_id": "2211863191",
            "product_id": 2001002,
            "vat": 21,
            "cost": {
                "currency": "CZK",
                "cost": 115000,
                "cost_vat": 24150
            },
            "recommended_retail_price": {
                "CZK": null,
                "EUR": null
            },
            "terminal_id": 789120444,
            "pin": "abcd-efgh-1234",
            "serial_number": null,
            "ean": "8595149006324",
            "valid_to": null,
            "status": "DELIVERED"
        },
        { ... },
        {
            "order_id": "moje_objednavka",
            "product_id": 1001001,
            "vat": 0,
            "cost": {
                "currency": "CZK",
                "cost": 9850,
                "cost_vat": 0
            },
            "recommended_retail_price": {
                "CZK": 10000,
                "EUR": null
            },
            "terminal_id": 789120555,
            "pin": null,
            "serial_number": "1416965707",
            "ean": null,
            "valid_to": null,
            "status": "DELIVERED"
        }
    ],
    "signature": "9332a19a3a86243cc3b694f385354b324a2fa629632daa79d4a3f74abfec527e"
}

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|null 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.
date_start date Y-m-d Začátek časového intervalu, za který jsou objednávky zobrazeny.
date_end date Y-m-d Konec časového intervalu, za který jsou objednávky zobrazeny.
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": null,
    "image_url": null,
    "vat": 21,
    "cost": {
        "currency": "CZK",
        "cost": 16000,
        "cost_vat": 3360
    },
    "recommended_retail_price": {
        "CZK": 19000,
        "EUR": null
    },
    "status": "ENABLED",
    "can_be_cancelled": true
}

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|null Popis produktu/návod na uplatnění. Plain text. Nový řádek oddělený znakem \n.
image_url string|null URL adresa - odkaz na logo/obrázek v PNG s průhledným pozadí.
vat int 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.
can_be_cancelled boolean Stornovatelnost produktu po jeho objednání.

 ReponseProductsList

{
    "error": null,
    "error_code": 0,
    "products_count": 9,
    "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,
            "cost": {
                "currency": "CZK",
                "cost": 9850,
                "cost_vat": 0
            },
            "recommended_retail_price": {
                "CZK": 10000,
                "EUR": null
            },
            "status": "ENABLED",
            "can_be_cancelled": true
        },
        { ... },
        {
            "id": 2001003,
            "name": "PlayStation Plus 1 měsíc",
            "text": null,
            "image_url": null,
            "vat": 21,
            "cost": {
                "currency": "CZK",
                "cost": 16000,
                "cost_vat": 3360
            },
            "recommended_retail_price": {
                "CZK": 19000,
                "EUR": null
            },
            "status": "ENABLED",
            "can_be_cancelled": true
        },
        {
            "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,
            "cost": {
                "currency": "EUR",
                "cost": 1900,
                "cost_vat": 0
            },
            "recommended_retail_price": {
                "CZK": 51900,
                "EUR": 2000
            },
            "status": "ENABLED",
            "can_be_cancelled": false
        }
    ],
    "signature": "e72be0cce08e54bb0cfc4bd509147588fcdf13f9fe2ac0890fa2eb8dda886d50"
}

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|null 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": 9900,
    "cost_vat": 0
}

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 int cena v setinách měny Cena bez DPH, která bude fakturována.
cost_vat int cena v setinách měny Vyčíslené DPH, které bude fakturováno.

RecommandedRetailPrice

Doporučené maloobchodní ceny pro obě měny jsou vyplněny

"recommended_retail_price": {
    "CZK": 51900,
    "EUR": 2000
}

Doporučená maloobchodní cena jen pro jednu měnu

"recommended_retail_price": {
    "CZK": 51900,
    "EUR": null
}

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 namísto čísla vložena hodnota null.

Parametr Datový typ Formát hodnoty Popis
CZK int|null cena v setinách měny Doporučená maloobchodní cena v CZK.
EUR int|null cena v setinách měny 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 vraceny s číslem chyby error_code a popisem chyby error. HTTP kód se liší podle druhu chyby. Popisy chyb nejsou určeny pro koncového zákazníka. Pro podrobnější popis chyby v nejasných individuálních případech nás kontaktujte.

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