API-Referenz Import

Der Endpunkt import/ stellt eine Schnittstelle für den Import von Daten in das System bereit. Über die API können Importvorgänge gestartet, pausiert, fortgesetzt, abgebrochen und der aktuelle Fortschritt abgefragt werden.

Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	GET	PUT	POST	DELETE
Import	import/

Allgemein

Unterstützte Services und Formate

Service	Unterstützte Formate
`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`, `zip`
`newsletterSubscriber`	`json`, `csv`
`product`	`json`, `csv`
`productRating`	`json`, `csv`
`seoViews`	`json`, `csv`
`text`	`json`, `xml`, `csv`
`voucher`	`json`, `csv`
`voucherPreset`	`json`, `csv`
`voucherTemplate`	`json`, `csv`

Das Format zip steht nur für den Service order zur Verfügung. Die ZIP-Datei darf ausschließlich Bestellungen aus WEBSALE 8 als einzelne .ord-Dateien, eine Datei pro Bestellung, enthalten. Informationen zur Übernahme von Bestellungen aus WEBSALE 8 finden Sie unter Daten-Migration.

Verhalten einzelner Services

Für einige Services gelten beim Import besondere Regeln:

Service	Verhalten
`product`	Jede Variante benötigt eine ID. Zeilen ohne ID werden bereits beim Einlesen abgewiesen. Ist eine ID bereits vergeben, wird der Datensatz als doppelter Eintrag gemeldet. Varianten können auch zu Produkten importiert werden, die bereits im Shop vorhanden sind.
`inventory`	Felder, die eine Zeile nicht enthält, behalten ihren gespeicherten Wert. Fehlt beispielsweise der Bestand in einer Zeile, bleibt der bisherige Bestand erhalten.
`category`	Beim Import im Format `csv` werden Medienfelder (Bilder und Videos) in benutzerdefinierten Feldern nicht übernommen. Das entspricht dem Verhalten beim Produktimport. Ungültige, fehlende oder falsch typisierte Feldwerte werden in `importErrors` gemeldet.

Methoden für den Datenimport

GET import/{service}/status

Dieser Endpunkt liefert den aktuellen Status eines laufenden oder zuletzt ausgeführten Importprozesses für einen angegebenen Service (beispielsweise newsletterSubscriber). Die Antwort enthält detaillierte Informationen zum Fortschritt, zu verarbeiteten und fehlerhaften Datensätzen sowie zum Startzeitpunkt. Wenn vorhanden, wird auch die Endzeit des Imports angezeigt. Der Status eines Importvorgangs wird über numerische Werte abgebildet:
0 = READY
1 = STARTING
2 = RUNNING
3 = PAUSED
4 = CANCELED
5 = FINISHED
6 = ERROR Diese Statuswerte geben Aufschluss über den aktuellen Fortschritt oder das Ergebnis eines Imports.

Über den Service newsletterSubscriber versendet der Shop am Ende des Imports die Double-Opt-In-E-Mails an neue Abonnenten, sofern die Option importSubscribeDoubleOptIn in newsletter.newsletter aktiviert ist. Dieser Vorgang kann bis zu 10 Minuten dauern. Schlägt er fehl, endet der Import mit dem Status 6 = ERROR. lastError enthält dann den Text Failed to send double opt-in emails und in globalError wird ein interner Fehler gemeldet.

Um auf die Services zuzugreifen, benötigen Sie die entsprechenden Berechtigungen oder einen Administratorenzugang mit Vollzugriff. Für die meisten Services benötigen Sie Schreib- und Erstellrechte. Für voucher, voucherTemplate, voucherPreset, inquiry und order genügt das Schreibrecht. Für product sind zusätzlich Schreib- und Erstellrechte für Produktvarianten nötig. Für adminUser ist der Administratorzugang mit Vollzugriff erforderlich. Dieselben Berechtigungen gelten für Start, Pause, Fortsetzen und Abbrechen eines Imports.

Beispiel

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

Antwort

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

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte des Services.
400 Bad Request		`service` ist unbekannt.
503 Service Unavailable	”internalError”	Redis hat keinen Status geliefert.

POST import/{service}/start

Dieser Endpunkt startet den Importprozess für einen angegebenen Service. Die hochzuladenden Daten (beispielsweise als JSON oder CSV) werden im Request-Body übergeben. Falls bereits ein Importprozess für den Service läuft, wird dieser automatisch abgebrochen, bevor der neue Import gestartet wird. Die Antwort liefert unmittelbar den aktuellen Status des gestarteten Imports. Enthalten sind Informationen zum Fortschritt, zur Anzahl verarbeiteter und fehlerhafter Datensätze sowie zu Start- und Endzeiten. Der Statuswert wird als numerische Codierung gemäß der Import-Definition zurückgegeben. Die erforderlichen Berechtigungen entsprechen denen des Status-Endpunkts (siehe Abschnitt zu GET import/{service}/status).

Query-Parameter

Parameter	Pflicht	Beschreibung
`format`	Nein	Das Datenformat der Import-Datei (beispielsweise `json`, `csv`). Die unterstützten Formate hängen vom jeweiligen Service ab (siehe Unterstützte Services und Formate).
`sendMail`	Nein	Nur für den Service `adminUser`: Steuert, ob eine E-Mail an die importierten Benutzer gesendet wird.

Beispiel

https://www.<ihr-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
        ]
    },
    ...
]

Antwort

{
    "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
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Schreiben oder Erstellen der Daten des Services.
400 Bad Request		`service` ist unbekannt. Der Service unterstützt das `format` nicht.
503 Service Unavailable	”serviceUnavailable”	Der Importprozess konnte nicht getriggert werden.
503 Service Unavailable	”internalError”	Redis hat keinen Status geliefert. Der interne `FileService` kann nicht erreicht werden. Request konnte nicht in einer Datei gespeichert werden. Der Status konnte nicht in Redis aktualisiert werden. Der Importprozess wurde nicht innerhalb von 10 Sekunden gestartet.

POST import/{service}/pause

Dieser Endpunkt pausiert einen laufenden Importprozess für einen angegebenen Service. Die Antwort enthält den aktuellen Status des pausierten Prozesses einschließlich der verarbeiteten Datensätze, des Fortschritts und eventueller Fehler. Nach erfolgreichen Pausieren wird der Statuswert auf PAUSED (3) gesetzt. Die erforderlichen Berechtigungen entsprechen denen des Status-Endpunkts (siehe Abschnitt zu GET import/{service}/status).

Beispiel

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

Antwort

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

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte.
400 Bad Request		`service` ist unbekannt.
404 Not found		Der Prozess läuft nicht oder befindet sich nicht im Status RUNNING.
503 Service Unavailable	”internalError”	Redis hat keinen Status geliefert. Redis kann nicht erreicht werden. Der Prozess konnte nicht gestoppt werden.

POST import/{service}/resume

Dieser Endpunkt führt einen pausierten Importprozess für einen angegebenen Service fort. Die Antwort enthält den aktuellen Status des fortgeführten Prozesses einschließlich der verarbeiteten Datensätze, des Fortschritts und eventueller Fehler. Die erforderlichen Berechtigungen entsprechen denen des Status-Endpunkts (siehe Abschnitt zu GET import/{service}/status).

Beispiel

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

Antwort

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

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte.
400 Bad Request		`service` ist unbekannt.
404 Not found		Der Prozess befindet sich nicht im Status PAUSED.
503 Service Unavailable	”internalError”	Redis hat keinen Status geliefert. Redis kann nicht erreicht werden. Der Prozess konnte nicht gestoppt werden.

DELETE import/{service}/cancel

Dieser Endpunkt bricht einen laufenden Importprozess für einen angegebenen Service ab. Die Antwort enthält den aktuellen Status des abgebrochenen Prozesses einschließlich der verarbeiteten Datensätze, des Fortschritts und eventueller Fehler. Nach einem erfolgreichen Abbruch wird der Statuswert auf CANCELED (4) gesetzt. Die erforderlichen Berechtigungen entsprechen denen des Status-Endpunkts (siehe Abschnitt zu GET import/{service}/status).

Beispiel

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

Antwort

{
    "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
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte.
400 Bad Request		`service` ist unbekannt.
404 Not found		Der Prozess läuft nicht oder befindet sich nicht in einem abbrechbaren Status (RUNNING, STARTING oder PAUSED).
503 Service Unavailable	”internalError”	Redis hat keinen Status geliefert. Redis kann nicht erreicht werden. Der Prozess konnte nicht gestoppt werden.

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.

Schnittstellen

Admin Interface API

Storefront API

Weitere

Unterstützte Methoden

Allgemein

Unterstützte Services und Formate

Verhalten einzelner Services

Methoden für den Datenimport

GET import/{service}/status

Beispiel

Antwort

Fehlercodes

POST import/{service}/start

Query-Parameter

Beispiel

Request Body

Antwort

Fehlercodes

POST import/{service}/pause

Beispiel

Antwort

Fehlercodes

POST import/{service}/resume

Beispiel

Antwort

Fehlercodes

DELETE import/{service}/cancel

Beispiel

Antwort

Fehlercodes

Support

​Unterstützte Methoden

​Allgemein

​Unterstützte Services und Formate

​Verhalten einzelner Services

​Methoden für den Datenimport

​GET import/{service}/status

​Beispiel

​Antwort

​Fehlercodes

​POST import/{service}/start

​Query-Parameter

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​POST import/{service}/pause

​Beispiel

​Antwort

​Fehlercodes

​POST import/{service}/resume

​Beispiel

​Antwort

​Fehlercodes

​DELETE import/{service}/cancel

​Beispiel

​Antwort

​Fehlercodes

​Support

Unterstützte Methoden

Allgemein

Unterstützte Services und Formate

Verhalten einzelner Services

Methoden für den Datenimport

GET import/{service}/status

Beispiel

Antwort

Fehlercodes

POST import/{service}/start

Query-Parameter

Beispiel

Request Body

Antwort

Fehlercodes

POST import/{service}/pause

Beispiel

Antwort

Fehlercodes

POST import/{service}/resume

Beispiel

Antwort

Fehlercodes

DELETE import/{service}/cancel

Beispiel

Antwort

Fehlercodes

Support