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

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"
}
],
...
}

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

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:

Fixed position data

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:

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

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"
},
...
],
...
}

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