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 are:

create a hub connection to our public endpoint
subscribe to the OrderStateChanged notification and/or to the OrderArticleStateChanged 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.

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