Slevomat Partner API

Co je Slevomat Partner API a jak funguje?

Slevomat Partner API je rozhraní, které slouží pro propojení partnerova informačního systému nebo e-shopu s informačním systémem Slevomatu. Přes Slevomat Partner API pak může napojený informační systém nebo e-shop automaticky interagovat s informačním systémem Slevomatu a vyměňovat si data o voucherech, které Slevomat vygeneroval pro zákazníky.

Pokud například prodáváte na Slevomatu svoje služby, po tom, co zákazník zakoupí Vaši službu, Slevomat mu vygeneruje voucher s kódem, který pak může u Vás uplatnit na nákup vybrané služby. Když pak svůj rezervační systém napojíte na Slevomat Partner API, může se tento systém automaticky zeptat systému Slevomatu přes Slevomat Partner API, jestli je nějaký kód voucheru platný a na jakou službu byl zakoupen a také může pak tento kód u Slevomatu automaticky uplatnit.

Funkce Slevomat Partner API

Slevomat Partner API má pouze dvě funkce. První je funkce check, která slouží pro získání informací o voucheru se zadaným kódem. Tuto funkci lze volat i opakovaně a v případě úspěšnosti vrátí volání funkce ve výsledku informace o daném voucheru jako například od kdy do kdy je daný voucher platný, nebo na jaký produkt a variantu produktu byl daný voucher zakoupen.

Druhou funkcí tohoto API je funkce apply, která slouží k uplatnění daného voucheru. Každý voucher lze uplatnit pouze jednou a pokud již je daný voucher uplatněn, skončí volání chybou. Jinak funkce vrací ve výsledku podobné informace jako funkce check.

Podrobnější informace k oběma funkcím jsou uvedeny v dokumentaci ke Slevomat Partner API.

Některé postřehy z praxe

Dokumentace ke Slevomat Partner API postrádala přesnou specifikaci jednotlivých parametrů. Když jsem pak implementoval log dotazování Slevomatu a jednotlivé parametry jsem ukládal do databáze, jejich validace a volba vhodných datových typů byla tak trochu pokusem-omylem.

Pomlčka vs. spojovník. Tohle trochu souvisí s předchozím bodem. U testovacích voucherů je v dokumentaci uvedena někde pomlčka [–] URLencodovaná jako "%E2%80%93" a jinde zase spojovník [-] URLencodován jako "-". Rozhraní sice přijímá kódy voucherů jak s pomlčkou tak se spojovníkem (není nikde v dokumentaci explicitně uvedeno), je ale nutné nezapomenout při dotazování parametry do URL adresy endpointu rozhraní vkládat URLencodované. Já tak nejdříve nedělal, protože jsem se milně domníval, že kód voucheru může obsahovat pouze alfanumerické znaky A-Z a 0-9 bez diakritiky a spojovník. Když jsem pak při testování do pokusné URL testovacímu HTTP klientovi nakopíroval z dokumentace testovací kód s pomlčkou, pěknou chvíli mi trvalo zjistit, proč rozhraní vrací chybu, že kód neexistuje. Ve výsledné implementaci pak u všech voucherů při validaci vstupů od zákazníka rovnou případnou pomlčku nahrazuji spojovníkem.

Absence stálého testovacího "playground" rozhraní. Ze Slevomatu jsem dostal přístupový token a produkční URL endpointů pro dotazování a tři testovací kódy (nezaplacený, zaplacený, uplatněný). Když se ale volá funkce apply na produkční API s neuplatněným/platným testovacím kódem, tento kód zůstane neuplatněný. Dále pak byla možnost napsat do Slevomatu, aby vygenerovali několik voucherů, se kterými bychom pak mohli implementaci na produkci otestovat. Implementoval jsem API v systému, přes který prodáváme mnoho produktů a jejich variant, a který uplatňuje vouchery až v den konání akce a tedy si také sám uchovává, které vouchery již má rezervované. Pro nějaké plnohodnotnější testování by bylo vhodné implementovat nějaké mockup rozhraní, které by se tvářilo jako Slevomat Partner API. To jsem ale nedělal a testovali jsme naši implementaci pouze na produkci - stydím se, i faux paux bylo - přesně takové, jaké se stávají u testování funkcí, které posílají e-maily, nad produkčními daty. Rozhodně tedy můžu při implementaci komplikovanějších procesů jen doporučit vytvořit si vlastní testovací mockup rozhraní a pořádně vše protestovat.

Slevomat Partner API pracuje trochu zvláštně s chybovými kódy HTTP protokolu. Je to sice celé trochu filozofický problém, ale nejviditelnější je "přetěžení" HTTP protokolu ve Slevomat Partner API u funkce apply. Funkce vrátí HTTP status kód 401 Unauthorized, pokud již byl voucher uplatněn. HTTP, jak je i v názvu uvedeno je pouze transportní protokol, a Slevomat Partner API pomocí jeho chybových stavů oznamuje chyby z nejvyšší aplikační vrstvy, jakou selhání uplatnění již uplatněného voucheru bezesporu je. Domnívám se, že zde by rozhraní rozhodně mělo vrátit stavový kód HTTP 200 a v těle odpovědi by měla být uvedena informace o aplikační chybě, která nastala - tedy, že voucher již byl uplatněn.

Shrnutí

Obzvlášť u propojování systémů pomocí rozhraní je nutné vytvořit a detailně technicky zdokumentovat jednoznačný standard tak, aby jej obě strany komunikace správně pochopili a mohli pomocí něj bez problémů komunikovat. Proto jako největší nedostatek tohoto rozhraní vnímám chybějící přesnou specifikaci formátů jednotlivých vstupních a výstupních parametrů komunikace. Jinak implementace Slevomat Partner API určitě stojí za to - dá se s ní ušetřit mnoho prostředků, jako tomu bylo i v našem případě, kdy jsme ušetřili spousty hodin zaměstnanců našeho obchodního oddělení.

Michal Strelec