/
Vendor Integration - Ordering

Vendor Integration - Ordering

Feb 20, 2025
Ordering


How it works

This is an option for vendors that don't have their own electronic order API (or for other reasons prefer to use this way to communicate order messages with our clients).

FTP

  1. FTP contains three root directories.

    • /ORDERS - Contains XML files with ORDERS documents. One file per order. File name format is  wmxorder_<internal-webmercs-id>.xml

    • /ORDRSP - Contains unprocessed order response (ORDRSP) documents. Each file should only contain information about one order, but multiple files for the same order is ok.

    • /DESADV - Contains unprocessed dispatch advice (DESADV) documents. Each file should only contain information about one order, but multiple files for the same order is ok.

  2. For each placed order we immediately send XML file with ORDERS document by FTP to the ORDERS directory.

  3. You periodically check ORDERS directory and process new files. Processed files may be removed from this directory (doesn't matter for us).

  4. For each received order you send XML files with ORDRSP and/or DESADV documents. ORDRSP is not required, but recommended, We will process DESADV messages even if there's no ORDRSP for the orders.

  5. We periodically check FTP directories ORDRSP and DESADV and process new files. Successfully processed files are removed from these folders (but we store them in archive on our servers). In case of processing error, file is moved to sub-directory ERROR.

Activation

To enable FTP ordering send request to support. You can specify which FTP should be used:

  • Webmercs FTP - we will prepare FTP for you.

  • Your own FTP - you should provide adress/username/password.

In case of Your own FTP you should also create three root directories ORDERS, ORDRSP, DESADV.

Possible errors

Code

Description

1001

Authentication failed. Check login \ password.

1002

Internal error.

1003

Some required properties are not provided or empty. See details in the exception message.

1004

Order not found. Check CustomerID \ CustomerPO properties.

1005

Invalid order response status. Check property Status of OrderResponse class. Possible values "Accepted" (1) and "Rejected" (2).

1006

Invalid order status. < add examples >

1007

Invalid XML structure.

1008

Invalid property format

Email

For each placed order we immediately send email to you with ORDERS document as an attachment. No way to send responses by email, please use FTP for that.

Activation

To enable Email notifications send request to support. You should specify email address(es) to which you will receive ORDERS documents.

 

Documents

Type

Direction

Description

FTP

Email

ORDERS

outgoing

Order request.

ORDRSP

incoming

Order response.

 

DESADV

incoming

Order despatch advice.

 

Common notes

  • Required segments\fields must exist in the document with non-empty values.

  • Optional segments\fields are either missing in the document, or have an empty value.

Order Request (ORDERS) 

<?xml version="1.0" encoding="utf-8"?> <OrderRequest xmlns="http://webmercs.com/vis/public"> <OrderHeader> <CustomerID></CustomerID> <CustomerPO></CustomerPO> <OrderDateTime></DateTime> <SplitOrder></SplitOrder> <ShippingMethod></ShippingMethod> <RequestedDeliveryDate></RequestedDeliveryDate> <Comment></Comment> <BillTo> <Name></Name> <Company></Company> <Department></Department> <Street></Street> <City></City> <StateProvince></StateProvince> <Zip></Zip> <Country></Country> <Phone></Phone> <Email></Email> </BillTo> <ShipTo> <Name></Name> <Company></Company> <Department></Department> <Street></Street> <City></City> <StateProvince></StateProvince> <Zip></Zip> <Country></Country> <Phone></Phone> <Email></Email> <EndUserPO></EndUserPO> </ShipTo> </OrderHeader> <OrderLines> <OrderLine> <LineNumber></LineNumber> <VendorSKU></VendorSKU> <WmxSKU></WmxSKU> <Description></Description> <Qty></Qty> <ExpectedPrice></ExpectedPrice> <Bid> <ClaimNo></ClaimNo> <Price></Price> </Bid> <Comment></Comment> </OrderLine> </OrderLines> </OrderRequest>

<OrderHeader> segment

Field

Required

Data Type

Description

Sample

CustomerID

yes

string

Customer identifier in a vendor system which is provided on setup step.

"CID-898800"

CustomerPO

yes

string

Unique order request identifier in Webmercs system.

"3445FHY-2"

OrderDateTime

yes

dateTime

Date and time when Webmercs received order request from customer.  

2012-10-25T12:50:12+01:00

SplitOrder

yes

string

Possible values: "Yes", "No".

"Yes"

ShippingMethod

no

string

 

 

RequestedDeliveryDate

no

dateTime

Customer may ask for a particular delivery date.

2012-10-30

Comment

no

string

Customer's comment.

"Test order, do not ship!"

ShipTo

yes

 

Shipping address, see <ShipTo> segment.

 

BillTo

no

 

Billing address. Same fields as <ShipTo> segment, except EndUserPO.

 

<ShipTo> segment

Field

Required

Data Type

Description

Sample

Name

yes

string

Contact person name.

"Mike Petrov"

Company

no

string

Company name.

"Horns and Hooves"

Department

no

string

Department name.

"Accounting"

Street

yes

string

Address line.

"Rådhusplassen 99"

City

yes

string

City name.

"Oslo"

StateProvince

no

string

State or province name or code.

 

Zip

yes

string

Postcode.

"0160"

Country

yes

string

Two letter country code (ISO 3166-1 alpha-2).

"NO"

Phone

no

string

Contact person phone.

"11100999"

Email

no

string

Contact person email.

"mike@hh.com"

EndUserPO

no

string

Contact person PO.

"HH-0289"

<OrderLine> segment

Field

Required

Data Type

Description

Sample

LineNumber

yes

int

Sequential number of order line, starting from 1.

1

VendorSKU

yes

string

Product identifier in a vendor system.

"SMT3000RMI2U"

WmxSKU

yes

string

Product identifier in Webmercs system.

"3931244"

Description

yes

string

Product description from Webmercs catalog.

"APC Smart UPS 3000VA"

Qty

yes

int

Quantity.

10

ExpectedPrice

no

decimal

Vendor price from customer's catalog.

8700.0

Bid

no

 

 

 

ClaimNo

no

string

 

 

Price

no

decimal

 

 

Comment

no

string

Customer's comment.

"Cancel if real price is higher."

Order Response (ORDRSP) 

Example.

<?xml version="1.0" encoding="utf-8"?> <OrderResponse xmlns="http://webmercs.com/vis/public"> <CustomerID></CustomerID> <CustomerPO></CustomerPO> <Status></Status> <Message></Message> <VendorOrderID></VendorOrderID> </OrderResponse>

<OrderResponse> segment

Field

Required

Data Type

Description

Sample

CustomerID

yes

string

Customer identifier in a vendor system, the same value as in ORDERS document.

"CID-898800"

CustomerPO

yes

string

Order identifier in Webmercs system, the same value as in ORDERS document.

"3445FHY-2"

Status

yes

string

Possible values: "Accepted", "Rejected".

"Accepted"

Message

no

string

Vendor's comment.

"Estimated delivery date is 21/10/2012"

VendorOrderID

yes, when "Accepted"

string

Order identifier in a vendor system.

"VND-O888"

Despatch Advice (DESADV) 

<?xml version="1.0" encoding="utf-8"?> <DespatchAdvice xmlns="http://webmercs.com/vis/public"> <CustomerID></CustomerID> <CustomerPO></CustomerPO> <VendorOrderID></VendorOrderID> <OrderLines> <OrderLine> <LineNumber></LineNumber> <VendorSKU></VendorSKU> <Qty></Qty> <Price></Price> <SerialNumbers> <SerialNo></SerialNo> </SerialNumbers> </OrderLine> </OrderLines> <TrackingLines> <TrackingLine> <TrackingNo></TrackingNo> <ShipMethod></ShipMethod> <TrackingURL></TrackingURL> </TrackingLine> </TrackingLines> </DespatchAdvice>

<DespatchAdvice> segment

Field

Required

Data Type

Description

Sample

CustomerID

yes

string

Customer identifier in a vendor system, the same value as in ORDERS document

"CID-898800"

CustomerPO

yes

string

Order identifier in Webmercs system, the same value as in ORDERS document.

"3445FHY-2"

VendorOrderID

yes

string

Order identifier in a vendor system.

"VND-O888"

OrderLines

yes

 

Contains list of <OrderLine> segments.

 

TrackingLines

no

 

Contains list of <TrackingLine> segments.

 

<OrderLine> segment