In the following section, we assume that you have set up a partner e-shop and that you are an approved Shoptet API partner. For example partner e-shop URL shall be https://12345.myshoptet.com.
OAuth Access Token
This string represents each individual installation of your addon at the e-shop and it is necessary to gain an API access token. It is therefore unique for each e-shop and addon. It has an unlimited duration. 255 characters long. The OAuth Access Token must not leave the backend developer. Do not send it to the e-shop operator, to backend, or in an e-mail.
code
String sent as a GET parameter to your URL, which was entered in the addon settings. Time limited validity.
API access token
String to access the Shoptet API. Time limited validity of 30 minutes. 255 characters long. You can gain an API access token by calling the authorized requirement on the OAuth server. Authorization is carried out using the OAuth Access Token, which you get from the process of installing the addon using the e-shop. A maximum of 5 simultaneously valid API access tokens (per single OAuth Access Token) can be requested.
For each individual installation of the addon, you need to gain an OAuth Access Token value and securely save it in your data structures. The OAuth Access Token therefore uniquely identifies the e-shop and the addon. The OAuth Access Token is only acquired once for each e-shop and addon during installation.
Process of obtaining the API access token:
code GET parameter. The URL, to which these requests with the code are to be sent, is entered in the addon settings. (Partner e-shop Administration → Connections → API Partner → Addons tab). URLs with 80, 8080, 443, and 8443 ports are permitted.
Use the code value to authorize you with the OAuth server. In response, you will receive an OAuth Access Token to be used to get the API access tokens.
Attention: The HTTP status of your server’s response to the code request if installation is successful must be 200. If your server does not respond with status 200, we consider the installation process to have been unsuccessful.
Installation calls from Shoptet will only be sent from IP addresses 78.24.15.64/26 or 93.185.110.117/28.
In the addon detail (Partner e-shop administration → Connections → API Partner → Addons tab) in the Settings tab, you enter the URL in Your URL to receive OAuth code, for which you expect the request with code, for example: https://www.my-server.com/shoptet-installation
When you install the addon, you will then receive an HTTP GET request for the specified url with the code parameter: https://www.my-server.com/shoptet-installation?code=21cc615b4a01067a75713dd1396057bf96bd925c
Once the code parameter is obtained, you authorize on the OAuth server API and get 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"
}
In $response is the access_token, to be used to authorize yourself to gain api tokens.
$response = json_decode($response, TRUE);
echo "oAuth access token: " . $response['access_token'];
$oAuthAccessToken = $response['access_token'];
Save the value of the $oAuthAccessToken, which is unique for each installation of the addon. By acquiring and saving the OAuth Access Token, the installation process is over.
If you can save the OAuth Access Token, respond to the HTTP request 200 OK. In the default PHP setting, you should be able to exit the script without setting a value.
The EshopId, eshopUrl and contactEmail items are the basic information about the e-shop, which is installed by the addon. For more information, please refer to the E-shop Info endpoint; see also “E-shop identity” below. However, if the installation should fail, you have at least some basic information that you can use to complete the installation later, or contact the customer.
Basic examples of an installation script
We consider the installation of the addon to have been unsuccessful, if upon a request with the code:
For testing purposes, the installation process can be called up in the detail of a specific addon in the Users tab. This allows you to test the installation process and the addon on your partner e-shop.
The new client will call the installation procedure anonymously (you will receive the basic information about the e-shop being installed with the OAuth Token). It is necessary to take the key and store it safely, and then identify the identity of the e-shop (OAuth Access Token and short-term API access tokens are clearly linked to one particular e-shop).
Common practice is to request API access token during the installation, and call E-shop Info endpoint. You can save the OAuth Access Token together with the number of the e-shop (data.contactInformation.eshopId), or the URL of the e-shop (data.contactInformation.url), contact e-mail, etc.
It is recommended that the installation routine does not execute more than one activity, in order for it to take as short a time as possible, and to minimize the risk of error. Ideally, simply obtain the OAuth Access Token, save it safely, and exit the installation script. You then obtain and complete the e-shop identification asynchronously. Do not send an email as part of the installation script, because it could significantly increase the installation runtime. This is annoying for the user and if it lasts for a longer period (5 seconds), we would end the installation as unsuccessful anyway.
You need to consider the case, when the e-shop operator uninstalls the addon, but after some time he decides to reinstall the addon. Without any processing, you may experience problems with duplicate accounts when you install the addon again. See more in article Uninstalling the addon.