DevLivery API Postman
RESTful API التوصيل الفوري والميل الأخير

ربط متجرك الإلكتروني بمنصة التوصيل

تتيح لك واجهة برمجة التطبيقات (API) إرسال طلبات الشراء تلقائياً من أي متجر إلكتروني (سواء كان موقعاً مخصصاً، شوبيفاي، ووكومرس، أو تطبيق جوال) ليتم توزيعها وإسنادها فوراً لأقرب مندوب توصيل داخل الرياض، مع إمكانية التتبع المباشر لحظة بلحظة واستقبال إشعارات الويب هوك عند تسليم الشحنة للعميل.

إسناد آلي ذكي

تحديد حي العميل وتكليف أقرب مندوب متاح خلال ثوانٍ.

رابط تتبع للعميل

توليد صفحة تتبع احترافية برقم الشحنة لترسلها لعميلك عبر SMS.

تحديثات الويب هوك

إرسال إشعار فوري لمتجرك لتغيير حالة الطلب إلى "تم التسليم".

المصادقة والمفاتيح (Authentication)

يتم التحقق من جميع الطلبات عبر تمرير الـ api-key في ترويسة الطلب (Header)، أو عبر Authorization: Bearer <KEY>.

Header Key Value الوصف
api-key 123456789 المفتاح السري لمتجرك (معرف في النظام بملف البيئة API_KEY).
Accept application/json يجب أن يطلب التطبيق استجابة من نوع JSON دائماً.
Content-Type application/json مطلوب في جميع طلبات الـ POST.
POST /api/v1/merchants/connect 1. ربط وتسجيل المتجر في النظام

يُستخدم لربط أي متجر إلكتروني خارجي بالنظام واعتماده في قائمة "التجار" مباشرة، حيث يحصل المتجر على merchant_id وتظهر لوحة تحليلات خاصة بكافة شحناته ومبالغه المحصلة.

ملاحظة هامة: يمكنك أيضاً تخطي هذا الطلب والبدء فوراً بإنشاء الطلبات عبر POST /api/v1/orders مع تمرير اسم متجرك في حقل store_name، وسيقوم النظام بتسجيل متجرك تلقائياً من أول طلب!
معاملات الطلب (Request Parameters):
الحقل النوع إلزامي؟ الوصف
name string مطلوب اسم متجرك الإلكتروني (مثال: متجر الأناقة الحديثة).
contact_person_name string اختياري اسم المدير أو المسؤول عن الشحنات في المتجر.
phone string اختياري رقم جوال المتجر أو المستودع للتواصل.
email string اختياري البريد الإلكتروني للمتجر.
address string اختياري عنوان المستودع أو نقطة الاستلام الرئيسية في الرياض.
platform string اختياري نوع المنصة (مثل: shopify, woocommerce, custom_store).
webhook_url string (url) اختياري رابط بمتجرك لاستقبال إشعارات تحديث حالة الشحنات تلقائياً.
أمثلة برمجية لاستدعاء الربط:
curl --location 'https://www.system.rabatlogistics.com/api/v1/merchants/connect' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: 123456789' \
--data '{
  "name": "متجر الأناقة الحديثة",
  "contact_person_name": "سعد الدوسري",
  "phone": "0501122334",
  "email": "store@modern-elegance.com",
  "address": "الرياض، حي السلي، مخرج 16",
  "platform": "custom_store",
  "webhook_url": "https://modern-elegance.com/api/delivery-webhook"
}'
const response = await fetch('https://www.system.rabatlogistics.com/api/v1/merchants/connect', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'api-key': '123456789'
  },
  body: JSON.stringify({
    name: "متجر الأناقة الحديثة",
    contact_person_name: "سعد الدوسري",
    phone: "0501122334",
    email: "store@modern-elegance.com",
    address: "الرياض، حي السلي، مخرج 16",
    platform: "custom_store"
  })
});
const data = await response.json();
console.log(data);
$client = new \GuzzleHttp\Client();
$response = $client->post('https://www.system.rabatlogistics.com/api/v1/merchants/connect', [
    'headers' => [
        'Content-Type' => 'application/json',
        'Accept'       => 'application/json',
        'api-key'      => '123456789',
    ],
    'json' => [
        'name'                => 'متجر الأناقة الحديثة',
        'contact_person_name' => 'سعد الدوسري',
        'phone'               => '0501122334',
        'email'               => 'store@modern-elegance.com',
        'address'             => 'الرياض، حي السلي، مخرج 16',
        'platform'            => 'custom_store',
    ]
]);
$body = json_decode($response->getBody(), true);
الاستجابة الناجحة (201 Created):
{
  "status": true,
  "message": "Merchant/Store connected successfully and listed in merchants directory",
  "data": {
    "merchant_id": 5,
    "store_name": "متجر الأناقة الحديثة",
    "contact_person": "سعد الدوسري",
    "phone": "0501122334",
    "email": "store@modern-elegance.com",
    "status": "active",
    "api_key": "123456789",
    "create_order_endpoint": "https://www.system.rabatlogistics.com/api/v1/orders",
    "webhook_configured": true,
    "connected_at": "2026-11-05T12:00:00+03:00"
  }
}
POST /api/v1/orders إنشاء طلب توصيل فوري

يُنشئ شحنة جديدة في النظام، ويقوم فورياً بتحديد الحي وإسنادها للمندوب المناسب في الرياض وتوليد كود التتبع tracking_code.

قواعد التوجيه والتسليم اللوجستي:
  • الطلبات داخل الرياض: يتم توجيهها وإسنادها آلياً إلى أسطول المناديب الداخلي لخدمة التوصيل السريع (خلال نفس اليوم).
  • الطلبات خارج الرياض (كافة مدن المملكة الأخرى): يتم استقبالها في النظام وتعيين حالتها إلى pending_approval لمراجعتها من قبل الإدارة والموافقة عليها قبل إسنادها لشركة RedBox، مما يمنحكم الأمان التام والتحكم الكامل في كافة الشحنات الخارجية بدون أي إرسال عشوائي.
معاملات الطلب (Request Body Parameters):
الحقل النوع إلزامي؟ الوصف
store_name string اختياري ومفضل اسم متجرك الإلكتروني (مثال: متجر الأناقة). يقوم النظام بتسجيل متجرك تلقائياً وربط كافة شحناته باسمه في قائمة التجار.
reference_id string مطلوب رقم الطلب في متجرك الإلكتروني (مثل: ORD-98214).
customer.name string مطلوب اسم العميل المستلم ثلاثي أو ثنائي.
customer.phone string مطلوب رقم جوال العميل (يدعم الصيغ: 0551234567 أو +966551234567).
customer.address string مطلوب العنوان الوطني أو الوصف النصي لموقع العميل.
customer.district_name string اختياري اسم الحي (مثال: "الملقا"، "الياسمين"، "النرجس") لمطابقة المندوب بدقة.
customer.lat / lng numeric اختياري إحداثيات خط العرض والطول لموقع العميل.
cod_amount numeric اختياري مبلغ الدفع عند الاستلام المطلوب من العميل (أو 0 إذا مدفوع مسبقاً).
webhook_url string (URL) اختياري رابط الويب هوك في متجرك لتلقي إشعارات الحالات التلقائية.
نموذج الإرسال (cURL)
curl --location 'http://localhost:8000/api/v1/orders' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: 123456789' \
--data-raw '{
  "reference_id": "ORD-2026-9812",
  "notes": "يرجى الاتصال بالعميل قبل الوصول بربع ساعة",
  "cod_amount": 150.00,
  "currency": "SAR",
  "webhook_url": "https://my-store.com/api/webhooks/delivery",
  "customer": {
    "name": "عبدالله محمد الشمري",
    "phone": "0551234567",
    "city": "الرياض",
    "district_name": "الملقا",
    "address": "طريق أنس بن مالك، عمارة 14، شقة 5",
    "lat": 24.810231,
    "lng": 46.618420
  },
  "items": [
    {
      "name": "عطر مخلط ملكي 100 مل",
      "quantity": 2,
      "unit_price": 75.00
    }
  ]
}'
الرد المتوقع (201 Created Response)
{
  "status": true,
  "message": "Delivery order created successfully",
  "data": {
    "tracking_code": "DEL-20261020-0012",
    "tracking_url": "http://localhost:8000/tracking/DEL-20261020-0012",
    "reference_id": "ORD-2026-9812",
    "status": "assigned",
    "status_label": "تم التعيين للمندوب",
    "driver": {
      "id": 4,
      "name": "أحمد السائق",
      "phone": "+966550001122"
    },
    "dropoff": {
      "name": "عبدالله محمد الشمري",
      "phone": "0551234567",
      "address": "طريق أنس بن مالك، عمارة 14، شقة 5"
    }
  }
}
POST /api/v1/shipping/calculate حاسبة تكلفة ووقت التوصيل

يمكن لمتجرك استدعاء هذه النقطة في صفحة الدفع (Checkout) لمعرفة هل الحي مشمول بالتوصيل السريع، وما هي تكلفة الشحن والوقت التقديري قبل إتمام العميل لعملية الشراء.

مثال الطلب:
{
  "city_name": "الرياض",
  "district_name": "الياسمين",
  "weight_kg": 2.5
}
مثال الرد (200 OK):
{
  "status": true,
  "message": "Shipping rate calculated successfully",
  "data": {
    "is_serviceable": true,
    "service_type": "same_day_delivery",
    "service_name": "توصيل خلال نفس اليوم (Same-Day Delivery)",
    "shipping_cost": 25.00,
    "currency": "SAR",
    "estimated_delivery_time": "خلال 2 إلى 4 ساعات",
    "matched_district": {
      "id": 14,
      "name_ar": "الياسمين",
      "city": "الرياض"
    }
  }
}
GET /api/v1/orders/{tracking_code} تتبع حالة الطلب والتفاصيل

يمكنك تمرير إما كود التتبع الصادر من نظامنا (مثل DEL-20261020-0012) أو رقم الطلب في متجرك reference_id. سيعيد الرد حالة الشحنة، بيانات المندوب، والخط الزمني الكامل (Timeline).

POST /api/v1/orders/{tracking_code}/cancel إلغاء الشحنة

إلغاء أمر التوصيل في حال لم يكن قد تم تسليمه بعد، مع تسجيل سبب الإلغاء في السجل.

Outbound Webhooks (إشعارات الويب هوك المرتدة)

إذا قمت بتمرير webhook_url عند إنشاء الطلب، سيقوم نظامنا بإرسال طلب POST إلى موقعك تلقائياً كلما تغيرت حالة الشحنة، مع ترويسة أمان X-Delivery-Signature مشفرة بـ HMAC-SHA256 لمطابقتها بمفتاح الربط الخاص بك.

مثال Payload الإشعار المُرسل لمتجرك:
{
  "event": "order.status_updated",
  "tracking_code": "DEL-20261020-0012",
  "reference_id": "ORD-2026-9812",
  "status": "delivered",
  "status_label": "تم التسليم بنجاح",
  "driver": {
    "name": "أحمد السائق",
    "phone": "+966550001122"
  },
  "timestamp": "2026-10-20T17:15:00+03:00"
}