API-Referenz Produktbewertungen - WEBSALE Dokumentation

Der Endpunkt /productRating stellt Ihnen eine Schnittstelle bereit um Produktbewertungen in unserem Shopsystem, zu verwalten. Sie können Produktbewertungen abrufen, aktualisieren, filtern und löschen.

Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	GET	POST	PUT	DELETE
Allgemeines Bewertung	productRating/

Datenfelder Bewertungen (Rating Resource)

Bewertungen sind in einer Datenbanktabelle gespeichert. Es gibt eine weitere Tabelle für Durchschnittswerte und die Anzahl der Bewertungen eines Produkts. Diese Tabelle wird automatisch aktualisiert, und ihre Werte werden gelesen, wenn man eine einzelne Bewertung abfragt.

Name	Typ	Bedeutung
accountId	String	ID des Kundenkontos, das die Bewertung abgegeben hat
accountType	Integer	Typ des Kundenkontos (z. B. Gast (`1`) oder registrierter Kunde (`3`))
anonymous	Boolean	`True` = Bewertung wurde anonym abgegeben, `False` = mit Kundenkonto verknüpft
answeredAt	String	Zeitpunkt der Händlerantwort (ISO 8601-Format, UTC)
approval	Boolean	Gibt an, ob die Bewertung freigegeben wurde
categoryId	String	Kategorie, der das bewertete Produkt zugeordnet ist
createdAt	String	Zeitpunkt der Erstellung der Bewertung (ISO 8601-Format, UTC)
description	String	Ausführliche Beschreibung bzw. Text der Bewertung
disapprovalReason	String	Grund für die Ablehnung der Bewertung (falls abgelehnt)
id	Integer	Eindeutige ID der Bewertung
merchantComment	String	Antwort oder Kommentar des Händlers zur Bewertung
orderId	String	ID der Bestellung, mit der das Produkt gekauft wurde
points	Number	Vergebene Punktzahl, z. B. im Bereich 1–5
productId	String	Technische ID des bewerteten Produkts
productName	String	Aktueller Name des Produkts
productNumber	String	Artikelnummer des Produkts
productType	String	Produkttyp (z. B. `standard`, `digital`)
subject	String	Betreff oder Titel der Bewertung
subshopId	String	Subshop, in dem die Bewertung abgegeben wurde
averageRating	Number	Durchschnittliche Bewertungspunktzahl des Produkts
totalRating	Integer	Gesamtanzahl der Bewertungen des Produkts
variationSelection	Array	Ausgewählte Produktvarianten aus der zugehörigen Bestellung
orderSubshop	String	Subshop der zugehörigen Bestellung

Beispiel von einem Datensatz

{
    "accountId": "1",
    "accountType": 0,
    "anonymous": false,
    "answeredAt": "2024-12-16 14:14:43",
    "approval": false,
    "categoryId": "911-78497",
    "createdAt": "2024-09-27 13:26:10",
    "description": "Meaningful description",
    "disapprovalReason": "You shall not pass",
    "id": 3,
    "merchantComment": "",
    "orderId": "233",
    "points": 2,
    "productId": "440-35068",
    "productName": "Regular product",
    "productNumber": "123456",
    "productType": "standard",
    "subject": "I do not like it",
    "subshopId": "deutsch"
}

Verwendung der Methoden

GET productRating

Zugriff auf Bewertungen mit Filtermöglichkeiten.

Beispiel

Zugriff auf bis zu 100 nicht freigegebenen Bewertungen im Zeiraum 2024.12.02–2025.01.06.

https://www.<ihr-shop>.de/admin/api/v1/productRating?size=100&filter_gte[createdAt]=2024-12-02T00:00:00.000Z
&filter_lte[createdAt]=2025-01-05T23:59:59.000Z&filter_eq[approval]=false

Antwort

{
    "endReached": true,
    "items": [
        {
            "accountId": "1",
            "accountType": 0,
            "anonymous": false,
            "answeredAt": "",
            "approval": false,
            "categoryId": "911-78497",
            "createdAt": "2024-09-27 13:26:10",
            "description": "Meaningful description",
            "disapprovalReason": "You shall not pass",
            "id": 3,
            "merchantComment": "",
            "orderId": "233",
            "points": 2,
            "productId": "440-35068",
            "productType": "standard",
            "subject": "I do not like it",
            "subshopId": "deutsch",

            "productName": "Regular product",
            "productNumber": "123456"
        }
    ],
    "nextPageToken": "MQ",
    "totalCount": 2
}

Filterfelder

id, productId, accountId, orderId, points, approval, createdAt, answeredAt, subject, disapprovalReason, anonymous, subshopId

Sortierfelder

createdAt, answeredAt, id, productId, accountId, orderId, points, approval, anonymous, subject, description, merchantComment, disapprovalReason, subshopId

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Bewertungen.
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	”syntaxError”	`sort` enthält mehr als einen oder keinen ”:“.
400 Bad Request	”invalidCharacters”	`size` ist keine Ganzzahl.

GET productRating/{id}

Zugriff auf eine bestimmte Bewertung. Es steht auch in der Antwort, wie oft das korrespondierende Produkt bewertet wurde und was der Durchschnittswert ist. Wenn eine Variante ausgewählt wurde, wird das auch mitgeteilt.

Beispiel

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

Antwort

{
    "accountId": "1",
    "accountType": 0,
    "anonymous": false,
    "answeredAt": "2025-01-16 11:33:52",
    "approval": true,
    "categoryId": "911-78497",
    "createdAt": "2024-12-18 22:35:24",
    "description": "I recomend it",
    "disapprovalReason": "",
    "id": 2,
    "merchantComment": "Thanks!",
    "orderId": "233",
    "points": 4,
    "productId": "105-59442",
    "productType": "standard",
    "subject": "Good product",
    "subshopId": "deutsch",

    "averageRating": 4.0,
    "totalRating": 1,
    "variationSelection": [],
    "orderSubshop": "deutsch"
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Bewertungen.
404 Not Found		Bewertungsstatistiken oder die korrespondierende Bestellung konnten nicht geladen werden.
503 Service Unavailable	”internalError”	Die Bewertung konnte nicht gelesen werden.

PUT productRating/{id}

Die Bewertung mit der angegebenen Id wird aktualisiert. Nur die im Beispiel gezeigte Felder können verändert werden.

Beispiel

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

Request Body

{
    "approval": false,
    "merchantComment": "",
    "disapprovalReason": "Bad rating"
}

Antwort

{
    "accountId": "1",
    "accountType": 0,
    "anonymous": false,
    "answeredAt": "2025-01-16 11:33:52",
    "approval": false,
    "categoryId": "911-78497",
    "createdAt": "2024-12-18 22:35:24",
    "description": "Dislike!",
    "disapprovalReason": "Bad rating",
    "id": 2,
    "merchantComment": "",
    "orderId": "233",
    "points": 1,
    "productId": "105-59442",
    "productType": "standard",
    "subject": "Dislike",
    "subshopId": "deutsch",

    "averageRating": 4.0,
    "totalRating": 1,
    "variationSelection": [],
    "orderSubshop": "deutsch"
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Bewertungen.
404 Not Found		Die Bewertung wurde nicht gefunden. Bewertungsstatistiken oder die korrespondierende Bestellung konnten nach dem Update nicht geladen werden.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”invalidFormat”	`merchantComment` oder `disapprovalReason` sind keine Strings. `approval` ist kein Boolean.
400 Bad Request	”unknownDataField”	Man aktualisiert ein Feld, das nicht aktualisiert werden darf.
503 Service Unavailable	”internalError”	Das Aktualisieren ist fehlgeschlagen.

DELETE productRating/{id}

Die Bewertung mit der angegebenen Id wird gelöscht.

Beispiel

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

Antwort

{
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Löschen von Bewertungen.
404 Not Found		Die Bewertung wurde nicht gefunden.
503 Service Unavailable	”internalError”	Das Löschen ist fehlgeschlagen.

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.

​Unterstützte Methoden

​Datenfelder Bewertungen (Rating Resource)

​Beispiel von einem Datensatz

​Verwendung der Methoden

​GET productRating

​Beispiel

​Antwort

​Filterfelder

​Sortierfelder

​Fehlercodes

​GET productRating/{id}

​Beispiel

​Antwort

​Fehlercodes

​PUT productRating/{id}

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​DELETE productRating/{id}

​Beispiel

​Antwort

​Fehlercodes

​Support

Unterstützte Methoden

Datenfelder Bewertungen (Rating Resource)

Beispiel von einem Datensatz

Verwendung der Methoden

GET productRating

Beispiel

Antwort

Filterfelder

Sortierfelder

Fehlercodes

GET productRating/{id}

Beispiel

Antwort

Fehlercodes

PUT productRating/{id}

Beispiel

Request Body

Antwort

Fehlercodes

DELETE productRating/{id}

Beispiel

Antwort

Fehlercodes

Support