Get Started

Authentication

Get Tokens

Shipments

Create Shipment

Create Shipment - Pick Up

Create Shipment - Drop Off

Shipment Tracking

Bulk Shipment Tracking

Label print

Shipment Cancelation

Webhook

New Collection 2162023

NEW API documentation - Live - EN

SPL Documentation - LIVE

Production

Sandbox

This Application Programming Interface (API) document is aimed at helping you connect your software &amp; online services to SPL’s shipping &amp; tracking platform. By using these APIs, you will be able to get the information that you need to get started with the integration. <div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div>

This Application Programming Interface (API) document is aimed at helping you connect your software & online services to SPL’s shipping & tracking platform. By using these APIs, you will be able to get the information that you need to get started with the integration. 

To ensure we maintain high standards of security and provide additional protection for users and accounts, our API services use a combination of technology and software protocols that impose API authentication. Users will require to get a bearer key token that requires frequent renewal.

To ensure we maintain high standards of security and provide additional protection for users and accounts, our API services use a combination of technology and software protocols that impose API authentication. Users will require to get a bearer key token that requires frequent renewal.

These APIs allow authorized users to: Create a shipment or multiple on SPL&apos;s platform and track shipments by AWB Number or by Reference Number.

rack shipments by AWB Number or by Reference Number.

Prerequisites: Before creating a shipment, ensure that you have an active account, a valid Customer Code, a registered Branch Code, and a registered Branch Address Code. These details are required to successfully create a shipment and can be obtained through the relevant onboarding or account setup process.Idempotency: An identical repeated request creates a duplicate shipment under a new Waybill number, idempotency is only applied on the AWB number , but not on reference numbers.

 Before creating a shipment, ensure that you have an 

. These details are required to successfully create a shipment and can be obtained through the relevant onboarding or account setup process.

 An identical repeated request creates a duplicate shipment under a new Waybill number, idempotency is only applied on the AWB number , but not on reference numbers.

Issued by SPL - Identifies your account and scopes the request.

customerCode

Issued by SPL - The registered branch the shipment is booked against. One code per location.

branchCode

Issued by SPL - The registered address under the branch used as the collection point. Required even when no pickup occurs.

branchAddressCode

Creation timestamp. A future value is accepted.

shippingDateTime

Sets the collection leg and the delivery leg. Determines whether a pickup task is created.
1. DoortoDoor
2. DoortoRetail
3. RetailtoDoor 
4. RetailtoRetail

deliveryModel

The service line. Determines which conditional field rules apply.

"DOM": Domestic
"INTIN": International into SA
"INTOUT": International out of SA
"ERTN": Returns

productType

Content class. Determines dimensional handling. Confirmed in the UAT contract.

"Parcel" or "Document":

Parcel means physical goods with dimensional handling. Document means paper documents only.

shipmentType

Contents description. Prints on the air waybill and used for customs assessment on international shipments.
Free text, Arabic and English, Number or Symbols all accepted.
English : up to 250 characters
Arabic : up to 125 characters

Examples:
English: Cotton garments, 3 items    Arabic: ملابس قطنية، 3 قطع

descriptionOfGoods

Declared value of the contents for customs. This is the field that causes the value to print on the label.

customsDeclaredValue

Currency of the declared value.
Required if customsDeclaredValue is filled.

customsDeclaredValueCurrency

Amount to collect from the consignee for this piece. State what happens when a comma is sent.

Total COD across all pieces of a multi piece shipment. State the exact technical relationship to cod.

totalCod

Currency of the COD amount. The field name is spelled codCurrnecy in the live contract. See section 12.

codCurrency

numberOfPieces

Identifies the carrier fulfilling the shipment.

supplierCode

Returns the label in the create response instead of a separate Label Print call. State encoding and format.

IncludeLabel

True only when productType is ERTN. False for DOM, INTIN and INTOUT. Confirmed in the UAT contract.

IsReturnEBU

shipper

shipmentWeight

consignee

reference

items

Mandatory if the "TimeDefnte" is entered as shipment service

ShipmentDeliveryTime

Only one of the three services "WEndDL", "SameDayDL", "TimeDefnte" can be used at the same time
 "WEndDL"، "SameDayDL"، "TimeDefnte"  يمكن استخدام أحد الخدمات الثلاث في نفس الوقت فقط











shipmentServicesCodes

Content-Type

Authorization

Prerequisites: Before creating a shipment, ensure that you have an active account, a valid Customer Code, a registered Branch Code, and a registered Branch Address Code. These details are required to successfully create a shipment and can be obtained through the relevant onboarding or account setup process.Idempotency: An identical repeated request creates a duplicate shipment under a new Waybill number, idempotency is only applied on the AWB number , but not on reference numbers.

Sets the collection leg and the delivery leg. Determines whether a pickup task is created.

1. DoortoDoor : Delivery to the customer's door

2. DoortoRetail: From the Customer to the nearest SPL Facility

Prerequisites: Before creating a shipment, ensure that you have an active account, a valid Customer Code, a registered Branch Code, and a registered Branch Address Code. These details are required to successfully create a shipment and can be obtained through the relevant onboarding or account setup process.Idempotency: An identical repeated request creates a duplicate shipment under a new Waybill number, idempotency is only applied on the AWB number , but not on reference numbers.Drop-Off (Nearest SPL Office or Parcel Location):

Drop-Off (Nearest SPL Office or Parcel Location):

Sets the collection leg and the delivery leg. Determines whether a pickup task is created.

1. RetailtoDoor: the Office or Parcel location address details should be provided in the shipper address details

2. RetailtoRetail: the Office or Parcel location address details should be provided in the shipper and consignee addresses

Only one of the three services "WEndDL", "SameDayDL", "TimeDefnte" can be used at the same time
 "WEndDL"، "SameDayDL"، "TimeDefnte" 






api_connection_error

API errors cover any other type of problem (e.g., a temporary problem with servers), and are extremely uncommon.

api_error

Failure to properly authenticate yourself in the request.

authentication_error

Card errors are the most common type of error you should expect to handle. They result when the user enters a card that can't be charged for some reason.

card_error

Idempotency errors occur when an Idempotency-Key is re-used on a request that does not match the first request's API endpoint and parameters.

idempotency_error

Invalid request errors arise when your request has invalid parameters.

invalid_request_error

Too many requests hit the API too quickly.

rate_limit_error

Errors triggered by our client-side libraries when failing to validate fields (e.g., when a card number or expiration date is invalid or incomplete).

validation_error

Status and Error Codes

The request was unacceptable, often due to missing a required parameter.

The parameters were valid but the request failed.

The API key doesnt have permissions to perform the request.

airwaybill

airwaybills

labelFormat

labelSize

Failed: "You can't perform this action! The shipment is out for delivery and/or already delivered"


Success : "The shipment Has Been Successfully Cancelled"


to setup the webhook please note the following:<ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">Authorization: The webhook events will be sent using either Basic Authorization or X-API-Key, with a set of credentials of your choosing.</div></li><li class="slate-li " ><div style="position:relative">Payload: Payload structure is listed bellow. Kindly ensure that your endpoint can accept this structure.</div></li><li class="slate-li " ><div style="position:relative">Events: A list of the most commonly sent events is listed under the “Tacking events” Tab for your reference and mapping.</div></li><li class="slate-li " ><div style="position:relative">Webhook Endpoint : You need to provide us with your Webhook Endpoint so we can configure it to your account.</div></li></ul>NOTE: The API needs to return a structured response in order for us to confirm whether the update was processed successfully. The expected response model is:public class DynamicTrackingShipmentResponse<div class="code-block-wrapper" style="width:100%;min-width:100%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden">​{​
​    public bool IsSuccess { get; set; }​
​    public string? Exception { get; set; }​
​} </textarea><code class="language-plainText keep-markup drop-tokens">​{​
​    public bool IsSuccess { get; set; }​
​    public string? Exception { get; set; }​
​}</code></pre></div>public class DynamicTrackingShipmentResponse
Without this response, our system cannot validate if the webhook call was accepted or failed. Kindly ensure the response is implemented accordingly.

————————————————-————————————————————————————————————————————————————————————————

Webhook Payload<ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">Kindly ensure that your endpoint can accept this structure.</div></li><li class="slate-li " ><div style="position:relative">Please note that our Webhook Payload is in Camel Case , and it&apos;s not Case Sensitive, kindly ensure that your Webhook is not case sensitive and can accept any format (Camel case or Pascal Case) , also keep it flexible in case any new fields were added from our side.</div></li></ul><div class="code-block-wrapper" style="width:100%;min-width:100%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden">{
 &quot;airwaybill&quot;: &quot;***************&quot;,
 &quot;eventCode&quot;: &quot;GN012&quot;,
 &quot;event&quot;: &quot;Shipment Delivered&quot;,
 &quot;eventName&quot;: &quot;Shipment Delivered&quot;,
 &quot;supplier&quot;: null,
 &quot;userName&quot;: &quot;admin&quot;,
 &quot;notes&quot;: null,
 &quot;actionDate&quot;: &quot;2024-10-29T17:30:00+00:00&quot;,
 &quot;eventCountry&quot;: &quot;AMMAN&quot;,
 &quot;eventCity&quot;: &quot;AMMAN&quot;,
 &quot;eventSubCode&quot;: null,
 &quot;eventSubName&quot;: null
 } </textarea><code class="language-plainText keep-markup drop-tokens">{
 &quot;airwaybill&quot;: &quot;***************&quot;,
 &quot;eventCode&quot;: &quot;GN012&quot;,
 &quot;event&quot;: &quot;Shipment Delivered&quot;,
 &quot;eventName&quot;: &quot;Shipment Delivered&quot;,
 &quot;supplier&quot;: null,
 &quot;userName&quot;: &quot;admin&quot;,
 &quot;notes&quot;: null,
 &quot;actionDate&quot;: &quot;2024-10-29T17:30:00+00:00&quot;,
 &quot;eventCountry&quot;: &quot;AMMAN&quot;,
 &quot;eventCity&quot;: &quot;AMMAN&quot;,
 &quot;eventSubCode&quot;: null,
 &quot;eventSubName&quot;: null
 }</code></pre></div>

to setup the webhook please note the following:

 The API needs to return a structured response in order for us to confirm whether the update was processed successfully. The expected response model is:

public class DynamicTrackingShipmentResponse

Without this response, our system cannot validate if the webhook call was accepted or failed. Kindly ensure the response is implemented accordingly.


​
————————————————-————————————————————————————————————————————————————————————————



Sections