> ## 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.
# API-Referenz Gutscheine
> Gutscheine, Chargen, Blaupausen und Vorlagen über die Admin Interface API anlegen, abrufen und löschen sowie Bulk-Aktionen ausführen.
Der Endpunkt `vouchers/` stellt Ihnen eine Schnittstelle zur Verfügung mit der Sie Gutscheine in unserem Shop-System verwalten können. Mit dieser Schnittstelle können Sie Gutscheine erzeugen, löschen, Vorlagen erstellen und und vorhandene Gutscheine einsehen.
***
## Unterstützte Methoden
Angabe aller unterstützten Methoden.
| **Befehl/Info** | **Endpunkte** | **GET** | **PUT** | **POST** | **DELETE** |
| ------------------------ | ------------------- | --------------------- | --------------------- | --------------------- | --------------------- |
| **Gutscheine** | vouchers/ | | | | |
| **Gutscheine (Bulk)** | vouchers/bulk | | | | |
| **Gutschein-Chargen** | vouchers/charges/ | | | | |
| **Gutschein-Blaupausen** | vouchers/templates/ | | | | |
| **Gutschein-Vorlagen** | vouchers/presets/ | | | | |
## Datenfelder
### Datenfelder eines Gutscheins
| Name | Typ | Bedeutung |
| --------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------ |
| active | Boolean | Gibt an, ob der Gutschein aktiv ist (true = aktiv, false = deaktiviert). |
| chargeId | String | ID der Charge, zu der der Gutschein gehört. |
| createdAt | String | Zeitpunkt der Erstellung des Gutscheins. |
| id | String | Eindeutige ID des Gutscheins. |
| labels | String\[] | Tags oder Bezeichnungen zur Gruppierung oder Identifikation des Gutscheins (z. B. Marketingaktionen). |
| maxUseCount | Integer | Maximale Anzahl an Einlösungen, bevor der Gutschein deaktiviert wird. |
| pool | Boolean | Gibt an, ob der Gutschein Teil eines Pools ist (gemeinsamer Kontingent). |
| types.appOnly | Boolean | Gutschein kann nur über die App eingelöst werden. |
| types.discount | Boolean | Werbegutschein / Kaufgutschein |
| types.freeShipping | Boolean | Gutschein gewährt kostenlosen Versand. |
| types.keepSurplus | Boolean | Verbleibender Restwert darf behalten und später erneut eingelöst werden. |
| types.multipleCustomer | Boolean | Gutschein ist mehrfach von verschiedenen Kunden einlösbar. |
| types.newCustomersOnly | Boolean | Gutschein darf nur von Neukunden verwendet werden. |
| types.existingCustomersOnly | Boolean | Gutschein darf nur von Bestandskunden verwendet werden. Kann nicht zusammen mit `types.newCustomersOnly` gesetzt werden. |
| types.maxUseCountSet | Boolean | Gutschein ist pro Benutzer begrenzt einlösbar. |
| types.maxUseCountPerUser | Integer | Maximale Anzahl an Einlösungen pro Benutzer |
| updatedAt | String | Zeitpunkt der letzten Aktualisierung des Gutscheins. |
| validCustomers\[].id | Integer | ID eines Kunden, der berechtigt ist, den Gutschein einzulösen. |
| validCustomers\[].number | String | Kundennummer eines berechtigten Kunden. |
| validProducts\[].number | String | Produktnummer, für das der Gutschein gültig ist. |
| validProducts\[].quantity | Integer | Mindestanzahl des Produkts im Warenkorb, damit Gutschein gilt. |
| validSubshops\[] | String\[] | Liste der Subshop-IDs, in denen der Gutschein gültig ist. |
| values\[].currency | String | Währungscode (z. B. EUR, GBP), für den der jeweilige Wert gilt. |
| values\[].percentValue | Float | Prozentualer Rabatt (z. B. 0.1 für 10 %). |
| values\[].taxId | String | Steuer-ID, die auf den Gutscheinwert angewendet wird. |
| values\[].usedValue | Float | Bereits eingelöster Wert des Gutscheins (für Mehrfachnutzung). |
| values\[].value | Float | Gesamtwert des Gutscheins in der jeweiligen Währung. |
| values\[].minOrderValue | Float | Mindestbestellwert in der Währung, um den Gutschein einzulösen. |
#### Beispiel
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"active": true,
"chargeId": "example-charge",
"createdAt": "2025-01-17T07:57:26.000Z",
"id": "VOUCHER-XY57Z3",
"labels": [
"summer2025"
],
"maxUseCount": 5,
"pool": false,
"types": {
"appOnly": false,
"discount": false,
"freeShipping": false,
"keepSurplus": true,
"multipleCustomer": false,
"newCustomersOnly": false,
"maxUseCountPerUser": 122,
"maxUseCountSet": true
},
"updatedAt": "2025-01-17T07:57:26.000Z",
"validCustomers": [
{
"id": 48
},
{
"number": "1234"
}
],
"validProducts": [
{
"number": "go1",
"quantity": 1
}
],
"validSubshops": [
"deutsch"
],
"values": [
{
"currency": "EUR",
"percentValue": 0.0,
"taxId": "",
"usedValue": 10.0,
"value": 42.0
},
{
"currency": "GBP",
"minOrderValue": 50.0,
"percentValue": 0.0,
"taxId": "",
"value": 10.0
}
]
}
```
### Datenfelder einer Gutschein-Charge
| **Name** | **Typ** | **Bedeutung** |
| ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **createdAt** | String | Zeitpunkt der Erstellung der Gutscheinladung (ISO 8601-Format, UTC). |
| **creator** | Integer | ID des Benutzers, der die Charge erstellt hat. |
| **description** | String | Freitextbeschreibung der Gutschein-Charge. |
| **id** | String | Eindeutige ID der Gutschein-Charge. |
| **name** | String | Name der Gutschein-Charge. |
| **redeemed** | Integer | Gibt an, ob Gutscheine der Charge eingelöst wurden. Mögliche Werte: `0 = NotRedeemed1 = PartiallyRedeemed2 = Redeemed` |
| **updatedAt** | String | Zeitpunkt der letzten Aktualisierung der Charge (ISO 8601-Format, UTC). |
| **voucherChargeCount** | Integer | Anzahl der mit dieser Charge erstellten Gutscheine. |
| **voucherData** | Objekt | Details zu Gutscheinen. Alle Felder stimmen mit [den Feldern der Gutscheine](https://websale.atlassian.net/wiki/spaces/WSDOKU/pages/3058532517/API-Referenz+Gutscheine#21-datenfelder-eines-gutscheins) überein. |
#### Beispiel
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"createdAt": "2025-04-11T13:25:53.000Z",
"creator": 1,
"description": "",
"id": "82",
"name": "myCharge",
"redeemed": 0,
"updatedAt": "2025-04-11T13:25:53.000Z",
"voucherChargeCount": 1,
"voucherData": {
"labels": [
"82"
],
"maxUseCount": 999,
"pool": false,
"types": {
"appOnly": false,
"discount": true,
"freeShipping": true,
"keepSurplus": false,
"maxUseCountSet": false,
"multipleCustomer": true,
"newCustomersOnly": false
},
"validProducts": [
{
"id": "100-41232",
"quantity": 1
}
],
"values": [
{
"currency": "EUR",
"minOrderValue": 1,
"percentValue": 0,
"taxId": "19",
"usedValue": 0,
"value": 55
}
]
}
}
```
### Datenfelder einer Gutschein-Blaupause
| **Name** | **Typ** | **Bedeutung** |
| ------------------------- | ------- | -------------------------------------------------------------------------- |
| **active (optional)** | Boolean | Gibt an, ob die Blaupause aktiv ist. |
| **createdAt** | String | Zeitpunkt, zu dem die Blaupause erstellt wurde (ISO 8601-Format, UTC). |
| **templateId** | String | Technische ID oder eindeutiger Name der Gutscheinblaupause. |
| **updatedAt** | String | Zeitpunkt der letzten Aktualisierung der Blaupause (ISO 8601-Format, UTC). |
| **validFrom (optional)** | String | Beginn der Gültigkeit. |
| **validUntil (optional)** | String | Ende der Gültigkeit. |
Weitere Felder stimmen mit [den Feldern der Gutscheine](/schnittstellen/admin-interface-api/api-referenz-gutscheine) überein.
#### Beispiel
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"active": true,
"chargeId": "53",
"createdAt": "2025-04-09T08:57:59.000Z",
"labels": [],
"templateId": "newTemplateName2",
"types": {
"appOnly": false,
"discount": false,
"freeShipping": false,
"keepSurplus": false,
"maxUseCountSet": false,
"multipleCustomer": false,
"newCustomersOnly": false
},
"updatedAt": "2025-04-29T08:48:39.000Z",
"values": [
{
"currency": "EUR",
"minOrderValue": 10,
"percentValue": 0,
"taxId": "",
"value": 1
}
]
}
```
### Datenfelder einer Gutschein-Vorlage
| **Name** | **Typ** | **Bedeutung** |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **createdAt** | String | Zeitpunkt, zu dem die Vorlage erstellt wurde (ISO 8601-Format, UTC). |
| **updatedAt** | String | Zeitpunkt der letzten Aktualisierung der Vorlage (ISO 8601-Format, UTC). |
| **presetId** | String | Technische ID oder eindeutiger Name der Gutscheinvorlage. |
| **system** | Boolean | Gibt an, ob die Vorlage von Websale bereitgestellt wurde. Bei solchen Vorlagen können nicht alle Felder bearbeitet werden. |
| **data.count** | Integer | Anzahl der Gutscheine |
| **data.data** | Objekt | Details zum Gutschein. Alle Felder stimmen mit [den Feldern der Gutscheine](/schnittstellen/admin-interface-api/api-referenz-gutscheine) überein. |
#### Beispiel
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"createdAt": "1970-01-01T00:33:45.000Z",
"data": {
"count": 1,
"data": {
"active": true,
"basketProducts": [],
"chargeId": "",
"labels": [],
"maxUseCount": 19,
"name": "myPreset",
"types": {
"appOnly": false,
"discount": true,
"freeShipping": false,
"keepSurplus": false,
"maxUseCountSet": false,
"multipleCustomer": true
},
"values": [
{
"currency": "GBP",
"minOrderValue": 40,
"taxId": "19",
"value": 20
}
]
}
},
"presetId": "myPreset",
"system": false,
"updatedAt": "1970-01-01T00:33:45.000Z"
}
```
## Methoden zur Verwaltung von Gutscheinen
In diesem Abschnitt werden alle Endpunkte zur Verwaltung einzelner Gutscheine beschrieben. Über die Schnittstelle können Gutscheine erstellt, aktualisiert, gelöscht und abgerufen werden. Die Verwaltung von Gutschein-Chargen wird in einem eigenen Abschnitt separat behandelt.
Für alle Operationen sind entsprechende Lese-, Schreib-, Erstell- oder Löschberechtigungen erforderlich.
### GET vouchers
Diese Methode liefert eine paginierte Liste aller im System vorhandenen Gutscheine.
Über Filter- und Sortierparameter können die Ergebnisse gezielt eingeschränkt und geordnet werden. Die zurückgegebenen Gutscheindaten umfassen Informationen zu Aktivität, Gültigkeit, Einlösebedingungen und Wertangaben.
Für den Zugriff sind Leseberechtigungen erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers?size=100
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"endReached": true,
"items": [
{
"active": true,
"chargeId": "example-charge",
"createdAt": "2025-01-17T07:57:26.000Z",
"id": "VOUCHER-XY57Z3",
"labels": [
"summer2025"
],
"maxUseCount": 5,
"pool": false,
"types": {
"appOnly": false,
"discount": false,
"freeShipping": false,
"keepSurplus": true,
"multipleCustomer": false,
"newCustomersOnly": false,
"maxUseCountSet": false
},
"updatedAt": "2025-01-17T07:57:26.000Z",
"validCustomers": [
{
"id": 48
},
{
"number": "1234"
}
],
"validProducts": [
{
"number": "go1",
"quantity": 1
}
],
"validSubshops": [
"deutsch"
],
"values": [
{
"currency": "EUR",
"percentValue": 0.0,
"taxId": "",
"usedValue": 10.0,
"value": 42.0
},
{
"currency": "GBP",
"minOrderValue": 50.0,
"percentValue": 0.0,
"taxId": "",
"value": 10.0
}
]
}
],
"nextPageToken": "Mw",
"totalCount": 1
}
```
#### Filterfelder
`id`, `active`, `pool`, `chargeId`, `createdAt`, `updatedAt`, `validFrom`, `validUntil`, `maxUseCount`
#### Sortierfelder
`id`, `active`, `pool`, `chargeId`, `createdAt`, `updatedAt`, `validFrom`, `validUntil`, `maxUseCount`
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Gutschein-Daten. |
| 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 ":". |
### PUT vouchers/\{id} - Coming soon
Diese Methode aktualisiert die Eigenschaften eines bestehenden Gutscheins anhand seiner eindeutigen ID. Über den Request-Body können verschiedene Felder wie Aktivierungsstatus, Gültigkeitszeiträume, Werte oder Einlösebedingungen geändert werden. Nach erfolgreicher Aktualisierung wird eine Bestätigung zurückgegeben.
Schreibberechtigungen für Gutschein-Daten sind erforderlich.
Diese Methode ist derzeit noch nicht implementiert und für eine zukünftige Version geplant.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/1CUA-8341-FD8Q-KPJ2
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"updateVoucher": "not implemented"
}
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Gutschein-Daten. |
### POST vouchers
Diese Methode erstellt einen oder mehrere neue Gutscheine. Die Gutscheine können entweder einer neuen Charge zugeordnet oder an eine bestehende Charge angehängt werden. Damit eine neue Charge erstellt wird, muss das Feld `chargeId` im Request Body leer sein.
Pro Anfrage können maximal 10.000 Gutscheine erstellt werden. Nach erfolgreicher Erstellung werden die zugehörige Charge-ID sowie die Anzahl der erzeugten Gutscheine zurückgegeben.
Erstellberechtigungen für Gutschein-Daten sind erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers
```
#### Request Body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"count": 1,
"data": {
"active": true,
"name": "cvcv89",
"chargeId": "",
"maxUseCount": 1,
"values": [
{
"value": 55,
"currency": "GBP",
"minOrderValue": 55,
"taxId": ""
}
],
"types": {
"keepSurplus": false,
"discount": true,
"freeShipping": false,
"maxUseCountPerUser": 1,
"maxUseCountSet": true,
"multipleCustomer": true,
"appOnly": false
},
"basketProducts": [],
"labels": []
}
}
```
#### Antwort
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"success": true,
"chargeId": "122",
"count": 1
}
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Erstellen von Gutschein-Daten. |
| 400 Bad Request | | Request body konnte nicht geladen werden. |
| 400 Bad Request | "invalidFormat" | `count` ist keine Zahl.
`data` ist kein Objekt. |
| 400 Bad Request | "missing" | `data` fehlt.
`appendToCharge` ist `true`, und `chargeId` fehlt. |
| 400 Bad Request | "invalidValue" | `count` ∉ \[1;10000] |
| 400 Bad Request | "invalidCombination" | `count` ≠ 1 und `voucherId` ist nicht leer. Beim Erstellen von mehreren Gutscheinen wird die Id automatisch generiert und kann nicht manuell gesetzt werden.
`newCustomersOnly` und `existingCustomersOnly` sind gesetzt. |
| 400 Bad Request | "duplicateEntry" | `voucherId` oder `chargeId` existieren bereits. |
| 400 Bad Request | "unknownDataField" | Ein unbekanntes Feld wurde im Request Body übergeben. |
### DELETE vouchers/\{id}
Diese Methode löscht einen bestehenden Gutschein anhand seiner eindeutigen ID.
Nach erfolgreicher Löschung wird die ID des entfernten Gutscheins als Bestätigung zurückgegeben.
Für die Ausführung sind Löschberechtigungen für Gutschein-Daten erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/ZZ3R-2ZPC-UDGF-S6DG
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"id": "ZZ3R-2ZPC-UDGF-S6DG"
}
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Löschen von Gutschein-Daten. |
| 400 Bad Request | "notFound" | Der Gutschein wurde nicht gefunden. |
### POST vouchers/bulk
Diese Methode ermöglicht das Erstellen oder Aktualisieren mehrerer Gutscheine in einem einzigen Request (Massenimport). Der Request Body muss ein JSON-Array enthalten, in dem jedes Element ein Objekt mit einem `data`-Feld ist, das die Gutscheindaten enthält.
Pro Anfrage können maximal 10.000 Einträge übergeben werden. Ungültige Einträge werden übersprungen und in der Antwort unter `skippedLines` aufgeführt.
Falls ein Gutschein mit derselben ID bereits existiert, wird geprüft, ob die Daten kompatibel sind. Mit dem Query-Parameter `?force` kann ein Update erzwungen werden.
Erstellberechtigungen für Gutschein-Daten sind erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/bulk
```
#### Query-Parameter
| **Parameter** | **Typ** | **Bedeutung** |
| ------------- | ------- | ----------------------------------------------------------------------------------------------------- |
| force | Flag | Wenn gesetzt, werden bestehende Gutscheine mit derselben ID ohne Kompatibilitätsprüfung aktualisiert. |
#### Request Body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
[
{
"data": {
"id": "BULK-0001",
"active": true,
"chargeId": "charge-1",
"maxUseCount": 1,
"values": [
{
"value": 10,
"currency": "EUR",
"minOrderValue": 20,
"taxId": ""
}
],
"types": {
"keepSurplus": false,
"discount": true,
"freeShipping": false,
"maxUseCountPerUser": 1,
"maxUseCountSet": true,
"multipleCustomer": false,
"appOnly": false
},
"basketProducts": [],
"labels": ["import-2025"]
}
},
{
"data": {
"id": "BULK-0002",
"active": true,
"chargeId": "charge-1",
"maxUseCount": 5,
"values": [
{
"value": 25,
"currency": "EUR",
"minOrderValue": 50,
"taxId": ""
}
],
"types": {
"keepSurplus": true,
"discount": false,
"freeShipping": false,
"maxUseCountPerUser": 1,
"maxUseCountSet": false,
"multipleCustomer": true,
"appOnly": false
},
"basketProducts": [],
"labels": []
}
}
]
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"items": [
"BULK-0001",
"BULK-0002"
],
"skippedLines": []
}
```
#### Antwort mit übersprungenen Zeilen
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"items": [
"BULK-0001"
],
"skippedLines": [
{
"lineNumber": 2,
"errorType": "invalidParameters",
"fieldErrors": {
"data": "invalidFormat"
}
}
]
}
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Erstellen von Gutschein-Daten. |
| 400 Bad Request | | Request Body konnte nicht geladen werden oder ist kein Array. |
| 400 Bad Request | "invalidFormat" | Ein Element im Array enthält kein gültiges `data`-Objekt. |
| 400 Bad Request | "invalidValue" | Die Charge-ID (`chargeId`) existiert bereits mit einem anderen Typ. |
| 400 Bad Request | "invalidCombination" | `newCustomersOnly` und `existingCustomersOnly` sind gleichzeitig gesetzt. |
### DELETE vouchers/bulk
Diese Methode ermöglicht das Löschen mehrerer Gutscheine in einem einzigen Request. Der Request Body muss ein JSON-Array enthalten, in dem jedes Element ein Objekt mit der `id` des zu löschenden Gutscheins ist.
Pro Anfrage können maximal 10.000 Einträge übergeben werden. Ungültige Einträge werden übersprungen und in der Antwort unter `skippedItems` aufgeführt.
Löschberechtigungen für Gutschein-Daten sind erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/bulk
```
#### Request Body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
[
{
"id": "BULK-0001"
},
{
"id": "BULK-0002",
"pool": true
}
]
```
#### Datenfelder pro Eintrag
| **Feld** | **Typ** | **Pflicht** | **Bedeutung** |
| -------- | ------- | ----------- | ------------------------------------------------------------------------ |
| id | String | Ja | Die eindeutige ID des zu löschenden Gutscheins. |
| pool | Boolean | Nein | Gibt an, ob es sich um einen Pool-Gutschein handelt (Standard: `false`). |
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"items": [
"BULK-0001",
"BULK-0002"
],
"skippedItems": []
}
```
#### Antwort mit übersprungenen Einträgen
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"items": [
"BULK-0001"
],
"skippedItems": [
{
"lineNumber": 2,
"errorType": "invalidParameters",
"fieldErrors": {
"id": "missing"
}
}
]
}
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Löschen von Gutschein-Daten. |
| 400 Bad Request | | Request Body konnte nicht geladen werden oder ist kein Array. |
| 400 Bad Request | "invalidFormat" | Ein Element im Array ist kein gültiges JSON-Objekt. |
| 400 Bad Request | "missing" | Das Pflichtfeld `id` fehlt in einem Eintrag. |
## Methoden für Gutschein-Chargen
In diesem Abschnitt werden alle Endpunkte zur Verwaltung von Gutschein-Chargen beschrieben. Eine Gutschein-Charge ist eine Gruppe von Gutscheinen, die gemeinsam erstellt und verwaltet werden können.
Über die Schnittstelle können Chargen aufgelistet, gefiltert, erstellt, aktualisiert, exportiert und gelöscht werden. Zudem können Ersteller-Informationen und Labels von bestehenden Chargen abgerufen werden.
Für alle Operationen sind entsprechende Lese-, Schreib-, Erstell- oder Löschberechtigungen erforderlich.
### GET vouchers/charges
Diese Methode liefert eine paginierte Liste aller im System vorhandenen Gutschein-Chargen.
Über Filter- und Sortierparameter kann die Liste nach verschiedenen Kriterien eingeschränkt und geordnet werden. Die zurückgegebenen Daten enthalten Informationen zur Charge selbst sowie zu den zugehörigen Gutschein-Einstellungen.
Für den Zugriff sind Leseberechtigungen erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/charges?size=100
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"endReached": true,
"items": [
{
"createdAt": "2025-01-17T07:56:50.000Z",
"creator": 0,
"description": "Example Charge",
"id": "example-charge",
"name": "Example Charge",
"redeemed": 0,
"updatedAt": "2025-01-17T07:56:50.000Z",
"voucherChargeCount": 1,
"voucherData": {
"labels": [
"bar"
],
"maxUseCount": 5,
"pool": false,
"types": {
"appOnly": false,
"discount": false,
"freeShipping": false,
"keepSurplus": true,
"multipleCustomer": false,
"newCustomersOnly": false,
"maxUseCountSet": false
},
"validCustomers": [
{
"id": 48
},
{
"number": "1234"
}
],
"validProducts": [
{
"number": "go1",
"quantity": 1
}
],
"validSubshops": [
"deutsch"
],
"values": [
{
"currency": "EUR",
"percentValue": 0.0,
"taxId": "",
"usedValue": 10.0,
"value": 42.0
},
{
"currency": "GBP",
"minOrderValue": 50.0,
"percentValue": 0.0,
"taxId": "",
"value": 10.0
}
]
}
}
],
"nextPageToken": "MQ",
"totalCount": 1
}
```
#### Filterfelder
`id`, `createdAt`, `updatedAt`, `type`, `name`, `creator`, `labels`, `description`
#### Sortierfelder
`id`, `createdAt`, `updatedAt`, `type`, `name`, `creator`, `description`
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Gutschein-Daten. |
| 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 vouchers/charges/creators
Diese Methode liefert eine Liste der Benutzerkonten mit Ids und E-Mails, die Gutschein-Chargen erstellt haben. Bei manuell angelegten Chargen entspricht der Name der E-Mail-Adresse des Benutzerkontos, bei importierten Chargen wird stattdessen "Import" angezeigt.
Für den Zugriff sind Leseberechtigungen erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/charges/creators
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
[
{
"id": 42,
"name": "m.mustermann@websale.de"
}
]
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Gutschein-Daten. |
### GET vouchers/charges/labels
Diese Methode liefert eine Liste aller vergebenen Labels für Gutschein-Chargen. Labels dienen der Kategorisierung von Chargen und werden bei der Volltextsuche berücksichtigt.
Der Zugriff auf diese Informationen setzt Leseberechtigungen für Gutschein-Daten voraus.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/charges/labels
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
[ "label1", "label2" ]
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Gutschein-Daten. |
### PUT vouchers/charges/\{chargeid} - Coming soon
Diese Methode aktualisiert die Eigenschaften einer bestehenden Gutschein-Charge anhand ihrer eindeutigen ID. Über den Request-Body können Felder wie Name, Beschreibung oder zusätzliche Labels geändert werden. Nach erfolgreicher Aktualisierung wird eine Bestätigung zurückgegeben.
Schreibberechtigungen für Gutschein-Daten sind erforderlich.
Diese Methode ist derzeit noch nicht implementiert und für eine zukünftige Version geplant.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/charges/123456789
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"updateCharge": "not implemented"
}
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Gutschein-Daten. |
### DELETE vouchers/charges/\{chargeid}
Diese Methode löscht eine bestehende Gutschein-Charge samt aller darin enthaltenen Gutscheine anhand der angegebenen Charge-ID. Nach erfolgreicher Löschung wird die ID der entfernten Charge als Bestätigung zurückgegeben.
Für die Ausführung sind Löschberechtigungen für Gutschein-Daten erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/charges/123456789
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"chargeId": "123456789"
}
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Löschen von Gutschein-Daten. |
| 400 Bad Request | "notFound" | Die Charge wurde nicht gefunden. |
## Methoden für Gutschein-Blaupausen
In diesem Abschnitt werden alle Endpunkte zur Verwaltung von Gutschein-Blaupausen (Templates) beschrieben. Gutschein-Blaupausen definieren vordefinierte Konfigurationen wie Rabatttypen, Gültigkeitszeiträume, Werte und weitere Bedingungen für Gutscheine. Über die Schnittstelle können Blaupausen erstellt, aktualisiert, abgerufen, gelöscht und mit Labels organisiert werden.
**Hinweis:** Das Feld `templateId` entspricht intern der Spalte `name` in der Datenbank. Trotz dieser Zuordnung darf im Rahmen der API jedoch nicht nach `name` sortiert, gefiltert oder der Wert explizit abgefragt oder gesetzt werden. Alle Vorgänge erfolgen ausschließlich über `templateId`.
Für alle Operationen sind entsprechende Lese-, Schreib-, Erstell- oder Löschberechtigungen erforderlich.
### GET vouchers/templates
Diese Methode liefert eine paginierte Liste aller vorhandenen Gutschein-Blaupausen (Templates). Über Filter- und Sortierparameter kann die Liste eingeschränkt und geordnet werden. Die Blaupausen definieren Standardwerte für Gutscheine oder Gutschein-Chargen, die später auf Basis dieser Blaupausen erstellt werden können.
Für den Zugriff sind Leseberechtigungen erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/templates
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"endReached": true,
"items": [
{
"active": true,
"chargeId": "template-charge",
"createdAt": "2025-02-19T12:45:47.000Z",
"labels": [],
"templateId": "Example Template",
"types": {
"appOnly": false,
"discount": false,
"freeShipping": false,
"keepSurplus": false,
"multipleCustomer": false,
"newCustomersOnly": false,
"maxUseCountSet": false
},
"updatedAt": "2025-02-19T12:45:47.000Z",
"values": [
{
"currency": "EUR",
"minOrderValue": 0.0,
"percentValue": 0.0,
"taxId": "",
"value": 1.0
}
]
}
],
"nextPageToken": "MA",
"totalCount": 1
}
```
#### Filterfelder
`templateId`, `chargeId`, `labels`, `value`, `active`, `createdAt`, `updatedAt`, `validFrom`, `validUntil`, `maxUseCount`
#### Sortierfelder
`id`, `templateId`, `chargeId`, `createdAt`, `updatedAt`, `active`, `validFrom`, `validUntil`, `maxUseCount`
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Gutschein-Daten. |
| 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 vouchers/templates/labels
Diese Methode liefert eine Liste aller vergebenen Labels, die bei Gutschein-Blaupausen (Templates) verwendet wurden. Labels dienen der Kategorisierung von Blaupausen und werden bei der Volltextsuche berücksichtigt.
Für den Zugriff sind Leseberechtigungen erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/templates/labels
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
[ "label1", "label2" ]
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Gutschein-Daten. |
### PUT vouchers/templates/\{templateId}
Diese Methode aktualisiert die Eigenschaften einer bestehenden Gutschein-Blaupausen (Template) anhand ihrer eindeutigen ID, wobei die ID dem Namen der Blaupause entspricht.
Über den Request-Body können Felder wie Name, Status, Werte, Typen oder Labels angepasst werden. Nach erfolgreicher Aktualisierung wird die `templateId` der bearbeitete Blaupause zurückgegeben.
Schreibberechtigungen für Gutschein-Daten sind erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/templates/oldTemplateName
```
#### Anfrage
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"templateId": "newTemplateName",
"data": {
"active": true,
"chargeId": "54",
"createdAt": "2025-02-19T12:45:47.000Z",
"labels": [],
"types": {
"appOnly": false,
"discount": false,
"freeShipping": false,
"keepSurplus": false,
"multipleCustomer": false,
"newCustomersOnly": false,
"maxUseCountSet": false
},
"updatedAt": "2025-02-19T12:45:47.000Z",
"values": [
{
"currency": "EUR",
"minOrderValue": 0.0,
"percentValue": 0.0,
"taxId": "",
"value": 1.0
}
]
}
}
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"active": true,
"chargeId": "54",
"createdAt": "2025-02-19T12:45:47.000Z",
"labels": [],
"templateId": "newTemplateName",
"types": {
"appOnly": false,
"discount": false,
"freeShipping": false,
"keepSurplus": false,
"multipleCustomer": false,
"newCustomersOnly": false,
"maxUseCountSet": false
},
"updatedAt": "2025-02-19T12:45:47.000Z",
"values": [
{
"currency": "EUR",
"minOrderValue": 0.0,
"percentValue": 0.0,
"taxId": "",
"value": 1.0
}
]
}
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Gutschein-Daten. |
| 400 Bad Request | | Request body konnte nicht geladen werden. |
| 400 Bad Request | "invalidFormat" | `templateId` ist kein String.
`data` ist kein Objekt. |
| 400 Bad Request | "missing" | `templateId` oder `data` fehlt. |
| 400 Bad Request | "invalidValue" | `chargeId` verweist auf eine nicht existierende Charge. |
| 400 Bad Request | "duplicateEntry" | `name` oder `chargeId` wurden schon verwendet. |
| 400 Bad Request | "notFound" | Die Blaupause wurde nicht gefunden. |
| 400 Bad Request | "unknownDataField" | Ein unbekanntes Feld wurde im Request Body übergeben. |
### POST vouchers/templates
Diese Methode erstellt eine neue Gutschein-Blaupause (Template) anhand der übermittelten Konfigurationsdaten.
Der Request-Body muss eine eindeutige `templateId` sowie ein `data`-Objekt mit den relevanten Gutscheineinstellungen enthalten. Nach erfolgreicher Erstellung wird die ID der neuen Blaupause zurückgegeben.
Erstellberechtigungen für Gutschein-Daten sind erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/templates
```
#### Request Body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"templateId": "myNewTemplate",
"data": {
"data": {
"active": true,
"name": "myNewTemplate",
"chargeId": "",
"maxUseCount": 1,
"values": [
{
"value": 15,
"currency": "EUR",
"minOrderValue": 55,
"taxId": "19"
}
],
"types": {
"keepSurplus": false,
"discount": true,
"freeShipping": false,
"maxUseCountSet": false,
"multipleCustomer": true,
"appOnly": false
},
"basketProducts": [
{
"id": "100-41232"
}
],
"labels": [
"Summer"
]
},
"templateId": "myNewTemplate"
}
}
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"active": null,
"chargeId": "55",
"createdAt": "2025-02-19T12:45:47.000Z",
"labels": [
"Summer"
],
"templateId": "myNewTemplate",
"types": {
"appOnly": false,
"discount": true,
"freeShipping": false,
"keepSurplus": false,
"maxUseCountSet": false,
"multipleCustomer": true,
"newCustomersOnly": false
},
"updatedAt": "2025-02-19T12:45:47.000Z",
"values": [
{
"currency": "EUR",
"minOrderValue": 55,
"percentValue": 0,
"taxId": "19",
"value": 15
}
]
}
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Erstellen von Gutschein-Daten. |
| 400 Bad Request | | Request body konnte nicht geladen werden. |
| 400 Bad Request | "invalidFormat" | `templateId` ist kein String.
`data` ist kein Objekt.
Weitere Felder haben den falschen Typ. |
| 400 Bad Request | "missing" | `templateId` fehlt.
`data` fehlt. |
| 400 Bad Request | "duplicateEntry" | `templateId` oder `chargeId` wurden schon verwendet. |
| 400 Bad Request | "unknownDataField" | Ein unbekanntes Feld wurde im Request Body übergeben. |
### DELETE vouchers/templates/\{templateId}
Diese Methode löscht eine bestehende Gutschein-Blaupause (Template) anhand ihrer eindeutigen ID, wobei die ID dem Namen der Blaupause entspricht. Nach erfolgreicher Löschung wird die `templateId` der entfernten Blaupause als Bestätigung zurückgegeben.
Für die Ausführung sind Löschberechtigungen für Gutschein-Daten erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/templates/myTemplate
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"templateId": "myTemplate"
}
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Löschen von Gutschein-Daten. |
| 400 Bad Request | "notFound" | Die Blaupause wurde nicht gefunden. |
## Methoden für Gutschein-Vorlagen
In diesem Abschnitt werden alle Endpunkte zur Verwaltung von Gutschein-Vorlagen beschrieben.
Im Gegensatz zu Gutschein-Blaupausen, die flexibel durch Benutzer erstellt und angepasst werden können, handelt es sich bei Gutschein-Vorlagen um standardisierte Strukturen, die bestimmte Typen oder Eigenschaften von Gutscheinen definieren. Vorlagen dienen als Basis für die Erstellung neuer Gutscheine nach festen Vorgaben und sind oft enger an das System gekoppelt.
Über die Schnittstelle können diese Vorlagen abgerufen und bei Bedarf angepasst werden. Für alle Operationen sind entsprechende Lese- und Schreibberechtigungen erforderlich.
**Hinweis:** Das Feld `presetId` entspricht intern der Spalte `name` in der Datenbank. Trotz dieser Zuordnung darf im Rahmen der API jedoch nicht nach `name` sortiert, gefiltert oder der Wert direkt abgefragt oder gesetzt werden. Alle Vorgänge erfolgen ausschließlich über `presetId`.
### GET vouchers/presets
Diese Methode liefert eine paginierte Liste aller vorhandenen Gutschein-Vorlagen (Presets).
Über Filter- und Sortierparameter kann die Liste nach Eigenschaften wie Systemstatus oder Erstellungsdatum eingeschränkt und geordnet werden.
Die Vorlagen enthalten vordefinierte Einstellungen für die Erstellung neuer Gutscheine.
Für den Zugriff sind Leseberechtigungen erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/presets
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"endReached": true,
"items": [
{
"createdAt": "1970-01-01T00:33:45.000Z",
"data": {
...
},
"presetId": "123",
"system": false,
"updatedAt": "1970-01-01T00:33:45.000Z"
}
],
"nextPageToken": "MA",
"totalCount": 1
}
```
#### Filterfelder
`presetId`, `system`, `createdAt`, `updatedAt`
#### Sortierfelder
`presetId`, `system`, `createdAt`, `updatedAt`
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Gutschein-Daten. |
| 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 vouchers/presets/labels
Diese Methode liefert eine Liste aller vergebenen Labels, die bei Gutschein-Vorlagen (Presets) verwendet wurden. Labels dienen der Kategorisierung von Vorlagen und werden bei der Volltextsuche berücksichtigt.
Für den Zugriff auf diese Informationen sind Leseberechtigungen erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/presets/labels
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
[ "label1", "label2" ]
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------ |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte. |
### PUT vouchers/presets/\{presetid}
Diese Methode aktualisiert die Eigenschaften einer bestehenden Gutschein-Vorlage (Preset) anhand ihrer eindeutigen ID, wobei die ID dem Namen der Vorlage entspricht.
Über den Request-Body werden die neuen Einstellungen der Vorlage übergeben, darunter Rabatttypen, Werte, Nutzungsbedingungen und weitere Attribute. Nach erfolgreicher Aktualisierung wird die ID der geänderten Vorlage zurückgegeben.
Schreibberechtigungen für Gutschein-Daten sind erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/presets/oldPresetName
```
#### Request Body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"data": {
"count": 1,
"data": {
"active": true,
"name": "newPresetName",
"chargeId": "",
"values": [
{
"value": 55,
"currency": "GBP",
"minOrderValue": 100,
"taxId": ""
}
],
"types": {
"keepSurplus": false,
"discount": true,
"freeShipping": false,
"maxUseCountPerUser": 1,
"maxUseCountSet": true,
"multipleCustomer": true,
"appOnly": false
},
"basketProducts": [],
"labels": [],
"maxUseCount": 1
}
},
"presetId": "newPresetName"
}
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"createdAt": "2025-04-11T13:25:53.000Z",
"data": {
"count": 1,
"data": {
"active": true,
"name": "newPresetName",
"chargeId": "",
"values": [
{
"value": 55,
"currency": "GBP",
"minOrderValue": 100,
"taxId": ""
}
],
"types": {
"keepSurplus": false,
"discount": true,
"freeShipping": false,
"maxUseCountPerUser": 1,
"maxUseCountSet": true,
"multipleCustomer": true,
"appOnly": false
},
"basketProducts": [],
"labels": [],
"maxUseCount": 1
}
},
"presetId": "newPresetName",
"system": false,
"updatedAt": "2025-04-11T13:25:53.000Z"
}
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Gutschein-Daten. |
| 400 Bad Request | | Request body konnte nicht geladen werden. |
| 400 Bad Request | "invalidFormat" | `presetId` ist kein String.
`data` ist kein Objekt.
Weitere Felder haben einen falschen Typ. |
| 400 Bad Request | "missing" | `presetId` fehlt.
`data` fehlt. |
| 400 Bad Request | "invalidCombination" | `newCustomersOnly` und `existingCustomersOnly` sind gesetzt. |
| 400 Bad Request | "readonlyField" | Es ist nicht erlaubt, `disabledFields` zu aktualisieren. |
| 400 Bad Request | "duplicateEntry" | `presetId` wurde schon verwendet. |
| 400 Bad Request | "notFound" | Die Vorlage wurde nicht gefunden. |
| 400 Bad Request | "internalError" | Alte Daten konnten nicht als JSON gelesen werden. |
| 400 Bad Request | "unknownDataField" | Ein unbekanntes Feld wurde im Request Body übergeben. |
### POST vouchers/presets
Diese Methode erstellt eine neue Gutschein-Vorlage (Preset) anhand der übermittelten Konfigurationsdaten.
Der Request-Body muss eine eindeutige `presetId` sowie ein `data`-Objekt mit den relevanten Gutscheineinstellungen enthalten. Nach erfolgreicher Erstellung wird die ID der neuen Vorlage zurückgegeben.
Erstellberechtigungen für Gutschein-Daten sind erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/presets
```
#### Request Body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"presetId": "cvcv89",
"systemPreset": "",
"data": {
"count": 1,
"data": {
"active": true,
"name": "cvcv89",
"chargeId": "",
"maxUseCount": 1,
"values": [
{
"value": 55,
"currency": "GBP",
"minOrderValue": 55,
"taxId": ""
}
],
"types": {
"keepSurplus": false,
"discount": true,
"freeShipping": false,
"maxUseCountPerUser": 1,
"maxUseCountSet": true,
"multipleCustomer": true,
"appOnly": false
},
"basketProducts": [],
"labels": []
}
}
}
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"createdAt": "2025-04-11T13:25:53.000Z",
"data": {
"count": 1,
"data": {
"active": true,
"name": "cvcv89",
"chargeId": "",
"maxUseCount": 1,
"values": [
{
"value": 55,
"currency": "GBP",
"minOrderValue": 55,
"taxId": ""
}
],
"types": {
"keepSurplus": false,
"discount": true,
"freeShipping": false,
"maxUseCountPerUser": 1,
"maxUseCountSet": true,
"multipleCustomer": true,
"appOnly": false
},
"basketProducts": [],
"labels": []
}
},
"presetId": "cvcv89",
"system": false,
"updatedAt": "2025-04-11T13:25:53.000Z"
}
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Erstellen von Gutschein-Daten. |
| 400 Bad Request | | Request body konnte nicht geladen werden. |
| 400 Bad Request | "invalidFormat" | `presetId` ist kein String.
`data` ist kein Objekt.
`validFrom` oder `validUntil` enthalten ungültige Zeitpunkte.
Weitere Felder haben einen falschen Typ. |
| 400 Bad Request | "missing" | `presetId` fehlt.
`data` fehlt. |
| 400 Bad Request | "invalidValue" | `presetId` ist leer. |
| 400 Bad Request | "invalidCombination" | `newCustomersOnly` und `existingCustomersOnly` sind gleichzeitig gesetzt. |
| 400 Bad Request | "readonlyField" | Es ist nicht erlaubt, `disabledFields` zu setzen. |
| 400 Bad Request | "duplicateEntry" | `presetId` wurde schon verwendet. |
| 400 Bad Request | "unknownDataField" | Ein unbekanntes Feld wurde im Request Body übergeben. |
### DELETE vouchers/presets/\{presetid}
Diese Methode löscht eine bestehende Gutschein-Vorlage (Preset) anhand ihrer eindeutigen ID, wobei die ID dem Namen der Vorlage entspricht. Nach erfolgreicher Löschung wird die ID der entfernten Vorlage als Bestätigung zurückgegeben.
Für die Ausführung sind Löschberechtigungen für Gutschein-Daten erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/presets/myPreset
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"presetId": "myPreset"
}
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Löschen von Gutschein-Daten. |
| 400 Bad Request | "notFound" | Die Vorlage wurde nicht gefunden. |
## Support
Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: [Zum Kundenportal](https://websale.atlassian.net/servicedesk/customer/portal/6)
Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.