Al-Shrouq Express
ALSHROUQ EXPRESS API v1.0
بوابة المطورين وتوثيق الربط البرمجي | الشروق إكسبريس
🇺🇸
البداية السريعة

نظرة عامة وبيئات التشغيل

مرحباً بك في التوثيق الرسمي لربط خدمات الشروق إكسبريس (Alshrouq Express API Documentation). ستجد هنا كافة الروابط الرسمية والمعاملات المطلوبة لإتمام التكامل مع خدمات التوصيل واللوجستيات في المملكة العربية السعودية.

REST JSON APIs
< 150ms Latency
URL Token Auth
1 تعيين مفتاح الربط

أدخل مفتاح التوكن الخاص بحسابك ليتم تضمينه تلقائياً في الأكواد والتجارب الحية.

2 اختيار بيئة التشغيل

قم بالاختبار الآمن على بيئة التجارب (Staging) أو إرسال الطلبات الحية لسائقي الشروق.

3 إرسال ومتابعة الطلبات

إنشاء طلبات التوصيل بإحداثيات الفرع والعميل وتفاصيل التحصيل المالي والدفع.

عناوين الخوادم وبيئات التشغيل الرسمية

يجب توجيه جميع استدعاءات الـ API عبر بروتوكول HTTPS الآمن إلى العناوين التالية:

تحميل مجموعة Postman
البيئة الإنتاجية الحية (Production) Live Drivers
https://alshrouqdelivery.com

السيرفر الفعلي المباشر لتنفيذ طلبات التوصيل وإسنادها لأسطول سيارات ودبابات الشروق.

بيئة التجارب والاختبار (Staging) Zero Billing
https://staging.alshrouqsse.org/

بيئة الاختبار المعتمدة لفحص الربط البرمجي واختبار الاستجابات بدون أي فواتير أو رسوم.

أمان وتشفير

المصادقة والتفويض

تتم المصادقة عبر وضع رمز التوكن المخصص لحسابك (API_TOKEN) مباشرة داخل مسار الرابط (Token in URL Path). لا يمكن إتمام أي طلب بدون توكن معتمد ونشط.

نمط تمرير التوكن داخل مسار الرابط

استبدل {API_TOKEN} برمز التوكن السري الخاص بمتجرك أو نظامك.

# المسار العام المعتمد:
POST https://alshrouqdelivery.com/api/integration/{API_TOKEN}/orders/create
# الرابط الفعلي المطبق حالياً مع التوكن النشط:
POST https://alshrouqdelivery.com/api/integration/YOUR_API_TOKEN/orders/create
إرشادات الأمان والحفاظ على سرية المفاتيح
  • لا تقم مطلقاً بتضمين مفتاح الـ API_TOKEN في كود المتصفح أو تطبيقات الهاتف الأمامية أو مستودعات Git العامة.
  • قم دائماً بتنفيذ استدعاءات الربط من الخوادم الخلفية الآمنة لمتجرك (Backend).
  • في حال الشك بتسرب المفتاح، تواصل فوراً مع الدعم الفني للشروق إكسبريس لإلغائه وتوليد مفتاح جديد.
الواجهات الأساسية

إدارة الطلبات المباشرة

الواجهات الرسمية الأساسية لإنشاء ومتابعة وتحديث وإلغاء طلبات التوصيل المباشرة من المتاجر ونقاط البيع وإسنادها لأسطول الشروق إكسبريس.

إنشاء طلب جديد

Production
POST
/api/integration/{token}/orders/create
الصلاحية المطلوبة (Scope): orders.create
نوع المصادقة: URL Token

ترويسات الطلب (Headers)

Accept: application/json
Content-Type: application/json

معاملات وبيانات الطلب (Body Parameters)

25 حقول
branch_lat integer body
إلزامي
مطلوب في حالة عدم وجود رقم للفرع
Example: 24.7136
branch_lng integer body
إلزامي
مطلوب في حالة عدم وجود رقم للفرع
Example: 46.6753
branch_id integer body
إلزامي
مطلوب في حالة عدم وجود احداثيات الفرع
Example: 9999927651182
client_order_id string body
اختياري
Example: "Test--0007"
value float body
اختياري
قيمة الطلب
Example: 100.5
payment_type enum<integer> body
إلزامي
نوع الدفع
القيم المقبولة
  • 1 الدفع عند الاستلام
  • 2 Span Machine
  • 3 مدفوع
  • 4 الشروق باي
Example: 1= COD (Cash on Delivery) , 2= SPAN Machine , 3= Paid , 4= AlshrouqPay
preparation_time integer body
اختياري
Example: 3
customer_lat float body
اختياري
Example: 24.7136
customer_lng float body
اختياري
Example: 46.6753
customer_phone string body
إلزامي
رقم هاتف العميل
Example: 501234567
customer_name string body
إلزامي
اسم العميل
Example: Ahmed
details string body
اختياري
تفاصيل الطلب
Example: Extra sauce, no onions
customer_national_address string body
اختياري
العنوان الوطني للعميل
Example: test address
building_no string body
اختياري
Example: 14
floor_no string body
اختياري
Example: 16
apartment_no string body
اختياري
Example: 3
customer_address string body
اختياري
Example: ""
deliver_at string body
اختياري
Example: "2029-05-20 14:00:00"
city integer body
اختياري
Example: 3
ingr_branch_name string body
اختياري
Example: ""
otp string body
اختياري
Example: ""
pick_up_code string body
اختياري
Example: ""
service_type integer body
اختياري
weight float body
اختياري
items_no float body
اختياري

قائمة رموز حالات الاستجابة (HTTP Status)

كود الحالة وصف الحالة
200 نجاح، تم انشاء الطلب بنجاح
نماذج الردود:
تم انشاء الطلب بنجاح 
{
  "order_id": 609077,
  "client_order_id": 12345,
  "customer_name": "Ahmed",
  "customer_phone": "501234567",
  "customer_lat": 24.7136,
  "customer_lng": 46.6753,
  "customer_address": null,
  "branch_name": "Tawera",
  "branch_id": 33,
  "fees": "0",
  "distance": "0",
  "status_id": "",
  "status_label": "Order created",
  "value": "100.5",
  "cod": "100.5",
  "payment_type_label": "Cash",
  "payment_type": 1,
  "details": "Extra sauce, no onions",
  "created_at": "2025-04-21 1:17 PM"
}

الغاء الطلب

Production
POST
/api/integration/{token}/orders/cancel
الصلاحية المطلوبة (Scope): orders.create
نوع المصادقة: URL Token

ترويسات الطلب (Headers)

Accept: application/json
Content-Type: application/json

معاملات وبيانات الطلب (Body Parameters)

2 حقول
order_id string body
إلزامي
رقم الطلب
Example: "5254700"
cancellation_reason string body
اختياري
سبب الالغاء
Example: Outside Zone

قائمة رموز حالات الاستجابة (HTTP Status)

كود الحالة وصف الحالة
200 نجاح، تم الغاء الطلب بنجاح
200 نجاح، تم انشاء طلب الغاء
422 خطأ، تم الغاء الطلب بالفعل / الطلب غير موجود
نماذج الردود:
تم الغاء الطلب بنجاح 
{
  "message": "ok , Order Cancelled"
}
تم انشاء طلب الغاء 
{
"message":"ok , Order Picked Up Cancel Request Submitted"

}
تم الغاء الطلب بالفعل / الطلب غير موجود 
{
  "error": "Order not found or has already been cancelled or cannot be cancelled."
}

استرجاع معلومات الطلب

Production
POST
/api/integration/{token}/orders/get
الصلاحية المطلوبة (Scope): orders.create
نوع المصادقة: URL Token

ترويسات الطلب (Headers)

Accept: application/json
Content-Type: application/json

معاملات وبيانات الطلب (Body Parameters)

1 حقول
order_id integer body
إلزامي
رقم الطلب مطلوب
Example: 5254808

قائمة رموز حالات الاستجابة (HTTP Status)

كود الحالة وصف الحالة
200 نجاح، HTTP 200
نماذج الردود:
HTTP 200 
{
  "data": {
    "order_id": 5254071,
    "client_order_id": "1231125",
    "customer_name": "Ahmed",
    "customer_phone": "501234567",
    "customer_lat": "24.7136",
    "customer_lng": "46.6753",
    "customer_address": "123 Main St",
    "branch_name": "Test alaraab",
    "branch_id": 9999927650791,
    "fees": "15",
    "distance": "0",
    "status_id": 22,
    "status_label": "Client Cancellation Request is being Proccessed",
    "value": "100.50",
    "tracking_url": "https://staging.alshrouqsse.org/tracking/eyJpdiI6Im1NcmxRRThzWVpWOHowWEwrQXYwQkE9PSIsInZhbHVlIjoiUzZLNVhCTUxxWERYL2w2b3UwVGtnMjF2aXlBYzdnaFU4emdXYkFQTnpXMnJsYTVYamxBWk1VSlcxREI1WVQxdiIsIm1hYyI6IjFjOWY1NmJhZjMyYmQ3NGQyY2I0OWIzMzZjODM4MmRmMGI2YmYzN2ZkNWM0MTM3MDRiNmM0YjMzMzIxOTliOGIiLCJ0YWciOiIifQ==",
    "cod": "115.5",
    "payment_type_label": "COD",
    "payment_type": 1,
    "details": "Extra sauce, no onions",
    "created_at": "2026-07-26 1:47 PM",
    "driver_accepted_time": null,
    "arrived_to_pickup_time": null,
    "picked_up_time": null,
    "arrived_to_dropoff_time": null,
    "delivered_at": null,
    "driver": null,
    "has_otp": false,
    "has_pickup_code": false,
    "pick_up_code": null,
    "otp": null,
    "invoice_url": "",
    "phone_code": null,
    "country_id": 2,
    "service_type_value": 0,
    "service_type_label": "On Demand",
    "current_status_timestamp": "2026-07-26T10:48:40.000000Z",
    "previous_status_timestamp": "2026-07-26T10:47:08.000000Z",
    "weight": "1.000",
    "eta": {
      "pickup": 0,
      "delivery": 0
    }
  }
}

متباعة الطلب

Production
POST
/api/integration/{token}/orders/track-order
الصلاحية المطلوبة (Scope): orders.create
نوع المصادقة: URL Token

ترويسات الطلب (Headers)

Accept: application/json
Content-Type: application/json

معاملات وبيانات الطلب (Body Parameters)

1 حقول
order_id integer body
إلزامي
Example: 5254808

قائمة رموز حالات الاستجابة (HTTP Status)

كود الحالة وصف الحالة
200 نجاح، HTTP 200
نماذج الردود:
HTTP 200 
{
    "data": {
        "order_id": 5254983,
        "client_order_id": "Test-create-01",
        "branch": {
            "lat": "24.7136",
            "lng": "46.6753"
        },
        "customer": {
            "lat": "24.7136",
            "lng": "46.6753"
        },
        "driver": null,
        "eta": {
            "pickup": 0,
            "delivery": 0
        }
    }
}

تحديث بيانات الطلب

Production
POST
/api/integration/{token}/orders/update
الصلاحية المطلوبة (Scope): orders.create
نوع المصادقة: URL Token

ترويسات الطلب (Headers)

Accept: application/json
Content-Type: application/json

معاملات وبيانات الطلب (Body Parameters)

9 حقول
order_id string body
إلزامي
رقم الطلب
Example: 751156
details string body
إلزامي
تفاصيل الطلب
Example: Extra sauce, no onions
value float body
إلزامي
قيمة الطلب
Example: 100.5
payment_type integer body
إلزامي
نوع الدفع
Example: 1 , 2 , 3 , 4
customer_lat float body
إلزامي
Example: 24.7136
customer_lng float body
إلزامي
Example: 46.6753
customer_address string body
إلزامي
عنوان العميل
Example: 123 Main St
customer_phone string body
إلزامي
رقم هاتف العميل
Example: 501234567
customer_name string body
إلزامي
اسم العميل
Example: Ahmed

قائمة رموز حالات الاستجابة (HTTP Status)

كود الحالة وصف الحالة
200 نجاح، تم تحديث بيانات الطلب
نماذج الردود:
تم تحديث بيانات الطلب 
{
  "order_id": 5254072,
  "client_order_id": "123115",
  "customer_name": "Ahmed",
  "customer_phone": "501234567",
  "customer_lat": 24.7136,
  "customer_lng": 46.6753,
  "customer_address": "123 Main St",
  "branch_name": "Test alaraab",
  "branch_id": 9999927650791,
  "fees": "15",
  "distance": "0",
  "status_id": 23,
  "status_label": "Order Created",
  "value": "100.5",
  "tracking_url": "https://staging.alshrouqsse.org/tracking/eyJpdiI6Ik1aY0JtakgwZnI2R3FJbG9oNnBMT0E9PSIsInZhbHVlIjoiL1VMUnBmZDBpeUZKR0R5M2dUWDFBQ0RFOENZRDlRT3c1ZWhtM2lET2JLQitkaUVhWWNwU3dETmJmYkxKQmMrVSIsIm1hYyI6IjRmNjEwNjMwNjcwZTAwYWYxNzJiZmJlODMwMzA3MTM5OTdmZmNkOWIzMDY1M2U1NTdmZjRkOTRhMTYxYzkxYmIiLCJ0YWciOiIifQ==",
  "cod": "115.5",
  "payment_type_label": "COD",
  "payment_type": 1,
  "details": "Extra sauce, no onions",
  "created_at": "2026-07-26 1:49 PM",
  "driver_accepted_time": null,
  "arrived_to_pickup_time": null,
  "picked_up_time": null,
  "arrived_to_dropoff_time": null,
  "delivered_at": null,
  "driver": null,
  "has_otp": false,
  "has_pickup_code": false,
  "pick_up_code": null,
  "otp": null,
  "invoice_url": "",
  "phone_code": null,
  "country_id": 2,
  "service_type_value": 0,
  "service_type_label": "On Demand",
  "current_status_timestamp": "2026-07-26T10:49:23.000000Z",
  "previous_status_timestamp": "2026-07-26T10:49:11.000000Z",
  "weight": "1.000",
  "eta": {
    "pickup": 0,
    "delivery": 0
  }
}

حساب مسافة وسعر الطلب

Production
POST
/api/integration/{{api_token}}/orders/get-rate
الصلاحية المطلوبة (Scope): integration.create
نوع المصادقة: URL Token

ترويسات الطلب (Headers)

Accept: application/json
Content-Type: application/json

معاملات وبيانات الطلب (Body Parameters)

3 حقول
pickup_id integer body
إلزامي
رقم الفرع
Example: 9999927650903
delivery_lat float body
إلزامي
Example: 24.75
delivery_lng float body
إلزامي
Example: 46.70

قائمة رموز حالات الاستجابة (HTTP Status)

كود الحالة وصف الحالة
200 نجاح، تم استرجاع حساب المسافة وتكلفة التوصيل
نماذج الردود:
تم استرجاع حساب المسافة وتكلفة التوصيل 
{
    "status": true,
    "message": "Rate retrieved successfully",
    "data": {
        "distance": 13.11,
        "fees": 15,
        "extra_fees": 3.11,
        "total_fees": 18.11
    }
}

اسباب الغاء الطلب

Production
GET
/api/integration/{token}/orders/cancel-reasons
الصلاحية المطلوبة (Scope): orders.read
نوع المصادقة: URL Token

ترويسات الطلب (Headers)

Accept: application/json

قائمة رموز حالات الاستجابة (HTTP Status)

كود الحالة وصف الحالة
200 نجاح، HTTP 200
نماذج الردود:
HTTP 200 
{
  "status": true,
  "message": "Cancel reasons retrieved successfully",
  "data": [
    {
      "id": 4,
      "name": "Customer Not Responding"
    },
    {
      "id": 11,
      "name": "Branch cancel orders"
    },
    {
      "id": 12,
      "name": "RTO"
    }
  ]
}

إنشاء فروع

إنشاء فرع جديد

Production
POST
/api/integration/{token}/branches/create
الصلاحية المطلوبة (Scope): branches.create
نوع المصادقة: URL Token

ترويسات الطلب (Headers)

Accept: application/json
Content-Type: application/json

معاملات وبيانات الطلب (Body Parameters)

12 حقول
branch_lat float body
إلزامي
Example: 24.7136
branch_ln float body
إلزامي
Example: 46.6753
city string body
اختياري
Example: 2
ingr_branch_name string body
إلزامي
Example: test
phone_number string body
اختياري
رقم هاتف الفرع
Example: 0512345678
street string body
اختياري
اسم الشارع
Example: King Fahd Road
landmark string body
اختياري
معلم بارز
Example: Near Kingdom Tower
building string body
اختياري
المبنى
Example: 12B
floor string body
اختياري
رقم الطابق
Example: 3
apartment string body
اختياري
رقم الشقة
Example: 301
description string body
اختياري
وصف الفرع
Example: Main branch
logo_url string body
اختياري
لوجو الفرع
Example: https://www.equinetmedia.com/hubfs/How-to-find-b2b-blog-images.png

قائمة رموز حالات الاستجابة (HTTP Status)

كود الحالة وصف الحالة
200 نجاح، تم إنشاء الفرع بنجاح
نماذج الردود:
تم إنشاء الفرع بنجاح 
{
    "status": true,
    "message": "Branch created successfully",
    "data": {
        "branch": {
            "id": 9999927651212,
            "name": "test 3",
            "client_branch_name": "test",
            "displayed_name": "test",
            "logo": "https://www.equinetmedia.com/hubfs/How-to-find-b2b-blog-images.png",
            "custom_id": null,
            "phone_number": "0512345678",
            "lat": 24.7135999999999995679900166578590869903564453125,
            "lng": 46.67530000000000001136868377216160297393798828125,
            "city": "Riyadh",
            "city_id": 2,
            "country": "Saudi Arabia",
            "country_id": 2,
            "street": "King Fahd Road",
            "landmark": "Near Kingdom Tower",
            "building": "12B",
            "floor": "3",
            "apartment": "301",
            "description": "Main branch",
            "is_active": true
        }
    }
}

ارجاع جميع الفروع

Production
GET
/api/integration/{token}/branches
الصلاحية المطلوبة (Scope): branches.read
نوع المصادقة: URL Token

ترويسات الطلب (Headers)

Accept: application/json

قائمة رموز حالات الاستجابة (HTTP Status)

كود الحالة وصف الحالة
200 نجاح، تم استرجاع جميع الفروع
نماذج الردود:
تم استرجاع جميع الفروع 
{
  "status": true,
  "message": "Branches retrieved successfully",
  "data": {
    "branches": [
     {
  "id": 9999927651208,
            "name": "test 12",
            "client_branch_name": "test",
            "displayed_name": "test",
            "logo": "https://alshrouqdelivery.b-cdn.net/https://www.equinetmedia.com/hubfs/How-to-find-b2b-blog-images.png",
            "custom_id": "BR-001",
            "phone_number": "0512345678",
            "lat": 24.7135999999999995679900166578590869903564453125,
            "lng": 46.67530000000000001136868377216160297393798828125,
            "city": "Riyadh",
            "city_id": 2,
            "country": "Saudi Arabia",
            "country_id": 2,
            "street": "King Fahd Road",
            "landmark": "Near Kingdom Tower",
            "building": "12B",
            "floor": "3",
            "apartment": "301",
            "description": "Main branch",
            "is_active": true
},
 {
  "id": 9999927651209,
            "name": "test 13",
            "client_branch_name": "test",
            "displayed_name": "test",
            "logo": "https://alshrouqdelivery.b-cdn.net/https://www.equinetmedia.com/hubfs/How-to-find-b2b-blog-images.png",
            "custom_id": "BR-001",
            "phone_number": "0512345678",
            "lat": 24.7135999999999995679900166578590869903564453125,
            "lng": 46.67530000000000001136868377216160297393798828125,
            "city": "Riyadh",
            "city_id": 2,
            "country": "Saudi Arabia",
            "country_id": 2,
            "street": "King Fahd Road",
            "landmark": "Near Kingdom Tower",
            "building": "12B",
            "floor": "3",
            "apartment": "301",
            "description": "Main branch",
            "is_active": true
},
 {
  "id": 99999276512010,
            "name": "test 14",
            "client_branch_name": "test",
            "displayed_name": "test",
            "logo": "https://alshrouqdelivery.b-cdn.net/https://www.equinetmedia.com/hubfs/How-to-find-b2b-blog-images.png",
            "custom_id": "BR-001",
            "phone_number": "0512345678",
            "lat": 24.7135999999999995679900166578590869903564453125,
            "lng": 46.67530000000000001136868377216160297393798828125,
            "city": "Riyadh",
            "city_id": 2,
            "country": "Saudi Arabia",
            "country_id": 2,
            "street": "King Fahd Road",
            "landmark": "Near Kingdom Tower",
            "building": "12B",
            "floor": "3",
            "apartment": "301",
            "description": "Main branch",
            "is_active": true
},
 {
  "id": 99999276512011,
            "name": "test 15",
            "client_branch_name": "test",
            "displayed_name": "test",
            "logo": "https://alshrouqdelivery.b-cdn.net/https://www.equinetmedia.com/hubfs/How-to-find-b2b-blog-images.png",
            "custom_id": "BR-001",
            "phone_number": "0512345678",
            "lat": 24.7135999999999995679900166578590869903564453125,
            "lng": 46.67530000000000001136868377216160297393798828125,
            "city": "Riyadh",
            "city_id": 2,
            "country": "Saudi Arabia",
            "country_id": 2,
            "street": "King Fahd Road",
            "landmark": "Near Kingdom Tower",
            "building": "12B",
            "floor": "3",
            "apartment": "301",
            "description": "Main branch",
            "is_active": true
},

    ],
    "pagination": {
      "current_page": 1,
      "last_page": 3,
      "per_page": 10,
      "total": 30,
      "next_page_url": "https://staging.alshrouqsse.org/api/integration/h0v6Xb9pwZvuTQL1CY0V3dXbfygQkO06Z277ojUYpZpqKL4CXP44HIjOmpIXRdFMH5mXOVgrmv6DXNnI/branches?page=2",
      "prev_page_url": null
    }
  }
}

ارجاع جميع المدن

Production
POST
/api/integration/{token}/cities?country_id=2
الصلاحية المطلوبة (Scope): cities?country_id=2.create
نوع المصادقة: URL Token

ترويسات الطلب (Headers)

Accept: application/json
Content-Type: application/json

قائمة رموز حالات الاستجابة (HTTP Status)

كود الحالة وصف الحالة
200 نجاح، HTTP 200
نماذج الردود:
HTTP 200 
{
    "id": 2,
    "name": "Riyadh",
    "lat": "24.714061319485616",
    "lng": "46.67583405296055",
    "country": "Saudi Arabia",
    "spl_id": "3",
    "spl_name": "RIYADH",
    "spl_region_id": "1",
    "distance_km": null
  },
  {
    "id": 3,
    "name": "Jeddah",
    "lat": "21.529183147129466",
    "lng": "39.17986254008007",
    "country": "Saudi Arabia",
    "spl_id": "18",
    "spl_name": "JEDDAH",
    "spl_region_id": "2",
    "distance_km": null
  }
إشعارات لحظية

إشعارات الويب هوك (Webhooks)

ترسل الشروق إكسبريس إشعارات POST بصيغة JSON إلى رابط الـ Callback الذي تُعدّه من لوحة التحكم عند تغيّر حالة الطلب أو موقع المندوب. يجب أن يستجيب خادمك بـ HTTP 200. لا يوجد توقيع HMAC، والتوكن الاختياري يُرسل في هيدر Authorization كما حفظته.

إشعار إنشاء طلب

Outbound
رابط التاجر
POST
https://{your-domain}/api/webhooks/HandleAlShrouqWebhook

الشروق بتبعت الإشعار ده لرابطكم عند إنشاء الطلب (type: order_created). الـ Request Body أدناه هو شكل الداتا اللي بنبعتها. هيدر Authorization فيه نفس قيمة الـ token المحفوظة على إعداد الويب هوك عندكم (غالباً Bearer + التوكن). رد الخادم بتاعكم أياً كان شكله بيتسجّل عندنا فقط.

الصلاحية المطلوبة (Scope): https:.create
نوع المصادقة: URL Token

ترويسات الطلب (Headers)

Accept: application/json
Content-Type: application/json

معاملات وبيانات الطلب (Body Parameters)

17 حقول
Content-Type string header
اختياري
نوع المحتوى اللي بنبعته: application/json
Example: application/json
Authorization string header
اختياري
المفتاح اللي بنبعته في الهيدر. قيمته = حقل token المحفوظ على إعداد الويب هوك عندكم (مثال: Bearer abc123). لو مفيش token متسجل مش هيتبعت الهيدر.
Example: Bearer YOUR_WEBHOOK_TOKEN
order_id integer body
اختياري
معرّف الطلب في نظام الشروق
Example: 84997
client_order_id string body
اختياري
رقم الطلب لدى التاجر
Example: ORD-98432
status_id integer body
اختياري
رمز حالة الطلب (انظر قسم Order Statuses)
Example: 1
status_label string body
اختياري
وصف الحالة
Example: Order created
customer_name string body
اختياري
اسم العميل
Example: Ahmed
customer_phone string body
اختياري
هاتف العميل
Example: 0501234567
customer_lat string body
اختياري
خط عرض التسليم
Example: 24.7136
customer_lng string body
اختياري
خط طول التسليم
Example: 46.6753
branch_id integer body
اختياري
معرّف الفرع
Example: 12
fees string body
اختياري
رسوم التوصيل
Example: 13
value string body
اختياري
قيمة الطلب
Example: 100.00
cod string body
اختياري
المبلغ المستحق عند التسليم
Example: 115
tracking_url string body
اختياري
رابط التتبع
Example: https://alshrouqexpress.com/tracking/84997
driver object body
اختياري
بيانات المندوب (قد تكون null عند الإنشاء)
Example: null
eta object body
اختياري
الوقت المتوقع بالدقائق للاستلام والتسليم
Example: {"pickup":12,"delivery":28}

قائمة رموز حالات الاستجابة (HTTP Status)

كود الحالة وصف الحالة
200 نجاح، هذا مجرد مثال. أي Body يرجع من عندكم بيتسجّل في سجلات الويب هوك عندنا. مش بنتحقق من شكله ولا بنعتمد عليه في المعالجة.
نماذج الردود:
مثال رد من خادم التاجر هذا مجرد مثال. أي Body يرجع من عندكم بيتسجّل في سجلات الويب هوك عندنا. مش بنتحقق من شكله ولا بنعتمد عليه في المعالجة. 
{
    "ok": Success
}

حالات الطلب

قائمة حالات الطلب المتاحة

رقم الحالة وصف الحالة
1 إنشاء طلب
2 في انتظار قبول السائق الطلب
17 تم قبول الطلب
16 تم الوصول للفرع
6 تم استلام الطلب
8 وصل الي موقع العميل
9 تم توصيل الطلب
10 تم الغاء الطلب
21 تم ارسال طلب الغاء
23 انشاء الطلب
معايير الأخطاء

رموز الحالات ومعالجة الأخطاء

قائمة شاملة برموز الاستجابة القياسية ومعانيها وكيفية التعامل مع كل حالة برمجياً.

كود الحالة المعنى العام التفسير والإجراء البرمجي الموصى به
503 السيستم مغلق السيستم مغلق
422 خطأ احداثيات الفرع مطلوبة في حالة عدم وجود رقم الفرع
401 خطأ التوكن غير صحيح
401 خطأ العميل غير مفعل
422 خطأ الفرع غير موجود
422 خطأ الفرع غير مفعل
404 خطأ الطلب موجود بالفعل
201 نجاح الطلب تم انشاء الطلب بنجاح
هيكل كائن الخطأ القياسي المرجع (Standard Error Object) 422 Example 
{
  "status": false,
  "message": "Validation error in request parameters.",
  "errors": {
    "branch_id": ["The branch_id field is required when coordinates are not provided."],
    "payment_type": ["The payment_type must be either 1 (Cash) or 2 (Card Machine)."]
  }
}
توثيق الشروق إكسبريس للمطورين v1.0 • نشط ومحدث
OpenAPI Spec • Postman Collection