REST WEBSALE-App

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

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.

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.

{
    "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

{
    "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

Schnittstellen

Nachricht erstellen

Nachricht bearbeiten

Allgemeine Push-Nachricht versenden

Personalisierte Nachricht versenden

Empfänger filtern

Personalisierung im Text

Status eines personalisierten Versands abfragen

Verwandte Themen

​Nachricht erstellen

​Nachricht bearbeiten

​Allgemeine Push-Nachricht versenden

​Personalisierte Nachricht versenden

​Empfänger filtern

​Personalisierung im Text

​Status eines personalisierten Versands abfragen

​Verwandte Themen

Nachricht erstellen

Nachricht bearbeiten

Allgemeine Push-Nachricht versenden

Personalisierte Nachricht versenden

Empfänger filtern

Personalisierung im Text

Status eines personalisierten Versands abfragen

Verwandte Themen