Inleiding
In dit document wordt de webservice MediaOrderB2C toegelicht. Deze webservice is ontwikkeld met REST/JSON.
Resources en operaties
In REST wordt gebruik gemaakt van Resources en Operaties. Een resource kan gezien worden als object, een operatie als activiteit op een object. De volgende resources zijn onderkent:
Resource (object) | YAML | Operatie (activiteit op een object) | Van | Naar | Beschrijving |
|---|---|---|---|---|---|
| File | MediaFile | placeFile | Klant | CB | Het versturen van een bestand (PDF) dat als bijlage aan een order gekoppeld is. Het bestand wordt bij het gereed maken van de zending geprint en bijgevoegd in de doos. Het PDF bestand dient voorafgaand aan de order door CB ontvangen te zijn. Opmerking: Deze operatie is nog niet beschikbaar. |
| Order | MediaOrderB2C | placeOrder | Klant | CB | Het versturen van een order naar CB. De bestelling. Bij ontvangst van de order wordt een basis validatie uitgevoerd, indien er geen uitzonderingen zijn aangetroffen zal de order als ontvangen opdracht wordt vastgelegd en wordt er als reply een bevestiging naar de klant gestuurd. |
| getOrderStatus | Klant | CB | Het opvragen van de status van de door de klant ingediende order. Bij vooraf gedefinieerde statusveranderingen van een order (events) wordt een notify signaal naar de klant gestuurd, operatie notifyOrder. De klant kan vervolgens de gedetailleerde orderstatus bij CB opvragen. De orderstatus geeft informatie van de gehele oorspronkelijk ingediende opdracht. | ||
| getShippingUnits | Klant | CB | Het opvragen van de levereenheden waarin de door de klant ingediende order is verstuurd. Ten behoeve van een volledigheidscontrole kan de klant een overzicht van alle shippingunits/levereenheden opvragen waarin de artikelen van de order in verstuurd zijn. Opmerking: Deze operatie is nog niet beschikbaar. | ||
| cancelOrderLine | Klant | CB | Het annuleren van een orderregel. De klant kan een order of een orderregel annuleren, dit kan tot het moment dat de order gereed gemaakt wordt voor distributie. | ||
| MediaOrderNotify | notifyOrder | CB | Klant | Het melden dat de order of orderregel een vooraf gedefinieerde status heeft bereikt. | |
| Shipment | MediaShipmentNotify | notifyShipment | CB | Klant | Het melden dat er een shippingunit/levereenheid aan de vervoerder overgedragen is. Voor elke levereenheid die klaar staat voor verzending wordt een notify signaal naar de klant gestuurd. De klant kan vervolgens de details van de levereenheid bij CB opvragen, operatie getShippingUnit. |
| MediaShipment | getShippingUnit | Klant | CB | Het opvragen van details van een shippingunit/levereenheid. In de details is per artikel een referentie naar de relevante orderregel opgenomen. | |
| Postponed-order | OrderBeheer | getPostponedOrders | CB | CB | Het opvragen van orders die gedurende het maintenance window zijn geparkeerd en nog niet zijn verwerkt. |
| placeSingleOrder | CB | CB | Het doorzetten van een order nadat deze tijdelijk geparkeerd is tijdens het maintenance window. | ||
| getPostponedCancelOrderLines | CB | CB | Het opvragen van annuleringen voor orderregels die gedurende het maintenance window zijn geparkeerd en nog niet zijn verwerkt. | ||
| cancelSingleOrderLine | CB | CB | Het doorzetten van een annulering voor een orderregel nadat deze tijdelijk geparkeerd is tijdens het maintenance window. |
Schematische weergave webservice Media orders B2C
CB Media Interface Description
Revisions
Version | Date | Description |
|---|---|---|
| 0.1 | 30-08-2019 | Initial document |
| 0.3 | 11-11-2019 | Add operations |
| 0.5 | 13-01-2020 | Add flows and sequence diagrams |
| 0.6 | 11-03-2020 | Add volume limits and error messages |
Introduction
This document contains a description of the standard interfaces for implementation of data exchange with CB via webservices.
| The entire set for the standard data exchange with CB consists of the following documents and files: | |
| The mapping from file based to webservice based messages | |
| The functional description of the definitions in the operations | |
| yaml definition files | An OpenAPI Specification file (yaml) for each resource |
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.
CB provides REST based webservices. In REST operations define the available activities.
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.
Webservices are available 24 hours a day, 7 days a week, however order handling is restricted to warehouse working hours. Our regular maintenance window is on Saturday from 08:00 hours until 14:00 hours. The webservice operations are available during this time, but received requests are stored only (i.e. not validated or processed).
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.
Orders are processed independent from the receiving channel.
| Mapping batch files versus webservice operations | |
|---|---|
| OPDNAW | placeOrder |
| ANNOPD | cancelOrder |
| UITOPD | notifyOrder / getOrderStatus + notifyShipment / getShippingUnit |
| NUITOP | notifyOrder / getOrderStatus |
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
MediaOrderB2C
| Webservice name: | MediaOrderB2C |
| Definition: | MediaOrderB2C.yaml |
| Resource: | Orders |
| Operations provided by CB: | |
| placeOrder | Send one (1) order to CB |
| cancelOrderLine | Cancel one (1) orderline |
| getOrderStatus | Retrieve the status of one (1) order |
Waardes voor lijsten
De webservice operaties gebruiken Engelse termen en human readable waardes voor lijsten.
Downloadable yaml files
- MediaOrderB2C v0.9.8.yaml
- MediaFile v0.9.0.yaml
- MediaOrderNotify v0.9.4.yaml
- MediaShipmentB2C v0.9.1.yaml
- MediaShipmentNotify v0.9.3.yaml
- MediaShippingUnit v0.9.2.yaml