Sabeq.ps API Documentation

Version: version 1.1

Author: Shuaib Zahda (alzahidi-tech.com)

Introduction

The API documentation below lists the capabilities of Sabeq.ps API and how they can be achieved.

The current API allows:

Creating parcels
Querying parcel’s status
Cancelling parcels
Get geographical areas.

API documentation

Note	All the requests and responses are in JSON format.

1. The Authentication and Verification Process

To implement any of the API functionalities, the system has to authenticate the user, then verify that the user is allowed to access Sabeq.ps API.

After the verification process is successful, the API returns verification token that is valid for 5 minutes. The verification token is to be used with the subsequent API funcations.

1.1. Authentication

The authentication process is the first request your client has to send in order to get the authentication token known as auth_token

The login token is for the owner of the business which is available in the My Profile page.

Request

URL: https://sabeq.ps/api/v1/auth
Method: POST

Table 1. Parameters
Name	Type	Value
login_token	String	Login token string, found in my profile page.

Response

On a successful request, auth_token will be returned. Use this token in the verification request below.

{
  "auth_token": "eyJhbGOiJIUzI1NiJ91c2VyXIjozMiwiZXhwaXJlIjoxNj..."
}

1.2. Verification

The verification step is to ensure that you are authorized to use the API, and you have a working profile on Sabeq.ps

Make sure that you got in touch with Sabeq.ps administration and got your business profile enabled to use the API.

Login to Sabeq.ps, go to the setting page of the business profile you want to use the API for, get the following information from the setting page in order to use them in this step

Profile id
API key

Request

URL: https://sabeq.ps/api/v1/verify_business
Method: POST

Table 2. Parameters
Name	Type	Value
auth_token	String	Obtained from the authentication response (see the authentication step).
profile_id	integer	Your business profile id, obtained from the setting page of your business on Sabeq.ps
api_key	string	API key found in the setting page of your business on Sabeq.ps

Response

On a successful request, verification_token will be returned. Use this token in any of the subsequent requests.

{
  "verification_token": "eyJhbGciOiJIUzIJidXNpbmVzc191c2VyX2lkIjozMiwiZX..."
}

Note	the verification_token is valid for 5 minutes only. After that you are required to repeat step 1 and 2.

2. Get Areas (cities and villages)

Since there is no predefined standards on the Internet on how Palestinian towns are named and abbreviated, Sabeq.ps uses its own method of naming and numbering the cities/villages of Palestine.

Important

You have to update your copy of Sabeq.ps on a regular basis on order to keey in sync with the cities names and villages.

To get the list of areas i.e. cities and their villages/towns use the following request

Request

URL: https://sabeq.ps/api/v1/parcels/get_areas
Method: GET

Table 3. Parameters
Name	Type	Value
verification_token	String	Obtained from the verification response (see the verification step).

Response

On a successful request, the list of cities and their villages/towns and a list of streets of each village will be returned as an array of hashes. See the example below.

[
  {
    "city_name": "الخليل",
    "areas": [
      {
          "name": "مدينة الخليل",
          "id": 1,
          "streets": [
              {
                  "name": "شارع رقم 1",
                  "id": 1
              },
              {
                  "name": "شارع رقم 2",
                  "id": 2
              },
              ....
          ]
      },
      {
          "name": "دورا",
          "id": 2,
          "streets": [
              {
                  "name": "شارع رقم 1",
                  "id": 3
              },
              {
                  "name": "شارع رقم 2",
                  "id": 4
              },
              ....
          ]
      },
      ....
    ]
  }....
]

3. Parcel information Query

It is possible to query the information of a certain parcel in order to know for example, the status of the parcel, the service cost and other information, see below.

Request

URL: https://sabeq.ps/api/v1/parcels/[track number]
Method: GET

The track number has to be replaced with the track number you want to query, the track number is obtained
from your parcels section in {sabeq}.

Table 4. Parameters
Name	Type	Value
verification_token	String	Obtained from the verification response (see the verification step).

Response

On a successful request, the following information is returned.

Note	the response below is NOT real and it is for educational purposes only.

{
  "track_number": "03201000",
  "status": "completed",
  "name": "شعيب زاهده",
  "address": "الخليل - مدينة الخليل - دوار ابن رشد"
  "phone": "0598308848",
  "payment_amount": 100,
  "service_cost": 20,
  "content": "اسم المنتج"
  "created_at": "2021-01-21T16:50:00"
}

3.1. Parcel statuses list

unknown: The unknown status means there is a problem in reporting the status.
created: The parcel is created in the system and is still with {sabeq.ps} client i.e. YOU.
warehouse: The parcel is in Sabeq.ps warehouse and is being worked on.
on_way: The parcel is on the way with the driver. It may be delivered soon.
delivered: The parcel is delivered to its destination, its value i.e. momey is with Sabeq.ps.
returned: The parcel is returned by the recipient for several reasons. Check Sabeq.ps for more details.
missing: The parcel is missing, Sabeq.ps takes care of its cost.
completed: The parcel transactions are completed. It means you received its value from Sabeq.ps.
cancelled: The parcel is cancelled by the customer.

4. Create a Parcel

The major funcationality of this API is to automatically create parcels in Sabeq.ps from your system. This funcationality is achieved through this API function.

Request

URL: https://sabeq.ps/api/v1/parcels
Method: POST

Table 5. Parameters
Name	Type	Required	Value
verification_token	String	Yes	Obtained from the verification response (see the verification step).
name	String	Yes	Recipient name, the person who will receive the parcel i.e. your product.
phone1	String	Yes	The first phone number of the person.
phone2	String	No	The second phone number of the person, if available. Leave blank in case there is no second phone number
content	String	Yes	The content of the parcel.
payment_amount	float	Yes	The money Sabeq.ps has to collect for you. Please note that this includes the delivery cost.
area_id	integer	Yes	The area id, obtained from the Get Areas function Get Areas.
street_id	integer	No	The id of the recipient’s street. Optional, leave blank.
address	String	Yes	The remaining of the address.
location_url	String	Yes	URL of the location e.g. google maps. Optional, leave balnk.
delivery_notes	String	No	Notes for Sabeq.ps to take into account for the delivery. Optional, leave balnk.
special_notes	String	No	Special Notes for your own reference. Optional, leave blank.
service_type	String	No	If left blank, it will be by default "pay_delivery". Allowed values: pay_delivery, deliver_only, fetch, exchange. Optional, leave blank.

Note	The city will be automatically selected by the system from the area id.

Note	All non required (optional) fields have to be sent blank in case there is no value for them.

Response

On a successful request, the following information is returned.

{
  track_number: "03212312"
  delivery_cost: 20
}

5. Cancel a parcel

It is possible to cancel a parcel if the parcel is in the initial statuses.

Request

URL: https://sabeq.ps/api/v1/parcels/[track number]/cancel
Method: GE

The track number has to be replaced with the track number of the parcel you want to cancel, the track number is obtained from your parcels section in {sabeq}.

Table 6. Parameters
Name	Type	Value
verification_token	String	Obtained from the verification response (see the verification step).

Response

On a successful request, the parcel’s new status ("cancelled") is returned.

{
  "status": "cancelled",
}

6. Parcel Webhook Notifications

Sabeq.ps supports webhook notifications to automatically notify your system when key parcel data changes. This allows your system to stay in sync with real-time updates from Sabeq.ps.

Note	This feature is optional and must be configured in your business profile settings.

6.1. When Webhooks Are Triggered

A webhook notification is triggered when any of the following attributes of a parcel are updated: Parcel status (e.g., from on_way to delivered) Collect money amount (payment to be collected from the recipient) Delivery cost (the service charge) The webhook will be triggered regardless of which of the above values changed.

6.2. How it works

Once configured, Sabeq.ps will automatically send an HTTP POST request to your webhook URL whenever a parcel’s status changes. The notification includes parcel details in JSON format.

6.3. Configuration

To enable webhook notifications:

Login to your business profile on Sabeq.ps.
Navigate to Settings.
Provide the following:
- Webhook URL: The endpoint on your server where notifications should be sent.
- Webhook Secret: A secret string used to verify the authenticity of incoming requests.

Note	Webhook URL must be accessible via HTTPS.

6.4. Request

Request

URL: [Your configured Webhook URL]
Method: POST

Table 7. Headers
Header Name	Value	Description
Content-Type	application/json	Payload is in JSON format.
X-Webhook-Signature	Your webhook secret (raw string)	Used for verifying the authenticity of the request.

Table 8. Payload fields
Field	Type	Description
track_number	String	The tracking number of the parcel.
status	String	The new status of the parcel.
name	String	Name of the recipient.
phone	String	Phone number of the recipient.
payment_amount	Float	The amount of money to be collected.
service_cost	Float	Delivery service cost.
content	String	Description of the parcel contents.

Response

Your server should return HTTP 200 OK to acknowledge successful receipt. If a non-200 response is returned (e.g., 400 or 500), the system will not retry. Ensure your endpoint is stable and handles incoming requests gracefully.

6.5. Security and Verification

Each webhook request includes a header X-Webhook-Signature containing your configured secret (as a raw string). To verify the authenticity of the request: Compare the received signature with your stored webhook secret.

7. Errors

Errors are returned in the format of error code and message.

Note	The errors are inspired from HTTP erros (client errors)

Table 9. Error codes table
Error Code	Error Message	Description
400	Missing parameters	Returned when any of the parameters mentioned in the API documentation is missing of in improper format.
401	Invalid Login Token	Returned when the login token is incorrect.
404	The requested resource is not found	Returned when the requested resource (profile, parcel, etc) is not found or does not belong to the current profile.
406	Not acceptable	Returned when the sent parameters are not accepted.
410	Authentication token is expired or no longer valid	Returned when the token sent is expired.
498	Invalid token	Returned when the sent token is invalid.