NAV Navbar
Přejít na partner.givery.cz

Úvod dokumentace

Platforma Givery disponuje 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ů koncovým 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.

V případě požadavku na VPN tunel nebo jiné nadstandardní zabezpečení nás kontakujte.

Životní cyklus transakce

Názvosloví používané v dokumentaci:

Autentizace a podepisování

Ověřování požadavků se skládá ze dvou úrovní. Parametrem API-Key v HTTP hlavičce, který je povinný pro všechny obchodníky a HMAC podpisem požadavků, který je nepovinný a zavisí na individuální dohodě.

1: API-Key parametr (povinné)

cURL Request

curl https://api.sandbox.givery.cz/v1/ping/20124 \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'API-Key: ak_sandbox_VGyXs0T6G8JkPuaX6C8C3Xwda'

HTTP hlavička požadavku je rozšířena o parametr API-Key, jehož hodnota je API_KEY (API klíč obchodníka). API klíč je obchodníkovi poskytnut během implementačního procesu.

HTTP hlavička požadavku musí dále obsahovat parametry
Content-Type: application/json
Accept: application/json

Odpověď také obsahuje v HTTP hlavičce parametr API-Key.

2. Signature a Timestamp (volitené)

JSON Request

{
  "type": "PIN",
  "order_id": "moje_objednavka123",
  "product_id": 237,
  "account_id": null,
  "activation_id": null,
  "pos_id": 1234,
  "value": null,
  "terminal_id": 116796190,
  "retailer_id": 11679,
  "chit_card_taken": null
}

Vytvoření podpisu v PHP

<?php

# tajny klic obchodnika pro podpis pozadavku
const SECRET_KEY = "sk_sandbox_CAsI4fcX0PJC8XVMH4AgIahwL";
const HTTP_METHOD = "POST"; # POST | GET | PUT - uppercase
const ENDPOINT = "/order";

$ts = time(); # UNIX v sekundach (UTC)
$json_request = '{"type":"PIN","order_id":"moje_objednavka123","product_id":237,"account_id":null,"activation_id":null,"pos_id":1234,"value":null,"terminal_id":116796190,"retailer_id":11679,"chit_card_taken":null}';

$s = HTTP_METHOD . "\n" . ENDPOINT . "\n" . $ts . "\n" . $json_request;

# vysledny podpis === '95101184222b9f91e229cce2bec4d30ef1ce3d56b9a6280d15115d499aa4fce8'
$signature = hash_hmac("sha256", $s, SECRET_KEY);
?>

cURL Request

curl --request POST 'https://api.sandbox.givery.cz/v1/order' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'API-Key: ak_sandbox_VGyXs0T6G8JkPuaX6C8C3Xwda' \
-H 'Signature: 95101184222b9f91e229cce2bec4d30ef1ce3d56b9a6280d15115d499aa4fce8' \
-H 'Timestamp: 1612174498'

-d '{"type":"PIN","order_id":"moje_objednavka123","product_id":237,"account_id":null,"activation_id":null,"pos_id":1234,"value":null,"terminal_id":116796190,"retailer_id":11679,"chit_card_taken":null}'

Pro podepisování je využita HMAC Autentizace. Podpisem 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 (SECRET_KEY), 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 parametr HTTP hlavičky s názvem Signature. Při přijetí požadavku je znovu druhou stranou spočítán podpis a je ověřena shoda.

Hlavička požadavku musí také obsahovat parametr Timestamp. Hodnotou je UNIX časová známka v časové zóně UTC, která nesmí být starší než 5 minut. Slouží pro zamezení eventuálním opakovaným útokům.

Řetězec pro zahashování je vytvořen z HTTP metody požadavku, endpointu bez domény a verze API, časové známky a neformátovaného JSON požadavku. Hodnoty jsou odděleny znakem \n.

signature = HTTP_METHOD + \n + ENDPOINT + \n + TIMESTAMP + \n + JSON_REQUEST

Pro metody GET je JSON vytvořen také ve formátu klíč-hodnota. Klíči jsou názvy parametrů v URL požadavku.

V odpovědi jsou nastaveny parametry HTTP hlavičky Timestamp a Signature. Hodnota parametru Signature je vytvořena stejným způsobem.

Příklady pro vytvoření požadavku

HTTP metoda Endpoint Timestamp JSON pro podpis
POST /order 1612282826 {"type":"PIN","order_id":"moje_objednavka123","product_id":237,"account_id":null,"activation_id":null,"pos_id":1234,"value":null,"terminal_id":116796190,"retailer_id":11679,"chit_card_taken":null}
GET /order/78912/moje_objednavka123 1612282826 {"retailer_id":78912,"order_id":"moje_objednavka123"}
GET /transaction/78912/1234567890 1612282826 {"retailer_id":78912,"transaction_id":1234567890}
GET /ping/78912 1612282826 {"retailer_id":78912}

Dostupné metody

Nová objednávka

/order

JSON Request

{
    "type": "PIN",
    "order_id": "moje_objednavka123",
    "product_id": 246537,
    "account_id": null,
    "activation_id": null,
    "pos_id": 1234,
    "value": null,
    "terminal_id": 789120555,
    "retailer_id": 78912,
    "chit_card_taken": true
}

JSON Response

{
    "error": null,
    "error_code": 0,
    "type": "PIN",
    "order_id": "moje_objednavka123",
    "transaction_id": 1234567890,
    "product_id": 246537,
    "vat": 0,
    "cost": {
        "currency": "CZK",
        "cost": 9850,
        "cost_vat": 0
    },
    "recommended_retail_price": {
        "CZK": 10000,
        "EUR": null
    },
    "terminal_id": 789120555,
    "retailer_id": 78912,
    "account_id": null,
    "activation_id": null,
    "pos_id": 1234,
    "value": null,
    "pin": "9999818580216628",
    "barcode": 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
}

Metoda pro vytvoření požadavku na novou objednávku. Po jejím zavolání bude vydán nový produkt. Rozlišujeme 3 typy požadavků:

Volba typů, které budete implementovat, závisí na vzájemně dohodnutých produktech. Nemusí tedy být vždy potřeba implementovat všechny typy.

Všechny parametry požadavku popsané níže jsou povinné.

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.
product_id int ID objednávaného produktu nebo jeho EAN. Hodnota musí odpovídat ID/EANu dostupného produktu. Dostupné produkty lze získat metodou /products nebo v administraci obchodníka.
account_id int|null Vyžadováno pouze pro typ požadavku ACCOUNT. ID dobíjeného účtu.
activation_id int|null Vyžadováno pouze pro typ požadavku ACTIVATION. ID dobíjeného/aktivovaného poukazu.
pos_id int Vaše označení fyzického místa (pobočka/pokladna,...), ze kterého je požadavek odesílán. Je potřeba pro reporting některým vydavatelům.
value int|null Hodnota NULL, pokud se jedná o produkt s pevnou cenou. Pokud se jedná o dobíjecí produkt, je parametr povinný a 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.
chit_card_taken bool|null Informace, zda si koncový zákazník odnesl z místa prodeje fyzický poukaz s sebou.

Odpověď

Odpoveď je objekt typu ResponseReceipt.

Dotaz na jednu objednávku

  /order/78912/moje_objednavka123
  /transaction/78912/1234567890

Response

{
    "error": null,
    "error_code": 0,
    "type": "PIN",
    "order_id": "moje_objednavka123",
    "transaction_id": 1234567890,
    "product_id": 246537,
    "vat": 0,
    "cost": {
        "currency": "CZK",
        "cost": 9850,
        "cost_vat": 0
    },
    "recommended_retail_price": {
        "CZK": 10000,
        "EUR": null
    },
    "terminal_id": 789120555,
    "retailer_id": 78912,
    "account_id": null,
    "activation_id": null,
    "pos_id": 1234,
    "value": null,
    "pin": null,
    "barcode": 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
}

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

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

Ukázkové hodnoty požadavku /order

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_objednavka123

Ukázkové hodnoty požadavku /transaction

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
transaction_id int (10 znaků, nezačíná nulou) ID transakce, které objednávce bylo automaticky přiděleno při vytvoření objednávky metodou /order 1234567890

Odpověď

Odpoveď je objekt typu ResponseReceipt.

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

/orders-list/78912/7

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": [
        {
            "type": "PIN",
            "order_id": "2211863191",
            "transaction_id": 1234567890,
            "product_id": 640993,
            "vat": 21,
            "cost": {
                "currency": "CZK",
                "cost": 115000,
                "cost_vat": 24150
            },
            "recommended_retail_price": {
                "CZK": null,
                "EUR": null
            },
            "terminal_id": 789120444,
            "account_id": null,
            "activation_id": null,
            "value": null,
            "pin": "abcd-efgh-1234",
            "barcode": "QR",
            "serial_number": null,
            "ean": "8595149006324",
            "valid_to": null,
            "status": "DELIVERED"
        },
        { ... },
        {
            "type": "PIN",
            "order_id": "moje_objednavka123",
            "transaction_id": 9876543120,
            "product_id": 246537,
            "vat": 0,
            "cost": {
                "currency": "CZK",
                "cost": 9850,
                "cost_vat": 0
            },
            "recommended_retail_price": {
                "CZK": 10000,
                "EUR": null
            },
            "terminal_id": 789120555,
            "account_id": null,
            "activation_id": null,
            "value": null,
            "pin": null,
            "barcode": null,
            "serial_number": "1416965707",
            "ean": null,
            "valid_to": null,
            "status": "DELIVERED"
        }
    ]
}

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 a druhý parametr určitě kolik dní do minulosti hledat objednávky.

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

Odpověď

Odpoveď je objekt typu ResponseReceiptsList.

Dotaz na více objednávek v intervalu

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

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": [
        {
            "type": "PIN",
            "order_id": "5215889594",
            "transaction_id": 1234567890,
            "product_id": 246537,
            "vat": 0,
            "cost": {
                "currency": "CZK",
                "cost": 9900,
                "cost_vat": 0
            },
            "recommended_retail_price": {
                "CZK": 10000,
                "EUR": null
            },
            "terminal_id": 789120444,
            "account_id": null,
            "activation_id": null,
            "value": null,
            "pin": null,
            "barcode": null,
            "serial_number": "1416966337",
            "ean": null,
            "valid_to": null,
            "status": "CANCELLED"
        },
        {
            "type": "PIN",
            "order_id": "test1",
            "transaction_id": 8527413698,
            "product_id": 246537,
            "vat": 0,
            "cost": {
                "currency": "CZK",
                "cost": 9900,
                "cost_vat": 0
            },
            "recommended_retail_price": {
                "CZK": 10000,
                "EUR": null
            },
            "terminal_id": 789120151,
            "account_id": null,
            "activation_id": null,
            "value": null,
            "pin": null,
            "barcode": null,
            "serial_number": "1416966338",
            "ean": null,
            "valid_to": null,
            "status": "DELIVERED"
        }
    ]
}

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
date_end date Y-m-d 2020-01-31

Odpověď

Odpoveď je objekt typu ResponseReceiptsList.

Storno objednávky

/order/cancel

JSON Request

{
  "retailer_id": 78912,
  "order_id": "moje_dalsi_objednavka"
}

Response HTTP code 200

{
    "error": null,
    "error_code": 0,
    "type": "PIN",
    "order_id": "moje_dalsi_objednavka",
    "transaction_id": 1234567890,
    "product_id": 978147,
    "vat": 0,
    "cost": {
        "currency": "CZK",
        "cost": 9850,
        "cost_vat": 0
    },
    "recommended_retail_price": {
        "CZK": 10000,
        "EUR": null
    },
    "terminal_id": 789120555,
    "retailer_id": 78912,
    "account_id": null,
    "activation_id": null,
    "pos_id": 1234,
    "value": null,
    "pin": null,
    "barcode": 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
}

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.

Všechny parametry požadavku popsané níže jsou povinné.

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, kterou si přejete stornovat. moje_dalsi_objednavka

Odpověď

Odpoveď je objekt typu ResponseReceipt.

Ping

/ping/78912

Response - OK

{
    "status": "ok",
    "ip": "127.0.0.1",
    "timestamp": "2021-02-02T12:47:30+00:00"
}

Response - ERROR

{
    "error": "Internal error",
    "error_code": 1
}

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ů. Nejedná se však o kontrolu dostupnosti systému vydavatele produktu. K tomu slouží metoda check.

Odpověď

V případě navázání spojení je v odpovědi klíč status s hodnotou ok, vaše IP adresa a časová známka (UTC timezone +00:00 v RFC 3339 formátu). Pokud spojení nebylo navázáno, je vrácen některý z chybových stavů.

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

Check

/check/78912/978147

Response - OK

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

Response - ERROR

{
    "error": "Service provider error",
    "error_code": 9
}

Prostředek pro otestování, zda je systém vydavatele dostupný a je schopný vydat nový produkt. Tuto metodu doporučujeme volat vždy před prvotním POST voláním a ověřit tak funkčnost spojení s námi a vydavatelem.

Odpověď

V případě potvrzení ze strany vydavatele, že je připraven přijímat požadavky, je v odpovědi klíč status s hodnotou ok, vaše IP adresa a časová známka (UTC timezone +00:00 v RFC 3339 formátu). Pokud vydavatel není schopen přijímat požadavky, je vrácen některý z chybových stavů.

Pokud je navrácen chybový stav, nedoporučujeme u dotazovaného produktu volat metodu /order. Volání zkuste později.

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 ID produktu, který bude předmětem objednávky. 2001003

Dostupné produkty

Jeden produkt

 /products/78912/978147

Všechny produkty

  /products/78912/ALL

Response

{
    "error": null,
    "error_code": 0,
    "products_count": 9,
    "products": [
        {
            "id": 978147,
            "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,
            "is_top_up": false
        },
        { ... },
        {
            "id": 246537,
            "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,
            "is_top_up": false
        },
        {
            "id": 794765,
            "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,
            "is_top_up": false
        }
    ]
}

Metoda vrací objekt typu ResponseProductsList obsahující jednotlivé produkty, které jsou pro obchodníka dostupné k prodeji. Jednotlivé produkty jsou objektem typu ResponseProduct. 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

Odpověď

Odpoveď je objekt typu ResponseProductsList.

Objekty odpovědí

ResponseReceipt

{
    "error": null,
    "error_code": 0,
    "type": "PIN",
    "order_id": "2211863191",
    "transaction_id": 1234567890,
    "product_id": 794765,
    "vat": 21,
    "cost": {
        "currency": "CZK",
        "cost": 115000,
        "cost_vat": 24150
    },
    "recommended_retail_price": {
        "CZK": null,
        "EUR": null
    },
    "terminal_id": 789120444,
    "retailer_id": 78912,
    "account_id": null,
    "activation_id": null,
    "pos_id": 1234,
    "value": null,
    "pin": "abcd-efgh-1234",
    "barcode": "QR",
    "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
}

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ě.
type enum PIN | ACCOUNT | ACTIVATION Typ požadavku.
order_id string ID objednávky, které určujete při vytváření nové objednávky.
transaction_id int (10 znaků, nezačíná nulou) ID transakce je unikátní číslo, které je přiděleno objednávce při jejím vytváření.
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.
account_id int|null ID dobíjeného účtu. Vyplněno pouze pro typ požadavku ACCOUNT.
activation_id int|null ID dobíjeného/aktivovaného poukazu. Vyplněno pouze pro typ požadavku ACTIVATION.
pos_id int Označení fyzického místa (pobočka/pokladna,...), které určujete při vytváření nové objednávky.
value int|null Hodnota NULL, pokud se jedná o produkt s pevnou cenou. Pokud se jedná o dobíjecí produkt, obsahuje dobíjenou částku v setinách měny.
pin string|null Hodnota NULL (pokud není znovu možné hodnotu získat - např. u Paysafecard) nebo PIN.
barcode enum Barcode Nepovinná reprezentace hodnoty pin. Obsahuje jednu z hodnot popsanou v Barcode.
serial_number string|null NULL (pokud hodnota není poskytnuta vydavatelem) 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 vydavatel 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.

Standardně se koncovému zákazníkovi předávají údaje pin, serial_number, valid_to, text, transaction_id a datum a čas prodeje (tedy většinou přibližně created_at).

ResponseReceiptSimplified

{
    "type": "PIN",
    "order_id": "2211863191",
    "transaction_id": 1234567890,
    "product_id": 794765,
    "vat": 21,
    "cost": {
        "currency": "CZK",
        "cost": 115000,
        "cost_vat": 24150
    },
    "recommended_retail_price": {
        "CZK": null,
        "EUR": null
    },
    "terminal_id": 789120444,
    "account_id": null,
    "activation_id": null,
    "value": null,
    "pin": "abcd-efgh-1234",
    "barcode": null,
    "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
type enum PIN | ACCOUNT | ACTIVATION Typ požadavku.
order_id string ID objednávky, které určujete při vytváření nové objednávky.
transaction_id int (10 znaků, nezačíná nulou) ID transakce je unikátní číslo, které je přiděleno objednávce při jejím vytváření.
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.
account_id int|null ID dobíjeného účtu. Vyplněno pouze pro typ požadavku ACCOUNT.
activation_id int|null ID dobíjeného/aktivovaného poukazu. Vyplněno pouze pro typ požadavku ACTIVATION.
value int|null Hodnota NULL, pokud se jedná o produkt s pevnou cenou. Pokud se jedná o dobíjecí produkt, obsahuje dobíjenou částku v setinách měny.
pin string|null Hodnota NULL (pokud není znovu možné hodnotu získat - např. u Paysafecard) nebo PIN.
barcode enum Barcode Předepsaná reprezentace hodnoty pin. Obsahuje jednu z hodnot popsanou v Barcode.
serial_number string|null NULL (pokud hodnota není poskytnuta vydavatelem) 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 vydavatel 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": [
        {
            "type": "PIN",
            "order_id": "2211863191",
            "transaction_id": 1234567890,
            "product_id": 640993,
            "vat": 21,
            "cost": {
                "currency": "CZK",
                "cost": 115000,
                "cost_vat": 24150
            },
            "recommended_retail_price": {
                "CZK": null,
                "EUR": null
            },
            "terminal_id": 789120444,
            "account_id": null,
            "activation_id": null,
            "value": null,
            "pin": "abcd-efgh-1234",
            "barcode": "QR",
            "serial_number": null,
            "ean": "8595149006324",
            "valid_to": null,
            "status": "DELIVERED"
        },
        { ... },
        {
            "type": "PIN",
            "order_id": "moje_objednavka123",
            "transaction_id": 9876543120,
            "product_id": 246537,
            "vat": 0,
            "cost": {
                "currency": "CZK",
                "cost": 9850,
                "cost_vat": 0
            },
            "recommended_retail_price": {
                "CZK": 10000,
                "EUR": null
            },
            "terminal_id": 789120555,
            "account_id": null,
            "activation_id": null,
            "value": null,
            "pin": null,
            "barcode": null,
            "serial_number": "1416965707",
            "ean": null,
            "valid_to": null,
            "status": "DELIVERED"
        }
    ]
}

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ší.

 ResponseProduct

{
    "id": 794765,
    "name": "PlayStation Plus 1 měsíc",
    "text": null,
    "image_url": null,
    "ean": "8595149006324",
    "vat": 21,
    "cost": {
        "currency": "CZK",
        "cost": 16000,
        "cost_vat": 3360
    },
    "recommended_retail_price": {
        "CZK": 19000,
        "EUR": null
    },
    "status": "ENABLED",
    "can_be_cancelled": true,
    "is_top_up": false
}

Z objektu lze vyčíst různé informace o produktu. Může sloužit pro automatizaci zalistování produktů do vašeho systému a pravidelnou aktualizaci nákupních cen. Objekt je vkládán do parametru products výsledného objektu ResponseProductsList, 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í.
ean string|null NULL (pokud hodnota není známá) nebo EAN produktu.
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í.
is_top_up boolean Obsahuje false pro produkt s pevnou cenou. Pro produkt s dobíjecí cenou obsahuje true. U objednávky dobíjecího produktu (POST požadavek) je parametr value povinný.

 ResponseProductsList

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

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 ResponseProduct Položkou pole je objekt typu ResponseProduct. Pokud nebyl nalezen žádný produkt, je pole prázdné.

Cost

"cost": {
    "currency": "CZK",
    "cost": 9900,
    "cost_vat": 0
}

Objekt obsahuje informace o nákupní ceně prodaného produktu. Některé hodnoty jsou u dobíjecích produktů vyplněny až po dobití.

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|null cena v setinách měny Cena bez DPH, která bude fakturována. NULL u dobíjecího produktu, pro který zatím dobíjená částka není známa.
cost_vat int|null cena v setinách měny Vyčíslené DPH, které bude fakturováno. NULL u dobíjecího produktu, pro který zatím dobíjená částka není známa.

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.

Objekt může do budoucna získávat nové hodnoty zejména u produktů, které nebudou regionálně omezeny uplatněním. Vždy budou však u všech produktů stejné klíče.

Parametr Datový typ Formát hodnoty Popis
CZK int|null cena s DPH v setinách měny Doporučená maloobchodní cena v CZK.
EUR int|null cena s DPH v setinách měny Doporučená maloobchodní cena v EUR.

Barcode

Nepovinná reprezentace hodnoty pin QR/čárovým kódem. Může nabývat hodnot QR, CODE128, CODE11 atd. V ostatních případech je vracena hodnota NULL. Bude upřesněno v průběhu implementace v závislosti na jednotlivých produktech.

Parametr barcode může do budoucna nabývat na nových hodnotách dle požadavků nových vydavatelů.

OrderStatus

Každá objednávka nabývá jeden z následujících stavů:

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

V případě, že jakýkoliv produkt již nebude dostupný, změní se mu status dostupnosti.

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

Návratové HTTP kódy

V odpovědích na volání našeho API jsou použity tyto HTTP status 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.

Ztraceným požadavkům, případně nedokončeným voláním z důvodu technických problémů na straně vydavatele produktů, lze předcházet voláním metod ping, resp. check před každým požadavkem.

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.

Pokud PIN kód již nelze objednávce přiřadit a vydavatel poukazu neumožňuje storno, celý požadavek včetně detailního logu uložte a kontaktujte nás, abychom situaci individuálně vyřešili. Vždy je potřeba pečlivě logovat, zda byl zejména PIN předán koncovému zákazníkovi, či nikoliv.

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
Doba, po kterou je
možné kupony stornovat
paysafecard ne ano 20 dní
Blizzard ano ano neomezeno
Steam ano ano neomezeno
Microsoft ano ne -
Sony ano ne -
Amazon ano ano 15 minut
Wargaming ano ano neomezeno
Adidas ano ano pouze v den objednání
Zalando ano ano neomezeno
Netflix ano ano pouze v den objednání
Twitch ano ano pouze v den objednání
Ostatní ano ne -