API-Referenz Benutzerverwaltung - WEBSALE Dokumentation

Die API-Referenz Benutzerverwaltung beschreibt Endpunkte zur Verwaltung von Benutzerkonten und individuellen Einstellungen im Admin Interface des Shops. Über die Schnittstelle lassen sich Benutzer anlegen, bearbeiten und löschen sowie persönliche Einstellungen wie Sprache oder Dashboard-Konfiguration abrufen und aktualisieren. Der Zugriff auf die jeweiligen Endpunkte richtet sich nach den Berechtigungen des angemeldeten Benutzers.

Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	GET	PUT	POST	DELETE
Benutzerkonto im Admin-Bereich	admin/user
Benutzereinstellungen	admin/settings

Allgemein

Datenfelder eines Benutzerkontos

Name	Typ
id	Integer	Eindeutige ID des Benutzers
firstName	String	Vorname des Benutzers
lastName	String	Nachname des Benutzers
role	Array	Rollen im Unternehmen als Array, z.B. [“marketing”, “seo”]
email	String	E-Mail-Adresse des Benutzers
userName	String	Benutzername des Benutzers
permissions	Objekt	Berechtigungen des Benutzers für Dienste

Beispiel

{
    "email": "vx-shop@websale.de",
    "firstName": "Horst",
    "id": 1,
    "lastName": "Schlämmer",
    "userName": "vx-shop",
    "permissions": {
        "admin": {
            "0": true
        }
    },
    "role": ["productMaintainer"]
}

Datenfelder der Benutzereinstellungen

Name	Typ	Verwendung
dashboard.content[]	Array	Liste von konfigurierten Widgets auf dem Benutzer-Dashboard
dashboard.content[].position.cols	Integer	Anzahl der Spalten, die das Widget belegt
dashboard.content[].position.rows	Integer	Anzahl der Zeilen, die das Widget belegt
dashboard.content[].position.x	Integer	Horizontale Position des Widgets im Raster
dashboard.content[].position.y	Integer	Vertikale Position des Widgets im Raster
dashboard.content[].settings	Object	Individuelle Einstellungen für das jeweilige Widget
dashboard.content[].settings.shortcuts[]	Array	(Nur für Widget „shortcuts“) Liste mit Link-Shortcuts
dashboard.content[].settings.shortcuts[].label	String	Text, der auf dem Button angezeigt wird
dashboard.content[].settings.shortcuts[].route	String	Interne Route, die beim Klick geöffnet wird
dashboard.content[].widgetId	String	Eindeutige Kennung des verwendeten Widgets
firstName	String	Vorname des Benutzers
language	String	Sprachcode des Benutzers (z. B. „deu“)
lastName	String	Nachname des Benutzers
salutation	String	Anrede des Benutzers (`m`, `w` oder `d`)
colorScheme	String	Farbschema des Admin-Interfaces

Beispiel

{
    "dashboard": {
        "content": [
            {
                "position": {
                    "cols": 3,
                    "rows": 4,
                    "x": 0,
                    "y": 0
                },
                "settings": {},
                "widgetId": "salesTrend"
            },
            {
                "position": {
                    "cols": 3,
                    "rows": 2,
                    "x": 0,
                    "y": 4
                },
                "settings": {},
                "widgetId": "inbox"
            },
            {
                "position": {
                    "cols": 2,
                    "rows": 3,
                    "x": 3,
                    "y": 0
                },
                "settings": {},
                "widgetId": "conversion-rate-trends"
            },
            {
                "position": {
                    "cols": 2,
                    "rows": 5,
                    "x": 3,
                    "y": 3
                },
                "settings": {
                    "shortcuts": [
                        {
                            "label": "Zu Kategorien",
                            "route": "/categories"
                        },
                        {
                            "label": "Zu Produkten",
                            "route": "/products"
                        },
                        {
                            "label": "Zu Bestellungen",
                            "route": "/orders"
                        }
                    ]
                },
                "widgetId": "shortcuts"
            }
        ]
    },
    "firstName": "Horst",
    "language": "deu",
    "lastName": "Schlämmer",
    "salutation": "m",
    "colorScheme": "light"
}

Berechtigungen

Technischer Name	Bedeutung	Werte
`"admin"`	Vollzugriff auf alle Bereiche	`0 = Active`
`"products"`	Produkte	`0 = Read1 = Write2 = Create3 = Delete4 = WriteProtectedFields`
`"productvariants"`	Produktvarianten	`0 = Read1 = Write2 = Create3 = Delete`
`"productRatings"`	Produktbewertungen	`0 = Read1 = Write2 = Create3 = Delete`
`"inventory"`	Produkte Lagerbestand	`0 = Read1 = Write2 = Create3 = Delete`
`"productFields"`	Produktfelder	`0 = Read1 = Write2 = Create3 = Delete`
`"categories"`	Kategorien	`0 = Read1 = Write2 = Create3 = Delete`
`"categoryFields"`	Kategoriefelder	`0 = Read1 = Write2 = Create3 = Delete`
`"configuration"`	Konfigurationen	`0 = Read1 = Write2 = Create3 = Delete`
`"seo"`	SEO	`0 = Read1 = Write2 = Create3 = Delete`
`"sitemaps"`	SiteMaps	`0 = Read1 = Create2 = Write3 = Delete4 = Publish`
`"datafeeds"`	Datenfeeds	`0 = Read1 = Write2 = Create3 = Delete4 = Publish`
`"orders"`	Bestellungen	`0 = Read1 = Write2 = Delete`
`"inquiries"`	Anfragen	`0 = Read1 = Write2 = Delete`
`"texts"`	Textbausteine	`0 = Read1 = Write2 = Create3 = Delete4 = Publish`
`"templates"`	Shop-Seiten-Templates	`0 = Read4 = Publish`
`"customerAccounts"`	Kundendaten	`0 = Read1 = Write2 = Create3 = Delete`
`"vouchers"`	Gutscheine	`0 = Read1 = Write2 = Create3 = Delete`
`"transactions"`	Transaktionen	`0 = Read1 = Write`
`"keyValue"`	Key-Value-Store	`0 = Read1 = Write2 = Create3 = Delete`
`"newsletter"`	Newsletter	`0 = Read1 = Write2 = Create3 = Delete`
`"blacklist"`	Newsletter-Blacklist	`0 = Add1 = Remove`
`"statistics"`	Alle Statistiken	`0 = Read`
`"logs"`	Logs	`0 = Read1 = Write2 = Create3 = Delete`
`"strapi"`	Link zum Strapi-CMS	`0 = Read`
`"dashboard"`	Dashboard im AI	`0 = Read`
`"imageconverter"`	Bildkonverter	`0 = Read1 = Write2 = Create3 = Delete4 = Publish`
`"paypalonboarding"`	Paypal-Onboarding	`0 = Read1 = Write2 = Create3 = Delete`
`"paymentprovider"`	Payment provider	`0 = Read1 = Write2 = Create3 = Delete`

Beispiel der Berechtigungen

"permissions": {
    "admin": {
        "0": false
    },
    "newsletter": {
        "0": true,
        "1": true,
        "2": true,
        "3": true
    },
    "customerAccounts": {
        "0": true,
        "1": false,
        "2": false,
        "3": false
    },
    "products": {
        "0": true,
        "1": false,
        "2": false,
        "3": false,
        "4": false
    }
}

Der Benutzer hat keinen Vollzugriff (die Berechtigung admin.0 (admin.active) ist auf false gesetzt). Er kann den gesamten Newsletter-Dienst nutzen – die Berechtigungen newsletter.0 (newsletter.Read), newsletter.1 (newsletter.Write), newsletter.2 (newsletter.Create) und newsletter.3 (newsletter.Delete) sind auf true gesetzt, und Kunden- sowie Produkt-Daten lesen – customerAccounts.0 (customerAccounts.Read) und products.0 (products.Read) sind auf true gesetzt.

Methoden für Benutzerkonten

Der Endpunkt /admin/user ermöglicht die Verwaltung von Benutzerkonten. Darüber können Benutzer erstellt, geändert, gelöscht und abgerufen werden.

GET admin/user

Dieser Endpunkt liefert eine Liste aller Benutzerkonten aus dem Admin Interface des Shops.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/admin/user

Antwort

{
    "endReached": true,
    "items": [
        {
            "id": 1,
            "role": [],
            "firstName": "",
            "lastName": "",
            "email": "",
            "permissions": {...}
        },
        ...
    ],
    "nextPageToken": "NA",
    "totalCount": 5
}

Filterfelder

id, firstName, lastName, email, privileges, websale

Sortierfelder

id, firstName, lastName, email, websale

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Benutzern.
400 Bad Request	”invalidValue”
400 Bad Request	”unknownDataField”	Ein Filter- oder Sortierfeld ist ungültig.
400 Bad Request	”unknownOperation”	Ein Filtertyp ist ungültig.
400 Bad Request	”invalidCharacters”	`size` ist keine Ganzzahl. Ein Filterwert ist ungültig.
400 Bad Request	”syntaxError”	`sort` enthält mehr als einen oder keinen ”:”.

GET admin/user/self

Dieser Endpunkt lädt die Daten des aktuell angemeldeten Benutzerkontos.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/admin/user/self

Antwort

{
    "email": "m.mustermann@websale.de",
    "firstName": "Max",
    "id": 1,
    "lastName": "Mustermann",
    "userName": "m.mustermann",
    "permissions": {
        "admin": {
            "0": false
        },
        "newsletter": {
            "0": true,
            "1": true,
            "2": true,
            "3": true
        }
    },
    "role": ["marketing"]
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
404 Not Found		Das Konto wurde in der Datenbank nicht gefunden.

GET admin/user/{accountId}

Dieser Endpunkt lädt die Daten eines bestimmten Benutzerkontos anhand der accountId.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/admin/user/123456

Antwort

{
    "email": "m.mustermann@websale.de",
    "firstName": "Max",
    "id": 1,
    "lastName": "Mustermann",
    "userName": "m.mustermann",
    "permissions": {
        "admin": {
            "0": false
        },
        "newsletter": {
            "0": true,
            "1": true,
            "2": true,
            "3": true
        }
    },
    "role": ["marketing"]
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Benutzern.
400 Bad Request	”invalidFormat”	`accountId` ist ungültig.
400 Bad Request	”invalidValue”	`accountId` ist 0.
404 Not Found		Das Konto wurde in der Datenbank nicht gefunden.

GET admin/permissions

Dieser Endpunkt gibt eine Liste mit allen Berechtigungen, die ein Benutzer haben kann.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/admin/permissions

Antwort

{
    "items": [
        {
            "id": "strapi",
            "permissions": [
                {
                    "id": 0,
                    "name": "read"
                }
            ]
        },
        {
            "id": "logs",
            "permissions": [
                {
                    "id": 0,
                    "name": "read"
                },
                {
                    "id": 1,
                    "name": "write"
                },
                {
                    "id": 2,
                    "name": "create"
                },
                {
                    "id": 3,
                    "name": "delete"
                }
            ]
        },
        {
            "id": "blacklist",
            "permissions": [
                {
                    "id": 0,
                    "name": "write"
                },
                {
                    "id": 1,
                    "name": "delete"
                }
            ]
        },
        ...
    ]
}

POST admin/user

Dieser Endpunkt erstellt ein neues Benutzerkonto für das Admin Interface. Beim Erstellen kann entweder direkt ein Passwort gesetzt oder eine E-Mail mit einem Link zum Passwortsetzen versendet werden.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/admin/user

Request Body

{
    "email": "m.mustermann@websale.de",
    "firstName": "Max",
    "lastName": "Mustermann",
    "permissions": {
        "admin": {
            "0": false
        },
        "newsletter": {
            "0": true,
            "1": true,
            "2": true,
            "3": true
        }
    },
    "role": ["marketing"],
    "passwordEmail": true
}

Antwort

{
    "id": 42,
    "role": ["marketing"],
    "firstName": "Max",
    "lastName": "Mustermann",
    "email": "m.mustermann@websale.de",
    "permissions": {...}
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”invalidFormat”	`firstName`, `lastName`, `email` oder `password` sind keine Strings. `passwordEmail` ist kein Boolean. `role` ist kein Array. `permissions` ist kein JSON-Objekt
400 Bad Request	”missing”	`email` oder `permissions` fehlen. `password` fehlt (wenn `passwordEmail` nicht auf `true` gesetzt ist).
400 Bad Request	”invalidCombination”	Ein Passwort ist angegeben, obwohl `passwordEmail` auf `true` gesetzt ist.
400 Bad Request	”unknownDataField”	Ein unbekanntes Feld wurde gesendet.
503 Service Unavailable	”internalError”	E-Mail konnte nicht gesendet werden.

POST admin/passwordChange

Dieser Endpunkt ändert das Passwort des aktuell angemeldeten Benutzerkontos.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/admin/passwordChange

Request Body

{
    "newPassword": <new password>,
    "newPasswordAgain": <new password>,
    "oldPassword": <old password>
}

Antwort

{
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”missing”	`newPassword`, `newPasswordAgain` oder `oldPassword` fehlen.
400 Bad Request	”invalidValue”	`newPassword` und `newPasswordAgain` stimmen nicht überein. `newPassword` ist kürzer als 12 Zeichen oder zu schwach. `oldPassword` stimmt nicht mit dem Passwort des Kontos überein. `newPassword`, `newPasswordAgain` oder `oldPassword` sind leere Strings.
400 Bad Request	”invalidFormat”	`newPassword`, `newPasswordAgain` oder `oldPassword` sind keine Strings.
400 Bad Request	”unknownDataField”	Ein unbekanntes Feld wurde gesendet.
401 Unauthorized		Nicht autorisiert: Sie verfügen nicht über die erforderlichen Schreibrechte.
403 Forbidden		Das Konto ist gesperrt.

POST admin/resend/{accountId}

Dieser Endpunkt versendet eine E-Mail mit einem Link zum Zurücksetzen des Passworts an die E-Mail-Adresse, die zum Benutzerkonto gehört.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/admin/resend/9

Request Body

{}

Antwort

{
    "id": 9,
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die Administratorrechte.
400 Bad Request	”invalidFormat”	`accountId` ist keine Ganzzahl.
400 Bad Request	”invalidValue”	`accountId` ist 0.
404 Not Found		Das Konto wurde nicht gefunden.
503 Service Unavailable	”internalError”	Die E-Mail konnte nicht versendet werden.

PUT admin/user/{accountId}

Dieser Endpunkt aktualisiert die Informationen eines Benutzerkontos anhand der accountId.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/admin/user/123456

Request Body

{
    "email": "m.mustermann@websale.de",
    "firstName": "Max",
    "lastName": "Mustermann",
    "permissions": {
        "admin": {
            "0": false
        },
        "newsletter": {
            "0": true,
            "1": true,
            "2": true,
            "3": true
        }
    },
    "role": ["marketing"]
}

Antwort

{
    "id": 42,
    "role": ["marketing"],
    "firstName": "Max",
    "lastName": "Mustermann",
    "email": "m.mustermann@websale.de",
    "permissions": {...}
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”invalidFormat”	`accountId` ist ungültig. `firstName`, `lastName` oder `email` sind keine Strings. `role` ist kein Array. `permissions` ist kein JSON-Objekt
400 Bad Request	”unknownDataField”	Ein unbekanntes Feld wurde gesendet.
404 Not Found		Das Konto wurde nicht gefunden.

DELETE admin/user/{accountId}

Dieser Endpunkt löscht ein bestehendes Benutzerkonto anhand der accountId.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/admin/user/123456

Antwort

{
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte. Ein Konto, das der Websale AG gehört, darf nicht gelöscht werden.
400 Bad Request	”invalidFormat”	`accountId` ist ungültig.
400 Bad Request	”invalidValue”	`accountId` ist 0.
404 Not Found		Das Konto wurde nicht gefunden.

Methoden für Benutzereinstellungen

Der Endpunkt /admin/settings ermöglicht das Speichern und Abrufen benutzerbezogener Einstellungen.

GET admin/settings

Dieser Endpunkt lädt die aktuellen Einstellungen des aktuell angemeldeten Benutzers, wie Sprache, Name und Dashboard-Konfiguration.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/admin/settings

Antwort

{
    "dashboard": {
        "content": [
            {
                "position": {
                    "cols": 2,
                    "rows": 2,
                    "x": 0,
                    "y": 0
                },
                "settings": {
                    "timeBetweenReloads": -1
                },
                "widgetId": "salesToday"
            }
        ]
    },
    "colorScheme": "light",
    "firstName": "Max",
    "language": "deu",
    "lastName": "Mustermann",
    "salutation": "m"
}

Fehlercodes

Fehler	Typ	Grund
404 Not Found		Es gibt keine gespeicherten Einstellungen für das aktive Konto.

PUT admin/settings

Dieser Endpunkt aktualisiert die Benutzereinstellungen. Nicht übergebene Parameter behalten ihren bisherigen Wert.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/admin/settings

Request Body

{
    "dashboard": {
        "content": [
            {
                "position": {
                    "cols": 2,
                    "rows": 2,
                    "x": 0,
                    "y": 0
                },
                "settings": {
                    "timeBetweenReloads": -1
                },
                "widgetId": "salesToday"
            }
        ]
    },
    "colorScheme": "light",
    "firstName": "Max",
    "language": "deu",
    "lastName": "Mustermann",
    "salutation": "m"
}

Antwort

<Settings as json, same as with GET>

Fehlercodes

Fehler	Typ	Grund
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”missing”	`dashboard.content`, `dashboard.content.widgetId`, `dashboard.content.position`, `dashboard.content.position.cols`, `dashboard.content.position.rows`, `dashboard.content.position.x` oder `dashboard.content.position.y` fehlen.
400 Bad Request	”unknownDataField”	Ein unbekanntes Feld wurde gesendet.
400 Bad Request	”invalidFormat”	`dashboard` ist kein JSON-Objekt. `salutation`, `language`, `colorScheme`, `firstName` oder `lastName` sind keine Strings.
400 Bad Request	”invalidValue”	`salutation` ist kein gültiger Wert (erlaubt: `m`, `w`, `d`).
401 Unauthorized		Nicht autorisiert: Sie verfügen nicht über die erforderlichen Schreibrechte.
404 Not Found		Es gibt keine gespeicherten Einstellungen für das aktive Konto.
503 Service Unavailable	”internalError”	Das Speichern ist fehlgeschlagen.

Support

Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: Zum Kundenportal 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.

​Unterstützte Methoden

​Allgemein

​Datenfelder eines Benutzerkontos

​Beispiel

​Datenfelder der Benutzereinstellungen

​Beispiel

​Berechtigungen

​Beispiel der Berechtigungen

​Methoden für Benutzerkonten

​GET admin/user

​Beispiel

​Antwort

​Filterfelder

​Sortierfelder

​Fehlercodes

​GET admin/user/self

​Beispiel

​Antwort

​Fehlercodes

​GET admin/user/{accountId}

​Beispiel

​Antwort

​Fehlercodes

​GET admin/permissions

​Beispiel

​Antwort

​POST admin/user

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​POST admin/passwordChange

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​POST admin/resend/{accountId}

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​PUT admin/user/{accountId}

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​DELETE admin/user/{accountId}

​Beispiel

​Antwort

​Fehlercodes

​Methoden für Benutzereinstellungen

​GET admin/settings

​Beispiel

​Antwort

​Fehlercodes

​PUT admin/settings

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​Support

Unterstützte Methoden

Allgemein

Datenfelder eines Benutzerkontos

Beispiel

Datenfelder der Benutzereinstellungen

Beispiel

Berechtigungen

Beispiel der Berechtigungen

Methoden für Benutzerkonten

GET admin/user

Beispiel

Antwort

Filterfelder

Sortierfelder

Fehlercodes

GET admin/user/self

Beispiel

Antwort

Fehlercodes

GET admin/user/{accountId}

Beispiel

Antwort

Fehlercodes

GET admin/permissions

Beispiel

Antwort

POST admin/user

Beispiel

Request Body

Antwort

Fehlercodes

POST admin/passwordChange

Beispiel

Request Body

Antwort

Fehlercodes

POST admin/resend/{accountId}

Beispiel

Request Body

Antwort

Fehlercodes

PUT admin/user/{accountId}

Beispiel

Request Body

Antwort

Fehlercodes

DELETE admin/user/{accountId}

Beispiel

Antwort

Fehlercodes

Methoden für Benutzereinstellungen

GET admin/settings

Beispiel

Antwort

Fehlercodes

PUT admin/settings

Beispiel

Request Body

Antwort

Fehlercodes

Support