واجهة WhizzyPro البرمجية

كل الطلبات إلى https://www.whizzypro.com/pro/api/v1 بترويسة Authorization: Bearer wzp_…، والمفتاح من صفحة «الربط البرمجي». المبالغ بأصغر وحدة للعملة: هللات أو فلوس.

تسعير شحنة

POST /pro/api/v1/quotes
{ "vehicleType": "pickup", "vehicleSize": "M",
  "pickup":  { "lat": 24.6995, "lng": 46.6853, "address": "مستودع العليا" },
  "dropoff": { "lat": 24.7745, "lng": 46.6215, "address": "عميلنا في الملقا", "floor": 2, "elevator": false },
  "helpers": 1 }

حجز شحنة

POST /pro/api/v1/shipments
{ ...نفس حقول التسعير,
  "title": "ثلاجة عرض", "reference": "ORDER-1001", "costCenter": "الرياض",
  "recipientName": "أحمد", "recipientPhone": "0551234567",
  "scheduledAt": "2026-11-05T07:00:00Z",
  "bookNow": true }
→ 201 { "id": 123, "status": "open", ... }

مكان محفوظ يُكتب باسمه بدل الإحداثيات: "pickup": { "saved": "مستودع السلي" }. وbookNow افتراضياً true في الواجهة البرمجية: أول سائق يقبل السعر الثابت يأخذ الشحنة.

حالة شحنة وقائمة الشحنات

GET /pro/api/v1/shipments/123
GET /pro/api/v1/shipments?status=delivered&reference=ORDER-1001

إلغاء

POST /pro/api/v1/shipments/123/cancel

تقييم السائق

بعد التسليم. tags اختيارية من: on_time, careful, friendly, helpful, clean.

POST /pro/api/v1/shipments/123/rate
{"stars": 5, "comment": "ممتاز", "tags": ["on_time", "careful"]}

المحادثة مع السائق

تُفتح بعد تعيين السائق وتبقى يوماً بعد التسليم. فتحها يعلّم رسائل السائق مقروءة، وchatUnread في الشحنة عدد غير المقروء.

GET  /pro/api/v1/shipments/123/messages
POST /pro/api/v1/shipments/123/messages  { "text": "البوابة الخلفية رقم 3" }

الإشعارات الآلية

عند كل تغيّر نرسل POST بجسم JSON:

{ "event": "shipment.delivered", "shipmentId": 123, "reference": "ORDER-1001",
  "status": "delivered", "at": "2026-11-05T09:12:00Z", "fare": 8500, "currency": "SAR" }

تحققوا من الترويسة x-whizzy-signature: قيمة HMAC-SHA256 للجسم بالمفتاح السري، بصيغة hex. أي رد غير 2xx يُعاد إرساله حتى 6 مرات.

الأخطاء

{ "error": { "code": "price_range", "message": "…" } }