ربط الشركاء (API)

1. الفكرة باختصار

يتيح الربط لمنصّتكم إرسال طلبات التوصيل إلى ريان ديلفري آلياً من موقع التاجر إلى موقع الزبون في أي منطقة ضمن دمشق وريفها، ومعرفة الأجرة قبل تأكيد الطلب، ومتابعة حالة الطلب واسم الكابتن ورقمه حتى التسليم. يصل الطلب مباشرة إلى أقرب كابتن متاح دون أي تدخل يدوي.

2. الأساسيات

• كل الطلبات: POST https://rayandelivery.com/api/index.php
• الترويسات: Content-Type: application/json و X-Api-Key: مفتاحكم
• جسم كل طلب JSON يحتوي الحقل "action" باسم العملية.
• الرد دائماً JSON فيه "success": true أو false، ومع الخطأ "code" و "message".
• المبالغ بالليرة السورية (SYP) أرقاماً صحيحة، والأوقات بتوقيت دمشق.
• أرقام الهواتف سورية بالصيغة 09xxxxxxxx، والإحداثيات بالدرجات العشرية (lat، lng).
• المفتاح سرّي: يُستخدم من خادمكم فقط، ولا يوضع في تطبيق أو صفحة يراها الزبون. إذا انكشف نصدر لكم مفتاحاً جديداً ويتوقف القديم فوراً.

curl -X POST https://rayandelivery.com/api/index.php \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: rk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{"action":"partner_ping"}' 

3. الوضع التجريبي

إذا رغبتم بتجربة الربط أولاً، نفعّل لحسابكم الوضع التجريبي: كل العمليات تعمل بشكل طبيعي، لكن الطلبات لا تصل إلى الكباتن، ويبدأ رقمها بـ TEST-. بعد نجاح التجربة نحوّل الحساب إلى الوضع الحقيقي بالمفتاح نفسه. يظهر الوضع الحالي (test أو live) في رد partner_ping.

4. فحص المفتاح: partner_ping

{"action": "partner_ping"}

{"success": true, "partner": "اسم منصتكم", "mode": "live", "server_time": "2026-10-20T14:05:00", "currency": "SYP"}

5. احتساب الأجرة: partner_quote

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

{
  "action": "partner_quote",
  "pickup":  {"lat": 33.4680, "lng": 36.3180},
  "dropoff": {"lat": 33.4330, "lng": 36.2350},
  "vehicle_type": "motorcycle",
  "distance_km": 10.4
}

{
  "success": true, "currency": "SYP", "vehicle_type": "motorcycle",
  "fee": 36000, "distance_km": 10.4, "minutes": 21,
  "fees": {"motorcycle": 36000, "car": 54000, "taxi": 54000, "suzuki": 72000, "van": 90000}
}

distance_km اختياري (مسافة الطريق إن كانت لديكم)؛ وبدونه نحسبها نحن من الإحداثيات.

6. إنشاء طلب: partner_create_order

{
  "action": "partner_create_order",
  "external_id": "FS-1001",
  "pickup":  {"address": "ببيلا - الشارع العام - محل الأمل", "lat": 33.4680, "lng": 36.3180,
              "name": "محل الأمل", "phone": "0933111222"},
  "dropoff": {"address": "صحنايا - حي النور - بناء 4", "lat": 33.4330, "lng": 36.2350,
              "name": "رامي", "phone": "0944222333"},
  "vehicle_type": "motorcycle",
  "cod_amount": 150000,
  "fee_payer": "receiver",
  "details": "كرتونة أحذية"
}

{
  "success": true, "order_id": "R000123", "external_id": "FS-1001",
  "status": "pending", "status_label": "بانتظار كابتن",
  "fee": 36000, "price_pending": false, "distance_km": 10.4, "minutes": 21,
  "vehicle_type": "motorcycle", "test": false
}

الأجرة النهائية: الأجرة في رد الإنشاء تقديرية. عند التسليم تُحسب النهائية: التقديرية، ويُضاف إليها انتظار الكابتن عند نقطة الاستلام بعد أول 5 دقائق مجانية، وأي وقت أو مسافة إضافية عن التقدير. تصلكم القيمة النهائية في fee بحالة الطلب وبإشعار التسليم.

7. حالة الطلب: partner_order_status

بـ order_id (رقمنا) أو external_id (رقمكم).

{"action": "partner_order_status", "external_id": "FS-1001"}

{
  "success": true, "order_id": "R000123", "external_id": "FS-1001",
  "status": "on_the_way", "status_label": "الطلب بالطريق للمستلم",
  "fee": 36000, "cod_amount": 150000, "fee_payer": "receiver",
  "captain": {"name": "أحمد", "phone": "0988000111",
              "location": {"lat": 33.4512, "lng": 36.2790, "age_sec": 12}},
  "created_at": "2026-10-20T14:05:10"
}

يظهر captain بعد أن يستلم كابتن الطلب، وموقعه المباشر أثناء التوصيل. وعند التسليم يظهر delivered_at.

8. إلغاء طلب: partner_cancel_order

ممكن قبل أن يستلم كابتن الطلب فقط. بعدها يعيد الرد cannot_cancel ويرجى التواصل معنا.

{"action": "partner_cancel_order", "external_id": "FS-1001", "reason": "ألغى الزبون الطلب"}

9. قائمة طلباتكم: partner_orders

{"action": "partner_orders", "from": "2026-10-01", "to": "2026-10-31", "limit": 100}

يعيد orders: قائمة بطلباتكم (الأحدث أولاً) بنفس شكل رد حالة الطلب. الحد الأقصى 200.

10. حالات الطلب

11. الإشعارات التلقائية (Webhook)

إذا زوّدتمونا برابط على خادمكم (https://)، نرسل إليه POST عند كل تغيير في حالة أي طلب، خلال دقيقة تقريباً. يجب أن يرد خادمكم بـ 200؛ وعند الفشل نعيد المحاولة كل دقيقتين تقريباً لمدة أقصاها 3 أيام.

• X-Rayan-Event: order.status
• X-Rayan-Signature: sha256=... = HMAC-SHA256 لجسم الطلب كما هو، بسرّ الإشعارات الخاص بكم (whs_...).

{
  "event": "order.status", "at": "2026-10-20T14:20:41",
  "order_id": "R000123", "external_id": "FS-1001",
  "status": "delivered", "status_label": "تم التسليم",
  "fee": 36000, "cod_amount": 150000, "fee_payer": "receiver",
  "captain": {"name": "أحمد", "phone": "0988000111"},
  "delivered_at": "2026-10-20T14:20:30", "test": false
}

التحقق من التوقيع (PHP):

$body = file_get_contents('php://input');
$sig  = 'sha256=' . hash_hmac('sha256', $body, 'whs_your_secret');
if (!hash_equals($sig, $_SERVER['HTTP_X_RAYAN_SIGNATURE'] ?? '')) { http_response_code(401); exit; }
$event = json_decode($body, true);
http_response_code(200);

التحقق من التوقيع (Node.js):

const crypto = require('crypto');
const sig = 'sha256=' + crypto.createHmac('sha256', 'whs_your_secret').update(rawBody).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(req.headers['x-rayan-signature'] || ''));

إذا لم يكن لديكم رابط، يمكنكم الاستعلام عن الحالة بـ partner_order_status بين الحين والآخر.

12. رموز الأخطاء والحدود

13. التواصل

للدعم الفني أو تفعيل الوضع الحقيقي: 0988530168 — 0951550898 — rayandelivery0@gmail.com