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

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.
For each placed order we immediately send XML file with ORDERS document by FTP to the ORDERS directory.
You periodically check ORDERS directory and process new files. Processed files may be removed from this directory (doesn't matter for us).
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.
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.

Web Service

Base URL	https://secure.webmercs.com/vis/vendorOrdering/v1
WSDL	https://secure.webmercs.com/vis/vendorOrdering/v1?singleWsdl

Interface

Methods

`GetOrders`	Returns a list of new orders. Order is considered new until one of three possible responses (listed below) is received. Class `GetOrdersResult` represents a list of orders where order class `OrderRequest` corresponds to the ORDERS document.
`SendOrderAcknowledgment`	Send an acknowledgment message to inform that order is succesfully received. Method is used just to remove received order from list of new orders which are returned by `GetOrders` method. Class `OrderAcknowledgment` corresponds to the ORDACK document.
`SendOrderResponse`	Send an order response message. Class `OrderResponse` corresponds to the ORDRSP document.
`SendOrderDespatchAdvice`	Send an order despatch advice message. Class `OrderDespatchAdvice` corresponds to the DESADV document.

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

Activation

To enable Web Service ordering send request to support. We will provide login/password to access it.

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 or Web Service 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
ORDERS	outgoing	Order request.
ORDRSP	incoming	Order response.
DESADV	incoming	Order despatch advice.
ORDACK	incoming	Order acknowledgment.

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

Field	Required	Data Type	Description	Sample
`LineNumber`	yes	int	Number of order line from ORDERS document.	1
`VendorSKU`	yes	string	Product identifier in a vendor system, the same value as in ORDERS document.
`Qty`	yes	int	Quantity.
`Price`	yes	decimal	Price.
`SerialNumbers`	no		List of serial numbers.
`SerialNo`	yes	string	Serial number.

`<TrackingLine>` segment

Field	Required	Data Type	Description
`TrackingNo`	yes	string	Package\tracking number.
ShipMethod	no	string	Shipping service (company) and method.
TrackingURL	no	string	URL to check package status.

Order Acknowledgment (ORDACK)

Web Service ordering only.

The Order Acknowledgment document is used to inform that the Order Request document is received.

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

`<OrderAcknowledgment>` 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"

Public:Documentation

Vendor Integration - Ordering

How it works

FTP

Web Service

Interface

Methods

Possible errors

Email

Documents

Common notes

Order Request (ORDERS)

`<OrderHeader>` segment

`<ShipTo>` segment

`<OrderLine>` segment

Order Response (ORDRSP)

`<OrderResponse>` segment

Despatch Advice (DESADV)

`<DespatchAdvice>` segment

`<OrderLine>` segment

`<TrackingLine>` segment

Order Acknowledgment (ORDACK)

`<OrderAcknowledgment>` segment

How it works

FTP

Web Service

Interface

Methods

Possible errors

Email

Documents

Common notes

Order Request (ORDERS)

<OrderHeader> segment

<ShipTo> segment

<OrderLine> segment

Order Response (ORDRSP)

<OrderResponse> segment

Despatch Advice (DESADV)

<DespatchAdvice> segment

<OrderLine> segment

<TrackingLine> segment

Order Acknowledgment (ORDACK)

<OrderAcknowledgment> segment

`<OrderHeader>` segment

`<ShipTo>` segment

`<OrderLine>` segment

`<OrderResponse>` segment

`<DespatchAdvice>` segment

`<OrderLine>` segment

`<TrackingLine>` segment

`<OrderAcknowledgment>` segment