Instalace doplňku

V následující textu předpokládáme, že máte založený partnerský eshop a že jste schválený jako Shoptet API partner. URL vašeho partnerského eshopu nechť je např. https://12345.myshoptet.com.

Použité termíny

OAuth access token
Tento řetězec reprezentuje každou jednotlivou instalaci vašeho doplňku na eshopu a je potřeba pro získání API access tokenu. Je tedy unikátní pro každý eshop a doplněk. Má časově neomezenou platnost. Délka 255 znaků. OAuth Access Token nesmí opustit backend vývojáře, neposílejte jej eshopaři, na backend, do mailu.

code
Řetezec posílaný jako GET parametr na vaši url, kterou jste zadali v nastavení doplňku. Časově omezená platnost.

API access token
Řetězec pro přístup do Shoptet API. Časově omezená platnost 30 minut. Délka 255 znaků. API access token získáte zavoláním autorizovaneného požadavku na OAuth server. Autorizaci provedete pomocí OAuth access tokenu, který získáte z procesu instalace vašeho doplňku eshopem. Je možné si vyžádat maximálně 5 současně platných API access tokenů (pro jeden OAuth access token).

Získání OAuth access tokenu

Pro každou jednotlivou instalaci doplňku je potřeba získat hodnotu OAuth access tokenu a bezpečně si ji uložit do svých datový struktur. OAuth access token tedy jednoznačně identifikuje daný eshop a doplněk. Získání OAuth Access Tokenu probíhá jen jednou pro každý eshop, během instalace.

Process získání OAuth access tokenu:
– Při instalaci doplňku eshopem obdržíte http požadavek, ve kterém bude jako GET parametr code. URL adresa, na kterou se mají tyto požadavky s code posílat se zadává v nastavení doplňku. (Administrace partnerského eshopu -> Propojení -> API partner -> Záložka doplňky).

Pozor: HTTP status odpovědi vašeho serveru na požadavek s code v případě úspěšné instalace musí být 200. Pokud váš server neodpoví statusem 200, považujeme proces instalace za neuspěšný.

Příklad získání OAuth access tokenu v PHP

V detailu doplňku (Administrace partnerského eshopu -> Propojení -> API partner -> Záložka doplňky) v záložce nastavení zadáte do kolonky Vaše adresa pro získání Oauth kódu url, na které očekáváte požadavek s code např.: https://www.mujserver.cz/instalaceshoptet

Při instalaci doplňku pak dostanete HTTP GET požadavek na zadanou url s parametrem code: https://www.mujserver.cz/instalaceshoptet?code=21cc615b4a01067a75713dd1396057bf96bd925c

Se získaným parametrem code se autorizujete vůči API OAuth serveru a získáte OAuth access token.

// Vaše klientské id v OAuth serveru
// Zde je pouze příklad, konkrétní hodnotu najdete v administraci partnerského eshopu -> propojení -> API partner -> přístup k api
$clientId = 'ae5d72b8964a08ed';

// Váš tajný řetězec pro komunikaci s OAuth serverem
// Pokud v administraci partnerského eshopu -> propojení -> API partner -> přístup k api hodnotu nevidíte, nemáte clientSecret aktivovaný a v komunikaci s OAuth serverem ho neposílejte.
$clientSecret = 'dqwffewfsgdrgwefsfgdtjtkyodg';

// Url pro autorizaci oproti OAuth serveru
// Zde je pouze příklad, konkrétní hodnotu najdete v administraci partnerského eshopu -> propojení -> API partner -> přístup k api
$oauthServerTokenUrl = 'https://12345.myshoptet.com/action/ApiOAuthServer/token'

// Obdržená hodnota code
$code = $_GET['code'];

// Typ autorizace OAuth serveru, vždy zadejte 'authorization_code'
$grantType = 'authorization_code';

// Skupina práv OAuth serveru, vždy zadejte 'api'
$scope = 'api';

// Url zadaná na stránce nastavení doplňku, na které očekáváte požadavek s parametrem 'code' např.:
$redirectUri = 'https://www.mujserver.cz/instalaceshoptet';

// Poslaní požadavku na získání secret_tokenu
$data = [
    'client_id' => $clientId,
    'client_secret' => $clientSecret, // zadáváte, jen pokud máte nastaveno
    'code' => $code,
    'grant_type' => $grantType,
    'redirect_uri' => $redirectUri,
    'scope' => $scope,
];
$curl = curl_init($oauthServerTokenUrl);
curl_setopt($curl, CURLOPT_POST, TRUE);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
$response = curl_exec($curl);
curl_close($curl);

Odpoveď $response je ve formátu json:

{"access_token":"5wty54dv2y5jxaj9lu2glnb6upv2z7a6b3v92xsy06wfaeygmcfa3alg2gx2rdp8ozjqytb3l4eqfub4nbnbm7somfgup58wf6jjjstwyvdtp3kjmh08nhskl0z06qyso27l0q6op5udooofq15zhq7w3h1k4b6jj0j4o83hyar2fu9847e802t56xa87v81lblzed5kgvutjzrp3afvpsefit304q6g3pat0m09pzbd5iyu0qk55zwu6a31sq9","expires_in":null,"token_type":"Bearer","scope":"api"}

V $response je access_token, kterým se budete autorizovat pro získání api tokenů.

$response = json_decode($response, TRUE);
echo "Oauth access token: " . $response['access_token'];
$OauthAccessToken = $response['access_token'];

Hodnotu $OauthAccessToken si uložte, jeho hodnota pro každou instalaci doplňku na eshopu unikátní. Získáním a uložením OAuth access tokenu je process instalace u konce.
Pokud se Vám OAuth access token podaří uložit, odpovězte na požadavek HTTP 200 OK. V standardním nastavení PHP by mělo stačit script ukončit bez nastavování hodnoty.

Základní ilustrační příklad instalačního skriptu
v PHP
v C# ASP.NET

Neúspěšná instalace

Instalaci doplňku považujeme za neúspešnou pokud na požadavek s code:
– odpovíte za dobu delší než 5 sekund.
– pokud odpovíte jiným HTTP kódem než 200

Testování instalace

Pro účely testování lze proces instalace vyvolat v detailu konkrétního doplňku v záložce uživatelé. Tím si můžete otestovat proces instalace a doplněk vyzkoušet na svém partnerském eshopu.

Identita eshopu

Nový klient se projeví voláním instalační procedury tak trochu anonymně. Je zapotřebí převzít klíč a bezpečně ho uložit
a poté zjistit identity eshopu (OAuth Access Token i krátkodobé API Access tokeny jsou jednoznačně svázány s jedním konkrétním eshopem).

Běžná praxe je hned během instalace si vyžádat API access token a volat endpoint Eshop Info. OAuth Access Token si uložíte spolu s číslem eshopu (data.contactInformation.eshopId), případně URL eshopu (data.contactInformation.url), kontaktní email apod.

Je doporučeno, aby instalační rutina dělala do nejméně činností, aby trvala co nejkratší dobu a aby bylo minimální riziko chyby. V ideálním případě jen získejte OAuth Access Token, bezpečně ho uložte a ukončete instalační script. Asynchronně si pak získejte a doplňte identifikaci eshopu. V rámci instalačního scriptu neposílejte email, protože jeho odesílání už může citelně prodloužit dobu běhu instalace, což je nepříjemné pro uživatele a při delším čekání (5 sec) bychom instalaci ukončili jako neúspěšnou.

Opakovaná instalace

Je potřeba počítat s případem, eshopař doplněk odinstaluje, avšak po nějaké době se rozhodne doplněk nainstalovat znovu – bez ošetření by mohlo dojít při druhé instalaci k problémům s duplicitou účtu. Více v článku Odinstalování doplňku.

Facebook
Twitter