API-Referenz Benutzerverwaltung

Benutzerkonten, Rollen und Berechtigungen für das WEBSALE Admin Interface per REST API anlegen, bearbeiten, löschen und individuell konfigurieren.

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	Verwendung
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": "[e-mail]",
    "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 = Read 1 = Write 2 = Create 3 = Delete 4 = WriteProtectedFields
"productvariants"	Produktvarianten	0 = Read 1 = Write 2 = Create 3 = Delete
"productRatings"	Produktbewertungen	0 = Read 1 = Write 2 = Create 3 = Delete
"inventory"	Produkte Lagerbestand	0 = Read 1 = Write 2 = Create 3 = Delete
"productFields"	Produktfelder	0 = Read 1 = Write 2 = Create 3 = Delete
"categories"	Kategorien	0 = Read 1 = Write 2 = Create 3 = Delete
"categoryFields"	Kategoriefelder	0 = Read 1 = Write 2 = Create 3 = Delete
"configuration"	Konfigurationen	0 = Read 1 = Write 2 = Create 3 = Delete
"seo"	SEO	0 = Read 1 = Write 2 = Create 3 = Delete
"sitemaps"	SiteMaps	0 = Read 1 = Create 2 = Write 3 = Delete 4 = Publish
"datafeeds"	Datenfeeds	0 = Read 1 = Write 2 = Create 3 = Delete 4 = Publish
"orders"	Bestellungen	0 = Read 1 = Write 2 = Delete
"inquiries"	Anfragen	0 = Read 1 = Write 2 = Delete
"texts"	Textbausteine	0 = Read 1 = Write 2 = Create 3 = Delete 4 = Publish
"templates"	Shop-Seiten-Templates	0 = Read 4 = Publish
"customerAccounts"	Kundendaten	0 = Read 1 = Write 2 = Create 3 = Delete
"vouchers"	Gutscheine	0 = Read 1 = Write 2 = Create 3 = Delete
"transactions"	Transaktionen	0 = Read 1 = Write
"keyValue"	Key-Value-Store	0 = Read 1 = Write 2 = Create 3 = Delete
"newsletter"	Newsletter	0 = Read 1 = Write 2 = Create 3 = Delete
"blacklist"	Newsletter-Blacklist	0 = Add 1 = Remove
"statistics"	Alle Statistiken	0 = Read
"logs"	Logs	0 = Read 1 = Write 2 = Create 3 = Delete
"strapi"	Link zum Strapi-CMS	0 = Read
"dashboard"	Dashboard im AI	0 = Read
"imageconverter"	Bildkonverter	0 = Read 1 = Write 2 = Create 3 = Delete 4 = Publish
"paypalonboarding"	Paypal-Onboarding	0 = Read 1 = Write 2 = Create 3 = Delete
"paymentprovider"	Payment provider	0 = Read 1 = Write 2 = Create 3 = 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.
403 Forbidden		Sie 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": "[e-mail]",
    "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": "[e-mail]",
    "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.
403 Forbidden		Sie 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": "[e-mail]",
    "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": "[e-mail]",
    "permissions": {...}
}

​

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		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.
403 Forbidden		Sie 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": "[e-mail]",
    "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": "[e-mail]",
    "permissions": {...}
}

​

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		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.
403 Forbidden		Sie 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.