SystemX - Customer Services Module
Designed for Customer Integration through Web API Calls
Table of contents
API Basics
In order to familiarise yourself with the API we have provided a visual interface which allows users to view documentation for, and also test, the various API methods available to them. The visual interface is available here.
If you are familiar with OAS3 (OpenAPI Specification 3.0), you may prefer to use/review the API documentation file in an application of your choice (e.g. Postman); OAS3.
Authorisation
All API methods are protected from unauthorised access by use of a 'key'; before you begin using the API you'll need your authentication key, which is normally provided via email - if you have not already received it then please ask for it now whilst you review the rest of the documentation.
The API Key will end with your 6 character account number (XXXXXXXXXXXXXXXXXXXX-XXXXXX). If you are a 'master' account (i.e. you have sub accounts under your control) you can use your key to make requests on behalf of your 'sub' accounts by changing the account number.
If you wish to use the visual interface to test/demonstrate requests then you will need to click the 'Authorize' button and input your credentials, in the pop-up window. Click 'Authorize' and 'Close' and the small padlocks on each of the API methods should change appearance (from unlocked to locked).
Basic Test
If this is your first time utilising the API we recommend you try executing the 'simple ping/pong test' method, to test the most primitive communication with the server; this basic GET request has no essential parameters and no request body.
Click on the 'GET /ping Simple ping/pong test' bar to expand the method:
Click the 'Try it out' button:
Select 'Execute' to send the request and fetch the response:
XML or JSON
All API methods support both XML or JSON data, where relevant. If you send an XML request to the server you will receive an XML reply, and vice versa. Use whichever format you prefer/is easiest for you to handle as there are no differences in functionality between the two data formats.
Note: As 'GET' methods have no request body, and therefore no 'Content-Type' header, the format of responses to these requests may be controlled using a parameter in the URL; see examples provided.
Getting Started / API Examples
Each endpoint has its own required fields and the API documentation will need to be referred. There are some examples in this documentation, but they are purely to give you a basic idea of what is expected.
API Response
Every API call will return back a consignment or multiple consignments
An ERROR will contain a list of <errors> and an OK will return back a <date> and <time>. The <date> and <time> will either hold the values of the current date and time or the timestamp submitted (i.e. scan time, pod time, etc).
A few different examples of Responses you may receive from the Depot Service API calls are shown below:
General Error Response
A general ERROR will not contain a consignment system reference (<systemref>) as it is an error with the data being submitted.
<?xml version="1.0" encoding="utf-8"?>
<statusservice>
<responses>
<response>
<valid>ERROR</valid>
<errors>
<error>No status updates found</error>
</errors>
</response>
</responses>
</statusservice>
Key Error
<?xml version="1.0" encoding="utf-8"?>
<statusservice>
<responses>
<response>
<valid>ERROR</valid>
<errors>
<error>Could not retrieve the customer account</error>
</errors>
</response>
</responses>
</statusservice>
Consignment OK Response
Customer Endpoint (/endpoint)
The Customer Endpoint current has access to two services. The Customer access key and account number are needed to make these calls.
- Consignment Status Updates
<type>statusupdates</type> - Volume/Weight Changes Report
<type>volumeweightchanges</type>
Here is a basic call
<?xml version="1.0" standalone="yes"?>
<xdpcustomerservice>
<accountnumber>9D257A</accountnumber>
<key>{APIKEY}</key>
<type>{SERVICE_REQUIRED}</type>
</xdpcustomerservice>
Each API has its own collection of attributes
Consignment Status Updates <type>statusupdates</type>
The Consignment Status Updates API will retrieve the statuses of Consignments. The account must have Status Export Enabled.
Basic Call
<?xml version="1.0" standalone="yes"?>
<xdpcustomerservice>
<accountnumber>9D257A</accountnumber>
<key>{APIKEY}</key>
<type>statusupdates</type>
</xdpcustomerservice>
The Basic Call will retrieve statuses that have been generated in the Past 2 hours and filtered by Status Types set against the Customer Account.
Additional Tags Allowed
<consignment> - Filter By Consignment Number, this will ignore Start and End Ids and return back all status updates
<statustype> - Here is a list of Status Types that could be applied
- CREATE
- The point of Creation
- PRINT
- Printing Barcode
- COLLECT
- Scanned at Collection Depot/Out for Collection Alert
- EDIT
- Generally for the Hub
- DELIVERY
- At Delivery Depot/Out for Delivery
- DELIVERED
- EXCEPTION
- Could be marked as Carded, Returned, Damaged, etc
- CALL
- Driver initialis call to consignee
- NEXT STOP
- When next stop comes up
<startid> - ID of first status
<endid> - ID of last status
<podimage> - yes/no whether to return POD image URLs
Call with Additional Tags
<?xml version="1.0" standalone="yes"?>
<xdpcustomerservice>
<accountnumber>9D257A</accountnumber>
<key>{APIKEY}</key>
<type>statusupdates</type>
<statustype>PRINT</statustype>
<statustype>EDIT</statustype>
<startid>1096313716</startid>
<endid>1096335906</endid>
<podimage>yes</podimage>
</xdpcustomerservice>
Response of Call
<?xml version="1.0" encoding="utf-8"?>
<statusservice>
<consignments>
<consignment>
<id>1096313716</id>
<consigNo>ZWAHMH003823</consigNo>
<barcode>ZWAHMH003823001,ZWAHMH003823002</barcode>
<references>FI-200603-0005</references>
<sdate>03-06-2020</sdate>
<statusTime>08:59:30</statusTime>
<location>9D257A</location>
<statusType>PRINT</statusType>
<statusData/>
<podImages>
<podImage>http://sysx.local:8888/assets/img/xsys/gdpr_removed.png</podImage>
</podImages>
</consignment>
<consignment>
<id>1096335906</id>
<consigNo>ZDBHMH003827</consigNo>
<barcode>ZDBHMH003827001</barcode>
<references>MA-801-1</references>
<sdate>03-06-2020</sdate>
<statusTime>09:11:39</statusTime>
<location>9D257A</location>
<statusType>EDIT</statusType>
<statusData/>
<podImages>
<podImage>http://sysx.local:8888/assets/img/xsys/gdpr_removed.png</podImage>
</podImages>
</consignment>
</consignments>
</statusservice>
Volume/Weight Changes Report <type>volumeweightchanges</type>
The Volume/Weight Changes API will report back all consignments where the volume or weight have been changed. If no start and end dates are specified, then the current week will be selected (from Sunday to the current day).
Basic Call
<?xml version="1.0" standalone="yes"?>
<xdpcustomerservice>
<accountnumber>XDP123</accountnumber>
<key>{APIKEY}</key>
<type>volumeweightchanges</type>
</xdpcustomerservice>
Response of Call
<?xml version="1.0" encoding="utf-8"?>
<statusservice>
<consignments>
<consignment>
<consigNo>ZDBXXX145749</consigNo>
<manifestPieces>2</manifestPieces>
<serviceLevel>O/N</serviceLevel>
<declaredWeight>20</declaredWeight>
<declaredVolumeWeight>6.75</declaredVolumeWeight>
<conPrice>8.00</conPrice>
<weightPrice>0</weightPrice>
<volPrice>10.64</volPrice>
</consignment>
</consignments>
</statusservice>
Additional Tags
<consignment> - Filter By Consignment Number, this will ignore Start and End Dates and return back all changes for the specified consignment number
<startdate> - Start Date of Volume Weight Changes (Format: YYYY-MM-DD)
<enddate> - End Date of Volume Weight Changes (Format: YYYY-MM-DD)
Calls with Additional Tags
<?xml version="1.0" standalone="yes"?>
<xdpcustomerservice>
<accountnumber>XDP123</accountnumber>
<key>{APIKEY}</key>
<type>volumeweightchanges</type>
<consignment>ZDBXXX145749</consignment>
<startdate>2021-07-11</startdate>
<enddate>2021-07-15</enddate>
</xdpcustomerservice>
Response of Call
<?xml version="1.0" encoding="utf-8"?>
<statusservice>
<consignments>
<consignment>
<consigNo>ZDBXXX145749</consigNo>
<manifestPieces>2</manifestPieces>
<serviceLevel>O/N</serviceLevel>
<declaredWeight>20</declaredWeight>
<declaredVolumeWeight>6.75</declaredVolumeWeight>
<conPrice>8.00</conPrice>
<weightPrice>0</weightPrice>
<volPrice>10.64</volPrice>
</consignment>
</consignments>
</statusservice>
Definitions
Consignment Number
A consignment number will be in the form of ZDBKYU005375; a 12 character string, generally starting with the customer account number.
Consignment Barcode Number (barcodeno)
A consignment barcode will be in the form of ZDBKYU005375001; a 15 character string starting with the consignment number and ending with a 3 digit number (unique to the individual item).
Consignment System Reference (systemref)
The consignment system reference is the unique identifier for a consignment and is in the form of 77761BE2D289.
Common Queries
My API Key suddenly stopped working
It may be that your API Key requires the account number. If this is the case, please ensure you supply the account number at the end of your Key {API-KEY}-{ACC-NUMBER}.