Storefront API Kundenbewertungen

Kundenbewertungen über die Storefront API erstellen, abrufen, aktualisieren, löschen sowie freigegebene Bewertungen und Statistiken auswerten.

Die Storefront-API für Kundenbewertungen stellt Funktionen bereit, um Kundenbewertungen zu erstellen, abzurufen, zu aktualisieren, zu löschen und auszuwerten. Darüber hinaus lassen sich z.B. die eigene Bewertung eines eingeloggten Kontos, alle freigegebenen Bewertungen eines Produkts sowie Statistikwerte abfragen.

Für die korrekte Verwendung der API für Kundenbewertungen muss zwingend immer eine x-sessionmitgegeben werden. Mehr dazu hier.

---

​

Unterstützte Methoden

Angabe aller Unterstützten Methoden.

Befehl	Endpunkte	GET	POST	PUT	DELETE
Letzte Bewertung abrufen	account/rating/latest
Alle Bewertungen aufrufen	account/rating/list
Existenz einer Bewertung prüfen	productRating/check
Eine bestimmte Bewertung abrufen	productRating/get
Alle Bewertungen eines Produkts abrufen	productRating/get
Bewertungsdurchschnitt eines Produkts abrufen	productRating/statistics
Bewertung erstellen	productRating/add
Bewertung aktualisieren	productRating/update
Bewertung löschen	productRating/update

​

Methoden für Bewertungen innerhalb eines Kundenkontos

Über diese Methoden können Bewertungen aus Sicht eines konkreten Kundenkontos abgefragt werden.

Damit kann das Frontend nach einem Bewertungsvorgang die aktuelle Bewertung des Kunden anzeigen oder in „Mein Konto“-Bereichen (z. B. Übersicht eigener Bewertungen) wiederverwenden.

​

GET account/rating/latest

Folgender Aufruf stellt die zuletzt abgegebene Kundenbewertung des aktuell angemeldeten Kunden bereit.

Beispiel-Aufruf der zuletzt abgegebenen Kundenbewertung des eingeloggten Kontos

GET https://<ihr-shop>.de/api/v1/account/rating/latest

​

Beispiel-Response

{
   "accountId" : "126",
   "accountType" : 2,
   "anonymous" : false,
   "answeredAt" : "",
   "approval" : false,
   "createdAt" : "1970-01-01T00:00:00.000Z",
   "description" : "Beschreibung",
   "disapprovalReason" : "",
   "merchantComment" : "",
   "orderId" : "4857",
   "points" : 5,
   "productId" : "83-1782",
   "subject" : "Titel",
   "subshopId" : "deutsch"
}

​

Parameterübersicht

​

Header-Parameter

Parameter	Beschreibung
x-session	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

​

GET account/rating/list

Folgender Aufruf listet alle Produktbewertungen des aktuell eingeloggten Kontos auf. Der Befehl kann beispielsweise verwendet werden, um eine Bewertungsübersicht im Kundenkonto “Mein Konto” anzuzeigen.

GET https://<ihr-shop>.de/api/v1/account/rating/list

​

Parameterübersicht

​

Header-Parameter

Parameter	Beschreibung
x-session	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

​

Beispiel-Response

{
  "items": [
    {
      "accountId": "126",
      "accountType": 2,
      "anonymous": false,
      "answeredAt": "",
      "approval": false,
      "createdAt": "1970-01-01T00:00:00.000Z",
      "description": "Beschreibung",
      "disapprovalReason": "",
      "merchantComment": "",
      "orderId": "4857",
      "points": 5,
      "productId": "12345",
      "subject": "Titel",
      "subshopId": "deutsch"
    }
  ]
}

​

Methoden für Kundenbewertungen (pro Bestellung)

Über diese Methode werden Kundenbewertungen verwaltet, die ein Kunde für ein bestimmtes Produkt innerhalb einer konkreten Bestellung abgegeben hat. Zudem können neue Bewertungen angelegt, vorhandene Bewertungen geändert oder wieder gelöscht werden.

Zusätzlich stehen Prüf- und Lese-Methoden zur Verfügung, um festzustellen, ob bereits eine Bewertung für die Kombination aus Produkt und Bestellung existiert und um diese Bewertung im Detail abzurufen (z. B. nach Aufruf eines Bewertungslinks in einer Service-E-Mail).

​

GET productRating/get

Mit diesem Aufruf wird – sofern vorhanden – die bereits abgegebene Kundenbewertung zu der angegebenen Kombination aus Bestellung und Produkt im Detail abgerufen, um sie z. B. in Formularen oder „Mein Konto“-Ansichten anzuzeigen.

Beispiel-Aufruf um eine Kundenbewertung für das Produkt mit der ID 99aus der Bestellung 0404-12 abzurufen

GET https://<ihr-shop>.de/api/v1/productRating/get?productId=99-0984&orderId=0404-12

​

Beispiel-Response

{}

​

Parameterübersicht

​

Header-Parameter

Parameter	Beschreibung
x-session	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

​

Body-Parameter

Parameter	Typ	Beschreibung
productId	string	Pflichtfeld ID des Produkts, für das die Bewertung abgegeben wurde.
orderId	string	Pflichtfeld ID der zugehörigen Bestellung, über die die Bewertung dem Kauf zugeordnet ist.

​

GET productRating/check

Mit dieser Methode wird geprüft, ob für die angegebene Kombination aus Bestellung und Produkt bereits eine Bewertung des Kunden vorliegt (z. B. zur Steuerung, ob ein Bewertungslink oder -formular noch angezeigt werden soll).

Beispiel-Aufruf um festzustellen, ob eine Kundenbewertung für das Produkt mit der ID 99 aus der Bestellung mit der ID 4857 existiert

GET https://<ihr-shop>.de/api/v1/productRating/check?productId=99-0984&orderId=4857

​

Beispiel-Response

Beispiel-Response, wenn die Bewertung existiert, ansonsten bekommt man “false” zurück:

{ "exists": true }

​

Parameterübersicht

​

Header-Parameter

Parameter	Beschreibung
x-session	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

​

Body-Parameter

Parameter	Typ	Beschreibung
productId	string	Pflichtfeld ID des Produkts, für das geprüft wird, ob eine Bewertung existiert.
orderId	string	Pflichtfeld ID der zugehörigen Bestellung, über die die Bewertung dem Kauf zugeordnet ist.

​

POST productRating/add

Mit dieser Methode wird für eine konkrete Kombination aus Bestellung orderId und Produkt productId eine neue Kundenbewertung angelegt.

Beispiel-Aufruf, der eine Kundenbewertung für das Produkt mit der ID 99-0984 für die Bestellung mit der ID 4900 abgibt

POST https://<ihr-shop>.de/api/v1/productRating/add

​

Beispiel-Request

{
  "productId": "99-0984",
  "orderId": "4900",
  "subject": "Titel",
  "description": "Meine Bewertung",
  "points": 5,
  "anonymous": false
}

​

Beispiel-Response

{}

​

Parameterübersicht

​

Header-Parameter

Parameter	Beschreibung
x-session	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

​

Body-Parameter

Parameter	Typ	Beschreibung
productId	string	Pflichtfeld ID des Produkts, für das die Bewertung abgegeben werden soll.
orderId	string	Pflichtfeld ID der Bestellung, mit der der Kauf des Produktes verbunden ist.
subject	string	Kurzer Titel der Bewertung
description	string	Freitext der Bewertung für Produktbeschreibung / Feedback
points	int	Pflichtfeld Bewertungswert. Dieser kann hier individuell festgelegt: general - Allgemeine Shopeinstellungen
anonymous	bool	Veröffentlicht die Bewertung ohne persönliche Zuordnung. Default: false

​

Fehlercodes

Fehlercode	Beschreibung
orderNotExists	Die angegebene Bestellung existiert im System nicht.
duplicateRating	Es wurde schon eine Bewertung für dieses Produkt von diesem User abgegeben.

​

PUT productRating/update

Mit dieser Methode wird eine bereits vorhandene Kundenbewertung zu einer bestimmten Bestellung orderId und einem bestimmten Produkt productId geändert, z. B. wenn der Kunde Text oder Bewertungssternzahl nachträglich anpasst.

Beispiel-Aufruf, um eine bereits vorhandene Kundenbewertung für das Produkt mit der ID 99-0984 aus der Bestellung mit der ID 4900 zu ändern

PUT https://<ihr-shop>.de/api/v1/productRating/update 

​

Beispiel-Request

{
  "productId": "99-0984",
  "orderId": "4900",
  "subject": "Titel",
  "description": "Beschreibung",
  "points": 5,
  "anonymous": false
}

​

Beispiel-Response

{}

​

Parameterübersicht

​

Header-Parameter

Parameter	Beschreibung
x-session	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

​

Body-Parameter

Parameter	Typ	Beschreibung
productId	string	Pflichtfeld ID des Produkts, für das die Bewertung aktualisiert werden soll.
orderId	string	Pflichtfeld ID der Bestellung, mit der der Kauf des Produktes verbunden ist.
subject	string	Kurzer Titel der Bewertung
description	string	Freitext der Bewertung für Produktbeschreibung / Feedback
points	int	Bewertungswert. Dieser kann hier individuell festgelegt: general - Allgemeine Shopeinstellungen
anonymous	bool	Veröffentlicht die Bewertung ohne persönliche Zuordnung. Default: false

​

DELETE productRating/update

Mit dieser Methode wird eine bestehende Kundenbewertung für eine konkrete Kombination aus Bestellung orderId und Produkt productId wieder gelöscht, sodass sie im Frontend nicht mehr angezeigt und in Auswertungen nicht mehr berücksichtigt wird.

Beispiel-Aufruf, um eine Kundenbewertung für das Produkt mit der ID 99-0984 für die Bestellung mit der ID 4900 zu löschen

DELETE https://<ihr-shop>.de/api/v1/productRating/update

​

Beispiel-Request

{
  "productId": "99-0984",
  "orderId": "4900"
}

​

Beispiel-Response

{}

​

Parameterübersicht

​

Header-Parameter

Parameter	Beschreibung
x-session	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

​

Body-Parameter

Parameter	Typ	Beschreibung
productId	string	Pflichtfeld ID des Produkts, dessen Bewertung gelöscht werden soll.
orderId	string	Pflichtfeld ID der Bestellung, über die die Bewertung dem Kauf zugeordnet ist.

​

Methoden für Bewertungsübersichten je Produkt

Diese Methoden stellen alle freigegebenen Kundenbewertungen sowie aggregierte Bewertungsinformationen für ein bestimmtes Produkt bereit.

​

GET productRating/list

Mit dieser Methode werden alle für das angegebene Produkt verfügbaren Kundenbewertungen abgerufen.

Die zurückgegebenen Daten können im Frontend z. B. für die Anzeige einer vollständigen Bewertungsübersicht auf der Produktdetailseite oder in separaten Bewertungslisten verwendet werden.

Beispiel-Aufruf, um alle Kundenbewertungen für das Produkt mit der ID 99-0984 anzeigen zu lassen

GET https://<ihr-shop>.de/api/v1/productRating/list?productId=99-0984

Beispiel-Response

{
   "items" : [
      {
         "accountId" : "126",
         "accountType" : 2,
         "anonymous" : false,
         "answeredAt" : "",
         "approval" : true,
         "createdAt" : "1970-01-01T00:00:00.000Z",
         "description" : "Beschreibung",
         "disapprovalReason" : "",
         "displayName" : "Max Mustermann",
         "merchantComment" : "",
         "points" : 5,
         "productId" : "99-0984",
         "subject" : "Titel",
         "subshopId" : "deutsch"
      }
   ]
}

Parameterübersicht

Header-Parameter

Parameter	Beschreibung
x-session	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

Body-Parameter

Parameter	Typ	Beschreibung
productId	string	Pflichtfeld ID des Produkts, für das Bewertungen abgerufen werden sollen.

​

GET productRating/statistics

Mit dieser Methode werden die aus allen freigegebenen Kundenbewertungen berechneten Kennzahlen für das angegebene Produkt abgerufen, insbesondere der durchschnittliche Bewertungswert und die Anzahl der berücksichtigten Bewertungen.

Die Daten eignen sich insbesondere für kompakte Darstellungen wie Bewertungssterne und kurze Bewertungszusammenfassungen auf Produktdetailseiten oder Übersichtsseiten.

Beispiel-Aufruf, um die Statistik für die Kundenbewertungen für das Produkt mit der ID 99-0984 zu laden

GET https://<ihr-shop>.de/api/v1/productRating/statistics?productId=99-0984

​

Parameterübersicht

​

Header-Parameter

Parameter	Beschreibung
x-session	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

​

Body-Parameter

Parameter	Typ	Beschreibung
productId	string	Pflichtfeld ID des Produkts, für das Bewertungen abgerufen werden sollen.

​

Beispiel-Response

{
   "averageRating" : 5,
   "productId" : "99-0984",
   "totalRatingCount" : 1
}