General

This documentation describes the transfer method of the REST interface for the import of

• Product and category data

• Customer data

• Voucher data

SFTP transfer

The import files themselves must first be transferred to the shop server via SFTP. For this purpose you will receive a common SFTP account for product, customer and voucher data from WEBSALE AG.

Import of product data

Transfer the import files to the "directimport" subdirectory on the shop server and to corresponding subdirectories.

Example for the PRD file "100721.prd" located in the directory "Deutsch_184.prd" of the subshop directory "Deutsch":
../directimport/Deutsch/Deutsch_184.prd/100721.prd

Then start the import via the REST interface. If the directory does not exist, then you need to create it. As "scope" (see below) "products" is sent. Format and content of the import files are described in the documentation

Format and content - WS-SFTP-Produkte PRO (EN)

Import of customer data

Transfer the import files to the "customerimport" subdirectory on the shop server and then start the import using the REST interface. If the directory does not exist, then you need to create it. "customers" is sent as the "scope" (see below). Format and content of the import files are described in the documentation

Format and content - WS-SFTP-Kunden PRO (EN)

Import of voucher data

Transfer the import files to the "voucherimport" subdirectory on the shop server and then start the import via the REST interface. As "scope" (see below) "vouchers" is sent. Format and content of the import files are described in the documentation

Format and content - WS-SFTP-Gutscheindaten (to-Shop) (EN)

Authentication

Authentication for the functions of this API is done by a "Web Token", which must be passed in the HTTP header for each call.

To obtain this token, you must authenticate with the following call:

Action: POST
URL: https://www.websale.de/api/authent/login/<shop-ID>
Request-Body: login ID and password as JSON object
Example:

If successful, the response to this request will contain a JSON object with the required token:

This token must be sent with all following calls in the HTTP header:
X-Authorization: Bearer TOKEN

Starting the import (start)

The command "start" starts the import and returns an import ID which can be used to query the status of the import afterwards.

Action: POST
URL: https://www.websale.de/api/import/start
The following parameter is passed in the body as JSON object:

Example request body:

Example response:

If successful, the function returns a JSON object with the import ID needed to query the import status.

The fact that the import was started successfully does not mean that data was also imported successfully. The start of the import is asynchronous, i.e. the REST function returns before the import has completed. Whether the import data was successfully processed cannot be determined at this point.

Query import status (status)

This command allows to query whether the import process is still running, how far it has progressed and what result (successful/cancelled) the import had.

Action: GET
URL: https://www.websale.de/api/import/status/<Import-ID>
In case of success, the status information is transmitted as a JSON object in the body of the response.

Fields that will be returned in any case:

Fields that are only returned when the import is finished:

Example 1:

Example 2:

Error handling

Authentication error

Error when starting the import or requesting the status

In addition to the HTTP status code, a JSON object with further information about the error can be sent with these errors in the body.

Example for additional information in the body of the response:

"error" contains an "error code" intended for evaluation by the calling program. There can be several "error" codes for one HTTP status code.

"detail" contains an error message that is slightly more verbose than "error" and is intended for a human reader.

"paramErrors" is a special parameter that is returned only for the "invalidParams" error. The value of the parameter is an object, each field inside this object corresponds to an invalid parameter sent to the REST interface. For each field there can be multiple errors, therefore the value of this field is an array. Each entry of the array has at least the "kind" field, which indicates the type of error. Depending on the "kind", there may be other fields with additional information about the error.

Errors returned by the "status" function

General remarks about "errors" and "warnings

(Serious) errors mean that there is no other option than to cancel the import or it cannot be started at all.
Such a case exists, for example, if the column with the required field "ProdIndex" is completely missing in a product import file.
(Minor) errors lead to the fact that individual data records cannot be imported.

This happens, for example, if the "ProdIndex" column is present in a product import file, but does not contain a value for individual products.
In this case, too, there would in principle be good arguments for canceling the import and not importing the data at all, after all the result of the import will obviously not correspond to the intended result. However, experience has shown that for most customers it is more important that the import goes through than that 100% of all products/customers have been imported.

Warnings occur when import data does not match the specification, but the import still interprets and reads it correctly with high probability.

Example: The value "0.99" is imported as the product price. This value does not correspond to the specification because a comma is used as decimal separator instead of a point. In this case, the import will replace the comma with a period and log a warning.

Error during customer data import:

Data import from different systems

In principle it is possible to import e.g. product data from one system and customer data from another system. However, it must be ensured that transfer and import do not take place simultaneously. Any attempt to start an import while another import is already running will result in an "EI002 Import already running" error.

More critical than the start of the import is the transfer of the data, since this is done via SFTP and no separation of the import directories for different systems is provided. The fact that the transfer is done via SFTP means that a simultaneous transfer from different systems cannot be prevented by the import software.

That the import directories are not separated means that one system may start importing data that another system has transferred.

URL

The current base URL for calling the REST interface for import is

https://www.websale.de/api/...

The URL may change in the future, so make sure it can be changed at your end without too much effort.