ربط متجرك الإلكتروني بمنصة التوصيل
تتيح لك واجهة برمجة التطبيقات (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. |
يُستخدم لربط أي متجر إلكتروني خارجي بالنظام واعتماده في قائمة "التجار" مباشرة، حيث يحصل المتجر على merchant_id وتظهر لوحة تحليلات خاصة بكافة شحناته ومبالغه المحصلة.
POST /api/v1/orders مع تمرير اسم متجرك في حقل store_name، وسيقوم النظام بتسجيل متجرك تلقائياً من أول طلب!
معاملات الطلب (Request Parameters):
| الحقل | النوع | إلزامي؟ | الوصف |
|---|---|---|---|
| name | string | مطلوب | اسم متجرك الإلكتروني (مثال: متجر الأناقة الحديثة). |
| contact_person_name | string | اختياري | اسم المدير أو المسؤول عن الشحنات في المتجر. |
| phone | string | اختياري | رقم جوال المتجر أو المستودع للتواصل. |
| string | اختياري | البريد الإلكتروني للمتجر. | |
| address | string | اختياري | عنوان المستودع أو نقطة الاستلام الرئيسية في الرياض. |
| platform | string | اختياري | نوع المنصة (مثل: shopify, woocommerce, custom_store). |
| webhook_url | string (url) | اختياري | رابط بمتجرك لاستقبال إشعارات تحديث حالة الشحنات تلقائياً. |
أمثلة برمجية لاستدعاء الربط:
curl --location 'https://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://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://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://system.rabatlogistics.com/api/v1/orders",
"webhook_configured": true,
"connected_at": "2026-11-05T12:00:00+03:00"
}
}
يُنشئ شحنة جديدة في النظام، ويقوم فورياً بتحديد الحي وإسنادها للمندوب المناسب في الرياض وتوليد كود التتبع 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 --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
}
]
}'
{
"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"
}
}
}
يمكن لمتجرك استدعاء هذه النقطة في صفحة الدفع (Checkout) لمعرفة هل الحي مشمول بالتوصيل السريع، وما هي تكلفة الشحن والوقت التقديري قبل إتمام العميل لعملية الشراء.
{
"city_name": "الرياض",
"district_name": "الياسمين",
"weight_kg": 2.5
}
{
"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": "الرياض"
}
}
}
يمكنك تمرير إما كود التتبع الصادر من نظامنا (مثل DEL-20261020-0012) أو رقم الطلب في متجرك reference_id. سيعيد الرد حالة الشحنة، بيانات المندوب، والخط الزمني الكامل (Timeline).
إلغاء أمر التوصيل في حال لم يكن قد تم تسليمه بعد، مع تسجيل سبب الإلغاء في السجل.
إذا قمت بتمرير webhook_url عند إنشاء الطلب، سيقوم نظامنا بإرسال طلب POST إلى موقعك تلقائياً كلما تغيرت حالة الشحنة، مع ترويسة أمان X-Delivery-Signature مشفرة بـ HMAC-SHA256 لمطابقتها بمفتاح الربط الخاص بك.
{
"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"
}