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

# REST WEBSALE-App

> Teaser, News und Push-Nachrichten der WEBSALE App über REST anlegen, bearbeiten und versenden, inklusive personalisierter Nachrichten mit Empfängerfiltern und Gutscheincodes.

Über diese Schnittstelle pflegen Sie die Inhalte Ihrer WEBSALE App aus eigenen Systemen heraus. Sie deckt zwei unterschiedliche Wege ab: den klassischen, bei dem Sie einen Eintrag anlegen, pflegen und später versenden, und den direkten Versand einer personalisierten Nachricht ohne vorherigen Eintrag.

Alle Aufrufe brauchen ein Token, siehe [REST-Authentifizierung](https://dokumentation.websale.de/v8s/schnittstellen/rest-osb-dienste/rest-authentifizierung.md). Content-Type ist durchgängig `application/json`.

## Nachricht erstellen

```
POST https://websale.de/api/websaleapp2/news/{subshopid}
```

| Eigenschaft | Typ | Beschreibung | Default |
| - | - | - | - |
| `newsType` | number | Nachrichtentyp: `0` für Push-Nachricht, `1` für News, `2` für Teaser. Pflichtfeld beim Anlegen und nachträglich nicht änderbar. | `0` |
| `title` | string | Überschrift, maximal 64 Zeichen | `""` |
| `text` | string | Nachrichtentext für den Reiter **News**, maximal 160 Zeichen | `""` |
| `urlType` | string | Art der URL, siehe Tabelle unten | `""` |
| `url` | string | URL, die bei Klick geöffnet wird, maximal 160 Zeichen | `""` |
| `image_url` | string | Relativer Pfad zum Teaserbild, ausgehend von `benutzer/appdata/bilder` | `""` |
| `validFrom` | number | Timestamp, ab dem die Nachricht angezeigt wird | `0` |
| `validUntil` | number | Timestamp, bis zu dem die Nachricht angezeigt wird | `0` |
| `active` | bool | Schaltet die aktive Verteilung an Geräte ein | `false` |

Die drei URL-Arten unterscheiden sich darin, wo die Seite geöffnet wird und ob der Benutzer dabei angemeldet ist:

| Wert | Verhalten |
| - | - |
| `internal-login` | Die URL wird innerhalb der App aufgerufen. Durch das mitgeschickte Token ist der Benutzer, sofern in der App angemeldet, direkt im Shop angemeldet. |
| `internal` | Die URL wird innerhalb der App aufgerufen, der Benutzer ist aber nicht automatisch im Shop angemeldet. |
| `external` | Die URL wird in einem separaten Browser geöffnet. Geeignet für externe Ziele. |

Welche Felder Pflicht sind, hängt davon ab, ob die Nachricht aktiviert werden soll. Zum Aktivieren müssen `title`, `text`, `validFrom`, `validUntil` und `active` gesetzt sein, bei einem Teaser statt `title` und `text` das Feld `image_url`. `url` wird zur Pflicht, sobald `urlType` angegeben ist. Zum reinen Anlegen genügt `newsType`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
curl \
 -X POST \
 -H "Content-Type: application/json" \
 -H "X-Authorization: Bearer eyJhbGciOiJIUzI1Ni...jBhOWMyMmRmNzFkOT==" \
 -d '{
    "newsType": 1,
    "title": "Neue News"
}' \
"https://websale.de/api/websaleapp2/news/Deutsch"
```

Bei Erfolg antwortet der Server mit HTTP-Code 200 und den aktuellen Daten des Nachrichten-Objekts, darunter der `id`, die Sie für alle weiteren Aufrufe brauchen.

## Nachricht bearbeiten

```
PUT https://websale.de/api/websaleapp2/news/{subshopid}/{id}
```

Aktualisiert werden nur die Felder, die im Request stehen und überschreibbar sind. Die Felder entsprechen denen beim Erstellen, mit Ausnahme von `newsType`, der sich nachträglich nicht ändern lässt.

## Allgemeine Push-Nachricht versenden

```
POST https://websale.de/api/websaleapp2/news/send/{subshopid}/{id}
```

Ein Request-Body ist nicht nötig.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
curl \
 -X POST \
 -H "Content-Type: application/json" \
 -H "X-Authorization: Bearer eyJhbGciOiJIUzI1Ni...jBhOWMyMmRmNzFkOT==" \
"https://websale.de/api/websaleapp2/news/send/Deutsch/65"
```

Zwei Bedingungen müssen erfüllt sein: Die Push-Nachricht muss aktiv sein, und sie darf noch nicht verschickt worden sein. Das Setzen von `active` allein verschickt also nichts, der Versand braucht immer diesen zusätzlichen Aufruf.

## Personalisierte Nachricht versenden

```
POST https://websale.de/api/websaleapp2/news/personalized/send/{subshopid}
```

Dieser Weg verschickt direkt, ohne dass Sie vorher einen Eintrag anlegen.

| Eigenschaft | Typ | Beschreibung | Pflichtfeld |
| - | - | - | - |
| `name` | string | Interne Bezeichnung zur Identifikation in der Versandliste | ja |
| `message` | object | Objekt mit allen Informationen der Nachricht | ja |
| `message.title` | string | Überschrift, maximal 64 Zeichen | ja |
| `message.text` | string | Nachrichtentext für den Reiter **News**, maximal 160 Zeichen | ja |
| `message.urlType` | string | Art der URL wie oben beschrieben | nein |
| `message.url` | string | URL, maximal 128 Zeichen. Ein personalisierter Gutschein lässt sich über das Tag `~VOUCHER-Number~` anhängen. | ja, wenn `urlType` gesetzt ist |
| `message.voucher` | string | Chargen-ID einer im Gutschein-Generator hinterlegten Gutschein-Charge | nein |
| `message.validUntil` | number | Anzahl Tage, die die Nachricht im News-Bereich der Geräte sichtbar bleibt, zwischen 1 und 31 | ja |
| `filter` | object | Filterkriterien für die Empfängerauswahl | nein |

### Empfänger filtern

| Filter | Typ | Beschreibung |
| - | - | - |
| `filter.connected` | bool | `true` sendet nur an verbundene Geräte, `false` nur an nicht verbundene. Ohne den Filter gehen die Nachrichten an alle Geräte. |
| `filter.os_type` | string | `ios` oder `android` |
| `filter.email` | array | Liste von E-Mail-Adressen, die als Empfänger berücksichtigt werden |
| `filter.zip` | array | Postleitzahlen, die in der Rechnungsadresse des Empfängers stehen müssen |
| `filter.zip_area` | array | Postleitzahlenbereiche mit `from` und `to`, nur für rein numerische Postleitzahlen |

Die Filter `email`, `zip` und `zip_area` lassen sich nur zusammen mit `connected: true` verwenden. Das ergibt sich daraus, dass der Shop diese Angaben nur für verbundene Geräte kennt.

### Personalisierung im Text

Geht die Nachricht ausschließlich an verbundene Geräte, lassen sich Titel und Text personalisieren:

| Tag | Bedeutung |
| - | - |
| `~A-FirstName~` | Vorname |
| `~A-LastName~` | Nachname |
| `~A-Street1~` | Straße |
| `~A-Street2~` | Straßenzusatz |
| `~A-Title~` | Titel |
| `~A-Salutation~` | Anrede |
| `~A-City~` | Stadt |
| `~A-Zip~` | Postleitzahl |
| `~A-CompleteSalutation~` | Vom Shop erzeugte Begrüßung |
| `~VOUCHER-Number~` | Personalisierte Gutscheinnummer, sofern eine Chargen-ID angegeben wurde |

Beispiel: eine Nachricht an Kunden mit Nürnberger Postleitzahl, mit personalisiertem Gutschein aus der Charge `appvoucher`, 30 Tage sichtbar.

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "name": "Hallo",
    "message": {
        "title": "Nachrichten Titel",
        "text": "Nachrichteninhalt",
        "urlType": "internal-login",
        "url": "https://www.domain.de/?voucher_number=~VOUCHER-Number~",
        "validUntil": 30,
        "voucher": "appvoucher"
    },
    "filter": {
        "connected": true,
        "zip_area": [
            {
                "from": 90402,
                "to": 90491
            }
        ]
    }
}
```

## Status eines personalisierten Versands abfragen

```
GET https://websale.de/api/websaleapp2/news/personalized/status/{id}
```

Ein Request-Body ist nicht nötig. Die Antwort enthält den Eintrag samt Statusinformationen.

| Feld | Beschreibung |
| - | - |
| `id` | ID der Push-Nachricht |
| `status` | Status des Versands, siehe Tabelle unten |
| `subshop` | Subshop, für den die Nachricht erstellt wurde |
| `type` | Typ der Push-Nachricht, siehe Tabelle unten |
| `name` | Interne Bezeichnung |
| `createTime` | Zeitstempel der Erstellung |
| `updateTime` | Zeitstempel der letzten Aktualisierung |
| `validUntil` | Anzahl Tage, die die Nachricht auf den Geräten sichtbar bleibt |
| `title`, `text` | Titel und Text der Nachricht |
| `urlType`, `url` | Art der URL und die URL selbst |
| `voucher` | Chargen-ID des personalisierten Gutscheins |
| `countReceiver` | Gesamtzahl der vorgesehenen Empfänger |
| `countSent` | Anzahl bereits verschickter Nachrichten |
| `countError` | Anzahl fehlgeschlagener Zustellversuche |
| `error` | Fehlertext, wenn der Versand durch einen Fehler abgebrochen wurde |

Werte für `status`:

| Wert | Bedeutung |
| - | - |
| 0 | Beginn |
| 1 | Initialisierung des Versands |
| 2 | Aktiver Versand |
| 3 | Beendet |
| 4 | Manuell abgebrochen |
| 5 | Abgebrochen durch Fehler |

Werte für `type`:

| Wert | Bedeutung |
| - | - |
| 0 | Push-Nachricht über den OSB-Dienst |
| 1 | Push-Nachricht über die REST-API |
| 2 | Versandbestätigungsnachricht |
| 3 | Erinnerung bei stehengelassenen Warenkörben |
| 4 | Geburtstagsgrüße |

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "id": 66,
    "status": 2,
    "subshop": "Deutsch",
    "type": 1,
    "name": "Hallo",
    "createTime": "1574870841",
    "updateTime": "1574870941",
    "validUntil": "30",
    "title": "Nachrichten Titel",
    "text": "Nachrichteninhalt",
    "urlType": "internal-login",
    "url": "https://www.domain.de/?voucher_number=~VOUCHER-Number~",
    "voucher": "appvoucher",
    "countReceiver": 10,
    "countSent": 3,
    "countError": 1,
    "error": ""
}
```

| Fehlercode | Beschreibung |
| - | - |
| 400 | Der übergebene Inhalt ist fehlerhaft |
| 404 | Kein Eintrag mit der angegebenen ID gefunden |

## Verwandte Themen

* Wegweiser: [REST-Schnittstelle für OSB-Dienste](https://dokumentation.websale.de/v8s/schnittstellen/rest-osb-dienste.md)
* Wegweiser: [WEBSALE App](https://dokumentation.websale.de/v8s/schnittstellen/service-und-app/websale-app.md)
* Wegweiser: [Gutscheine anlegen oder importieren](https://dokumentation.websale.de/v8s/gutscheine-anbieten/gutscheine-anlegen-oder-importieren.md)


## Related topics

- [WEBSALE App](https://dokumentation.websale.de/v8s/schnittstellen/service-und-app/websale-app.md)
- [REST-Schnittstelle für OSB-Dienste](https://dokumentation.websale.de/v8s/schnittstellen/rest-osb-dienste.md)
- [app - WEBSALE APP](https://dokumentation.websale.de/konfiguration/app-websale-app.md)
- [Service und App](https://dokumentation.websale.de/v8s/schnittstellen/service-und-app.md)
- [Einwilligung zur Datenverarbeitung (Cookies)](https://dokumentation.websale.de/v8s/einstellungen/einwilligung-zur-datenverarbeitung-cookies.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.