Revision

Introduction

This document contains a description of the standard interfaces for implementation of data exchange with CB via webservices.

Tag matrix for Green and Standard option
CB has two options for submitting e-commerce orders: Green option no document attached to shipment Standard option packing slip or invoice included with shipment
The entire set for the standard data exchange with CB consists of the following documents and files:
File versus webservice. Communication about orders is based on the receiving channel, i.e. file base communication is used for orders received via file based interfaces and webservice communication is used for orders received via the webservice MediaOrderB2C. Order are processed independent from the receiving channel
Mapping berichten naar webservices B2C.xlsx	The mapping from file based to webservice based messages
File based	Webservice operation
OPDNAW	placeOrder
ANNOPD	cancelOrder
UITOPD	notifyOrder / getOrderStatus + notifyShipment / getShippingUnit
NUITOP	notifyOrder / getOrderStatus

Authentication & Authorisation

Webservice information

Overview webservices

This chapter gives an overview of the available interaction patterns for data exchange with CB. The figure below gives an high level overview of the CB system landscape and the available webservice operations.

The webservices provide online creation and cancelation of media orders at CB. Changes to an order (other than cancel) are not available. Resending an order is possible only when the order was not accepted by CB earlier. 

Operations

Order - placeOrder

The operation placeOrder supports sending one order for a customer. An order can contain multiple orderlines, each for a specific title. Confirmation of the operation is provided with a http-response-code.

Check order identification (Requestor Order Id)

The identification of an order is used to check if an order already exists in the CB systems. If this is the case the new order is rejected. Only open orders are taken into account, so closed/cancelled orders are ignored.

Order type

The operation is available for order types ShipBuyer (LNAFN), ShipOwner (LNEIG) and ShipSecundaryOwner (LMEONE).

Sender and Owner

In the common scenario for media orders the sender requests CB to ship titles owned by a publisher to a consumer. This scenario identifies the publisher as owner, the sender (shop) as buyer from the owner and the consumer as receiver (and buying from the shop). An alternative scenario is secondary ownership, in this alternative scenario the sender (shop) already purchased titles from the publisher and requests CB to ship from its own stock.

Party

Because parties where goods have to be delivered are not known by CB the PartyType “ReceiverAddress,” is mandatory and all name and address information must be provided.

Values added services (VAS)

VAS activities can be controlled by means of special handling instructions for the order.

Examples of instructions:

• Wrap the books in gift paper

• Add leaflet to the package

Available special handling instructions must be agreed upon in advance by requestor and CB.

cancelOrderLine

The operation cancelOrderLine supports cancellation of one orderline. Cancellation is available until the orderline is released for production (“vrijgegeven”). Confirmation of the operation is provided with a http-response-code. The operation requires the OrderId and OrderLineId as input and is available for orders entered via webservices only.

getOrderStatus

When the status of an order or orderline is changed a notifyOrder message is sent. This is the preferred trigger to call the operation getOrderStatus.

The operation getOrderStatus provides the status summary of the requested order. An order can contain multiple orderlines, each for a specific product. The status of every orderline is reported separately. An orderline can also be reported in multiple statuses, for instance when part of the quantity is available and ready for production and the remaining quantity is in backorder. If (a part of) the order is not delivered, the status includes an explanation why.

The operation requires the OrderId as input and available for orders entered via webservices only.

Available statuses for notifyOrder:

• New Order is accepted after being received during the service window

• InProgress Order(line) passed validation

• ProductionReady Order(line) is ready for pick/pack in warehouse

• Warning Order processing started with an issue for at least one orderline

• Processed Order is finished with shipment

• Cancelled Order is finished without shipment

Shipment - getShippingUnit

When a shipment is ready to be shipped a notifyShipment message is sent per available shipping unit. The operation getShippingUnit provides the contents of the shipping unit and the relation to order and orderlines. An order can be shipped in multiple shipping units.

The operation requires the ShippingUnitId as input.

Available statuses for notifyShipment:

• Processed ShippingUnit is ready for shipping

Response messages

MediaOrderB2C
HTTP code	Error code	Description/Message	getOrderStatus	placeOrder	cancelOrderLine
200		Request executed
204		Request executed
206		Request executed with pending status
400		Request failed
401		Not authorised
404		Order not found
HTTP code	Error code	Description/Message The list of error codes within these groups may change in time without notice	getOrderStatus	placeOrder	cancelOrderLine
CEP-***	CEP-002	The request does not comply with the yaml definition; Value is not one of the possible/allowed values [instance value (\"1234567890\") not found in enum (possible values: [\"SecundaryOwnerStock\",\"SecundaryOrPrimary\",\"PrimaryOwnerStock\",\"PrimaryOrSecundary\"]), format attribute \"decimal\" not supported, format attribute \"int32\" not supported]
	CEP-002	The request does not comply with the yaml definition; Value does not meet regex [ECMA 262 regex \"^[^#]*$\" does not match input string \"#\", format attribute \"int32\" not supported]
	CEP-002	The request does not comply with the yaml definition; Value does not meet set minimum or maximum value [numeric instance is lower than the required minimum (minimum: 6000000, found: 123), format attribute \"decimal\" not supported, format attribute \"int32\" not supported]
	CEP-003	Authentication/Authorisation error You are not authenticated
WMO-***	WMO-00503	The request encountered a mapping error, mainly due to incorrect shipment date(s); Delivery period and delivery date cannot both be given If Delivery is specified, then either DeliveryDate or DeliveryPeriod must be supplied
	WMO-00508	The request encountered a mapping error, mainly due to incorrect shipment date(s); Date must be in the future The DeliveryDate is in the past
	WMO-00509	The request encountered a mapping error, mainly due to incorrect shipment date(s); Invalid date Invalid date for Delivery/DeliveryPeriod/Till: <Submitted ShipmentPeriod.Till> compared to Delivery/DeliveryPeriod/From <Submitted ShipmentPeriod.From>
	WMO-00510	The request encountered a mapping error, mainly due to incorrect shipment date(s); Date must be in the future The Delivery/DeliveryPeriod/From is in the past
	WMO-00511	The request encountered a mapping error, mainly due to incorrect shipment date(s); Date must be in the pastThe The Delivery/DeliveryPeriod/Till is in the past
HTTP code	Error code	Description/Message The list of error codes within these groups may change in time without notice	getOrderStatus	placeOrder	cancelOrderLine
OMS-***
	OMS-01268	Order not found <OrderId>
	OMS-01342	Orderline was already cancelled
	OMS-01269	Unable to cancel order. Order already processed
	OMS-01378	Crossdock orderline can not be cancelled
	OMS-01373	Unable to cancel orderline. Orderline already promoted to the Warehouse

Process flows

This chapter contains the identified flows when using webservices to order physical books at CB. The most common and regular scenario is describes in the happy flow. In addition 7 frequent scenarios are described in alternative flows.

Happy flow

The customer orders one or more products, stock is available and the order is shipped in one shipment.

Flow description:

• The customer puts one or more products in the shopping basket

• The shop forwards the order to CB with the operation placeOrder

• CB verifies and accepts the order, the shop is notified with the operation notifyOrder and status event In Progress

• CB assigns stock to the order

• CB prepares for logistic processing of the order. Cancellation of the order is not possible anymore, the shop is notified with the operation notifyOrder and status event ProductionReady

• The shop can retrieve the order process status to see which orderlines are ready for production and cannot be cancelled anymore

• CB executes pick and pack for the order and creates a shipment. The shop is notified with the operation notifyShipment and status event Processed

• The shop can retrieve the shipment details (including tracking number and a list of products) per shipping unit and can inform the customer.

Alternative Flow 1 – multiple shipments

The customer orders multiple products and stock is available for all products. At pick and pack multiple shipping units are created. The order is shipped in multiple shipments.

Flow description:

• The customer puts multiple products in the shopping basket

• The shop forwards the order to CB with the operation placeOrder

• CB verifies and accepts the order, the shop is notified with the operation notifyOrder and status event In Progress

• CB prepares for logistic processing of the order. The shop is notified with the operation notifyOrder and status event ProductionReady

• The shop can retrieve the order process status to see which orderline(s) are ready for production and cannot be cancelled anymore

• CB executes pick and pack for orderline 1 and creates a shipment. The shop is notified with the operation notifyShipment and status event Processed

• The shop can retrieve the shipment details (including tracking number and a list of products) per shipping unit and can inform the customer

• CB executes pick and pack for orderline 2 and creates a shipment. The shop is notified with the operation notifyShipment and status event Processed

• The shop can retrieve the shipment details (including tracking number and a list of products) per shipping unit and can inform the customer

Alternative Flow 2 – multiple shipments due to partial backorder

The customer orders multiple products and stock is available for at least one product. Also at least one product is in backorder. The order is shipped in multiple shipments.

Flow description:

• The customer puts multiple products in the shopping basket

• The shop forwards the order to CB with the operation placeOrder

• CB verifies and accepts the order, the shop is notified with the operation notifyOrder and status event In Progress

• CB prepares for logistic processing of orderline 1. The shop is notified with the operation notifyOrder and status event ProductionReady

• The shop can retrieve the order process status to see which orderline(s) are ready for production and cannot be cancelled anymore

• CB executes pick and pack for orderline 1 and creates a shipment. The shop is notified with the operation notifyShipment and status event Processed

• The shop can retrieve the shipment details (including tracking number and a list of products) per shipping unit and can inform the customer

• CB received stock for orderline 2, assigns stock and prepares for logistic processing of orderline The shop is notified with the operation notifyOrder and status event ProductionReady

• The shop can retrieve the order process status to see which orderline(s) are ready for production and cannot be cancelled anymore

• CB executes pick and pack for orderline 2 and creates a shipment. The shop is notified with the operation notifyShipment and status event Processed

• The shop can retrieve the shipment details (including tracking number and a list of products) per shipping unit and can inform the customer.

Alternative Flow 3 – customer cancellation

The customer orders one or more products, but decides to cancel the order shortly after ordering.

Flow description:

• The customer puts one or more products in the shopping basket

• The shop forwards the order to CB with the operation placeOrder. The operation confirms acceptance of the order

• CB verifies the order, the shop is notified with the operation notifyOrder and status event In Progress

• The customer decides to cancel the order at the shop

• The shop forwards the cancel request per orderline to CB with the operation cancelOrderLine. The operation confirms acceptance of the cancellation

• CB informs the shop that the complete order is cancelled with the operation notifyOrder and status event Cancelled

• The shop confirms the cancellation to the customer.

Alternative Flow 4 – partial customer cancellation

The customer orders multiple products, but decides to cancel at least one of the orderlines but not all shortly after ordering.

Flow description:

• The customer puts multiple products in the shopping basket

• The shop forwards the order to CB with the operation placeOrder. The operation confirms acceptance of the order

• CB verifies the order, the shop is notified with the operation notifyOrder and status event In Progress

• The customer decides to cancel orderline 1 in the shop

• The shop forwards the cancel request for orderline 1 to CB with the operation cancelOrderLine.The operation confirms acceptance of the cancellation

• CB informs the shop that an orderline is cancelled with the operation notifyOrder and status event Cancelled

• The shop confirms the cancellation to the customer

• CB prepares for logistic processing of orderline 2. The shop is notified with the operation notifyOrder and status event ProductionReady

• CB executes pick and pack for orderline 2 and creates a shipment. The shop is notified with the operation notifyShipment and status event Processed

• The shop can retrieve the shipment details (including tracking number and a list of products) per shipping unit and can inform the customer.

Alternative Flow 5 – CB order reject

The customer orders one or more products, but the order is not accepted by CB due to unknown products.

Flow description:

• The customer puts multiple products in the shopping basket

• The shop forwards the order to CB with the operation placeOrder. The operation confirms rejection of the order

Alternative Flow 6 – partial CB cancellation

The customer orders multiple products and stock is available for at least one product. Also stock is not available for at least one product and backlog is not allowed.

Flow description:

• The customer puts multiple products in the shopping basket

• The shop forwards the order to CB with the operation placeOrder. The operation confirms acceptance of the order

• CB verifies the order and identifies that orderline 1 is not available, the shop is notified with the operation notifyOrder and status event Cancelled

• CB identifies that orderline 2 is available, the shop is notified with the operation notifyOrder and status event InProgress

• The shop retrieves the order process status to see which orderline(s) are not available

• CB prepares for logistic processing of orderline 2. The shop is notified with the operation notifyOrder and status event ProductionReady

• CB executes pick and pack for orderline 2 and creates a shipment. The shop is notified with the operation notifyShipment and status event Processed

• The shop can retrieve the shipment details (including tracking number and a list of products) per shipping unit and can inform the customer

Alternative Flow 7 – order during service window

The customer orders one or more products during the service window. Stock is available for all products.

Flow description:

• The customer puts one or more products in the shopping basket

• The shop forwards the order to CB with the operation placeOrder. The operation confirms receipt of the order during the service window

• CB verifies the order, the shop is notified with the operation notifyOrder and status event InProgress

• CB prepares for logistic processing of the order. The shop is notified with the operation notifyOrder and status event ProductionReady

• The shop can retrieve the order process status with operation getOrderStatus to see which orderline(s) are ready for production and cannot be cancelled anymore

• CB executes pick and pack for the order and creates a shipment. The shop is notified with the operation notifyShipment and status event Processed

• The shop can retrieve the shipment details (including tracking number and a list of products) per shipping unit and can inform the customer

Alternative Flow 8 – cancel during service window

The customer orders one or more products, but decides to cancel the order during the service window.

Flow description:

• The customer puts multiple products in the shopping basket

• The shop forwards the order to CB with the operation placeOrder. The operation confirms acceptance of the order

• CB verifies the order, the shop is notified with the operation notifyOrder and status event In Progress

• The customer decides to cancel the order in the shop

• The shop forwards the cancel request per orderline to CB with the operation cancelOrderLine. The operation confirms receipt of the cancellation request during the service window

• CB confirms a successful cancellation of the order after the service window ended. The shop is notified with the operation notifyOrder and status event Cancelled

• The shop confirms the cancellation to the customer