Základní informace o API

API je implementováno jako REST, požadavky i odpovědi se posílají ve formátu JSON. API slouží pouze jako rozhraní pro čtení a aktualizaci dat. Pro čtecí i zapisovací požadavky se používají URL volání zvané endpointy, jejich popis naleznete v Apiary dokumentaci. Dále je dostupná služba oznámení o událostech (webhooky), kdy po zaregistrování webhoku zavoláme zadané URL například po vytvoření nové objednávky. API není určeno pro úpravy frontendu eshopu, určitých úprav ale lze dosáhnout pomocí HTML kódů vkládaných do šablon.

API není volně přístupné, v současné fázi je dostupné poze pro vývojáře tzv. doplňků, které jsou po dokončení zveřejněny na marketplace https://doplnky.shoptet.cz. Odtud si je může kterýkoliv eshop (mimo zkušebních verzí) nainstalovat. V současné době není možné API používat eshopařem nebo pro partnery, kteří by vyvíjel jen pro jeden eshop.

V rámci instalace vznikne unikátní API klíč, který jednoznačně identifikuje eshop a doplněk. Jeho pomocí se získávají krátkodové přístupové API tokeny, které je potřeba uvádět v HTTP hlavičce volání API jako autentifikaci.

Doplňky (software využívající API) musí běžet a ukládat data na infrastruktuře partnera – vývojáře. Shoptet hosting ani ukládání dat doplňku nezajišťuje. Vývojář má volnou ruku ve volbě technologií.

Doplněk voláním API může získat přístup ke všem datům eshopu, včetně například objednávek, cen nebo údajů o zákazníkovi. Proto musí každý doplněk říci, jaká data využívá a jen příslušná volání je možné pro daný API klíč získat. Seznam poskytovaných dat schvaluje Shoptet před uveřejněním doplňku na webu Doplňků a každý uživatel (eshopař) je před instalací může revidovat.

Pokud nová verze doplňku potřebuje další data, je potřeba rozsah oprávnění rozšířít, nechat schválit Shoptetem a posléze uživatelem. Uživatel je o potřebě nových oprávnění upozorněn v administraci a navigován ke schválení.

Vývoj doplňku

Pro vývoj nového doplňku má partner k dispozici svůj testovací eshop, ve kterém může vyvíjet a testovat. Schválený partner má k dispozici sekci „API Partner“, ve které může zadat nový doplněk, definovat požadované endpointy a získat dočasný testovací API access token napojený na jeho partnerský eshop. S jeho pomocí je možné volat API endpointy (které mu poskytují data z jeho partnerského testovacího eshopu).

Dříve či později je třeba vytvořit instalační rutinu, kterou voláme, jakmile si doplněk někdo objednává. Pro vývoj instalační rutiny je možné instalaci doplňku simulovat. Simulovanou instalací svého doplňku na svůj eshop získá partner trvale platný API klíč (OAuth Access Token), kterým si žádá o krátkodobé API tokeny a volá API (které mu poskytuje data z jeho testovacího eshopu).

Pak je možné volat API a naprogramovat činnost doplňku. Po odladění doplňku a schválení Shoptetem je doplněk vystaven na Doplňcích a k dispozici všem eshopům k instalaci.

Práce s doplňkem má v podstatě dva kroky: instalace a běžný provoz

Instalace

V rámci instalace je volána instalační URL partnera, který v ní získá API klíč (OAuth Access Token) a zjistí si identitu eshopu, který doplněk instaluje. Obojí je třeba si bezpečně uložit.

Zároven je to informace o novém klientovi, kterému můžete chtít poslat uvítací email, vytvořit profil, stáhnout základní data, zpřístupnit různá nastavení atp.

Běžný provoz doplňku

K volání jednotlivých API endpointů se používá krátkodobý API Access Token. Ten získáte z OAuth serveru, přičemž se autorizujete pomocí OAuth Access Token získaný v prvním kroku (instalace). API Access Token je tedy opět platný pro jeden doplněk a jeden eshop. Jeho trvanlivost je 30 minut, pak je třeba vyžádat nový. Je dobré si ho uložit, ale není to tak kritické, jako v bodě 1, protože jeho platnost je časově omezena. Můžete si buď sledovat jeho platnost a po jejím překročení vyžádat nový anebo ho používat, dokud vám naše API nevrátí HTTP kód 401 s hláškou „invalid-token“, vyžádat si nový token a opakovat volání.

Facebook
Twitter