REST WEBSALE-App (EN)

Below 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

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

Content-Type

application/json

Authorization token

is required

Request-Body

Property	Type	Description	Default	Mandatory field for activation
newsType	number	Message type (mandatory field for creating an entry, cannot be changed later) 0 = Push message 1 = News 2 = Teaser	0	Yes
title	string	Headline (max. 64 characters)	""	Yes (except teaser)
text	string	Message text to be displayed in the "News" tab. (max. 160 characters)	""	Yes (except teaser)
urlType	string	Type of URL specified "internal-login" = 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" = The specified URL is called within the app. In contrast to "internal-login", the user is not automatically logged into the store. "external" = The specified URL is called up in a separate browser (preferably suitable for external URLs).	""	No
url	string	URL to be opened on click (max. 160 characters)	""	Yes, if "urlType" is specified
image_url	string	relative path to teaser image (relative from user/appdata/images )	""	Yes, if message is of type teaser
validFrom	number	Timestamp from which message should be displayed	0	Yes
validUntil	number	Timestamp up to which the message should be displayed	0	Yes
active	bool	Switch so that the message is actively distributed to devices. Sending push messages must also be triggered by a separate endpoint.	false	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".

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

Example cURL

Create a new news with the title "New 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

On success HTTP code 200 is returned. The content contains the current data of the news object.

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

If 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

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

Content-Type

application/json

Authorization token

is required

Request-Body

Property	Type	Description	Default	Mandatory field for activation
title	string	Headline	""	Yes (except teaser)
text	string	News text to be displayed in the "News" tab	""	Yes (except teaser)
urlType	string	Type of the specified URL "internal-login" = 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" = The specified URL is called up within the app. In contrast to "internal-login", the user is not automatically logged into the store. "external" = The specified URL is called up in a separate browser (preferably suitable for external URLs).	""	No
url	string	URL to be opened on click	""	Yes, if urlType is specified
image_url	string	relative path to teaser image (relative from user/appdata/images )	""	Yes, if message is of type teaser
validFrom	number	Timestamp from which message should be displayed	0	Yes
validUntil	number	Timestamp up to which the message should be displayed	0	Yes
active	bool	Switch so that the message is actively distributed to devices. Sending push messages must also be triggered by a separate endpoint.	false	Yes

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

Example request body

Activation of an existing message

{
	"active": true
}

Example cURL

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

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

If successful, HTTP code 200 is returned. The content contains the current data of the message object.

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

If 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

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

Content-Type

^{application/json}

Authorization-Token

is required

Request-Body

not required

Example cURL

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

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

Response

If 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

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

Content-Type

application/json

Authorization token

is required

Request-Body

Property	Type	Description	Default	Mandatory field
name	string	Internal name of the push message for identification in the dispatch list	""	Yes
message	object	Object with all message information	{}	Yes
message.title	string	Title* (max. 64 characters)	""	Yes
message.text	string	Message text to be displayed in the "News" tab* (max. 160 characters)	""	Yes
message.urlType	string	Type of URL specified "internal-login" = 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" = The specified URL is called up within the app. In contrast to "internal-login", the user is not automatically logged into the store. "external" = The specified URL is called up in a separate browser (preferably suitable for external URLs).	""	No
message.url	string	URL to be opened on click (max. 128 characters) If a personalized voucher is to be included, it can be appended to the URL using the ~VOUCHER-Number~ tag.	""	Yes, if urlType is specified
message.voucher	string	Batch ID of a voucher batch stored in the voucher generator	""	No
message.validUntil	number	Number of days the message should be displayed on the devices in the news section. (between 1 and 31)	1	Yes
filter	object	Filter criteria for selecting recipients	{}	No
filter.connected	bool	Filter criterion whether to send a push message only to connected devices (true), only to unconnected devices (false), or to all devices (filter not set).	not set	No
filter.os_type	string	Filter on a specific operating system. "ios" = iOS devices "android" = Android devices	not set	No
filter.email	array<string>	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	No
filter.zip	array<string>	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	No
filter.zip_area	aray<object>	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	No
filter.zip_area[n].from	number	Start of the zip code area to be filtered	not set	No
filter.zip_area[n].to	number	End of the zip code area to filter	not set	No

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

The following tags are supported for this purpose:

Tag	Tag
~A-FirstName~	First name
~A-LastName~	LastName
~A-Street1~	Street
~A-Street2~	Street suffix
~A-Title~	Title
~A-Salutation~	Salutation
~A-City	City
~A-Zip~	Postal code
~A-CompleteSalutation~	Salutation (generated by store)
~VOUCHER-Number~	Personalized voucher number (if a batch ID was specified)

Example Request-Body

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

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

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

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

If successful, HTTP code 200 is returned. The content contains the current shipping ID

{
	"id": 66
}

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

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

Content-Type

^{application/json}

Authorization token

is required

Request-Body

not required

Example cURL

Status request for sending push message with 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

If successful, HTTP code 200 is returned. The content contains the entry including status information.

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

Field name	Description
id	ID of the push message
status	Status of the dispatch Possible values: 0 = Start 1 = Initialization of dispatch 2 = Active dispatch 3 = Finished 4 = Canceled manually 5 = Canceled by error
subshop	Subshop for which the message was created
type	Type of push message: 0 = Push message via OSB service 1 = Push message via REST API 2 = Shipping confirmation message 3 = Reminder for abandoned carts 4 = Birthday greetings
name	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

REST WEBSALE-App (EN)

Create a news item

Request

Content-Type

Authorization token

Request-Body

Example Request-Body

Example cURL

Response

Editing an existing message

Request

Content-Type

Authorization token

Request-Body

Example request body

Example cURL

Response

Sending a general push message

Request

Content-Type

Authorization-Token

Request-Body

Example cURL

Response

Sending a personalized message

Request

Content-Type

Authorization token

Request-Body

Example Request-Body

Example cURL

Response

Status request for sending a personalized push message

Request

Content-Type

Authorization token

Request-Body

Example cURL

Response

Field description

0 Comments