API reference import - WEBSALE Dokumentation

The import/ endpoint provides an interface for importing data into the system. The API can be used to start, pause, resume, cancel, and query the current progress of import processes.

Supported methods

List of all supported methods.

Command/info	Endpoints	GET	PUT	POST	DELETE
Import	import/

General

Supported services and formats

The import/ endpoint provides an interface for importing data into the system. The API can be used to start, pause, resume, cancel, and query the current progress of import processes. The import function is currently supported for the following services:

Service	Supported formats
`adminUser`	`json`, `csv`
`category`	`json`, `csv`
`customerAccount`	`json`, `csv`
`dataFeed`	`json`, `csv`
`dataFeedTemplate`	`json`, `csv`
`inquiry`	`json`, `csv`, `xml`
`inventory`	`json`, `csv`
`order`	`json`, `xml`
`newsletterSubscriber`	`json`, `csv`
`product`	`json`, `csv`
`productRating`	`json`, `csv`
`seoViews`	`json`, `csv`
`voucher`	`json`, `csv`
`voucherPreset`	`json`, `csv`
`voucherTemplate`	`json`, `csv`

Methods for data import

GET import/{service}/status

This endpoint returns the current status of a running or most recently executed import process for a given service (e.g. newsletterSubscriber). The response contains detailed information about the progress, processed and erroneous data records, the start time, and — if available — the end time of the import. The status of an import process is represented by numeric values:
0 = READY
1 = STARTING
2 = RUNNING
3 = PAUSED
4 = CANCELED
5 = FINISHED
6 = ERROR These status values provide information about the current progress or result of an import. Appropriate permissions for the respective service are required for access — either write and create permissions, or an administrator account with full access.

Example

https://www.<your-shop>.de/admin/api/v1/import/newsletterSubscriber/status

Response

{
    "duration": 2,
    "end": "",
    "failed": 0,
    "globalError": 0,
    "importErrors": [],
    "lastError": "",
    "percentage": 60,
    "processed": 3,
    "start": "2025-02-19T13:31:40.000000000Z",
    "status": 2,
    "total": 5
}

Error codes


Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in or do not have the required permissions for the service.
400 Bad Request		`service` is unknown.
503 Service Unavailable	”internalError”	Redis did not return a status.

POST import/{service}/start

This endpoint starts the import process for a given service. The data to be uploaded (e.g. as JSON or CSV) is passed in the request body. If an import process is already running for the service, it is automatically canceled before the new import is started. The response immediately returns the current status of the started import. It contains information about progress, the number of processed and erroneous data records, and start/end times. The status value is returned as a numeric code according to the import definition. Write and create permissions for the respective service (e.g. newsletter) are required to start an import. Alternatively, an administrator account with full access is required.

Query parameters

Parameter	Required	Description
`format`	No	The data format of the import file (e.g. `json`, `csv`). The supported formats depend on the respective service (see section 2.1).
`sendMail`	No	Only for the `adminUser` service: controls whether an email is sent to the imported users.

Example

https://www.<your-shop>.de/admin/api/v1/import/newsletterSubscriber/start?format=json

Request body

[
    {
        "blacklisted": false,
        "createdAt": "2025-02-04T15:05:24.000Z",
        "createdBy": 0,
        "email": "subscriber@websale.de",
        "fields": {
            "firstName": "fda",
            "lastName": "fafdsa",
            "salutation": "1"
        },
        "id": 2,
        "isImport": true,
        "subshopId": "deutsch",
        "targetGroupIds": [
            1,
            2,
            3
        ]
    },
    {
        "blacklisted": true,
        "createdAt": "2025-02-04T16:06:23.000Z",
        "createdBy": 1,
        "email": "foo@example.com",
        "fields": {},
        "id": 3,
        "isImport": false,
        "subshopId": "deutsch",
        "targetGroupIds": [
            1
        ]
    },
    ...
]

Response

{
    "duration": 1,
    "end": "2025-04-28T11:55:13.000000000Z",
    "failed": 9,
    "globalError": 0,
    "importErrors": [
        {
            "errors": [
                {
                    "entryId": "",
                    "error": 0,
                    "field": "salutation"
                },
                {
                    "entryId": "",
                    "error": 0,
                    "field": "lastName"
                },
                {
                    "entryId": "",
                    "error": 0,
                    "field": "firstName"
                }
            ],
            "index": 1
        },
        {
            "errors": [
                {
                    "entryId": "",
                    "error": 0,
                    "field": "salutation"
                },
                {
                    "entryId": "",
                    "error": 0,
                    "field": "lastName"
                },
                {
                    "entryId": "",
                    "error": 0,
                    "field": "firstName"
                }
            ],
            "index": 3
        },
        ...
    ],
    "lastError": "",
    "percentage": 100,
    "processed": 12,
    "start": "2025-04-28T11:55:12.000000000Z",
    "status": 5,
    "total": 12
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in or do not have the required permissions to write or create the service’s data.
400 Bad Request		`service` is unknown. The service does not support the `format`.
503 Service Unavailable	”serviceUnavailable”	The import process could not be triggered.
503 Service Unavailable	”internalError”	Redis did not return a status. The internal `FileService` cannot be reached. Request could not be stored in a file. The status could not be updated in Redis. The import process did not start within 10 seconds.

POST import/{service}/pause

This endpoint pauses a running import process for a given service. The response contains the current status of the paused process, including processed data records, progress, and any errors. After a successful pause, the status value is set to PAUSED (3). Write and create permissions for the respective service (e.g. newsletter) are required to pause an import. Alternatively, an administrator account with full access is required.

Example

https://www.<your-shop>.de/admin/api/v1/import/newsletterSubscriber/pause

Response

{
    "duration": 0,
    "end": "",
    "failed": 0,
    "globalError": 0,
    "importErrors": [],
    "lastError": "",
    "percentage": 60,
    "processed": 3,
    "start": "2025-02-19T13:39:17.000000000Z",
    "status": 3,
    "total": 5
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in or do not have the required permissions.
400 Bad Request		`service` is unknown.
404 Not found		The process is not running or is not in the RUNNING status.
503 Service Unavailable	”internalError”	Redis did not return a status. Redis cannot be reached. The process could not be stopped.

POST import/{service}/resume

This endpoint resumes a paused import process for a given service. The response contains the current status of the resumed process, including processed data records, progress, and any errors. Write and create permissions for the respective service (e.g. newsletter) are required to resume an import. Alternatively, an administrator account with full access is required.

Example

https://www.<your-shop>.de/admin/api/v1/import/newsletterSubscriber/resume

Response

{
    "duration": 0,
    "end": "",
    "failed": 0,
    "globalError": 0,
    "importErrors": [],
    "lastError": "",
    "percentage": 60,
    "processed": 3,
    "start": "2025-02-19T13:39:17.000000000Z",
    "status": 2,
    "total": 5
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in or do not have the required permissions.
400 Bad Request		`service` is unknown.
404 Not found		The process is not in the PAUSED status.
503 Service Unavailable	”internalError”	Redis did not return a status. Redis cannot be reached. The process could not be stopped.

DELETE import/{service}/cancel

This endpoint cancels a running import process for a given service. The response contains the current status of the canceled process, including processed data records, progress, and any errors. After a successful cancel, the status value is set to CANCELED (4). Write and create permissions for the respective service (e.g. newsletter) are required to cancel an import. Alternatively, an administrator account with full access is required.

Example

https://www.<your-shop>.de/admin/api/v1/import/newsletterSubscriber/cancel

Response

{
    "duration": 2,
    "end": "2025-02-19T13:39:19.000000000Z",
    "failed": 0,
    "globalError": 0,
    "importErrors": [],
    "lastError": "",
    "percentage": 60,
    "processed": 3,
    "start": "2025-02-19T13:39:17.000000000Z",
    "status": 4,
    "total": 5
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in or do not have the required permissions.
400 Bad Request		`service` is unknown.
404 Not found		The process is not running or is not in a cancelable status (RUNNING, STARTING, or PAUSED).
503 Service Unavailable	”internalError”	Redis did not return a status. Redis cannot be reached. The process could not be stopped.

Support

Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: Zum Kundenportal Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.

​Supported methods

​General

​Supported services and formats

​Methods for data import

​GET import/{service}/status

​Example

​Response

​Error codes

​POST import/{service}/start

​Query parameters

​Example

​Request body

​Response

​Error codes

​POST import/{service}/pause

​Example

​Response

​Error codes

​POST import/{service}/resume

​Example

​Response

​Error codes

​DELETE import/{service}/cancel

​Example

​Response

​Error codes

​Support

Supported methods

General

Supported services and formats

Methods for data import

GET import/{service}/status

Example

Response

Error codes

POST import/{service}/start

Query parameters

Example

Request body

Response

Error codes

POST import/{service}/pause

Example

Response

Error codes

POST import/{service}/resume

Example

Response

Error codes

DELETE import/{service}/cancel

Example

Response

Error codes

Support