Skip to main content

Installing the addon

In the following section, we assume that you have already set up a partner e-shop and have been approved as a Shoptet API partner. For the purposes of this example, the partner e-shop URL will be https://12345.myshoptet.com.

Used terms​

OAuth Access Token
A unique string representing each individual installation of your add-on in an e-shop. It is required to obtain an API access token. It has unlimited validity and is 255 characters long.

code
A string sent as a GET parameter to your specified URL (as set in the add-on settings). It has limited-time validity.

API access token
A string used to access the Shoptet API. It has limited-time validity and its length ranges from 38 to 60 characters. You can obtain an API access token by making an authorized request to the OAuth server. This authorization is carried out using the OAuth access token, which you receive during the add-on installation process by the e-shop.

How to obtain an OAuth access token​

For each individual installation of the addon, you need to obtain an OAuth Access Token and securely store it in your data structures. The OAuth Access Token uniquely identifies both the e-shop and the addon. It is acquired only once for each e-shop and addon during installation.

Process of obtaining the API Access Token:

  • When installing the e-shop, you will receive an HTTP request containing a code GET parameter. The URL to which these requests with the code are sent is specified in the addon settings (Partner e-shop Administration → Connections → API Partner → Addons tab). URLs with ports 80, 8080, 443, and 8443 are permitted.

  • Use the code value to authorize with the OAuth server. In response, you will receive an OAuth Access Token, which is then used to retrieve the API access tokens.

note

Attention: Your server must respond with HTTP status 200 to the code request if the installation is successful. If your server does not respond with status 200, we consider the installation process to have failed.

Installation calls from Shoptet will only be sent from the IP ranges 185.184.254.0/24.

An example of obtaining the OAuth Access Token in PHP​

In the addon detail (Partner e-shop Administration → Connections → API Partner → Addons tab), under the Settings tab, enter the URL in the Your URL to receive OAuth code field. This is the URL where you expect to receive the request containing the code parameter — for example: https://www.my-server.com/shoptet-installation

When you install the addon, your server will receive an HTTP GET request to the specified URL with the code parameter, for example: https://www.my-server.com/shoptet-installation?code=21cc615b4a01067a75713dd1396057bf96bd925c

Once you have obtained the code parameter, use it to authorize with the OAuth server API and retrieve the OAuth Access Token.

// Your client ID in the OAuth server
// This is an example only. For a specific value,
// refer to Partner e-shop administration -> Connections -> API partner -> Access to API
$clientId = 'ae5d72b8964a08ed';

// Your secret string for communicating with the OAuth server
// If, in Partner e-shop administration -> Connections -> API partner -> Access to API,
// you do not see the value, clientSecret has not been activated (older API partners),
// so do not send it in communication // with OAuth server
$clientSecret = 'dqwffewfsgdrgwefsfgdtjtkyodg';

// URL for authorization vs. OAuth server
// This is an example only. For a specific value,
// refer to Partner e-shop administration -> Connections -> API partner -> Access to API
$oAuthServerTokenUrl = 'https://12345.myshoptet.com/action/ApiOAuthServer/token';

// Received value of code
$code = $_GET['code'];

// OAuth server authorization type, always enter 'authorization_code'
$grantType = 'authorization_code';

// OAuth server rights group, always enter 'api'
$scope = 'api';

// URL entered on the addon settings page that you expect a request with the parameter 'code' for example:
$redirectUri = 'https://www.my-server.com/shoptet-installation';

// Sending the request to get secret_token
$data = [
    'client_id' => $clientId,
    'client_secret' => $clientSecret, // Enter only if set for you
    '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, json_encode($data));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_HTTPHEADER, ['Content-type: application/json']);
$response = curl_exec($curl);
curl_close($curl);

The response $response is in JSON format:

{
   "access_token":"5wty54dv2y5jxaj9lu2glnb6upv2z7a6b3v92xsy06wfaeygmcfa3alg2gx2rdp8ozjqytb3l4eqfub4nbnbm7somfgup58wf6jjjstwyvdtp3kjmh08nhskl0z06qyso27l0q6op5udooofq15zhq7w3h1k4b6jj0j4o83hyar2fu9847e802t56xa87v81lblzed5kgvutjzrp3afvpsefit304q6g3pat0m09pzbd5iyu0qk55zwu6a31sq9",
   "expires_in": null,
   "token_type": "Bearer",
   "scope": "api",
   "eshopId": 222651,
   "eshopUrl": "https:\/\/12345.myshoptet.com\/",
   "contactEmail": "customer@example.com"
}

The $response contains the access_token, which is used to authorize yourself and obtain API tokens.

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

Save the value of $oAuthAccessToken, which is unique for each addon installation. Once you acquire and store the OAuth Access Token, the installation process is complete.

If you are able to save the OAuth Access Token, respond to the HTTP request with 200 OK. In the default PHP configuration, you should be able to exit the script without setting a return value manually.

The EshopId, eshopUrl, and contactEmail fields contain the basic information about the e-shop where the addon is being installed. For more details, refer to the E-shop info endpoint (see also the E-shop identity section below). However, if the installation fails, you still have some basic data that may help you complete the installation later or contact the customer.

Basic examples of an installation script:

Unsuccessful installation​

We consider the installation of the addon to have been unsuccessful, if upon a request with the code:

  • You respond after more than 5 seconds.
  • If you respond with an HTTP code other than 200

Testing the installation​

For testing purposes, the installation process can be triggered from the Users tab in the detail of a specific addon. This allows you to test both the installation process and the addon itself on your partner e-shop.

Identity of an e-shop​

A new client initiates the installation process anonymously (you receive basic information about the e-shop being installed along with the OAuth Access Token). It is essential to extract this key information and store it securely. The OAuth Access Token and short-term API access tokens are always linked to a specific e-shop, which allows you to identify it reliably.

A common practice during installation is to request an API access token and call the E-shop info endpoint. You can then store the OAuth Access Token together with the e-shop’s ID (data.contactInformation.eshopId), URL (data.contactInformation.url), contact email, and other relevant details.

It is recommended that the installation routine performs only a single action to keep the duration as short as possible and minimize the risk of errors. Ideally, you should just obtain the OAuth Access Token, store it securely, and exit the installation script. The e-shop identification and any further processing should be handled asynchronously.

Do not send an email as part of the installation script, as this could significantly increase the execution time. This degrades the user experience, and if the installation takes longer than 5 seconds, we will consider it unsuccessful.

Reinstalling​

You must also account for the case where the e-shop operator uninstalls the addon and later decides to reinstall it. Without proper handling, this may lead to issues such as duplicate accounts or conflicting data. For more information, refer to the article Uninstalling the Addon.

Pausing/resuming the add-ons​

In rare cases, an OAuth Access Token can be paused, which is a condition where the add-on remains installed and billing continues, but API requests are rejected. Here you can find more information about pausing/resuming the add-ons.