Nápověda

REST API Dáme Knihu

Slovníček pojmů

• API - Rozhraní mezi prodejcem a portálem specifikované touto dokumentací.
• Portál - Webový portál DámeKnihu.cz sloužící pro nákup a ověření Poukazů.
• Prodejce - Provozovatel obchodu nebo e-shopu, příjemce poukazů od zákazníků.
• Zákazník - Vlastník poukazu, který u prodejce nakupuje využitím poukazu.
• Obchod - Prodejní místo či e-shop Prodejce.
• Poukaz - Cenina konkrétní hodnoty určená k nákupu knih či příslušenství u Prodejců .
• Kód poukazu - Poukaz obsahuje 10 místný alfanumerický kód pro ověření platnosti a čerpání.
• Veřejný klíč - Veřejná část asynchronního šifrovacího klíče.
• Privátní klíč - Tajná část asynchronního šifrovacího klíče.
• Podpis - Datový otisk odeslaných dat pomocí privátního klíče, sloužící k ověření původu dat.

Průběh komunikace

Komunikace s API se odehrává na pozadí obchodu během procesu objednávky, prodejce nebo zákazník eshopu vidí jen výsledek (záleží na konkrétní implementaci).

Prodejce naskenuje kód z poukazu klienta (nebo jej klient zadá v e-shopu), a následně obchod přes API pošle dotaz na jeho hodnotu a stav.

API vyhledá poukaz dle kódu, ověří jeho platnost a vrátí informace o poukazu, zejména hodnotu a zda je možné čerpat. Pokud je možné čerpat, poukaz dočasně zablokuje aby jej nevyčerpal jiný obchod.

Pokud je možné čerpat, obchod započítá hodnotu poukazu do objednávky a pokračuje v nákupním procesu. Je možné ověřit i další poukazy.

Při dokončení objednávky obchod pošle dotaz na vyčerpání použitého poukazu (je možné vložit poznámku, například číslo paragonu či objednávky).

API poukaz znovu ověří, a následně označí za vyčerpaný. Obchodu vrací potvrzení, že došlo k čerpání (nebo chybový stav).

Příprava pro implementaci

1. Registrace účtu prodejce - registrujte se, a následně ověřte váš účet pomocí odkazu zaslaného e-mailem.
2. Ověření administrátorem - pro získání opravnění musíte vyčkat na ověření administrátorem - do 2 pracovních dnů Vás kontaktujeme.
3. Založení pobočky - přihlaste se do portálu, a vytvořte novou prodejnu (tlačítko "nová prodejna" na stránce po přihlášení).
4. Vygenerování klíčů
   1. klikněte na ikonu klíče u vybrané prodejny
   2. zkontrolujte data ve formuláři
   3. poznamenejte si číslo v poli "pobočka" (budete jej potřebovat pro identifikaci obchodu během komunikace s API).
   4. vyplňte vaše heslo a potvrďte.
   Odesláním formuláře se vygeneruje nový pár veřejného a soukromého klíče - veřejný klíč bude uložen v databázi portálu, soukromý klíč Vám bude nabídnut ke stažení. Tento soukromý klíč uložte a pečlivě jej uschovejte, nesdílejte jej s nikým (s výjímkou osob které budou implementovat napojení na API portálu).
5. Veřejný klíč Portálu - náš veřejný klíč si můžete stáhnout kdykoliv.

Implementace

Obecný dotaz do API

API vychází z principů REST API, je dostupné přes HTTP protokol, data jsou posílána v JSON formátu, zašifrována metodou RSA včetně podpisu dat.

Zde si rozebereme průběh jednoho dotazu - jeho sestavení, podpis, zašifrování a odeslání, a také ověření odpovědi.

Data dotazu musí vždy obsahovat parametr "akce" (například "overeni"), a parametr "pobocka" který identifikuje konkrétní obchod a prodejce.

Data ve formátu JSON podepište soukromým klíčem obchodu (algoritmus SHA512), podpis přiložte na konec dat a celý řetězec zašifrujte (padding OAEP) veřejným klíčem portálu.

Dotazy posílejte metodou POST jako hodnotu s klíčem "data".
curl -v -X POST https://www.dameknihu.cz/API-v1 -d '{ "data":"..." }'

V API jsou data dešifrována, dle nich vyhledán příslušný obchod a prodejce, a pomocí veřejného klíče obchodu je ověřen podpis dat.

Po zpracování dotazu jsou data odpovědi zpracována obdobně - podepsána soukromým klíčem portálu, zašifrována veřejným klíčem obchodu, a odeslána s návratovým kódem 200.

Příchozí odpověď dešifrujte vaším soukromým klíčem, oddělte podpis (posledních 512 bytů) a ověřte ho veřejným klíčem portálu.

V případě chyby na straně API vrací odpověď s návratovým kódem 4xx (chyba klienta) nebo 5xx (chyba serveru), obsahem odpovědi je pouze nezašifrovaný chybový kód.

Ověření poukazu

Tento dotaz slouží k ověření platnosti a získání hodnoty poukazu během nákupu, e-shop i kamenná prodejna by jej měla volat po zadání či naskenování kódu poukazu. API vyhledá poukaz dle kódu a vrací zpět jeho stav, hodnotu v CZK a datum platnosti.

Parametry dotazu:

• akce - určuje typ dotazu, pro ověření poukazu použijte 'overit'
• pobocka - ID vašeho obchodu v Portálu (například 384), získáte jej během generování klíčů
• kod - kód poukazu, který chcete ověřit (například 'DK-DEMO-000A')
• uzivatel - email zaměstnance pobočky (nepovinný), slouží k identifikaci vašeho zaměstnance v rámci Portálu a detailnějšímu reportu.

Odpověď:

Pokud dotaz proběhl správně, vrací vždy parametry 'stav' a 'text', další parametry jsou závislé na stavu poukazu, odpověď je nemusí obsahovat.

• stav - jednoznakový kód (viz tabulka stavů poukazu)
• text - doplňující text ke stavu poukazu
• data
  • hodnota - hodnota poukazu v CZK
  • hodnota_txt - textová hodnota poukazu vč. měny
  • stav_txt - popis stavu poukazu, například Aktivní
  • datum_blokace - timestamp do kdy je poukaz zablokovaný
  • datum_blokace_txt - například Poukaz máte blokovaný do 11:04:25.
  • datum_platnosti - timestamp do kdy je poukaz platný
  • datum_platnosti_txt - například Poukaz je platný do 17. 5. 2022
  • datum_cerpani - timestamp kdy byl poukaz vyčerpán 1609498800
  • datum_cerpani_txt - například Poukaz byl vyčerpán 1. 1. 2021 12:00:00.
  • prodejce_cerpani - ID prodejce, který poukaz vyčerpal, například 1
  • pobocka_cerpani - ID pobočky, kde byl poukaz vyčerpán, například 384

Ověřování a čerpání poukazů je omezeno - pokud se vrací stav F, znamená to že vaše pobočka překročila kvótu a musíte počkat. Detaily najdete zde: kvóty a limity.

Stavy N a E znamenají, že poukaz s daným kódem neexistuje. Pokud se vrací stav U nebo X, poukaz již není platný a nelze jej čerpat.

Při ověření platného poukazu přes API bude poukaz po několik minut rezervován pouze pro vaši pobočku (vrátí stav R),
jiná pobočka jej během té doby nebude moci čerpat (dostane stav B).

Čerpání poukazu

Čerpání je vpodstatě jen rozšířený dotaz pro ověření. V ideálním případě by měl být volán až po úspěšném ověření, během dokončení objednávky a v intervalu kdy máte poukaz rezervovaný pro vaši pobočku. Můžete jej ale volat i nezávisle.

Parametry dotazu:

• akce - určuje typ dotazu, pro čerpání poukazu použijte 'cerpat'
• pobocka, kod, uzivatel - neliší se od dotazu pro čerpání.
• poznamka - textový řetězec (nepovinný), zapíše se k poukazu při čerpání poukazu, můžete jej využít například pro číslo dokladu nebo pokladny, externí identifikaci objednávky či uživatele e-shopu. Limit je 255 znaků.

Odpověď:

Pokud čerpání proběhlo vpořádku a poukaz byl uplatněn, vrací stav P, poukaz v portálu bude doplněn o ID vaší pobočky a také čas čerpání. Nebude možné jej znovu čerpat. Poukaz je vždy vyčerpán celý, není možné jej vyčerpat částečně.

V opačném případě vrací stavy stejně jako ověření poukazu.

Chyby a návratové kódy

Pokud dotaz na API proběhl správně (byť je odpověď negativní), vrací se zpět s HTTP stavovým kódem 200, a odpověď obsahuje zašifrovaná data a podpis.

Pokud se dotaz na API vrátí s jiným HTTP stavovým kódem, došlo při zpracování dotazu k chybě - stavový kód určuje zda jde o chybu ze strany obchodu (stav 400, například neplatný podpis dat) nebo portálu (stav 500, například selhání při dešifrování dat).

Dotaz který se vrátil s chybou obsahuje namísto zašifrovaných dat pouze jeden z chybových číselných kódů z přiložené tabulky (nezašifrovaný).

Kvóty a omezení
Musíme se chránit před útoky, z toho důvodu je počet ověření kódu omezen. Každá pobočka může za poslední 3 hodiny ověřovat až 540 unikátních poukazů (3 ověření za minutu). I v případě překročení hranice může ověřovat a čerpat dál, ale jen za podmínky, že alespoň 1/3 kódů existuje. Při překročení kvóty API vrací stav F.

Ukázka implementace, testování

Aplikace psané v PHP mohou využít připravenou třídu nebo sadu funkcí pro komunikaci s API. Připravená je i microsite, která demonstruje komunikaci s API pomocí webového formuláře a připraveného soukromého klíče naší testovací pobočky. Celé demo si můžete stáhnout zde.

Pro testování jsou připravené 4 kódy, každý v jiném ze stavu. Platný poukaz je možné čerpat, při dalším dotazu pak vrací, že byl použitý (tento poukaz je následně obnoven pro další testování čerpání).