WS-REST-OrderManagement (EN)

WS-REST-OrderManagement (EN)

General

The following describes a REST-based interface that allows a WEBSALE shop to receive customer-specific orders from an ERP system in real time and display them to the customer/orderer in the shop. In particular, this interface is used to display all orders to the customer, i.e. including orders that were not placed in the shop but were placed by call center, letter or fax, for example. Furthermore, cancellations and returns can be transmitted to the ERP system.

If the ERP system is not directly accessible via the Internet, then WEBSALE AG can provide a VPN tunnel. Via this VPN tunnel the ERP system can establish a secure TCP/IP connection to the Internet.

REST functions

All functions listed here are called using POST. If successful, the ERP system returns the Http code 200.

Transferring a list of orders (header and optional item data)

  • The shop requests a list of purchase orders from the ERP system.

  • The ERP system returns a list of orders.

In the list, only part of the order data is transmitted. Usually, this is the header data.

Transfer of a single purchase order (header and item data)

  • The shop requests a single purchase order from the ERP system.

  • The ERP system returns the header and all item data of the order.

Transfer of a PDF file

  • The shop requests the PDF file from the ERP system.

  • The ERP system returns the PDF file.

  • The shop offers the PDF file to the customer as a download.

Cancellation/return of one or more items

  • The customer cancels/returns one or more items.

  • The shop sends the cancellation/return to the ERP system.

  • The ERP system confirms or rejects the cancellation/return.

Transfer of the last shop order number

  • The shop requests the last shop order number from the ERP system.

  • The ERP system returns the last shop order number.

Transfer of the stock level/branch stock of a single product

  • The shop requests the stock level for a single product.

  • The ERP system returns the stock level of the product.

Transfer of general customer data

  • The shop requests general customer data from the ERP system.

  • The ERP system returns the general customer data.

Exclusively encrypted retrieval

The web service is accessed exclusively via SSL. Unencrypted connections must be rejected on both sides (shop/ERP system).

UTF-8 encoding

All data is transferred in UTF-8 format.

Error

The ERP system responds with an Http code not equal to 200 if it cannot deliver any data. This is given in the following cases, for example:

  • wrong REST password

  • unknown customer number

  • unknown ShopID/SubshopID

  • unknown type

  • internal error

  • etc.

The shop expects an error code given by the ERP system and an optional error message. Based on the error code, the designer can display language-dependent explanations/hint messages to the orderer. The optional error message is not used to display this to the orderer, but is used for logging in the log file. It can therefore be purely technical.

The error code must be unique and consistent in each response. Example:

  • 0001: wrong REST password

  • 0002: unknown customer number

  • 0003: unknown ShopID

  • 0004: unknown SubshopID

  • 0005: unknown type

  • 1000: internal error X

  • 1001: internal error Y

  • 1002: internal error Z

  • etc.

For example, if the ERP system returns the error code "0002", the following message could be displayed to the orderer:

"Dear Mr. Müller,

unfortunately we do not have any information about your customer number at the moment. Please contact us at telephone number XYZ or use our contact form (→ link to contact form)."

In addition, corresponding (code-dependent) graphics can be displayed.

Response:

Http code = 400

{

"ErrCode": 2,

"ErrMsg": "Unknown customer number"

}

Transfer of a list of orders

During the transfer, the ERP system provides the shop with

  • fixed data

  • any data

back.

Request from the shop for a list of orders

Parameters

Max. Length

Required

Data type

Comment

Parameters

Max. Length

Required

Data type

Comment

ShopID

128

yes

String

A unique shop ID. The shop ID is assigned by WEBSALE AG.

Password

128

yes

String

The REST password. Is assigned by WEBSALE AG and must be checked by the ERP system. The ERP system must reject the request if the password is incorrect.

SubshopID

128

yes

String

A unique subshop ID in which the data will be displayed.

CustomerSubshopIDs

128 per ID

yes

String array

List of valid subshops of the customer

CustomerID

64

yes

String

A unique customer number

BillCountry

3

no

String

Bill country ISO 3166 (e.g. DEU) of the customer, if known in the shop.

Type

 

yes

Integer

A type that specifies the requested data. If "0", the ERP system returns all types that are available in the ERP system. The individual types are freely configurable in the shop and are specified by the ERP system.
Example

1: Invoice
2: Return
3: Cancellation
etc.

Please note:

Types 1000 to 1100 are reserved for internal purposes.

MaxEntries

 

no

Integer

The max. number of list entries to be sent. If the parameter is missing or "0", the ERP system uses its own default value for the maximum list entries.

DateFrom

10

no

String

 

Format: YYYY-MM-DD

An optional start date from which list items will be sent.
Whether "DateFrom" is used in the shop can be configured in the shop.

DateUntil

10

no

String

 

Format: YYYY-MM-DD

An optional end date up to which the list entries are sent.
Whether "DateUntil" is used in the shop can be configured in the shop.

SearchFilters

 

no

Filter array

Optional free search filters. Maximum 10 entries.

Free search filters given by the ERP system

Optionally, up to 10 free search filters can be transferred to the ERP system. The possible filters and the corresponding codes are predefined by the ERP system.

{
"SearchFilters" : [
{
"Code": 1,
"Value": "FilterText"
},
{
"Code": 2,
"Value": "FilterText"
}
],
...
}

Parameters

Max. Length

Required

Data type

Comment

Parameters

Max. Length

Required

Data type

Comment

Code

16

yes

String

The code of the search filter. The ERP system specifies which codes it supports. A code may only contain the characters a-z, A-Z and 0-9.

Value

128

yes

String

The value to filter by. The maximum length that can be entered can be set/reduced by the designer.

Request /GetOrderList:

{
"ShopID": "myshop",
"password": "1234567890",
"SubshopID": "German",
"BillCountry": "DEU",
"CustomerID": "1001",
"CustomerSubshopIDs": [
"German"
],
"MaxEntries": 10,
"SearchFilters": [
{
"code": "code01",
"Value": "1"
}
],
"Type": 1,
"DateFrom": "2020-03-02",
"DateUntil": "2020-03-08",
}

Response from ERP system

The ERP system returns fixed data to the shop and data that can be freely configured in the shop.

Fixed header data

Parameter

Max. Length

Required

Data type

Comment

Parameter

Max. Length

Required

Data type

Comment

ID

128

yes

String

Unique ID of the order, e.g. the order number

Type

 

yes

Integer

A type that specifies the data sent. The type is assigned/managed by the ERP system and is freely configurable in the shop. Example

1: Invoice
2: Exchange
3: Return
etc.

FileAvailable

 

yes

Boolean

This parameter specifies whether a PDF file (e.g. the invoice/cancellation, etc.) is available for the order.
Possible values

"true or false

ReturnsFileAvailable

 

no

Boolean

Only if return is registered.

This parameter specifies whether a PDF file (e.g. returns label, etc.) is available when a return is logged in.
Possible values

"true or false

CancellationFileAvailable

 

no

Boolean

Only if a cancellation is performed.

This parameter specifies whether a PDF file is available when a cancellation is performed.
Possible values

"true or false

BankTransferRefund

 

no

Boolean

Only in case of a possible return/cancellation.

This parameter specifies whether in case of a possible return/cancellation the refund should be made by bank transfer and the bank details should be requested from the purchaser.
Possible values

"true" or "false".

If true, the ERP system can send the customer's stored bank details to the shop. Then the bank fields are preset with these data.

RefundBankName

128

no

String

Name of the bank for the refund

RefundBankOwner

128

no

String

Account owner for the refund

RefundBankIBAN

128

no

String

IBAN for refund

RefundBankBIC

128

no

String

BIC for refund

Header data freely configurable in the shop

A maximum of 1000 different header data H1...H1000 are supported in the shop.

The maximum length of a single record is 4096 characters.

The header data are freely configurable in the shop (optionally per type).
Example of a configuration file in the shop independent of the data type:

<HeadData>
H1 = customer number
H2 = Order date
H3 = Order number
H4 = Invoice number
...
</HeadData>

Parameter

Max. Length

Required

Data type

Comment

Parameter

Max. Length

Required

Data type

Comment

Name

5

yes

String

The name of the header data field

H1...H1000

Value

4096 per Value

yes

String

One or more values assigned to the header data field.

Please note:

This parameter may occur a maximum of 10 times!

Fixed position data

Parameter

Max. Length

Required

Data type

Comment

Parameter

Max. Length

Required

Data type

Comment

PositionID

128

Yes

String

Unique ID of the position, e.g. the article number or consecutive position number

OrderQuantity

 

Yes

Integer

Order quantity

MaxReturns

 

Yes

Integer

Maximum number of possible returns.

0 = No returns possible

PartReturns

 

Yes

Boolean

true=part returns possible

false= no partial returns possible only "MaxReturns" possible

Example:
MaxReturns=5
PartReturns=true
→ Customer can return 1..5 pieces

Example:
MaxReturns=5
PartReturns=false
→ Customer must return all 5 pieces

MaxCancellations

 

Yes

Integer

Maximum number of pieces that can be cancelled.

0 = No cancellation possible

PartCancellations

 

Yes

Boolean

true=part cancellations possible

false= no partial cancellations possible only "MaxCancellations" possible.

Example:
MaxCancellations=5
PartCancellations=true
→ Customer can cancel 1..5 pcs

Example:
MaxCancellations=5
PartCancellations=false
→ Customer must cancel 5 pieces

Freely configurable position data in the shop

A maximum of 1000 different position data P1...P1000 are supported in the shop.

The maximum length of a single data record is 4096 characters.

The position data are freely configurable in the shop (optionally per type).

Example of a configuration file in the shop independent of the data type:

<PositionData>
P1 = Item number
P2 = Designation
P3 = Color
P4 = Weight
P5 = unit price
..
</ItemData>

Parameter

Max. Length

Required

Data type

Comment

Parameter

Max. Length

Required

Data type

Comment

Name

5

yes

String

The name of the position data field

P1...P1000

Value

4096 per Value

yes

String

One or more values assigned to the position data field.

Please note:
This parameter may occur a maximum of 10 times!

Response /GetOrderList:

[
{
"FileAvailable": true,
"HeadData": [
{
"Name": "H1",
"Value": "015552222"
},
{
"name": "H2",
"Value": "10.99"
},
{
"Name": "H3",
"Value": "19.99"
},
...
],
"ID": "90909009909009",
"Type": 1
},
...
]

Transfer of a single order

Request from the shop for a single order

Parameter

Max. Length

Required

Data type

Comment

Parameter

Max. Length

Required

Data type

Comment

ShopID

128

yes

String

A unique shop ID. The shop ID is assigned by WEBSALE AG.

Password

128

yes

String

The REST password. Is assigned by WEBSALE AG and must be checked by the ERP system. The ERP system must reject the request if the password is incorrect.

SubshopID

128

yes

String

A unique subshop ID in which the orders will be displayed.

CustomerSubshopIDs

128 per ID

yes

String array

List of valid subshops of the customer

CustomerID

64

yes

String

A unique customer number

BillCountry

3

no

String

Bill country ISO 3166 (e.g. DEU) of the customer, if known in the shop.

Type

 

yes

Integer

This value was supplied by the ERP system in the list and is returned here.

ID

128

yes

String

This value was supplied by the ERP system in the list and is returned here.

Request /GetOrder:

{
"ShopID": "myshop",
"Password": "1234567890",
"BillCountry": "DEU",
"CustomerID": "1001",
"CustomerSubshopIDs": [
"German"
],
"ID": "90909009909009",
"SubshopID": "German",
"Type": 1
}

Response from ERP system /GetOrder:

(See also header data and item data)

{
"Type": 0,
"ID": "90909009909009",
"FileAvailable": true,
"ReturnFileAvailable": false,
"CancellationFileAvailable": false,
"BankTransferRefund": true,
"HeadData": [
{
"name": H1,
"Value": CustomerNumber
},
{
"Name": H2,
"Value": Order Date
},
...
],
"Positions": [
{
"MaxCancellations": 0,
"MaxReturns": 1,
"OrderQuantity": 1,
"PartCancellations": true,
"PartReturns": false,
"PositionData": [
{
"name": "P1",
"Value": "Part Number"
},
{
"Name": "P2",
"Value": "Description"
},
...
],
"ItemID": "p0"
},
{
"MaxCancellations": 1,
"MaxReturns": 2,
"OrderQuantity": 2,
"PartCancellations": true,
"PartReturns": false,
"PositionData": [
{
"name": "P1",
"Value": "Part Number"
}
],
"PositionID": "p1"
},
...
]
}

Transfer of the possible reasons for cancellation/returns

Optionally, the ERP system can provide the possible reasons in the header data of the order, which the customer can select in the shop in case of a cancellation or a return.

This overwrites any reasons stored in the shop configuration.

  • To overwrite the cancellation reasons, the CancellationReasons array must be transferred.

  • To overwrite the return reasons, the ReturnReasons array must be transferred.

{
"Type": 0,
"ID": "90909009909009",
"FileAvailable": true,
"ReturnFileAvailable": false,
"CancellationFileAvailable": false,
"BankTransferRefund": true,
"CancellationReasons": [
{
"Code": 0,
"Text": "No Reason"
},
{
"Code": 1,
"Text": "Incorrectly ordered"
},
...
],
"ReturnReasons": [
{
"code": 0,
"text": "No Reason"
},
{
"Code": 1,
"Text": "Incorrectly ordered"
},
...
],
...
}

Parameter

Max. Length

Required

Data type

Comment

Parameter

Max. Length

Required

Data type

Comment

Code

 

yes

Integer

The code of the reason

Text

1024

yes

String

The readable text of the justification available for selection in the shop.

Transfer of a PDF file

If, for example, an invoice is requested via PDF, the ERP system supplies all the data of an order:

  • complete invoice address

  • complete delivery address

  • all items of the order

  • Total amount

  • Payment method

  • Shipping method/deliverer

  • etc.

The shop transfers to the ERP system the unique ID of the order and the type that the ERP system sent in the order.

Returns

If a return is registered, then the ERP system can provide the shop with a PDF file (return label, etc.) and announces this to the shop in the header data.

{
"Type": 0,
"ID": "90909009909009",
"FileAvailable": true,
" ReturnFileAvailable": true,
"CancellationFileAvailable": false,
"BankTransferRefund": false,
...
}

The PDF file of a return is requested with type "1001".

Cancellations

If a cancellation is performed, then the ERP system can provide the shop with a PDF file (cancellation confirmation, etc.) and notifies the shop of this in the header data.

{
"Type": 0,
"ID": "90909009909009",
"FileAvailable": true,
"ReturnFileAvailable": false,
" CancellationFileAvailable": true,
"BankTransferRefund": false,
...
}

PDF file of a cancellation is requested with type "1002".

Request from the shop for a single order as PDF file

Parameter

Max. Length

Required

Data type

Comment

Parameter

Max. Length

Required

Data type

Comment

ShopID

© 2025 WEBSALE AG | Impressum | Datenschutz