Pickup Cloud API realtime push mechanism

1. Introduction

The Pickup Cloud API provides the functionality of sending realtime events when changes regarding an order occur (e.g. when an order is created, canceled or packs of an order are picked up).

All that is needed to interact with the api is:

use one of the supported client technologies (c#, java, javascript, c++)
have an API Key; this is needed to authenticate your API client to the Pickup Cloud API and is the same API Key you can use to create a new pickup order. Once a connection between your API client and our server is established, you will be notified whenever one of the order you create via our Pickup Cloud API has changed.
You don't have an API Key yet? Request one!

2. SignalR

The underlying technology used by the realtime notification API is Microsoft SignalR Core, which is built on top of modern websockets.

In order to be able to connect to the realtime API, you must use one of the supported platforms.

3. Pickup Cloud Realtime API description

Although the SignalR technology is, basically, a RPC (remote procedure call) technology which allows clients initiate requests, currently our realtime Pickup Cloud API implements only server initiated events, in order to maximize supported scenarios. The basic steps to connect to the realtime API is:

create a hub connection to our public endpoint
subscribe to the OrderStateChanged notification and/or to the OrderArticleStateChanged / OrderArticleWithPackStateChanged notification
connect and wait for notifications

In case of a disconnect or network error, you should retry after a reasonable delay (which can also be gradually increased if the reconnect attempt keeps failing).

The OrderStateChanged is a notification callback method; if something with an order triggered by the Pickup Cloud API, the Pickup Cloud UI or physically happens, this hub method is called. It has the following parameters:

OrderNumber: the order number (in the third party application) of the order which state changed. It is the same order number that you must provide when you create a new pickup order via Pickup Cloud API.
PickupCode: the pickup code you received when you created a new pickup order via Pickup Cloud API.
OrderState: the new state of the order, it is one of the values you also get via the Pickup Cloud API endpoint, meaning one of the following values:

READYFORINPUT
READYFORPICKUP
PICKEDUP
CANCELED
SCHEDULED

OrderStateChangedDate date when state of the order changes (for Scheduled state, null is provided, as is not relevant at the moment)
ExtraData: Currently the ExtraData field is reserved for future use (you may get a null or an empty string) and it is safe to ignore it.

Whenever OrderStateChange is triggered, the third party application can use the Pickup Cloud API to query for more details about the order, if they are needed.

The OrderArticleStateChanged is a notification callback method; if something with an article of an order triggered by the Pickup Cloud API, the Pickup Cloud UI or physically happens, this hub method is called. It has the following parameters:

OrderNumber: the order number (in the third party application) of the order which changed state. It is the same order number that you must provide when you create a new pickup order via Pickup Cloud API.
PickupCode: the pickup code you received when you created a new pickup order via Pickup Cloud API.
ArticleStatusChangedDto: is an object that contains specific information about each article of an order:
- ArticleId article id which is encoded in the code of the package
- RequiredQuantity required quantity requested
- OrderArticleStateChangedDate date when state of the article changes (for Scheduled state, null is provided, as is not relevant at the moment)
- DueDate date when a customer can pickup the article (this due date minus a Pickup Cloud configured preparation time in days until the order is canceled the customer can pickup the article; e.g. Due date is the date when the customer should pickup the medication, in fact the customer can pick it up from a few days before (configured in the Pickup Cloud UI settings) until the order is cancelled)
- OrderArticleState the new state of the article, it is one of the values you also get via the Pickup Cloud API endpoint, meaning one of the following values:

READYFORINPUT
READYFORPICKUP
PICKEDUP
CANCELED
SCHEDULED

ExtraData: Currently the ExtraData field is reserved for future use (you may get a null or an empty string) and it is safe to ignore it.

Whenever OrderArticleStateChange is triggered, the third party application can use the Pickup Cloud API to query for more details about the order, if they are needed.

The OrderArticleWithPackStateChanged is a notification callback method just like OrderArticleStateChanged but with additional pack info; if something with an article of an order triggered by the Pickup Cloud API, the Pickup Cloud UI or physically happens, this hub method is called. It has the following parameters:

OrderNumber: the order number (in the third party application) of the order which changed state. It is the same order number that you must provide when you create a new pickup order via Pickup Cloud API.
PickupCode: the pickup code you received when you created a new pickup order via Pickup Cloud API.
ArticleWithPackStatusChangedDto: is an object that contains specific information about each article of an order:
- ArticleId article id which is encoded in the code of the package
- RequiredQuantity required quantity requested
- OrderArticleStateChangedDate date when state of the article changes (for Scheduled state, null is provided, as is not relevant at the moment)
- DueDate date when a customer can pickup the article (this due date minus a Pickup Cloud configured preparation time in days until the order is canceled the customer can pickup the article; e.g. Due date is the date when the customer should pickup the medication, in fact the customer can pick it up from a few days before (configured in the Pickup Cloud UI settings) until the order is cancelled)
- Pack the object containing the information about the pack:
  - InternalId Picking system internal ID of the outputted pack
  - DeliveryNumber Stock delivery number of the outputted pack
  - BatchNumber Batch number of the outputted pack
  - ExternalId External ID of the outputted pack
  - SerialNumber SerialNumber of the outputted pack
  - ExpiryDate Expiration date of the outputted pack in format YYYY-MM-DD
  - ExpiryDateSource Source of expiry date transmitted in the request
```
Unknown
AutoCalculated
ManualEntry
ITSystem
OCR
Barcode
Infeed
```
  - ScanCode Barcode of the output pack
  - SubItemQuantity Number of units (e.g. tablets or ampules) in the outputted pack. The value "0" means that the pack is full
  - Depth Depth of the pack in mm
  - Width Width of the pack in mm
  - Height Height of the pack in mm
  - Shape Form factor of the pack
```
Cuboid
Cylinder
```
  - IsInFridge Flag indicating whether the pack has been stored refrigerated
  - BoxNumber Number of the box to which the pack was outputted. The data is only required if an automatic box filler is being used.
  - OutputDestination Number of the output location to which the pack was sent. A possible error case is output to a point other than the one requested, for example because the requested output point was not operational.
  - OutputPoint Detailed information on the output location (e.g. belt number) used for pack output
  - LabelStatus Status of the labeling of the outputted pack. This is only relevant in conjunction with labeling
  - StockLocationId ID of the stock location in the automated storage and retrieval system. Is only used when an automated storage and retrieval system is divided into several virtual stock locations
  - MachineLocation Identification of the machine that was used to store packs of this article. Only relevant if the automated storage and retrieval system consists of several physical stand-alone machines
- OrderArticleState the new state of the article, it is one of the values you also get via the Pickup Cloud API endpoint, meaning one of the following values:

READYFORINPUT
READYFORPICKUP
PICKEDUP
CANCELED
SCHEDULED

ExtraData: Currently the ExtraData field is reserved for future use (you may get a null or an empty string) and it is safe to ignore it.

Whenever OrderArticleWithPackStateChange is triggered, the third party application can use the Pickup Cloud API to query for more details about the order, if they are needed.

Example of a simple create pickup order + package input flow:

Next: running the sample clients

In order to speed-up the development of third party apps, we have provided a small sample API client for the OrderStateChange notification for each of the supported technologies (for the OrderArticleStateChange the same steps as for OrderStateChange shall be done), here is how to run them.

👉 .NET Sample Client (C#)

👉 Java Sample Client

👉 JavaScript Sample Client

👉 C++ Sample Client