Pokud si to povaha vašeho doplňku žádá, je možné uživatelům připravit na zadané URL webové rozhraní s detailním nastavení (např. přístupové údaje k externí službě).

Identifikace a zobrazení nastavení pro eshop uživatele

V nejjednodušším případě je možné využít zástupného kódu _ESHOP_CODE_ v parametru URL. V nastavení doplňku lze tedy například uvézt URL pro nastavení: https://plugin.tld/store?store=_ESHOP_CODE_.

Pro zvýšení bezpečnosti a komfortu uživatelů však doporučujeme implementovat přihlašování prostřednictvím Webareal účtů. V systému Webareal může jeden uživatel spravovat více eshopů, na kterých může být nainstalován váš doplněk. Ve vlastním rozhraní tak můžete uživatelům nabidnout rychlé překliknutí na jiný eshop nebo propojení eshopů a hromadné nastavení!

Proces přihlášení využívá protokolu OAuth 2.0 (více zde). Pro implementaci přihlašování nejdříve vygenerujte přístupové údaje k autorizační API na kartě v detailu doplňku. POZOR! Tyto přístupové údaje se liší od přístupových údajů k Webareal API.

Přihlášení uživatele

Uživatel je nejprve přesměrován na autentizační stránku.

GET https://marketplace.webareal.cz/user-auth s parametry:

  • client_id - ID aplikace
  • redirect_uri - URL pro přesměrování uživatele zpět na stránky doplňku. Musí se shodovat s adresou zadanou při vytváření přístupu k autorizační API
  • response_type - s hodnotou code
  • scope - s hodnotou USER_INFO
  • state - volitelný parametr obsahující vlastní CSRF token, což umožňuje validaci odpovědi serveru, která tento token bude také obsahovat

Po úspěšném přihlášení je uživatel přesměrován zpět s následujícími parametry:

  • code - autorizační kód, který bude vyměněn za přístupový token. Platnost toho kódu je 10 minut.
  • state - CSRF token

Příklad:

 
    header('Location: https://marketplace.webareal.cz/user-auth?client_id=LGWQrb7CCOLR5qt8zWnTZXP&redirect_uri=https://url-doplnku.cz/login&response_type=code&scope=USER_INFO&state');
 

Dalším krokem je získání access tokenu

POST https://marketplace.webareal.cz/api/token

  • grant_type s hodnotou authorization_code
  • client_id - ID aplikace
  • client_secret - tajný klíč
  • code - autorizační kód
  • redirect_uri - stejná URL pro přesměrování uživatele

Autorizační server odpoví JSON objektem:

 
    {
        "token_type": "Bearer",
        "expires_in": 3600,
        "access_token": "...", // použití pro získání údajů o uživateli a volání API requestů
        "refresh_token": "..."
    }
 

Příklad:

 
    $curl = curl_init();
    curl_setopt_array($curl, array(
        CURLOPT_URL => https://marketplace.webareal.cz/api/token,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => '',
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 0,
        CURLOPT_FOLLOWLOCATION => true,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => 'POST',
        CURLOPT_POSTFIELDS => [
            'grant_type' => 'authorization_code',
            'client_id' => 'LGWQrb7CCOLR5qt8zWnTZXP',
            'client_secret' => 'e0976500a9ab1bdeacbe7264856ce88d',
            'code' => $code,
            'redirect_uri' => 'https://url-doplnku.cz/login'
        ],
    ));
    $response = curl_exec($curl);
    curl_close($curl);
    echo $response;
 
Parametry je potřeba zapsat jako array (form-data), nikoliv jako JSON.


Získání údajů o uživateli

Pomocí získaného access tokenu je nyní možné dotazem na API načíst údaje o přihlášeném uživateli.

GET https://marketplace.webareal.cz/api/user/about

 
    {
        "user": "user@email.com",
        "stores": [
            {
                "system": "www.webareal.cz",
                "code": "...",
                "name": "..."
            }
        ]
    }
 

Objekt také obsahuje seznam eshopů uživatele, na kterých je daný doplněk nainstalován.


Příklad:

 
    $curl = curl_init();
    curl_setopt_array($curl, array(
        CURLOPT_URL => https://marketplace.webareal.cz/api/user/about,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => '',
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 0,
        CURLOPT_FOLLOWLOCATION => true,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => 'GET',
        CURLOPT_HTTPHEADER => array(
            'Authorization: Bearer ' . $bearer // access token
        ),
    ));
    $response = curl_exec($curl);
    curl_close($curl);
    echo $response;
 


Obnova access tokenu

Access token má omezenou platnost na 1 hodinu, po jeho vypršení lze vyměnit refresh token za nový access token. Platnost refresh tokenu je 1 měsic.

POST https://marketplace.webareal.cz/api/token

  • grant_type s hodnotou refresh_token
  • refresh_token - předešlý refresh token
  • client_id - ID aplikace
  • client_secret - klíč aplikace

Autorizační server vrací nový access a refresh token:

 
    {
        "token_type": "Bearer",
        "expires_in": 3600,
        "access_token": "...",
        "refresh_token": "..."
    }