REST WEBSALE-App (EN)

Nachfolgend finden Sie die Beschreibung der WEBSALE API zur Anbindung Ihrer Systeme zum Erstellen, Bearbeiten und Versenden von Teasern, News und Push-Nachrichten für Ihre WEBSALE App.

Erstellen einer Nachricht

Erstellen eines neuen Teasers, einer News oder einer Push-Nachricht für einen Subshop

Request

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

Content-Type

application/json

Authorization-Token

wird benötigt

Request-Body

Eigenschaft	Typ	Beschreibung	Default	Pflichtfeld für Aktivierung*
newsType	number	Nachrichtentyp (Pflichtfeld zum Anlegen eines Eintrags, kann nachträglich nicht geändert werden) 0 = Push-Nachricht 1 = News 2 = Teaser	0	Ja
title	string	Überschrift (max. 64 Zeichen)	""	Ja (außer Teaser)
text	string	Nachrichtentext, der im "News"-Reiter angezeigt werden soll. (max. 160 Zeichen)	""	Ja (außer Teaser)
urlType	string	Art der angegebenen URL "internal-login" = Die angegebene URL wird innerhalb der App aufgerufen. Durch den mitgeschickten Authentifizierungstoken ist der User (wenn in der App angemeldet) direkt im Shop angemeldet "internal" = Die angegebene URL wird innerhalb der App aufgerufen. In Gegensatz zu "internal-login" ist der User nicht automatisch im Shop angemeldet. "external" = Die angegebene URL wird in einem separaten Browser aufgerufen (vorzugsweise für externe URLs geeignet).	""	Nein
url	string	URL, die bei Klick geöffnet werden soll (max. 160 Zeichen)	""	Ja, wenn "urlType" angegeben wurde
image_url	string	relativer Pfad zum Teaserbild (relativ ab benutzer/appdata/bilder )	""	Ja, wenn Nachricht vom Typ Teaser ist
validFrom	number	Timestamp, ab dem die Nachricht angezeigt werden soll	0	Ja
validUntil	number	Timestamp, bis zu dem die Nachricht angezeigt werden soll	0	Ja
active	bool	Schalter, damit die Nachricht aktiv an Geräte verteilt wird. Der Versand von Push-Nachrichten muss zusätzlich über einen separaten Endpunkt angestoßen werden.	false	Ja

* Damit eine Nachricht aktiviert werden kann, müssen alle Pflichtfelder korrekt gesetzt sein.

Beispiel Request-Body

Erstelle eine neue News mit dem Titel "Neue News".

{
	"newsType": 1,
	"title": "Neue News"
}

Beispiel cURL

Erstelle eine neue News mit dem Titel "Neue News".

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"

Response

Bei Erfolg wird HTTP-Code 200 zurückgegeben. Der Content beinhaltet die aktuellen Daten des Nachrichten-Objekts.

 {
	"id": 64, 
	"title": "Neue News", 
	"sendCount": 0, 
	"newsType": 1, 
	"active": false, 
	"sentStatus": 0, 
	"text": "", 
	"url": "", 
	"urlType": "", 
	"timeStamp": 1574870841, 
	"validFrom": 0, 
	"validUntil": 0, 
	"image_url": "", 
	"progressCurrent": 0, 
	"progressTotal": 0, 
	"sentDateTime": 0, 
	"firstActivated": 0, 
	"lastUpdated": 1574870841
}

Ist ein Fehler aufgetreten, wird ein 400er-Code zurückgegeben.

Fehlercode	Beschreibung
400	Fehlerhafter Content. Genauerer Fehlergrund innerhalb vom Response-Body

Bearbeiten einer vorhandenen Nachricht

Bearbeiten eines vorhandenen Teasers, einer News oder einer Push-Nachricht für einen Subshop. Es werden nur die Felder aktualisiert, die im Request angegeben wurden und überschreibbar sind.

Request

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

Content-Type

application/json

Authorization-Token

wird benötigt

Request-Body

Eigenschaft	Typ	Beschreibung	Default	Pflichtfeld für Aktivierung*
title	string	Überschrift	""	Ja (außer Teaser)
text	string	Nachrichtentext, der im "News"-Reiter angezeigt werden soll	""	Ja (außer Teaser)
urlType	string	Art der angegebenen URL "internal-login" = Die angegebene URL wird innerhalb der App aufgerufen. Durch den mitgeschickten Authentifizierungstoken ist der User (wenn in der App angemeldet) direkt im Shop angemeldet "internal" = Die angegebene URL wird innerhalb der App aufgerufen. In Gegensatz zu "internal-login" ist der User nicht automatisch im Shop angemeldet. "external" = Die angegebene URL wird in einem separaten Browser aufgerufen (vorzugsweise für externe URLs geeignet).	""	Nein
url	string	URL, die bei Klick geöffnet werden soll	""	Ja, wenn urlType angegeben wurde
image_url	string	relativer Pfad zum Teaserbild (relativ ab benutzer/appdata/bilder )	""	Ja, wenn Nachricht vom Typ Teaser ist
validFrom	number	Timestamp, ab dem die Nachricht angezeigt werden soll	0	Ja
validUntil	number	Timestamp, bis zu dem die Nachricht angezeigt werden soll	0	Ja
active	bool	Schalter, damit die Nachricht aktiv an Geräte verteilt wird. Der Versand von Push-Nachrichten muss zusätzlich über einen separaten Endpunkt angestoßen werden.	false	Ja

* Damit eine Nachricht aktiviert werden kann, müssen alle Pflichtfelder korrekt gesetzt sein.

Beispiel Request-Body

Aktivierung einer vorhandenen Nachricht

{
	"active": true
}

Beispiel cURL

Aktivierung der Nachricht mit der ID 64 aus dem Subshop 'Deutsch'

curl \
 -X PUT \
 -H "Content-Type: application/json" \
 -H "X-Authorization: Bearer eyJhbGciOiJIUzI1Ni...jBhOWMyMmRmNzFkOT==" \
 -d '{
	"active": true
}' \
"https://websale.de/api/websaleapp2/news/Deutsch/64"

Response

Bei Erfolg wird HTTP-Code 200 zurückgegeben. Der Content beinhaltet die aktuellen Daten des Nachrichten-Objekts.

{
	"id": 64, 
	"title": "Neue News", 
	"sendCount": 0, 
	"newsType": 1, 
	"active": true, 
	"sentStatus": 0, 
	"text": "121", 
	"url": "", 
	"urlType": "", 
	"timeStamp": 1574870841, 
	"validFrom": 0, 
	"validUntil": 0, 
	"image_url": "", 
	"progressCurrent": 0, 
	"progressTotal": 0, 
	"sentDateTime": 0, 
	"firstActivated": 0, 
	"lastUpdated": 1574871267
}

Ist ein Fehler aufgetreten, wird ein 400er-Code zurückgegeben.

Fehlercode	Beschreibung
400	Fehlerhafter Content. Genauerer Fehlergrund innerhalb vom Response-Body
404	Der Eintrag mit der angegebenen ID existiert nicht.

Versand einer allgemeinen Push-Nachricht

Versand einer noch nicht verschickten Push-Nachricht an alle Empfänger. Die Push-Nachricht muss aktiv sein und sie durfte noch nicht verschickt worden sein.

Request

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

Content-Type

^{application/json}

Authorization-Token

wird benötigt

Request-Body

wird nicht benötigt

Beispiel cURL

Verschicke Push-Nachricht mit der ID 65 aus dem Subshop 'Deutsch'.

curl \
 -X POST \
 -H "Content-Type: application/json" \
 -H "X-Authorization: Bearer eyJhbGciOiJIUzI1Ni...jBhOWMyMmRmNzFkOT==" \
"https://websale.de/api/websaleapp2/news/send/Deutsch/65"

Response

Bei Erfolg wird HTTP-Code 200 zurückgegeben.

Ist ein Fehler aufgetreten, wird ein 400er-Code zurückgegeben.

Fehlercode	Beschreibung
404	Der Eintrag mit der angegebenen ID existiert nicht.
406	Der angegebene Eintrag ist nicht vom Typ 'Push-Nachricht', ist noch nicht aktiv oder wurde bereits verschickt.

Versand einer personalisierten Nachricht

Versand einer personalisierten Nachricht ohne vorheriges Erzeugen eines Eintrags

Request

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

Content-Type

application/json

Authorization-Token

wird benötigt

Request-Body

Eigenschaft	Typ	Beschreibung	Default	Pflichtfeld
name	string	Interne Bezeichnung der Push-Nachricht zur Identifikation in der Versandliste	""	Ja
message	object	Objekt mit allen Informationen der Nachrichten	{}	Ja
message.title	string	Überschrift* (max. 64 Zeichen)	""	Ja
message.text	string	Nachrichtentext, der im "News"-Reiter angezeigt werden soll* (max. 160 Zeichen)	""	Ja
message.urlType	string	Art der angegebenen URL "internal-login" = Die angegebene URL wird innerhalb der App aufgerufen. Durch den mitgeschickten Authentifizierungstoken ist der User (wenn in der App angemeldet) direkt im Shop angemeldet "internal" = Die angegebene URL wird innerhalb der App aufgerufen. In Gegensatz zu "internal-login" ist der User nicht automatisch im Shop angemeldet. "external" = Die angegebene URL wird in einem separaten Browser aufgerufen (vorzugsweise für externe URLs geeignet).	""	Nein
message.url	string	URL, die bei Klick geöffnet werden soll (max. 128 Zeichen) Wenn ein personalisierter Gutschein mitgeschickt werden soll, kann dieser über das Tag ~VOUCHER-Number~ an die URL angehängt werden.	""	Ja, wenn urlType angegeben wurde
message.voucher	string	Chargen-ID einer im Gutscheingenerator hinterlegten Gutschein-Charge	""	Nein
message.validUntil	number	Anzahl Tage, die die Nachricht auf den Geräten im News-Bereich angezeigt werden soll. (zw. 1 und 31)	1	Ja
filter	object	Filterkriterien für die Auswahl der Empfänger	{}	Nein
filter.connected	bool	Filterkriterium, ob eine Push-Nachricht nur an verbundene Geräte (true), nur an nicht verbundene Geräte (false) oder an alle Geräte (Filter nicht gesetzt) verschickt werden soll.	not set	Nein
filter.os_type	string	Filterung auf ein spezifisches Betriebssystem. "ios" = iOS-Geräte "android" = Android-Geräte	not set	Nein
filter.email	array<string>	Liste von E-Mail-Adressen, die als Empfänger berücksichtigt werden sollen. Der Filter kann nur gewählt werden, wenn nur an verbundene Geräte geschickt werden soll.	not set	Nein
filter.zip	array<string>	Filterung auf Postleitzahl. Die Empfänger müssen eine der im Array angegebenen Postleitzahlen in ihrer Rechnungsadresse stehen haben. Der Filter kann nur gewählt werden, wenn nur an verbundene Geräte geschickt werden soll.	not set	Nein
filter.zip_area	aray<object>	Liste von Postleitzahlenbereichen, in der ein Empfänger steht. Dies ist nur bei Empfängern möglich, die eine rein numerische Postleitzahl in der Rechnungsadresse besitzen. Der Filter kann nur gewählt werden, wenn nur an verbundene Geräte geschickt werden soll.	not set	Nein
filter.zip_area[n].from	number	Beginn des zu filternden Postleitzahlenbereichs	not set	Nein
filter.zip_area[n].to	number	Ende des zu filternden Postleitzahlenbereichs	not set	Nein

* Sofern die Nachricht an nur verbundene Geräte gesendet wird, kann der Inhalt personalisiert werden.

Folgende Tags werden dafür unterstützt:

Tag	Bezeichnung
~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~	Begrüßung (durch Shop generiert)
~VOUCHER-Number~	Personalisierte Gutscheinnummer (sofern eine Chargen-ID angegeben wurde)

Beispiel Request-Body

Versende eine personalisierte Nachricht mit dem Namen "Hallo" an Shopkunden, die innerhalb von Nürnberg (PLZ 90402 bis 90491) leben.
Dabei soll ein personalisierter Gutschein von der Charge "appvoucher" mitgeschickt werden. Diese Nachricht soll in den News für die nächsten 30 Tagen gelesen werden können.

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

Beispiel cURL

Versende eine personalisierte Nachricht mit dem Namen "Hallo" an Shopkunden, die innerhalb von Nürnberg (PLZ 90402 bis 90491) leben.
Dabei soll ein personalisierter Gutschein von der Charge "appvoucher" mitgeschickt werden. Diese Nachricht soll in den News für die nächsten 30 Tagen gelesen werden können.

curl \
 -X POST \
 -H "Content-Type: application/json" \
 -H "X-Authorization: Bearer eyJhbGciOiJIUzI1Ni...jBhOWMyMmRmNzFkOT==" \
 -d '{
	"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
			}
		]
	}
}' \
"https://websale.de/api/websaleapp2/news/personalized/send/Deutsch"

Response

Bei Erfolg wird HTTP-Code 200 zurückgegeben. Der Content beinhaltet die aktuelle Versand-ID

 {
	"id": 66
}

Ist ein Fehler aufgetreten, wird ein 400er-Code zurückgegeben.

Fehlercode	Beschreibung
400	Der übergebene Content ist fehlerhaft.

Statusabfrage zum Versand einer personalisierten Push-Nachricht

Request

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

Content-Type

^{application/json}

Authorization-Token

wird benötigt

Request-Body

wird nicht benötigt

Beispiel cURL

Statusabfrage für den Versand der Push-Nachricht mit der ID 66.

curl \
 -X POST \
 -H "Content-Type: application/json" \
 -H "X-Authorization: Bearer eyJhbGciOiJIUzI1Ni...jBhOWMyMmRmNzFkOT==" \
"https://websale.de/api/websaleapp2/news/personalized/status/66"

Response

Bei Erfolg wird HTTP-Code 200 zurückgegeben. Der Content beinhaltet den Eintrag inklusive Statusinformationen.

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

Feldbeschreibung

Feldname	Beschreibung
id	ID der Push-Nachricht
status	Status des Versands Mögliche Werte: 0 = Beginn 1 = Initialisierung des Versands 2 = Aktiver Versand 3 = Beendet 4 = Manuell abgebrochen 5 = Abgebrochen durch Fehler
subshop	Subshop, für den die Nachricht erstellt wurde
type	Typ der Push-Nachricht: 0 = Push-Nachricht über OSB-Dienst 1 = Push-Nachricht über REST-API 2 = Versandbestätigungsnachricht 3 = Erinnerung bei stehengelassenen Warenkörben 4 = Geburtstagsgrüße
name	Interne Bezeichnung der Push-Nachricht zur Identifikation in der Versandliste
createTime	Zeitstempel, wann die Push-Nachricht erstellt wurde
updateTime	Zeitstempel, wann der Eintrag zuletzt aktualisiert wurde
validUntil	Anzahl Tage, die die Nachricht auf den Geräten im News-Bereich angezeigt werden soll
title	Nachrichtentitel
text	Nachrichtentext
urlType	Art der angegebenen URL
url	URL, die bei Klick geöffnet werden soll.
voucher	Angegebene Chargen-ID des zu personalisierten Gutscheins
countReceiver	Gesamtzahl der Empfänger, die die Push-Nachricht empfangen sollen
countSent	Anzahl der bereits verschickten Push-Nachrichten
countError	Anzahl der fehlerhafte Zustellversuche
error	Fehlertext (wenn Versand durch Fehler abgebrochen wurde)

Ist ein Fehler aufgetreten, wird ein 400er-Code zurückgegeben.

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