Skip to main content

Documentation Index

Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt

Use this file to discover all available pages before exploring further.

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.
BefehlEndpunkteGETPOSTPUTDELETE
Letzte Bewertung abrufenaccount/rating/latest
Alle Bewertungen aufrufenaccount/rating/list
Existenz einer Bewertung prüfenproductRating/check
Eine bestimmte Bewertung abrufenproductRating/get
Alle Bewertungen eines Produkts abrufenproductRating/get
Bewertungsdurchschnitt eines Produkts abrufenproductRating/statistics
Bewertung erstellenproductRating/add
Bewertung aktualisierenproductRating/update
Bewertung löschenproductRating/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

ParameterBeschreibung
x-sessionPflichtfeld
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

ParameterBeschreibung
x-sessionPflichtfeld
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

ParameterBeschreibung
x-sessionPflichtfeld
ID der aktuellen Session.
Mehr Informationen dazu: Storefront API Basics

​
Body-Parameter

ParameterTypBeschreibung
productIdstringPflichtfeld ID des Produkts, für das die Bewertung abgegeben wurde.
orderIdstringPflichtfeld 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

ParameterBeschreibung
x-sessionPflichtfeld
ID der aktuellen Session.
Mehr Informationen dazu: Storefront API Basics

​
Body-Parameter

ParameterTypBeschreibung
productIdstringPflichtfeld ID des Produkts, für das geprüft wird, ob eine Bewertung existiert.
orderIdstringPflichtfeld 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

ParameterBeschreibung
x-sessionPflichtfeld
ID der aktuellen Session.
Mehr Informationen dazu: Storefront API Basics

​
Body-Parameter

ParameterTypBeschreibung
productIdstringPflichtfeld ID des Produkts, für das die Bewertung abgegeben werden soll.
orderIdstringPflichtfeld ID der Bestellung, mit der der Kauf des Produktes verbunden ist.
subjectstringKurzer Titel der Bewertung
descriptionstringFreitext der Bewertung für Produktbeschreibung / Feedback
pointsintPflichtfeld Bewertungswert. Dieser kann hier individuell festgelegt: general - Allgemeine Shopeinstellungen
anonymousboolVeröffentlicht die Bewertung ohne persönliche Zuordnung. Default: false

​
Fehlercodes

FehlercodeBeschreibung
orderNotExistsDie angegebene Bestellung existiert im System nicht.
duplicateRatingEs 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

ParameterBeschreibung
x-sessionPflichtfeld
ID der aktuellen Session.
Mehr Informationen dazu: Storefront API Basics

​
Body-Parameter

ParameterTypBeschreibung
productIdstringPflichtfeld ID des Produkts, für das die Bewertung aktualisiert werden soll.
orderIdstringPflichtfeld ID der Bestellung, mit der der Kauf des Produktes verbunden ist.
subjectstringKurzer Titel der Bewertung
descriptionstringFreitext der Bewertung für Produktbeschreibung / Feedback
pointsintBewertungswert. Dieser kann hier individuell festgelegt: general - Allgemeine Shopeinstellungen
anonymousboolVerö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

ParameterBeschreibung
x-sessionPflichtfeld
ID der aktuellen Session.
Mehr Informationen dazu: Storefront API Basics

​
Body-Parameter

ParameterTypBeschreibung
productIdstringPflichtfeld
ID des Produkts, dessen Bewertung gelöscht werden soll.
orderIdstringPflichtfeld
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
ParameterBeschreibung
x-sessionPflichtfeld
ID der aktuellen Session.
Mehr Informationen dazu: Storefront API Basics
Body-Parameter
ParameterTypBeschreibung
productIdstringPflichtfeld
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

ParameterBeschreibung
x-sessionPflichtfeld
ID der aktuellen Session.
Mehr Informationen dazu: Storefront API Basics

​
Body-Parameter

ParameterTypBeschreibung
productIdstringPflichtfeld
ID des Produkts, für das Bewertungen abgerufen werden sollen.

​
Beispiel-Response

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