Zpět

REST API Dáme Knihu

Slovníček pojmů



Průběh komunikace

Obchod Portál zadání / naskenování kódu poukazu ověřit rezervace poukazu ověřeno odečtení hodnoty poukazu z ceny objednávky proces objednávky dokončení objednávky čerpat vyčerpání poukazu vyčerpáno potvrzení čerpání
schéma úspěšné komunikace Obchodu s Portálem

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

Obchod Portál dotaz převod do JSON podepsání JSON zašifrování POST dešifrování vyhledání obchodu ověření podpisu dat zpracování dotazu podepsání odpovědi zašifrování odpovědi :200 dešifrování odpovědi ověření podpisu dekódování JSON odpověď
kompletní schéma úspěšného dotazu

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:

Odpověď:

stavpopis
FChyba - ověření kódu nepovoleno, zkuste později!
NChyba - poukaz nenalezen
EChyba - formát kódu neodpovídá!
UPoukaz byl vyčerpán dříve, nelze čerpat
XPlatnost poukazu vypršela, nelze čerpat
BPoukaz má momentálne rezervovaný jiná pobočka
RPoukaz je platný, aktuálně rezervovaný pro vás
PPoukaz byl úspěšně vyčerpán (pouze pro akce='cerpat')
APoukaz je platný (pouze pro front-end portálu)
přehled možných stavů poukazu

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.

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:

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

kódhttppopis
1400žádná vstupní data!
2400žádný podpis vstupních dat!
3500načtení privátního klíče selhalo
4500dešifrování příchozích dat selhalo
5400nevalidní vstupní data (JSON)
6400pobočka nenalezena
7400prodejce nenalezen
8500načtení veřejného klíče pobočky selhalo
9400neplatný podpis vstupních dat
10500podepsání odchozích dat selhalo
11500šifrování odchozích dat selhalo
přehled chybových kódů API

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í

kódstav poukazu
DK-TEST-000Xexpirovaný
DK-TEST-000Uvyčerpaný
DK-TEST-000Bblokovaný
DK-TEST-000Aplatný
testovací poukazy pro demoverzi

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 implementaci v .NET můžete také využít připravenou ukázku. Můžete si ji 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í).