واجهة برمجة وصّلني

(test mode فقط) ينقل الطلب للحالة التالية: accepted → picked_up → in_transit → delivered. كل خطوة بتطلق الـ webhook المناسب.

نسخcurl -X POST https://wasally.budoorzahera.cloud/api/v1/orders/123/test/advance \
  -H "Authorization: Bearer $WASSALNI_API_KEY"

الردود:

• 200: الطلب الجديد مع status المحدث
• 409 terminal_status: الطلب وصل delivered ومش هينقل تاني
• 409 not_a_test_order: مش طلب test

إنشاء طلب توصيل جديد. يدعم نقاط مصدر متعددة، وجهات متعددة، وفاتورة منتجات (line items) مع طريقة دفع.

Request body

نسخ{
  "description": "طلب من المتجر",
  "payment_mode": "cod",          // cod | prepaid | none
  "notes": "ملاحظات اختيارية",
  "dropoff_instructions": "اتصل عند الوصول",
  "items": [                       // line items للفاتورة (product_value يُحسب تلقائياً)
    {"name": "Phone case", "qty": 2, "unit_price": 50},
    {"name": "Charger",    "qty": 1, "unit_price": 80}
  ],
  "locations": [
    {"type": "source",      "lat": 30.0444, "lng": 31.2357, "address": "وسط القاهرة", "sequence": 0},
    {"type": "destination", "lat": 30.0626, "lng": 31.2497, "address": "الزمالك",     "sequence": 1}
  ],
  "contacts": [
    {"type": "destination", "name": "محمد", "phone": "01111111111", "sequence": 1}
  ]
}

Response (canonical breakdown)

نسخ{
  "id": 123,
  "shipping_fee": 35,              // محسوب من النظام (source of truth)
  "product_value": 180,            // مجموع items
  "commission_amount": 5.25,       // عمولة المنصة من الشحن
  "final_price": 215,              // shipping_fee + product_value
  "payment_mode": "cod",
  "settlement_mode": "B",          // كيف تتم تسوية الكاش
  "items": [...],
  "status": "pending"
}

أمثلة

نسخcurl -X POST https://wasally.budoorzahera.cloud/api/v1/orders \
  -H "Authorization: Bearer $WASSALNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "وثائق رسمية",
    "expected_price": 50,
    "locations": [
      {"type":"source","lat":30.0444,"lng":31.2357,"sequence":0},
      {"type":"destination","lat":30.0626,"lng":31.2497,"sequence":1}
    ],
    "contacts": [
      {"type":"destination","name":"محمد","phone":"01111111111","sequence":1}
    ]
  }'

نسخconst r = await fetch("https://wasally.budoorzahera.cloud/api/v1/orders", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.WASSALNI_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    description: "وثائق رسمية",
    expected_price: 50,
    locations: [
      {type:"source",      lat:30.0444, lng:31.2357, sequence:0},
      {type:"destination", lat:30.0626, lng:31.2497, sequence:1}
    ],
    contacts: [
      {type:"destination", name:"محمد", phone:"01111111111", sequence:1}
    ]
  })
});
const order = await r.json();
console.log("Order ID:", order.id);

نسخimport os, requests
API = "https://wasally.budoorzahera.cloud/api/v1"
HEAD = {"Authorization": f"Bearer {os.environ['WASSALNI_API_KEY']}",
        "Content-Type": "application/json"}

r = requests.post(f"{API}/orders", headers=HEAD, json={
  "description": "وثائق رسمية",
  "expected_price": 50,
  "locations": [
    {"type":"source",      "lat":30.0444, "lng":31.2357, "sequence":0},
    {"type":"destination", "lat":30.0626, "lng":31.2497, "sequence":1}
  ],
  "contacts": [
    {"type":"destination", "name":"محمد", "phone":"01111111111", "sequence":1}
  ]
})
print("Order ID:", r.json()["id"])

Response (201)

نسخ{
  "id": 1234,
  "client_id": 42,
  "status": "pending",
  "description": "وثائق رسمية",
  "expected_price": 50.0,
  "final_price": null,
  "created_at": "2026-05-27T12:00:00",
  "locations": [...],
  "contacts": [...]
}

قائمة الطلبات التي أنشأها هذا المفتاح. يدعم الفلترة بـ status (pending, accepted, in_transit, delivered, cancelled).

نسخcurl "https://wasally.budoorzahera.cloud/api/v1/orders?status=delivered" \
  -H "Authorization: Bearer $WASSALNI_API_KEY"

تفاصيل طلب واحد بكامل البيانات (locations، contacts، delivery_man عند التعيين).

الحالة الحالية + موقع المندوب live على الخريطة.

نسخ{
  "order_id": 1234,
  "status": "in_transit",
  "delivery_lat": 30.052,
  "delivery_lng": 31.241,
  "accepted_at": "2026-05-27T12:05:00",
  "picked_up_at": "2026-05-27T12:20:00",
  "delivered_at": null,
  "delivery_photo": null
}

تعديل حقول محددة فقط: notes و dropoff_instructions. لا يمكن تغيير المسار أو السعر بعد الإنشاء.

نسخcurl -X PATCH https://wasally.budoorzahera.cloud/api/v1/orders/1234 \
  -H "Authorization: Bearer $WASSALNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"notes": "تغيير: اتصل قبل الوصول"}'

إلغاء طلب (فقط إذا كان pending أو accepted). يرجع 409 لو فات الأوان.

نسخcurl -X POST https://wasally.budoorzahera.cloud/api/v1/orders/1234/cancel \
  -H "Authorization: Bearer $WASSALNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "إلغاء من العميل"}'

اعرف السعر قبل الإنشاء. النتائج مخزنة لـ 60 ثانية لنفس الإحداثيات (تجنب الإسراف).

نسخcurl -X POST https://wasally.budoorzahera.cloud/api/v1/price-estimate \
  -H "Authorization: Bearer $WASSALNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"src_lat":30.0444,"src_lng":31.2357,"dst_lat":30.0626,"dst_lng":31.2497}'

نسخ{
  "suggested_price": 45.5,
  "mode": "simple",     // or "ml"
  "distance_km": 2.93
}

تسجيل دخول أو إنشاء حساب عبر Google Identity Services. يعيد توكن JWT جاهزاً للاستخدام.

needs_phone: true يعني الحساب جديد ويحتاج رقم هاتف — اتّبع بـ POST /me/complete-phone.

نسخ// credential = الـ id_token من google.accounts.id.initialize callback
POST /auth/google
{ "credential": "<google_id_token>" }

→ { "access_token": "...", "role": "client", "needs_phone": false, ... }

يحفظ ويستعيد مسوّدة طلب واحدة لكل مستخدم (autosave). مفيد لاستعادة البيانات لو أغلق المستخدم التطبيق في المنتصف.

نسخ// حفظ
PUT /me/order-draft
Authorization: Bearer <token>
{ "payload": { "locations": [...], "desc": "شحنة", "step": 1 } }

// استعادة
GET /me/order-draft
→ { "payload": { ... }, "updated_at": "2026-05-30T..." }

// حذف بعد الإرسال
DELETE /me/order-draft

عناوين محفوظة لكل مستخدم لإعادة الاستخدام السريع في نموذج الطلب.

نسخ// إضافة عنوان (label اختياري — يُسمَّى تلقائياً من الإحداثيات)
POST /me/addresses
{ "lat": 30.0444, "lng": 31.2357, "label": "البيت", "address": "شارع التحرير" }

// قائمة
GET /me/addresses
→ [{ "id": 1, "label": "البيت", "lat": 30.0444, "lng": 31.2357, "address": "..." }]

// حذف
DELETE /me/addresses/{id}