API docs by Redocly

Chemist4U Connect Partner API (2.2.0-Draft)

Download OpenAPI specification:

An API for Chemist4U partners to manage orders in the Connect system

Access

Access to the API is granted via an IP whitelist, and a client_id and client_secret pair. For this reason a static IP is required from the calling system. The client_id represents you as a partner and is used to restrict access to orders that you have created.

Change Log

  • 2.0.0-Draft
    • Initial draft of the second revision of the partner API
  • 2.0.1-Draft
    • Updated the required fields in Address, Customer, OrderItem, Order, Prescription, Prescriber, Surgery, OrderStatus, OrderStatusUpdate, Webhook and Webhooks
  • 2.1.0-Draft
    • Updated address schema to match Royal Mail to avoid address mismatch issues
    • Removed dte of birth as required field
    • Added shipping method
    • Added item name to order items as optional field for information only
    • Added category to webhooks to allow webhooks for product availability changes
    • Added the items endpoints for retrieving stock availability
  • 2.0.1-Draft
    • Updated the required fields in Address, Customer, OrderItem, Order, Prescription, Prescriber, Surgery, OrderStatus, OrderStatusUpdate, Webhook and Webhooks

Orders

Creates a new order

Creates a new order for Chemist4U for fulfillment. This endpoint accepts detailed information about the order, including customer details, order items, and optional prescription details.

An order may be a none-prescription order, or maybe linked to a prescription. If linked to a prescription, the prescription details should be provided in the prescription field. Depending on the type of order, and type of items within the order, then the fulfillment workflow will be different.

Notes

  • If the partnerOrderId already exists with the same data, this endpoint is idempotent and will return a 201 status with no changes.

  • Returns 409 if the partnerOrderId exists but the provided data conflicts.

Authorizations:
OAuth2
Request Body schema: application/json
required
partnerOrderId
required
string >= 5 characters
orderDateTime
required
string <date-time>
required
object (Customer)
object (Prescription)
required
Array of objects (OrderItem)
object (ShippingMethod)

The pre-arranged shipping method to use for the Order, if not supplied then shipping option used will be as per prior agreement and the contents of the order

Responses

Request samples

Content type
application/json
{
  • "partnerOrderId": "99877672211",
  • "orderDateTime": "2019-08-24T14:15:22Z",
  • "customer": {
    },
  • "prescription": {
    },
  • "orderItems": [
    ],
  • "shippingMethod": {
    }
}

Retrieve an order

Only orders created by the same partner as the partner using this operation can be retrieved.

This simply returns the main information about an order for verification purposes, if you wish to see the current status of an order then please use the /order/{partnerOrderId}/status endpoint.

Authorizations:
OAuth2
path Parameters
partnerOrderId
required
string

Responses

Response samples

Content type
application/json
{
  • "partnerOrderId": "99877672211",
  • "orderDateTime": "2019-08-24T14:15:22Z",
  • "customer": {
    },
  • "prescription": {
    },
  • "orderItems": [
    ],
  • "shippingMethod": {
    }
}

Retrieve an order's status

Only orders created by the same partner as the partner using this operation can be retrieved.

This endpoint will return the current order status in the system, and can be used to check the progress of fulfillment as well as to retrieve the shipping tracking code if dispatched.

Authorizations:
OAuth2
path Parameters
partnerOrderId
required
string

Responses

Response samples

Content type
application/json
{
  • "partnerOrderId": "998776722",
  • "lastUpdatedDateTime": "2019-08-24T14:15:22Z",
  • "currentStatus": "Dispatched",
  • "courier": "Royal Mail",
  • "trackingNumber": "OD162124181GB"
}

Update an order's status

Only orders created by the same partner as the partner using this operation can be updated.

This endpoint allows attempting the update of an orders status if possible. This is mostly used for cancelling orders that have not yet been progressed through processing and dispatch.

Authorizations:
OAuth2
path Parameters
partnerOrderId
required
string
Request Body schema: application/json
required
status
required
string
Value: "Cancelled"
orderNote
required
string

Responses

Request samples

Content type
application/json
{
  • "status": "Cancelled",
  • "orderNote": "Raised in error"
}

Upload a prescription image to an order

Only orders created by the same partner as the partner using this operation can be updated.

This endpoint allows uploading of an image of a prescription to an prescription order. This combines with the meta-data that is in the prescription order to allow it to be progressed.

The order must be a prescription order with the prescription field filled in, and this should be sent through soon after the order is created. If its sent through long after then the order may have already been processed.

Depending on the agreement with Chemist4U then this image may be able to be used to increase operation efficiency, may be used for verification purposes only, or maybe no required.

Alternatively a PDF can be uploaded as well with the /order/{partnerOrderId}/pdf endpoint.

Authorizations:
OAuth2
path Parameters
partnerOrderId
required
string
Request Body schema:
required
string <binary>

Responses

Upload a prescription PDF to an order

Only orders created by the same partner as the partner using this operation can be updated.

This endpoint allows uploading of a PDF file of a prescription to an prescription order. This combines with the meta-data that is in the prescription order to allow it to be progressed.

The order must be a prescription order with the prescription field filled in, and this should be sent through soon after the order is created. If its sent through long after then the order may have already been processed.

Depending on the agreement with Chemist4U then this PDF may be able to be used to increase operation efficiency, may be used for verification purposes only, or maybe no required.

Alternatively an image can be uploaded as well with the /order/{partnerOrderId}/image endpoint.

Authorizations:
OAuth2
path Parameters
partnerOrderId
required
string
Request Body schema: application/pdf
required
string <binary>

Responses

Webhooks

Get a list of webhooks

This endpoint returns a list of all the webhooks that are registered for the partner making the request.

This can be used to verify that the webhooks are still registered, and to see what statuses are being listened for.

A webhook is a URL that Chemist4U will send a POST request to when an order status changes or product availability changes. The format of this is a work-in-progress but will be a JSON payload with the partner order ID, order status/item code, and tracking details if they exist for the order.

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{}

Register a new webhook endpoint

This allows a partner to receive webhooks when statuses change on orders, or availability changes on a product. A webhook is a URL that Chemist4U will send a POST request to when an order status changes. The format of this is a work-in-progress but will be a JSON payload with either the partner order ID, order status, and tracking details if they exist, or the item code, item code type, and availability status.

Authorizations:
OAuth2
Request Body schema: application/json
required
endpoint
string <uri>
authentication
string
category
string
Enum: "OrderStatus" "ProductAvailability"

OrderStatus for order status changes, ProductAvailability for product availability changes (in/out of stock)

statuses
Array of strings
Items Enum: "Dispatched" "Cancelled"

Required if webhook is a OrderStatus category, these are the statuses that will trigger a webhook

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Update a webhook

Authorizations:
OAuth2
path Parameters
id
required
string
Request Body schema: application/json
required
endpoint
string <uri>
category
string
Enum: "OrderStatus" "ProductAvailability"

OrderStatus for order status changes, ProductAvailability for product availability changes (in/out of stock)

statuses
Array of strings
Items Enum: "Dispatched" "Cancelled"

Required if webhook is a OrderStatus category, these are the statuses that will trigger a webhook

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Delete a webhook

Authorizations:
OAuth2
path Parameters
id
required
string

Responses

Items

Get a list of items

This endpoint returns a list of all items available in the system for the partner making the request. These are the items that can be included in orders by the partner.

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a single item

This endpoint returns details of a single item based on the itemCode and itemCodeType. This is an item that can be included in orders by the partner.

Authorizations:
OAuth2
path Parameters
itemCodeType
required
string
Enum: "AMP" "VMP" "SKU"
itemCode
required
string

Responses

Response samples

Content type
application/json
{
  • "itemCode": "42014411000001104",
  • "itemCodeType": "VMP",
  • "itemName": "Paracetamol 500mg Tablets",
  • "available": true
}