> ## 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.

# 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-session`mitgegeben werden. Mehr dazu [hier](https://websaleag-44ee7ea6.mintlify.app/schnittstellen/storefront-api/storefront-api-basics#3-session-handling).

***

## Unterstützte Methoden

Angabe aller Unterstützten Methoden.

| **Befehl**                                    | **Endpunkte**              | **GET**               | **POST**              | **PUT**               | **DELETE**            |
| --------------------------------------------- | -------------------------- | --------------------- | --------------------- | --------------------- | --------------------- |
| Letzte Bewertung abrufen                      | `account/rating/latest`    | <Icon icon="check" /> | <Icon icon="ban" />   | <Icon icon="ban" />   | <Icon icon="ban" />   |
| Alle Bewertungen aufrufen                     | `account/rating/list`      | <Icon icon="check" /> | <Icon icon="ban" />   | <Icon icon="ban" />   | <Icon icon="ban" />   |
| Existenz einer Bewertung prüfen               | `productRating/check`      | <Icon icon="check" /> | <Icon icon="ban" />   | <Icon icon="ban" />   | <Icon icon="ban" />   |
| Eine bestimmte Bewertung abrufen              | `productRating/get`        | <Icon icon="check" /> | <Icon icon="ban" />   | <Icon icon="ban" />   | <Icon icon="ban" />   |
| Alle Bewertungen eines Produkts abrufen       | `productRating/get`        | <Icon icon="check" /> | <Icon icon="ban" />   | <Icon icon="ban" />   | <Icon icon="ban" />   |
| Bewertungsdurchschnitt eines Produkts abrufen | `productRating/statistics` | <Icon icon="check" /> | <Icon icon="ban" />   | <Icon icon="ban" />   | <Icon icon="ban" />   |
| Bewertung erstellen                           | `productRating/add`        | <Icon icon="ban" />   | <Icon icon="check" /> | <Icon icon="ban" />   | <Icon icon="ban" />   |
| Bewertung aktualisieren                       | `productRating/update`     | <Icon icon="ban" />   | <Icon icon="ban" />   | <Icon icon="check" /> | <Icon icon="ban" />   |
| Bewertung löschen                             | `productRating/update`     | <Icon icon="ban" />   | <Icon icon="ban" />   | <Icon icon="ban" />   | <Icon icon="check" /> |

## 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**

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<ihr-shop>.de/api/v1/account/rating/latest
```

#### Beispiel-Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
   "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**<br />ID der aktuellen Session.   <br />Mehr Informationen dazu: [Storefront API Basics](../storefront-api/storefront-api-basics.md#2-session-handling) |

### 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.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<ihr-shop>.de/api/v1/account/rating/list
```

#### Parameterübersicht

#### Header-Parameter

| **Parameter** | **Beschreibung**                                                                                                                                                                                                        |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session`   | **Pflichtfeld**<br />ID der aktuellen Session.   <br />Mehr Informationen dazu: [Storefront API Basics](https://websaleag-44ee7ea6.mintlify.app/schnittstellen/storefront-api/storefront-api-basics#3-session-handling) |

#### Beispiel-Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "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** `99`**aus der Bestellung** `0404-12 `**abzurufen**

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<ihr-shop>.de/api/v1/productRating/get?productId=99-0984&orderId=0404-12
```

#### Beispiel-Response

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{}
```

#### Parameterübersicht

#### Header-Parameter

| **Parameter** | **Beschreibung**                                                                                                                                                                                                        |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session`   | **Pflichtfeld**<br />ID der aktuellen Session.   <br />Mehr Informationen dazu: [Storefront API Basics](https://websaleag-44ee7ea6.mintlify.app/schnittstellen/storefront-api/storefront-api-basics#3-session-handling) |

#### 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**

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{ "exists": true }
```

#### Parameterübersicht

#### Header-Parameter

| **Parameter** | **Beschreibung**                                                                                                                                                                                                        |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session`   | **Pflichtfeld**<br />ID der aktuellen Session.   <br />Mehr Informationen dazu: [Storefront API Basics](https://websaleag-44ee7ea6.mintlify.app/schnittstellen/storefront-api/storefront-api-basics#3-session-handling) |

#### 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**

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
POST https://<ihr-shop>.de/api/v1/productRating/add
```

#### Beispiel-Request

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "productId": "99-0984",
  "orderId": "4900",
  "subject": "Titel",
  "description": "Meine Bewertung",
  "points": 5,
  "anonymous": false
}
```

#### Beispiel-Response

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{}
```

#### Parameterübersicht

#### Header-Parameter

| **Parameter** | **Beschreibung**                                                                                                                                                                                                        |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session`   | **Pflichtfeld**<br />ID der aktuellen Session.   <br />Mehr Informationen dazu: [Storefront API Basics](https://websaleag-44ee7ea6.mintlify.app/schnittstellen/storefront-api/storefront-api-basics#3-session-handling) |

#### 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](/konfiguration/general-allgemeine-shopeinstellungen#generalproductrating-produktbewertung) |
| `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**

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
PUT https://<ihr-shop>.de/api/v1/productRating/update 
```

#### Beispiel-Request

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "productId": "99-0984",
  "orderId": "4900",
  "subject": "Titel",
  "description": "Beschreibung",
  "points": 5,
  "anonymous": false
}
```

#### Beispiel-Response

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{}
```

#### Parameterübersicht

#### Header-Parameter

| **Parameter** | **Beschreibung**                                                                                                                                                                                                        |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session`   | **Pflichtfeld**<br />ID der aktuellen Session.   <br />Mehr Informationen dazu: [Storefront API Basics](https://websaleag-44ee7ea6.mintlify.app/schnittstellen/storefront-api/storefront-api-basics#3-session-handling) |

#### 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](/konfiguration/general-allgemeine-shopeinstellungen#generalproductrating-produktbewertung) |
| `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**

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
DELETE https://<ihr-shop>.de/api/v1/productRating/update
```

#### Beispiel-Request

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "productId": "99-0984",
  "orderId": "4900"
}
```

#### Beispiel-Response

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{}
```

#### Parameterübersicht

#### Header-Parameter

| **Parameter** | **Beschreibung**                                                                                                                                                                                                        |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session`   | **Pflichtfeld**<br />ID der aktuellen Session.   <br />Mehr Informationen dazu: [Storefront API Basics](https://websaleag-44ee7ea6.mintlify.app/schnittstellen/storefront-api/storefront-api-basics#3-session-handling) |

#### Body-Parameter

| **Parameter** | **Typ** | **Beschreibung**                                                                        |
| ------------- | ------- | --------------------------------------------------------------------------------------- |
| `productId`   | string  | **Pflichtfeld**<br />ID des Produkts, dessen Bewertung gelöscht werden soll.            |
| `orderId`     | string  | **Pflichtfeld**<br />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**

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<ihr-shop>.de/api/v1/productRating/list?productId=99-0984
```

**Beispiel-Response**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
   "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**<br />ID der aktuellen Session.   <br />Mehr Informationen dazu: [Storefront API Basics](https://websaleag-44ee7ea6.mintlify.app/schnittstellen/storefront-api/storefront-api-basics#3-session-handling) |

**Body-Parameter**

| **Parameter** | **Typ** | **Beschreibung**                                                                   |
| ------------- | ------- | ---------------------------------------------------------------------------------- |
| `productId`   | string  | **Pflichtfeld**<br />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**

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<ihr-shop>.de/api/v1/productRating/statistics?productId=99-0984
```

#### Parameterübersicht

#### Header-Parameter

| **Parameter** | **Beschreibung**                                                                                                                                                                                                        |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session`   | **Pflichtfeld**<br />ID der aktuellen Session.   <br />Mehr Informationen dazu: [Storefront API Basics](https://websaleag-44ee7ea6.mintlify.app/schnittstellen/storefront-api/storefront-api-basics#3-session-handling) |

#### Body-Parameter

| **Parameter** | **Typ** | **Beschreibung**                                                                   |
| ------------- | ------- | ---------------------------------------------------------------------------------- |
| `productId`   | string  | **Pflichtfeld**<br />ID des Produkts, für das Bewertungen abgerufen werden sollen. |

#### Beispiel-Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
   "averageRating" : 5,
   "productId" : "99-0984",
   "totalRatingCount" : 1
}
```