Content Comparison

Revision

Introduction

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

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.

...

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

Order - 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.

Order - 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.

...

• 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.

...

• Processed ShippingUnit is ready for shipping

Response messages

[instance value (\"1234567890\") not found in enum (possible values: [\"SecundaryOwnerStock\",\"SecundaryOrPrimary\",\"PrimaryOwnerStock\",\"PrimaryOrSecundary\"]), format attribute \"decimal\" not supported, format attribute \"int32\" not supported]

 [ECMA 262 regex \"^[^#]*$\" does not match input string \"#\", format attribute \"int32\" not supported]

[numeric instance is lower than the required minimum (minimum: 6000000, found: 123), format attribute \"decimal\" not supported, format attribute \"int32\" not supported]

You are not authenticated

If Delivery is specified, then either DeliveryDate or DeliveryPeriod must be supplied

The DeliveryDate is in the past

Invalid date for Delivery/DeliveryPeriod/Till: <Submitted ShipmentPeriod.Till> compared to Delivery/DeliveryPeriod/From <Submitted ShipmentPeriod.From> 

The Delivery/DeliveryPeriod/From is in the past

The Delivery/DeliveryPeriod/Till is in the past

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.

...

• 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.

...

• 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.

...

• 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.

...

• 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.

...

• 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.

...

• 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.

...

• 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.

...

• 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.

...

• 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

Volume, limits and performance requirements

Timing

Webservice requests are processed realtime, i.e. an order is registered immediately when the webservice call is executed. Order processing at CB is based on scheduled processes and not primarily triggered by the webservice request.

Responses to the requester are send in Near-Realtime (NRT) with an average delay of 2 to 3 minutes. The regular maximum delay is 5 minutes, in exceptions running up to 10 minutes. During this timeframe the orderstatus has reached a status that is not yet reported to the requestor.

Volume

Webservice requests are limited to a maximum of 10 requests per service per second per requestor.

Performance

The media webservices comply with the generic CB webservice performance requirements:

• Average response time within 2 seconds during prime-time (08:00-01:00 CET)

• Response within 3 seconds for 99,95% of the requests during prime-time

• Response within 6 seconds for 99% of the requests outside prime-time

Order simulation for test purpose

In order to test the web service independently as much as possible, a test order based on a few characteristics, that the customer provides, must be processed fully automatically. The functionality described here is available on CB's test environment, but not on the production environment.

Operation of order simulation web service MediaOrderB2C

The order simulation functionality is built into the order handling and processing. 

Simulation characteristic

An order is included in the order simulation on the basis of a test characteristic in the order. The attribute identifier is:

...

The customer can choose which field is used for the characteristic. The other field remains available for the customer's reference. A customer who wants to use both order reference fields in production for his own references must, in order to apply the order simulation, choose which of the two fields is “sacrificed” for the characteristic.

Order Instructions

By default one ShippingUnitID is created for each order, independent of the number of order lines, ordered copies and dimensions of the items. We simulate that everything fits into one ShippingUnitID, which gives the customer a clear expectation of the result of the order. In practice, not everything fits in a ShippingUnitID, so the customer can indicate in the order how many ShippingUnitID's CB need to create.

Orderline instruction

By default, for each OrderLine, the number of copies ordered is also included in the ShippingUnitID as delivered. In practice, various scenarios are possible, as a result of which a different number of copies is delivered. The order simulation supports one scenario, a shortage ('manco') situation. The customer can indicate at the Orderline how many copies are reported missing. 

Test articles

Results for customer

The customer is informed almost immediately when the order status is changed. The diagram below shows which stages are defined and which web service operations are used to communicate or make information available to the customer. 

...