Zajil Shipment Integration API Documentation

V 2.1

Overview
The Zajil Shipment Integration API enables developers to integrate shipping functionalities into their
applications using the Zajil shipping service. With this API, you can:

• Create new shipments

• Retrieve shipment labels in PDF format
• Track shipments based on Air Waybill (AWB) numbers

This documentation provides detailed information about each endpoint, including input parameters,
response formats, example usages, validation errors, error handling, and additional notes.

Table of Contents
• Authentication
• API Endpoints
o Get List of Cities
o Create a New Shipment
o Retrieve Shipment Label
o Track a Shipment
• Error Handling
• Examples
• Additional Notes
• Contact Information

Authentication
For API key use the Authorization header. IP whitelisting adds a security layer; requests from non-
whitelisted IPs are denied (403 Forbidden). Contact support to whitelist your IP.

Example Header:

Authorization: YOUR_API_KEY_HERE

API Endpoints Base URL

[Link]
Get List of Cities
Retrieve the list of cities supported by the Zajil shipping service.

• URL: /api/cities
• Method: GET
• Authentication: Not required

Response:

• Success (200 OK): A list of city objects.

o City Object:
▪ id (integer): Unique identifier for the city.
▪ name (string): Name of the city.

Example Request

GET /api/cities HTTP/1.1

Host: [Link]

Example Response

[
{
"id": 1,
"name": "Abha"
},
{
"id": 2,
"name": "AbuAreesh"
},
{
"id": 62,
"name": "Riyadh"
}
// ... more cities
]

Notes

• Use the city IDs from this endpoint when specifying receiverCity and senderCity in
shipment requests.
Create a New Shipment
Create a new shipment with the Zajil shipping service.

• URL: /api/shipment/create
• Method: POST
• Authentication: API key required in Authorization header.
• Headers:
o Content-Type: application/json
o Authorization: YOUR_API_KEY_HERE

Request Body Parameters

Parameter Type Required Description

Your unique reference number for the shipment. Must
referenceNo string Yes
be unique per customer.
customerId integer Yes Your customer ID in the system.
receiverPhoneNumber string Yes Phone number of the receiver.
receiverName string Yes Name of the receiver.
receiverCity integer Yes ID of the receiver's city (use IDs from /api/cities).
ReceiverAddress string Yes Address of the receiver.
shipmentDescription string Yes Description of the shipment contents.
actualWeight float Yes Actual weight of the shipment in kilograms.
Payment type ID (1 for Cash on Delivery, 2 for
paymentType integer Yes
Prepaid).
deliveryService boolean Yes Whether delivery service is required (true or false).
totalPieces integer Yes Total number of pieces in the shipment.
shipmentValue float Yes Declared value of the shipment.
Total amount to be paid upon delivery. Must be
totalAmountToPaid float Yes greater than 0 if paymentType is 1. Must be 0 if
paymentType is 2.
opsServiceType integer No Operations service type ID (1, 2, or 3).
Phone number of the sender. If not provided, the
senderPhoneNumber string No
system will use your default.
Name of the sender. If not provided, the system will
senderName string No
use your default.
senderCity integer No ID of the sender's city (use IDs from /api/cities).
nationalAddress string Yes 8 characters (4 letters + 4 digits) example
(Required after Jan 1, 2026 "RQWA3237"
Environment to use: "test" or "production". Default is
environment string No
"test".
Example Request
Example cURL Command
postman request POST '[Link] \
--header 'Content-Type: application/json' \
--header 'Authorization: OTiCARYdiolyM' \
--body '{
"referenceNo": "TEST-NA-100",
"customerId": 708,
"receiverPhoneNumber": "555046758",
"receiverName": "Ahmed Test",
"receiverCity": 62,
"ReceiverAddress": "King Fahad Road",
"shipmentDescription": "Test with National Address",
"actualWeight": 1.0,
"paymentType": 2,
"deliveryService": true,
"totalPieces": 1,
"shipmentValue": 1,
"opsServiceType": 1,
"totalAmountToPaid": 0,
"senderPhoneNumber": "505154568",
"senderName": "Administrator",
"senderCity": 62,
"sameDay": 0,
"environment": "test",
"nationalAddress": "RQWA3237"
}'

Response Success

(200 OK)

{
"jsonrpc": "2.0",
"id": null,
"result": {
"status": "SUCCESS",
"code": "Created",
"message": "Shipment created successfully",
"refNo": "53569659001",
"cusRefNo": "TEST-NA-007",
"labelUrl": "[Link]
}
}
Error

{
"status": "Failure",
"code": "ValidationError",
"message": "Missing required fields: customerId, receiverPhoneNumber"
}

Notes

• Payment Types:
o 1: Cash on Delivery
o 2: Prepaid (For your account should be always 2)
• Operations Service Type:
o 1: Full service with pickup and delivery.
o 2: Sender drops off the shipment; delivery to receiver's address. (For your account should be
always 1)
o 3: Sender drops off the shipment; receiver picks up from the nearest branch.
• City IDs: Use city IDs from the /api/cities endpoint for receiverCity and senderCity.
• Validation:
o totalAmountToPaid must be greater than 0 if paymentType is 1 (Cash on
Delivery).
o totalAmountToPaid must be 0 if paymentType is 2 (Prepaid).
o referenceNo must be unique per customer.
• Environment:
o "test": Sends the request to the test environment.
o "production": Sends the request to the production environment.

2. Retrieve Shipment Label

Retrieve the shipment label PDF for a given AWB number.

• URL: /api/shipment/label/{awb_number}
• Method: GET
• Authentication: Not required
• Path Parameters:
o awb_number (string): The AWB number of the shipment.
• Query Parameters:
o environment (string, optional): Specify 'production' or 'test'. Default is 'test'.

Response:

• Success (200 OK): PDF file of the shipment label.

o Content-Type: application/pdf
o Content-Disposition: attachment; filename="shipment_label_{awb_number}.pdf"
• Error: JSON object with error code and message.
 Example Request

GET /api/shipment/label/2678571741?environment=test HTTP/1.1

Host: [Link]

Example cURL Command

curl --location '[Link]

[Link]/api/shipment/label/2678571741?environment=test'

Notes

• The endpoint returns a PDF file as a binary stream.

• Ensure that your HTTP client handles binary content appropriately.
• If the AWB number is invalid, an error message is returned.

Error Response

{
"status": "Failure",
"code": "InvalidAWB",
"message": "AWB number is not valid"
}

Track a Shipment
Track the status of a shipment using its AWB number.

• URL: /api/track
• Method: POST
• Authentication: Not required
• Headers:
o Content-Type: application/json
• Query Parameters:
o environment (string): Specify 'production' or 'test'.

Request Body Parameters

Parameter Type Required Description

awb string Yes The AWB number of the shipment to track.

Example Request
 POST /api/track?environment=test HTTP/1.1
Host: [Link]
Content-Type: application/json

{
"awb": "2678571741"
}

Example cURL Command

curl --location '[Link] \

--header 'Content-Type: application/json' \
--data '{
"awb": "2678571741"
}'

Example Respons

Notes

• The environment parameter is required and determines which environment the tracking request
is sent to.
• The response includes the current status of the shipment.

Error Response

If the awb field is missing:

{
"status": "Failure",
"code": "ValidationError",
"message": "Missing required fields: awb"
}

Tracking a Shipment Request

curl --location '[Link] \

--header 'Content-Type: application/json' \
--data '{
"awb": "2678571741"
}'

Response

{
"status": "SUCCESS",
"statusDetail": "In Transit"
}
Get All Shipment Statuses
Retrieve a list of all possible shipment status codes and their descriptions.

• URL: /api/shipment/statuses
• Method: GET
• Authentication: Not required
• Headers: o accept: application/json o Content-Type: application/json
• Query Parameters: o environment (string, required): Specify 'production' or 'test'.

Response:

• Success (200 OK): JSON object containing list of status codes o status (string): Response status
("SUCCESS" or "Failure") o statuses (array): List of status objects containing: ▪ id (string):
Status ID ▪ name (string): Status description ▪ code (string): Status code abbreviation

Example Request

curl --location '[Link]

[Link]/api/shipment/statuses?environment=test' \
--header 'accept: application/json' \
--header 'Content-Type: application/json'

Example Response

{
"status": "SUCCESS",
"statuses": [
{
"id": "10",
"name": "Data received",
"code": "DRS"
},
{
"id": "60",
"name": "Delivered",
"code": "DLV"
},
// ... more statuses
]
}
Get Full Tracking Details
Retrieve detailed tracking history for a shipment including all status updates.

• URL: /api/track/full
• Method: POST
• Authentication: API key required in Authorization header
• Headers: o Content-Type: application/json o Authorization: zajil
• Query Parameters: o environment (string, required): Specify 'production' or 'test'.

Request Body Parameters

Parameter Type Required Description

shipment string Yes The shipment number to track

Example Request

curl --location '[Link]

[Link]/api/track/full?environment=test' \
--header 'Content-Type: application/json' \
--header 'Authorization: zajil' \
--data '{
"shipment": "3328580655"
}'

Example Response

{
"jsonrpc": "2.0", "id": null,
"result": {
"status": "SUCCESS", "updates": [
{
"status": "Data received", "code": "DRS",
"codeid": "10",
"date": "2024-11-27 [Link]"
},
{
"status": "Out For Delivery", "code": "OFD",
"codeid": "50",
"date": "2024-11-27 [Link]"
},
{"status": "Delivered", "code": "DLV",
"codeid": "60",
"date": "2024-11-27 [Link]"
}
],
"statusDetail": "Data received"
}
}
Response Format:

• status: Overall request status ("SUCCESS" or "Failure")

• updates: Array of tracking updates, each containing: o status (string): Status description o code
(string): Status code o codeid (string): Status ID o date (string): Timestamp of the status update
(YYYY-MM-DD HH:mm:ss)
• statusDetail: Current status description

Notes:

• The tracking history is ordered chronologically

• Timestamps are in the server's timezone
• Status codes correspond to those returned by the /api/shipment/statuses endpoint
• Full tracking provides more detailed history compared to the basic tracking endpoi
Error Handling
Error Response Format

In case of an error, the API returns a JSON object with the following format:

{
"status": "Failure",
"code": "ErrorCode",
"message": "Detailed error message"
}

Common Error Codes

• InvalidJSON: The JSON payload is invalid or cannot be parsed.

• ValidationError: Missing or invalid parameters.
• AuthorizationFailed: Invalid API key or customer ID.
• ContactCreationError: Failed to create or update contact information.
• CreationError: Failed to create shipment.
• InvalidAWB: Invalid Air Waybill number.
• InvalidInput: Missing required input fields.
• UnexpectedError: An unexpected error occurred.

HTTP Status Codes

• 200 OK: The request was successful.

• 400 Bad Request: The request was malformed or missing required fields.
• 401 Unauthorized: Authentication failed due to invalid API key.
• 403 Forbidden: Access denied due to IP restrictions.
• 404 Not Found: The requested resource was not found.
• 500 Internal Server Error: An unexpected error occurred on the server.
• 502 Bad Gateway: Unable to reach the upstream server.

Notes on Error Handling

• Always check the HTTP status code of the response.

• In case of Failure status in the response body, refer to the code and message fields for more
details.
• For validation errors, the message field will detail the missing or invalid parameters.
• Implement proper exception handling in your application to capture and respond to these errors
appropriately.
Examples
Creating a Shipment Request

curl --location '[Link] \

--header 'Content-Type: application/json' \
--header 'Authorization: zajil \
--data '{
"referenceNo": "REF123456",
"customerId": 485,
"receiverPhoneNumber": "500051029",
"receiverName": "John Doe",
"receiverCity": 62,
"ReceiverAddress": "Riyadh AlQudus area",
"shipmentDescription": "Electronics",
"actualWeight": 5.5,
"paymentType": 2,
"deliveryService": true,
"totalPieces": 2,
"shipmentValue": 1000.0,
"opsServiceType": 1,
"totalAmountToPaid": 0,
"senderPhoneNumber": "500051028",
"senderName": "Jane Smith",
"senderCity": 1,
"nationalAddress": "RQWA3237",
"environment": "test"
}'

Response

{
"status": "SUCCESS",
"code": "Created",
"message": "Shipment created successfully",
"refNo": "2678571741",
"cusRefNo": "REF123456",
"labelUrl": "[Link]
}

Handling Validation Errors

If the request data is invalid, you may receive a response like:

{
"status": "Failure",
"code": "ValidationError",
"message": "Missing required fields: customerId, receiverPhoneNumber"
}

Resolution:

• Review the message field to identify missing or invalid fields.

• Ensure all required fields are provided and have valid values.
• Correct the data and retry the request.

Retrieving a Shipment Label Request

curl --location '[Link]

[Link]/api/shipment/label/2678571741?environment=test'

Notes

• This will download the shipment label PDF for the specified AWB number.

Handling Errors

If the AWB number is invalid:

{
"status": "Failure",
"code": "InvalidAWB",
"message": "AWB number is not valid"
}
 Additional Notes
• IP Whitelisting:
o The API uses IP whitelisting for additional security.
o Only requests from whitelisted IP addresses are allowed.
o Attempts from non-whitelisted IPs will result in a 403 Forbidden error.
• Date and Time Formatting:
o All date and time values are in YYYY-MM-DD format unless specified
otherwise.
o Timezone is based on the server's settings.
• Data Types:
o String fields should be UTF-8 encoded.
o Numeric fields should not include thousands separators.
o Boolean fields should be true or false (case-insensitive).
• Internationalization:
o Currently, the API supports English language responses.
• Environment:
o The 'environment' parameter in requests determines whether the operation is
performed in the test or production environment.
o Always use the test environment for development and testing purposes.
• Caching:
o The API does not use caching for real-time data. Each request fetches the most up-to-
date information.
• Rate Limiting:
o There may be rate limits applied to API requests. If you exceed these limits, you may
receive a 429 Too Many Requests response.
• Webhook Support:
o The API currently does not support webhooks for real-time updates. Polling is
required for status updates.

Important Notice – Mandatory National Address

Starting January 1, 2026, all shipments must include a valid nationalAddress.

Requests without National Address will be rejected.

Example Blocking Response

"status": "Failure",

"code": "NATIONAL_ADDRESS_REQUIRED",

"message": "Your account requires National Address for all shipments. Please provide valid
nationalAddress data.",

"refNo": "",

"cusRefNo": ""

Action Required
All integrations must be updated to send nationalAddress with every shipment before this date.
Contact Information
For additional support or questions, please contact the Zajil support team:

• Email: support@[Link]
Phone: +966-500051029