REST API

Here you will find everything you need to get started with our REST API.

Authentication

The authentication runs via an API token which you can create in our software under API Tokens. This token is a JSON Web Token, therefore it contains some information for you in the payload, which will be explained in more detail.

For each of our services e. g. Amazon DE and Amazon UK you need a separate API token. You can also have several API tokens per service, e. g. one for your ERP system and another for an Excel plugin. We recommend that you give each token a unique name, which you can find in the payload of the token.

Each API token has a limited lifetime, usually one year. Once your token has expired, you can create a new API token under API Tokens. The expiration date of the token is specified in the payload under exp as Unix time and can therefore be checked by yourself.

The token is transmitted for authentication in the request header as follows Authorization: Bearer.

First steps

Now that you have your token, you can take your first steps with our API. Using our API Swagger we can make your first steps together in the SWAGGER UI.

Within our Swagger UI you can select the appropriate API endpoint at the top right under Select a definition.

swagger-ui

If you have opened the SWAGGER UI, please click on Authorize and enter your API token under Value:. Make sure that you place the word Bearer with a space in front of the token.

Once you have deposited your token, navigate to Repricing Item if you are using our RePricing for Amazon API or to Item if you are using our RePricing for eBay API. Click on /item and then click try it out. For the beginning, we skip all great filter and sorting possibilities and scroll down to the Execute button. By clicking on this button, you have successfully executed your first API request!

From now on, I recommend that you spend a few minutes with SWAGGER UI, which not only provides you with a graphical user interface for our API, but also contains documentation on all endpoints including all request and response models.

Request Limits

Our API also uses request limits, how to get in touch with these restrictions as little as possible is explained in the Best practices section.

The limit for the corresponding endpoint and the remaining requests are reported in the response header. X-RateLimit-Limit specifies how many requests can be executed at the endpoint per hour. The available queries are contained in the X-RateLimit-Remaining header.

The following response to the request shown below contains the two headers described above.

$ curl -X GET -i "https://api.esagu.de/amzn/repricing/v1/price-gaps" -H "accept: application/json" -H "Authorization: Bearer "

HTTP/1.1 200 OK
Server: nginx
Date: Tue, 28 Nov 2017 12:25:29 GMT
Content-Type: application/json;charset=utf-8
Content-Length: 3809
Connection: keep-alive
X-RateLimit-Limit: Requests per hour: 120
X-RateLimit-Remaining: Remaining requests: 117
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: X-Requested-With, Content-Type, Accept, Origin, Authorization
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS

[{"id":3278,"inserted":"2015-12-18T13:18:00+00:00","updated":"2016-02-16T13:22:53+00:00","name":"Gleichziehen","isDefaultMFN":false,"isDefaultFBA":false,"shippingIncluded":true,"priceGaps":[{"gap":0,"mode":"ABSOLUTE"}]}]

Here is an example of a response when the request limit has been exceeded.

HTTP/1.1 503 Service Unavailable
Server: nginx
Date: Tue, 28 Nov 2017 13:57:11 GMT
Content-Type: application/json;charset=utf-8
Content-Length: 76
Connection: keep-alive

{"message":"Rate limit, of \"120\" requests per hour, exceeded.","code":503}

Best practices

Get item data / Pagination

Our RePricing for Amazon or eBay APIs return up to 100 articles at a time via the endpoint /item. The query parameters limit and offset can be used to retrieve the next "page" as in a SQL database. However, our API responds much faster if you omit the offset parameter and use by-id-greater-than instead. To do this, the article ID (id) of the last article from the previously loaded page is used as its value. By default, sorting is in ascending order by our internal article ID (id).

The number of all articles corresponding to the query parameters used for the query is displayed in the X-total-count response header if the query parameter count-items with the value true was used for the request. For performance reasons, this should only be used when fetching the first page, since this value will not change when further pages are requested.

If you don't need all the data that the API provides, such as the list of competitors, it is always the quicker way to request a csv file via our API.

Edit item data

Via the end point /item/{itemId}/strategy article data such as price settings can be edited, also here the request limits apply. So if you want to edit several thousand articles at once, a CSV import via our API is often the faster way. Alternatively, a bulk edit (EasyEdit e²) can also be executed via the API of our ebay RePricing.

Generate API client code

We at eSagu can't handle all programming languages, but thanks to Swagger you can generate an API client for your preferred programming language.

Für PHP gibt es die API Clients für unser Amazon und ebay RePricing auf GitHub zum download. Diese können über composer require e-sagu/e-bay-re-pricing-api-client-php bzw. composer require e-sagu/amzn-re-pricing-api-client-php einfach installiert werden.

You will need to install Swagger Codegen, as described in this installation guide. Or you can execute the following command wget https://oss.sonatype.org/content/repositories/releases/io/swagger/swagger-codegen-cli/2.2.1/swagger-codegen-cli-2.2.1.jar.

Calling Swagger Codegen without further parameters java -jar swagger-codegen-cli-2.2.1.jar returns a list of available languages.

Available languages: [android, aspnet5, async-scala, cwiki, csharp, cpprest, dart, flash, python-flask, go, groovy, java, jaxrs, jaxrs-cxf, jaxrs-resteasy, jaxrs-spec, inflector, javascript, javascript-closure-angular, jmeter, nancyfx, nodejs-server, objc, perl, php, python, qt5cpp, ruby, scala, scalatra, silex-PHP, sinatra, rails5, slim, spring, dynamic-html, html, html2, swagger, swagger-yaml, swift, tizen, typescript-angular2, typescript-angular, typescript-node, typescript-fetch, akka-scala, CsharpDotNet2, clojure, haskell, lumen, go-server]

Somewhat hidden is also the help for this command line application: java -jar swagger-codegen-cli-2.2.1.jar help generate.

For example, if we want to use an API client for PHP, try the following call java -jar swagger-codegen-cli-2.2.1.jar generate -i https://api.esagu.de/ebay/repricing/v1/swagger.json --invoker-package "eSagu\RePricing\V1" --api-package "eSagu\RePricing\V1\Api" --model-package "eSagu\RePricing\V1\Model" -l php -o ./src/. Which creates an ebay Repricing API client for PHP within the following namespace eSagu\RePricing\V1 and in the src/ directory.

The newly generated PHP client can be tried out, as in the following example, which loads and outputs the global settings.

require_once(__DIR__ . '/vendor/autoload.php');

eSagu\RePricing\V1\Configuration::getDefaultConfiguration()->setApiKey('Authorization', 'YOUR_API_KEY');
eSagu\RePricing\V1\Configuration::getDefaultConfiguration()->setApiKeyPrefix('Authorization', 'Bearer');

try {
 $settingsApi = new eSagu\RePricing\V1\Api\SettingsApi();
 print_r($settingsApi->get());
} catch (Exception $e) {
 echo 'Exception when calling SettingsApi->get: ', $e->getMessage(), PHP_EOL;
}

Examples

Below are some examples for using our APIs. The examples are written in PHP and use one of our two API clients, which can be installed via the PHP Composer: composer require e-sagu/e-bay-re-pricing-api-client-php or composer require e-sagu/amzn-re-pricing-api-client-php

Disable/activate price uploads

Relatively practice near, at night at 3 o' clock our e. g. ERP always makes a great update and we don't want to price uploads from eSagu to Amazon during this time.

require_once(__DIR__ . '/../vendor/autoload.php');

// Configure API key authorization: jwt
eSagu\Amzn\RePricing\V1\Configuration::getDefaultConfiguration()->setApiKey('Authorization', JWT_API_TOKEN);
eSagu\Amzn\RePricing\V1\Configuration::getDefaultConfiguration()->setApiKeyPrefix('Authorization', 'Bearer');

$repricingSettingsApi = new eSagu\Amzn\RePricing\V1\Api\RepricingSettingsApi();

try {
 $settings = $repricingSettingsApi->get();
 $settings->setUploadEnabled(!$settings->getUploadEnabled());

 $repricingSettingsApi->put($settings);

 echo "Upload enabled has been set to \"{$settings->getUploadEnabled()}\".", PHP_EOL;
} catch (Exception $e) {
 echo $e->getMessage(), PHP_EOL;
}

Adjust price settings

In the following example, the price ranges are adjusted for all items on eBay that match the search term "FIFA". Our API always quotes and transfers prices in cents, 2995 is equivalent to € 29.95.

use eSagu\EBay\RePricing\V1\Model\RepricingItemPriceSettingsDTO;

require_once(__DIR__ . '/../vendor/autoload.php');

// Configure API key authorization: jwt
eSagu\EBay\RePricing\V1\Configuration::getDefaultConfiguration()->setApiKey('Authorization', JWT_API_TOKEN);
eSagu\EBay\RePricing\V1\Configuration::getDefaultConfiguration()->setApiKeyPrefix('Authorization', 'Bearer');

$itemApi = new eSagu\EBay\RePricing\V1\Api\ItemApi();
$itemStrategyApi = new eSagu\EBay\RePricing\V1\Api\ItemStrategyApi();

try {
 $items = $itemApi->callList(null, null, null, null, 'FIFA');

 foreach ($items as $item) {
 $itemPriceSettings = $item->getStrategy()->getPriceSettings();
 $itemPriceSettings->setMinPrice(2995);
 $itemPriceSettings->setFixedPrice((int)(2995 + 4995) / 2);
 $itemPriceSettings->setMaxPrice(4995);
 $itemPriceSettings->setMode(RepricingItemPriceSettingsDTO::MODE_OPTIMIZATION_BEST_VISIBILITY)

 $itemStrategyApi->put($item->getId(), $item->getStrategy());

 echo "Updated item with id \"{$item->getId()}\"", PHP_EOL;
 }

} catch (Exception $e) {
 echo $e->getMessage(), PHP_EOL;
}

Request a CSV file

In the following example we request a CSV file and wait until it has the status DONE to download it.

use eSagu\Amzn\RePricing\V1\Model\RepricingCSVRequestDTO;

require_once(__DIR__ . '/../vendor/autoload.php');

// Configure API key authorization: jwt
eSagu\Amzn\RePricing\V1\Configuration::getDefaultConfiguration()->setApiKey('Authorization', JWT_API_TOKEN);
eSagu\Amzn\RePricing\V1\Configuration::getDefaultConfiguration()->setApiKeyPrefix('Authorization', 'Bearer');

$csvExportAPI = new \eSagu\Amzn\RePricing\V1\Api\RepricingCSVRequestApi();

try {
 $repricingCsvExport = (new RepricingCSVRequestDTO())
 ->setFields([
 RepricingCSVRequestDTO::FIELDS_SKU,
 RepricingCSVRequestDTO::FIELDS_ESAGU_ITEM_ID,
 RepricingCSVRequestDTO::FIELDS_MIN_PRICE,
 RepricingCSVRequestDTO::FIELDS_MAX_PRICE,
 RepricingCSVRequestDTO::FIELDS_FIXED_PRICE,
 RepricingCSVRequestDTO::FIELDS_PRICE_MODE
 ])
 ->setNumberFormat(RepricingCSVRequestDTO::NUMBER_FORMAT_CENTS);

 list($response, $statusCode, $httpHeader) = $csvExportAPI->postWithHttpInfo($repricingCsvExport);
 $csvRequestId = (int)basename($httpHeader['Location']);

 echo "The CSV request id is: $csvRequestId", PHP_EOL;

 while (true) {
 sleep(60);

 $csvExport = $csvExportAPI->get($csvRequestId);

 if ($csvExport->getState() === RepricingCSVRequestDTO::STATE_DONE) {
 file_put_contents('/tmp/esagu-amzn-repricing.csv', fopen($csvExport->getCsvDownloadUrl(), 'r'));
 echo 'The CSV has been generated and downloaded to /tmp/esagu-amzn-repricing.csv', PHP_EOL;

 break;
 }
 }

} catch (Exception $e) {
 echo $e->getMessage(), PHP_EOL;
}

Thank you for reading up to here. I hope these few words could make it easier for you to get started with our API.

And have a look at our frequently asked questions.