🚧

The Carrier Integration Service is currently under development and expected to be ready end of Q4 2024. API’s documented below are subject to change and not (all) available at the moment.

Xentral offers a limited set of carriers as Shipping Methods. To work with additional carriers we offer a set of API’s (referred to in this document as the ‘Carrier Integration Service Contract’) that help you built custom shipping methods. In this document we will go over what the Carrier Integration Service Contract looks like, and how you can built a custom Carrier Service yourself.

---

Glossary

Carrier

A party that helps you send parcels. For example DHL, UPS, or DPD.

Shipping Method

A configured carrier inside of Xentral that can be used to send parcels

Product

aka ‘Carrier Product’. A type of service a carrier can offer. For example. DHL can offer ‘Express’ or ‘Warenpost’.

Shipment

A parcel that needs to be shipped.

Shipping Label

A digital representation of a carrier shipping label that is used to track or identify a parcel.

Carrier Integration Service Contract

In short CISC. The contract an external Carrier Service needs to adhere to in order to be compatible with Xentral

Carrier Service

The service a partner implements.

Carrier Service URL

The URL at which the Carrier Integration Service Contract is implemented.

---

Information flow

There are three flows involved that MUST be implemented when adhering to the Carrier Integration Service Contract:

• Setup → The user sets up your Carrier Service as a Shipping Method in Xentral
• Health check → Xentral makes regular checks to verify that your Carrier Service is healthy
• Shipment creation → Xentral reaches out to your Carrier Service to fetch a Shipment.

There are additional flows that CAN be implemented by the Carrier Service:

• Shipment cancelling → Xentral reaches out to when a shipping label is no longer necessary.
• Get existing shipment → Xentral reaches out when it wants to have details on a previously created shipment

Let’s go over each flow in more detail

Setup

In this scenario the user is setting up a new Shipping Method inside of Xentral based on a Carrier Service. Highlighted in pink the Carrier Integration Service Contract between Xentral and the Carrier Service.

It involves the following steps:

1. The user starts setting up a new Shipping Method.
2. The user fills in the credentials for theCarrier Service.
3. Xentral makes a request a request on behalf of the user ( POST [serviceUrl]/xentral/carriers ) to the Carrier Service with credentials to fetch a list of available Carriers and their Products for that specific user.
4. The user completes the configuration of the Shipping Method based on the features available for a specific Carrier and Product.

Shipment creation

In this scenario the user requests a new label that needs to be printed. Highlighted in pink the Carrier Integration Service Contract between Xentral and the Carrier Service.

Shipment cancelling

In this scenario the user intends to cancel an already existing shipment. Highlighted in pink the Carrier Integration Service Contract between Xentral and the Carrier Service.

Get existing shipment

In this scenario Xentral refetches information for an existing shipment. This can happen in the case of data loss, or when additional data becomes available later. Highlighted in pink the Carrier Integration Service Contract between Xentral and the Carrier Service.

Health check

The Carrier Integration Service Contract

There are three endpoints that must be implemented in order to comply with the Carrier Integration Service Contract:

• GET /xentral/liveness → A required endpoint we will call every minute to make sure your service is actually alive.
• GET /xentral/carriers → A required endpoint that returns what carriers and their accompanying products are available for a customer. This endpoint is used to setup your implemented service as Shipping Method within Xentral.
• POST /xentral/shipments → A required endpoint that will be used by Xentral to get a label from your service

There are two endpoints that we highly recommend to implement:

• DELETE /xentral/shipments/{id} → An OPTIONAL endpoint that will be used to void a shipment that is no longer necessary.
• GET /xentral/shipments/{id} → An OPTIONAL endpoint that will be used by Xentral to refetch the data for a specific shipment.

The full spec is available here.