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:

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

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:

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

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

Request /GetFile:

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

Response from the ERP system as a PDF file

The ERP system returns the following data:

Response from ERP system /GetFile:

{
"FileName": "1234567890.pdf",
"FileData": "Base64-encoded PDF data"
}

The file name should be generated as uniquely as possible by the ERP system, e.g. from the invoice number and the extension "pdf". It should not contain any special characters or spaces.

The file format does not necessarily have to be PDF. In principle, any format can be sent that has the widest possible distribution among Internet users. Currently, PDF is the best choice.

Cancellation/return of items of an order

As described above, the ERP system announces for each item whether and how many pieces can be cancelled/returned.

{
...
"Positions": [
{
"MaxCancellations": 0,
"MaxReturns": 2,
"OrderQuantity": 2,
"PartCancellations": false,
"PartReturns": true,
"PositionData": [
{
"name": "P3",
"Value": "asdf0000"
}
],
"PositionID": "1"
},
...

Thus, for example, a purchaser could cancel the first item and return the 2nd item if the 2nd item has already been shipped in a partial delivery.

An item can either be cancelled or returned. Both at the same time is not possible.

Cancellation per position
If the ERP system transfers the value "0", then no cancellation is offered. Otherwise a

• Cancellation checkbox

• Quantity input field, if MaxCancellations > 1

• DropDown list for a reason

is offered.

Return per item
If the ERP system passes the value "0", then no return is offered. Otherwise a

• Returns checkbox

• Quantity input field, if MaxReturns > 1

• DropDown list for a reason

is offered.

The shop optionally offers a freely configurable drop-down list for each item, by means of which the customer can specify a reason. A code is transmitted to the ERP system for this purpose.

Example for returns:
0=no reason given
1=don't like quality
2=wrong item delivered
3=delivered too late
etc.

The code and texts are given by the ERP system and stored in the shop.

Querying the bank details
If the ERP system reports to the shop that the bank details for the refund should be queried (BankTransferRefund=true), then 4 further input fields are used as required fields

• Name of the bank

• Account holder

• IBAN

• BIC

will be displayed.

Sending a return or a cancellation to the ERP system

Request /CancelOrder:

{
"ShopID": "myshop",
"Password": "1234567890",
"SubshopID": "German",
"BillCountry": "DEU",
"CustomerID": "1001",
"CustomerSubshopIDs": [
"German"
],
"ID": "90909009909009",
"RefundBankBIC": "BIC",
"RefundBankIBAN": "IBAN",
"RefundBankName": "BankName",
"RefundBankOwner": "AccountOwner",
"positions": [
{
"PositionID": "1",
"CancelType": 1,
"ReasonCode": 0,
"Quantity": 1
},
...
]
}

Please note:
Only the items that should be cancelled/returned are sent to the ERP system.

Response from ERP system

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

Additional header data
In the header data, the ERP system can inform now and in later requests for this order that a return PDF file, or cancellation PDF file can be picked up.

Additional item data
The ERP system reports for each item which action was performed and whether the action was successful or not. These values should only be sent once. They should then be omitted for subsequent requests.

Please note:
If an item was successfully returned, the ERP system must set the values for

"MaxReturns": 0,
"PartReturns": false,

in this response (and all subsequent responses) accordingly, so that the orderer cannot return again. The same applies to a successful cancellation.

Also, from this point on, the ERP system should pass the date and time of the cancellation/return so that this information can be displayed to the orderer in subsequent queries.

Response (example: orderer has cancelled 2nd item and returned 3rd item) /CancelOrder:

{
"Type": 0,
"BankTransferRefund": true,
"FileAvailable": true,
"ID": "90909009909009",
"HeadData": [
{
"name": "H1",
"value": "CustomerNumber"
},
...
],
"positions": [
{
"MaxCancellations": 2,
"MaxReturns": 0,
"OrderQuantity": 2,
"PartCancellations": true,
"PartReturns": false,
"PositionData": [
{
"name": "P1",
"Value": "PartID"
},
...
],
"PositionID": "1"
},
{
"MaxCancellations": 0,
"MaxReturns": 0,
"OrderQuantity": 1,
"PartCancellations": false,
"PartReturns": false,
"CancelType": 1,
"CancelErrCode": 0,
"CancelErrMsg": "Position Cancelled Successfully",
"PositionData": [
{
"name": "P1",
"Value": "Item Number"
},
...
],

"PositionID": "2" },
{
"MaxCancellations": 0,
"MaxReturns": 0,
"OrderQuantity": 2,
"PartCancellations": false,
"PartReturns": false,
"CancelType": 2,
"CancelErrCode": 0,
"CancelErrMsg": "Return successfully registered",
"PositionData": [
{
"name": "P3",
"Value": "asdf0003"
}
],
"PositionID": "3"
},
...
]
}

Transfer of the last shop order number

In order for the shop to display the orders that have not yet been imported into the ERP system, it is necessary that the ERP system informs the shop of the last shop order number that the ERP system has imported or that is known to the ERP system.

The shop's request contains the following parameters:

Request from shop/GetLastOrderNumber:

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

Response from the ERP system for the last shop order number

The ERP system returns the following data:

Response from ERP system /GetLastOrderNumber:

{
"LastOrderNumber": "1234567890"
}

Transfer of a single stock (of a branch)

The request from the shop contains the following parameters:

The branch ID is optional. If no branch ID is transferred, the ERP system returns the stock level of the article with regard to the subshop. If a branch ID is transferred, then the ERP system returns the stock level with regard to the branch.

Request from shop /GetStockAmount:

{
"ShopID": "myshop",
"password": "1234567890",
"SubshopID": "German",
"ProductNumber": "1234567",
"BranchID": "123"
}

Response from the ERP system for the individual stock

The ERP system returns the following data:

Response from ERP system /GetStockAmount:

{
"StockAmount": 100
}

Transfer of general customer data

This information is not about order data, but about general customer data, such as a customer's accumulated bonus points or discounts on a purchase.

The shop's request contains the following parameters:

Request from shop /GetCommonData:

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

Response from ERP system for general data

The ERP system returns in the shop freely configurable data.

In the shop freely configurable data:

A maximum of 1000 different command data C1...C1000 are supported in the shop.

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

Common data is freely configurable in the shop(optionally per type).
Example of a configuration file in the shop independent of the data type:

<CommonData>
C1 = Bonus points
C2 = Customer specific discounts by calendar year
...
</CommonData>

Response from ERP system /GetCommonData:

[

{
"Name": "C1",
"Value": "100"
},
{
"Name": "C2",
"Value": [
"sales-based customer discount 2010: 5%",
"sales-based customer discount 2011: 12%",
"sales-based customer discount 2012: 5%",
"sales-based customer discount 2013: 12%"
]
},
...
]