Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents
maxLevel2
minLevel2
printablefalse

...


Erstellen einer Nachricht

Erstellen eines neuen Teasers, einer News oder einer Push-Nachricht für einen SubshopBelow is the description of the WEBSALE API to connect your systems to create, edit and send teasers, news and push messages for your WEBSALE app.

Create a news item

Create a new teaser, news or push message for a subshop

Request

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

Content-Type

application/json

Authorization

...

token

is required

Request-Body

Eigenschaft

Property

Typ

Type

Beschreibung

Description

Default

Pflichtfeld für Aktivierung*

Mandatory field for activation

newsType

number

Nachrichtentyp (Pflichtfeld zum Anlegen eines Eintrags, kann nachträglich nicht geändert werden

Message type (mandatory field for creating an entry, cannot be changed later)

0 = Push

-Nachricht

message

1 = News

2 = Teaser

0

Ja

Yes

title

string

Überschrift

Headline (max. 64

Zeichen

characters)

""

Ja

Yes (

außer Teaser

except teaser)

text

string

Nachrichtentext, der im

Message text to be displayed in the "News"

-Reiter angezeigt werden soll

tab. (max. 160

Zeichen

characters)

""

Ja

Yes (

außer Teaser

except teaser)

urlType

string

Art der angegebenen

Type of URL specified

"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

The specified URL is called within the app. Due to the authentication token sent along, the user (if logged into the app) is directly logged into the store

"internal" =

 Die angegebene URL wird innerhalb der App aufgerufen. In Gegensatz zu

The specified URL is called within the app. In contrast to "internal-login"

ist der User nicht automatisch im Shop angemeldet

, the user is not automatically logged into the store.

"external" =

Die angegebene URL wird in einem separaten Browser aufgerufen (vorzugsweise für externe URLs geeignet

The specified URL is called up in a separate browser (preferably suitable for external URLs).

""

Nein

No

url

string

URL

, die bei Klick geöffnet werden soll

to be opened on click (max. 160

Zeichen

characters)

""

Ja

Yes,

wenn

if "urlType"

angegeben wurdebenutzer

is specified

image_url

string

relativer Pfad zum Teaserbild (relativ ab

relative path to teaser image (relative from user/appdata/

bilder

images )

""

Ja, wenn Nachricht vom Typ Teaser ist

Yes, if message is of type teaser

validFrom

number

Timestamp

, ab dem die Nachricht angezeigt werden soll

from which message should be displayed

0

Ja

Yes

validUntil

number

Timestamp

, bis zu dem die Nachricht angezeigt werden soll

up to which the message should be displayed

0

Ja

Yes

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

Switch so that the message is actively distributed to devices. Sending push messages must also be triggered by a separate endpoint.

false

Ja

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

Beispiel Request-Body

...

Yes

* All mandatory fields must be set correctly for a message to be activated.

Example Request-Body

Create a new news with the title "New news".

Code Block
languagejs
{
	"newsType": 1,
	"title": "Neue News"
}

...

Example cURL

Erstelle eine neue News mit dem Titel "Neue Create a new news with the title "New News".

Code Block
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-ObjektsOn success HTTP code 200 is returned. The content contains the current data of the news object.

Code Block
languagejs
  {
	"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 sindIf an error occurred, a 400 code is returned.

Error code

Description

400

Faulty content. Exact reason for the error within the response body

Editing an existing message

Edit an existing teaser, news or push message for a subshop. Only the fields that were specified in the request and can be overwritten will be updated.

Request

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

Content-Type

application/json

Authorization

...

token

is required

Request-Body

Eigenschaft

Property

Typ

Type

Beschreibung

Description

Default

Pflichtfeld für Aktivierung*

Mandatory field for activation

title

string

Überschrift

Headline

""

Ja

Yes (

außer Teaser

except teaser)

text

string

Nachrichtentext, der im

News text to be displayed in the "News"

-Reiter angezeigt werden soll

tab

""

Ja

Yes (

außer Teaser

except teaser)

urlType

string

Art der angegebenen

Type of the specified 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

The specified URL is called within the app. The authentication token sent with the URL means that the user (if logged in to the app) is logged in directly to the store

"internal" =

 Die angegebene URL wird innerhalb der App aufgerufen. In Gegensatz zu

The specified URL is called up within the app. In contrast to "internal-login"

ist der User nicht automatisch im Shop angemeldet

, the user is not automatically logged into the store.

"external" =

Die angegebene URL wird in einem separaten Browser aufgerufen (vorzugsweise für externe URLs geeignet

The specified URL is called up in a separate browser (preferably suitable for external URLs).

""

Nein

No

url

string

URL

, die bei Klick geöffnet werden soll

to be opened on click

""

Ja

Yes,

wenn

if urlType

angegeben wurdebenutzer

is specified

image_url

string

relativer Pfad zum Teaserbild (relativ ab

relative path to teaser image (relative from user/appdata/

bilder

images )

""

Ja, wenn Nachricht vom Typ Teaser ist

Yes, if message is of type teaser

validFrom

number

Timestamp

, ab dem die Nachricht angezeigt werden soll

from which message should be displayed

0

Ja

Yes

validUntil

number

Timestamp

, bis zu dem die Nachricht angezeigt werden soll

up to which the message should be displayed

0

Ja

Yes

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

Switch so that the message is actively distributed to devices. Sending push messages must also be triggered by a separate endpoint.

false

Ja

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

Beispiel Request-Body

...

Yes

* All mandatory fields must be set correctly for a message to be activated.

Example request body

Activation of an existing message

Code Block
languagejs
{
	"active": true
}

Beispiel cURL

...

Example cURL

Activation of the message with the ID 64 from the subshop 'German

Code Block
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-ObjektsIf successful, HTTP code 200 is returned. The content contains the current data of the message object.

Code Block
languagejs
{
	"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 seinIf an error occurred, a 400 code is returned.

Error code

Description

400

Faulty content. Exact reason for the error within the response body

404

The entry with the specified ID does not exist.

Sending a general push message

Sending of a push message that has not yet been sent to all recipients. The push message must be active and it must not have been sent yet.

Request

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

Content-Type

application/json

Authorization-Token

wird benötigtis required

Request-Body

wird nicht benötigt

Beispiel cURL

Verschicke Push-Nachricht mit der ID 65 aus dem Subshop 'Deutschnot required

Example cURL

Send push message with ID 65 from subshop 'German'.

Code Block
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 EintragsIf successful, HTTP code 200 is returned.

If an error occurred, a 400 code is returned.

Error code

Description

404

The entry with the given ID does not exist.

406

The specified entry is not of type 'Push message', is not yet active or has already been sent.

Sending a personalized message

Sending a personalized message without first creating an entry

Request

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

Content-Type

application/json

Authorization

...

token

is required

Request-Body

Eigenschaft

Property

Typ

Type

Beschreibung

Description

Default

Pflichtfeld

Mandatory field

name

string

Interne Bezeichnung der Push-Nachricht zur Identifikation in der Versandliste

Internal name of the push message for identification in the dispatch list

""

Ja

Yes

message

object

Objekt mit allen Informationen der Nachrichten

Object with all message information

{}

Ja

Yes

message.title

string

Überschrift

Title* (max. 64

Zeichen

characters)

""

Ja

Yes

message.text

string

Nachrichtentext, der im

Message text to be displayed in the "News"

-Reiter angezeigt werden soll

tab* (max. 160

Zeichen

characters)

""

Ja

Yes

message.urlType

string

Art der angegebenen

Type of URL specified

"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

The specified URL is accessed within the app. The authentication token sent with the message means that the user (if logged into the app) is logged into the store directly

"internal" =

 Die angegebene URL wird innerhalb der App aufgerufen. In Gegensatz zu

The specified URL is called up within the app. In contrast to "internal-login"

ist der User nicht automatisch im Shop angemeldet

, the user is not automatically logged into the store.

"external" =

Die angegebene URL wird in einem separaten Browser aufgerufen (vorzugsweise für externe URLs geeignet

The specified URL is called up in a separate browser (preferably suitable for external URLs).

""

Nein

No

message.url

string

URL

, die bei Klick geöffnet werden soll

to be opened on click (max. 128

Zeichen)
Wenn ein personalisierter Gutschein mitgeschickt werden soll, kann dieser über das Tag ~VOUCHER-Number~ an die URL angehängt werden

characters)

If a personalized voucher is to be included, it can be appended to the URL using the ~VOUCHER-Number~ tag.

""

Ja

Yes,

wenn

if urlType

angegeben wurde

is specified

message.voucher

string

Chargen-ID einer im Gutscheingenerator hinterlegten Gutschein-Charge

Batch ID of a voucher batch stored in the voucher generator

""

Nein

No

message.validUntil

number

Anzahl Tage, die die Nachricht auf den Geräten im News-Bereich angezeigt werden soll. (zw. 1 und

Number of days the message should be displayed on the devices in the news section. (between 1 and 31)

1

Ja

Yes

filter

object

Filterkriterien für die Auswahl der Empfänger

Filter criteria for selecting recipients

{}

Nein

No

filter.connected

bool

Filterkriterium, ob eine Push-Nachricht nur an verbundene Geräte

Filter criterion whether to send a push message only to connected devices (true),

nur an nicht verbundene Geräte

only to unconnected devices (false)

oder an alle Geräte (Filter nicht gesetzt) verschickt werden soll

, or to all devices (filter not set).

not set

Nein

No

filter.os_type

string

Filterung auf ein spezifisches Betriebssystem

Filter on a specific operating system.

"ios" = iOS

-Geräte

devices

"android" = Android

-Geräte

devices

not set

Nein

No

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

List of email addresses to be considered as recipients.

The filter can be selected only if you want to send only to connected devices.

not set

Nein

No

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

Filter on postal code. Recipients must have one of the zip codes specified in the array in their billing address.

The filter can only be selected when sending to connected devices only.

not set

Nein

No

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

List of zip code areas where a recipient is located. This is only possible for recipients that have a purely numeric zip code in

of the billing address.

The filter can only be selected when sending only to connected devices.

not set

Nein

No

filter.zip_area[n].from

number

Beginn des zu filternden Postleitzahlenbereichs

Start of the zip code area to be filtered

not set

Nein

No

filter.zip_area[n].to

number

Ende des zu filternden Postleitzahlenbereichs

End of the zip code area to filter

not set

Nein

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

...

No

* Provided the message is sent to only connected devices, the content can be personalized.

The following tags are supported for this purpose:

Tag

Bezeichnung

Tag

~A-FirstName~

Vorname

First name

~A-LastName~

Nachname

LastName

~A-Street1~

Straße

Street

~A-Street2~

Straßenzusatz

Street suffix

~A-Title~

Titel

Title

~A-Salutation~

Anrede

Salutation

~A-

City~

City

Stadt

City

~A-Zip~

Postleitzahl

Postal code

~A-CompleteSalutation~

Begrüßung (durch Shop generiert

Salutation (generated by store)

~VOUCHER-Number~

Personalisierte Gutscheinnummer (sofern eine Chargen-ID angegeben wurde)

...

Personalized voucher number (if a batch ID was specified)

Example 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önnenSend a personalized message with the name "Hello" to store customers living within Nuremberg (zip codes 90402 to 90491).

A personalized voucher from the batch "appvoucher" is to be included. This message is to be read in the news for the next 30 days.

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

...

Example 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önnenSend a personalized message with the name "Hello" to store customers who live within Nuremberg (postal codes 90402 to 90491).

A personalized voucher from the batch "appvoucher" should be included. This message is to be read in the news for the next 30 days.

Code Block
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-If successful, HTTP code 200 is returned. The content contains the current shipping ID

Code Block
languagejs
 {
	"id": 66
}

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

...

Fehlercode

...

Beschreibung

...

400

...

Der übergebene Content ist fehlerhaft.

...

If an error occurred, a 400 code is returned.

Error code

Description

400

The passed content is faulty.

Status request for sending a personalized push message

Request

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

Content-Type

application/json

Authorization

...

token

is required

Request-Body

wird nicht benötigt

Beispiel cURL

Statusabfrage für den Versand der Push-Nachricht mit der not required

Example cURL

Status request for sending push message with ID 66.

Code Block
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 StatusinformationenIf successful, HTTP code 200 is returned. The content contains the entry including status information.

Code Block
languagejs
  {
	"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": { ... }
  }

...

Field description

Feldname

Field name

Beschreibung

Description

id

ID

der Push-Nachricht

of the push message

status

Status

des VersandsMögliche Werte

of the dispatch

Possible values:

0 =

Beginn

Start
1 =

Initialisierung des Versands

Initialization of dispatch
2 =

Aktiver Versand

Active dispatch
3 =

Beendet

Finished
4 =

Manuell abgebrochen

Canceled manually
5 =

Abgebrochen durch Fehler

Canceled by error

subshop

Subshop

, für den die Nachricht erstellt wurde

for which the message was created

type

Typ der Push-Nachricht

Type of push message:

0 = Push

-Nachricht über OSB-Dienst

message via OSB service
1 = Push

-Nachricht über

message via REST

-

API
2 =

Versandbestätigungsnachricht

Shipping confirmation message
3 =

Erinnerung bei stehengelassenen Warenkörben

Reminder for abandoned carts
4 =

Geburtstagsgrüße

Birthday greetings

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)

...

Fehlercode

Beschreibung

400

Der übergebene Content ist fehlerhaft

404

Kein Eintrag mit der angegebenen ID gefunden

Internal name of the push message for identification in the shipping list

createTime

Timestamp when the push message was created

updateTime

Timestamp when the entry was last updated

validUntil

Number of days the message should be displayed on the devices in the news section

title

Message title

text

Message text

urlType

Type of the specified URL

url

URL to be opened on click

voucher

Specified batch ID of the voucher to be personalized

countReceiver

Total number of recipients who should receive the push message

countSent

Number of push messages already sent

countError

Number of failed delivery attempts

error

Error text (if sending was aborted by error)


If an error has occurred, a 400 code is returned.

Error code

Description

400

The passed content is faulty

404

No entry found with the specified ID

Include Page
Haftungsausschluss/Disclaimer
Haftungsausschluss/Disclaimer