Shoptet API SDK PHP

The official PHP library for the Shoptet REST API.

Documentation

See the Shoptet API doc.

Requirements

• PHP 8.3 and later

Dependencies

SDK require the following extensions and libraries in order to work properly:

• curl - You can use your own non-cURL client if you prefer.
• json
• psr/log

If you use Composer, these dependencies should be handled automatically.

If you install the library manually, please ensure that these extensions are available.

Installation

Composer

You can install the sdk via Composer. Run the following command:

@todo Currently not working as it's not public

composer require shoptet/api-sdk-php

To use the sdk, use Composer's autoload:

require_once 'vendor/autoload.php';

Manual

require_once '/path/to/api-sdk-php/init.php';

Getting Started

Simple usage

Authorization

For authorization, you need to set the partner domain URL and the token.

\Shoptet\Api\Sdk\Php\Sdk::setPartnerDomainUrl('https://partner-eshop.myshoptet.com');
\Shoptet\Api\Sdk\Php\Sdk::authorizeRequest('token-for-target-eshop');

If token does not exist or is expired, you will need to obtain it first. For Obtaining a fresh public API token, you need to have the OAuth token for the eshop. See how to get access token for more information.

// Set partner domain URL for obtaining fresh public API token
\Shoptet\Api\Sdk\Php\Sdk::setPartnerDomainUrl('https://partner-eshop.myshoptet.com');

try {
    // Try to authorize request with token for some eshop
    \Shoptet\Api\Sdk\Php\Sdk::authorizeRequest('token-for-target-eshop');
} catch (TokenHasExpiredException | TokenNotFoundException) {
    // If token has expired or not found, create fresh public API token with specific OAuth token for eshop.
    \Shoptet\Api\Sdk\Php\Sdk::createFreshPublicApiToken('token-for-target-eshop', 'oauth-token-for-target-eshop');
    // Try to authorize request again with fresh public API token
    \Shoptet\Api\Sdk\Php\Sdk::authorizeRequest('token-for-target-eshop');
}

You can obtain oAuth access token after addon is installed in the eshop and you receive installation callback request. See how to process addon installation for more information.

// Set partner domain URL for obtaining fresh public API token
\Shoptet\Api\Sdk\Php\Sdk::setPartnerDomainUrl('https://partner-eshop.myshoptet.com');

$requestData = new \Shoptet\Api\Sdk\Php\Endpoint\OAuth\CreateOauthAccessToken\CreateOauthAccessTokenRequestData([
'client_id' => 'some-client-id',
'client_secret' => 'some-client-secret',
'redirect_uri' => 'https://partner-redirect-domain.com/after/authorize',
'code' => 'fdqmcvw0b89p3xv31j7w....', // use code from request
]);

$authorizationFacade = \Shoptet\Api\Sdk\Php\Sdk::createAuthorizationFacade();
// obtain and store new OAuth token
$authorizationFacade->addonInstallationCallback('oauth-token-for-target-eshop', $requestData);

For storing tokens, there is in default basic implementation used FileTokenStorage which stores tokens in the file system. Default path for storing tokens is:

protected const string DEFAULT_FILE_STORAGE_PATH = '/tmp/shoptet-api';

This implementation is not recommended for production use. You should implement your own token storage which implements TokenStorage interface.

\Shoptet\Api\Sdk\Php\Sdk::setTokenStorage(new MyTokenStorage());

Call endpoint with request body

\Shoptet\Api\Sdk\Php\Sdk::setPartnerDomainUrl('https://partner-eshop.myshoptet.com');
\Shoptet\Api\Sdk\Php\Sdk::authorizeRequest('token-for-target-eshop');

$createdBrandResponse = \Shoptet\Api\Sdk\Php\Sdk::createBrand([
    'data' => [
        'name' => 'Brand name',
        'description' => 'Brand description',
        'indexName' => 'brand-name',
    ]
]);

$createdBrandResponse->getBody();
//...

Read more about possible methods, how to call endpoints with request body.

Paginator

\Shoptet\Api\Sdk\Php\Sdk::setPartnerDomainUrl('https://partner-eshop.myshoptet.com');
\Shoptet\Api\Sdk\Php\Sdk::authorizeRequest('token-for-target-eshop');

$listOfProductResponse = \Shoptet\Api\Sdk\Php\Sdk::getListOfProducts();
//... Process response
try {
    $listOfProductResponseNextPage = $listOfProductResponse->getNextPage();
} catch (\Shoptet\Api\Sdk\Php\Exception\OutOfRangeException $e) {
    //Next page is out of range - Last page already reached
}

Custom header

// Add/remove custom header
\Shoptet\Api\Sdk\Php\Sdk::setHeader('X-MY-AWESOME-HEADER', 'my-awesome-header-value');
\Shoptet\Api\Sdk\Php\Sdk::unsetHeader('X-MY-AWESOME-HEADER');

Custom request timeouts

$httpClient = \Shoptet\Api\Sdk\Php\Sdk::getHttpClient();

/**
 * Set connection timeout on 60sec
 * Default is 30sec
 * @see \Shoptet\Api\Sdk\Php\HttpClient\CurlClient::DEFAULT_TIMEOUT
 */
$httpClient->setTimeout(60);

/**
 * Set timeout on 90sec
 * Default is 80sec
 * @see \Shoptet\Api\Sdk\Php\HttpClient\CurlClient::DEFAULT_CONNECT_TIMEOUT
 */
$httpClient->setConnectTimeout(90);

echo $httpClient->getTimeout(); // 60
echo $httpClient->getConnectTimeout(); // 90

Custom cURL options

You can customize the default CurlClient with extra options. The keys should be valid CURLOPT_* constants or their integer equivalents. The options will be used in curl_setopt_array().

// Add/remove custom option in HttpClient
\Shoptet\Api\Sdk\Php\Sdk::getHttpClient()
    ->addOption(CURLOPT_PROXY, 'my-proxy.local:80');
    ->removeOption(CURLOPT_PROXY);

Response body type

The SDK provides multiple options how to handle response body automatically.

• Return response body as the corresponding Entity object
  • Factory class: \Shoptet\Api\Sdk\Php\Factory\Response\EntityResponseFactory
  • Default option
• Return response body as array
  • Factory class: \Shoptet\Api\Sdk\Php\Factory\Response\ArrayResponseFactory
• Return response body as raw string
  • Factory class: \Shoptet\Api\Sdk\Php\Factory\Response\RawResponseFactory

echo get_class(\Shoptet\Api\Sdk\Php\Sdk::getEshopInfo()->getBody()); // Shoptet\Api\Sdk\Php\Endpoint\Eshop\GetEshopInfoResponse\GetEshopInfoResponse

// Set response factory to ArrayResponseFactory so the response body will return as array (not the Entity)
\Shoptet\Api\Sdk\Php\Sdk::getHttpClient()->setResponseFactory(new \Shoptet\Api\Sdk\Php\Factory\Response\ArrayResponseFactory());

echo gettype(\Shoptet\Api\Sdk\Php\Sdk::getEshopInfo()->getBody()); // array

Custom HttpClient

If current HttpClient is not sufficient you can implement your own Client. The client must implement \Shoptet\Api\Sdk\Php\HttpClient\ClientInterface.

\Shoptet\Api\Sdk\Php\Sdk::setHttpClient($httpClient);

Logger

The library does minimal logging. Logging can be configured with a PSR-3 compatible logger. Default Logger is the Psr\Log\NullLogger - So the logs end up in the void.

\Shoptet\Api\Sdk\Php\Sdk::setLogger($logger);

Exceptions

All exceptions should implement Shoptet\Api\Sdk\Php\Exception\Exception.

There are 3 base types of Exceptions:

• Shoptet\Api\Sdk\Php\Exception\LogicException
• Shoptet\Api\Sdk\Php\Exception\RuntimeException
• Shoptet\Api\Sdk\Php\Exception\ReflectionException