If the nature of your plugin requires it, it is possible to provide users with a web interface with detailed settings (e.g. access data to an external service) at a specified URL.

Identify and display settings for eshop users

In the simplest case, you can use the _ESHOP_CODE_ placeholder in the URL parameter. For example, you can specify a URL for the settings in the add-on settings: https://plugin.tld/store?store=_ESHOP_CODE_.

However, to increase security and user convenience, we recommend implementing login via Webareal accounts. In Webareal, one user can manage multiple e-shops on which your add-on can be installed. In your own interface, you can offer users to quickly switch to another eshop or link eshops and bulk settings!

The login process uses the OAuth 2.0 protocol (more here). To implement login, first generate the login API credentials on the tab in the add-on details. ATTENTION! These access data are different from the access data to the Webareal API.

User login

The user is first redirected to the authentication page.

GET https://marketplace.fast-webshop.com/user-auth with parameters:

  • client_id - application ID
  • redirect_uri - URL to redirect the user back to the plugin site. It must match the address specified when creating access to the authorization API
  • response_type - with value code
  • scope - with value USER_INFO
  • state - an optional parameter containing a custom CSRF token, which allows validation of the server response, which will also contain this token

After a successful login, the user is redirected back with the following parameters:

  • code - authorization code, which will be exchanged for an access token. The validity of this code is 10 minutes.
  • state - CSRF token

Example:

 
    header('Location: https://marketplace.fast-webshop.com/user-auth?client_id=LGWQrb7CCOLR5qt8zWnTZXP&redirect_uri=https://plugin-url.tld/login&response_type=code&scope=USER_INFO&state');
 

The next step is to obtain the access token

POST https://marketplace.fast-webshop.com/api/token

  • grant_type with value authorization_code
  • client_id - application ID
  • client_secret - secret key
  • code - authorization code
  • redirect_uri - the same URL to redirect the user

The authorization server responds with a JSON object:

 
    {
        "token_type": "Bearer",
        "expires_in": 3600,
        "access_token": "...", // use to retrieve user data and call API requests
        "refresh_token": "..."
    }
 

Example:

 
    $curl = curl_init();
    curl_setopt_array($curl, array(
        CURLOPT_URL => https://marketplace.fast-webshop.com/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://plugin-url.tld/login'
        ],
    ));
    $response = curl_exec($curl);
    curl_close($curl);
    echo $response;
 
The parameters need to be written as an array (form-data), not as JSON.


Obtaining user data

The access token can now be used to query the API to retrieve data about the logged-in user.

GET https://marketplace.fast-webshop.com/api/user/about

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

The object also contains a list of the user`s eshops on which the plugin is installed.


Example:

 
    $curl = curl_init();
    curl_setopt_array($curl, array(
        CURLOPT_URL => https://marketplace.fast-webshop.com/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;
 


Access token renewal

The access token has a limited validity of 1 hour, after its expiration the refresh token can be exchanged for a new access token. The validity of the refresh token is 1 month.

POST https://marketplace.fast-webshop.com/api/token

  • grant_type with value refresh_token
  • refresh_token - previous refresh token
  • client_id - application ID
  • client_secret - application key

The authorization server returns a new access and refresh token:

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