Mobile Workforce

Driver API Reference

Endpoints consumed by the Routerizon driver mobile app — login, today's route, live GPS tracking, delivery status updates, proof of delivery, and cash-on-delivery collection with offline sync.

Open Interactive Explorer

Getting Started

Authentication

Every request (except login) requires a Sanctum bearer token, obtained once via POST /api/driver/login and sent on every subsequent call:

Authorization: Bearer <token>

Base URL: https://your-domain.com/api

POST /api/driver/login

curl -X POST https://your-domain.com/api/driver/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "driver@example.com",
    "password": "secret123"
  }'

200 OK
{
  "code": 200,
  "message": "Success",
  "data": {
    "token": "1|abcXYZ...",
    "driver_info": { "id": 52, "code": "D52" }
  }
}

Endpoints

Route

Sample Response 200 OK

{
  "code": 200,
  "message": "Success",
  "data": [
    {
      "order_id": 8842,
      "tracking_number": "RZ-994208-SA",
      "sequence_no": 3,
      "ship_to_name": "Ahmed Al-Harbi",
      "ship_to_city": "Riyadh",
      "cod_amount": "285.00",
      "cod_status": "pending",
      "status": "Out for Delivery"
    }
  ]
}

Sample Request

{
  "route_id": 4821
}

Sample Response 200 OK

{
  "code": 200,
  "message": "Route started",
  "data": { "route_id": 4821, "started_at": "2026-09-28T08:02:11Z" }
}

Sample Request

{
  "route_id": 4821,
  "action": "vehicle-parked",
  "geocode": "24.7136,46.6753",
  "sequence_no": 3
}

Sample Response 200 OK

{
  "code": 200,
  "message": "Logged",
  "data": { "id": 91234 }
}

Sample Request

{
  "route_id": 4821,
  "status_id": 12,
  "successful_tracking_number": ["RZ-994208-SA"],
  "unsuccessful_tracking_number": []
}

Sample Response 200 OK

{
  "code": 200,
  "message": "Updated",
  "data": {
    "updated": ["RZ-994208-SA"],
    "cod_required": []
  }
}

Sample Request

{
  "tracking_number": ["RZ-994208-SA"],
  "route_id": 4821,
  "stop_image": "https://cdn.example.com/pod/rz-994208.jpg",
  "signature_image": "data:image/png;base64,iVBORw0KGgo...",
  "geocode": "24.7136,46.6753"
}

Sample Response 200 OK

{
  "code": 200,
  "message": "Saved",
  "data": { "tracking_number": ["RZ-994208-SA"] }
}

Sample Request

{
  "date": "2026-09-28"
}

Sample Response 200 OK

{
  "code": 200,
  "message": "Success",
  "data": {
    "total": 24,
    "delivered": 21,
    "failed": 2,
    "remaining": 1
  }
}

Tracking

Sample Request

{
  "route_info_id": 4821,
  "mode": "drive",
  "device_uuid": "8f1c2e9a-driver-tab-01",
  "geocode": "24.7136,46.6753",
  "speed": 42.5
}

Sample Response 200 OK

{
  "code": 200,
  "message": "Tracking log created successfully",
  "data": { "id": 550123 }
}

Statuses & Reasons

Sample Response 200 OK

{
  "code": 200,
  "message": "Statuses retrieved successfully",
  "data": [
    { "id": 12, "name": "Delivered", "is_delivery_status": 1 },
    { "id": 13, "name": "Failed Attempt", "is_delivery_status": 2 }
  ]
}

Sample Response 200 OK

{
  "code": 200,
  "message": "Reasons retrieved successfully",
  "data": [
    { "id": 4, "status_id": 13, "name": "Customer not available" },
    { "id": 5, "status_id": 13, "name": "Address not found" }
  ]
}

Cash on Delivery

Sample Response 200 OK

{
  "code": 200,
  "message": "Success",
  "data": {
    "date": "2026-09-28",
    "cash_in_hand": { "SAR": "1240.00" },
    "collected_today": { "SAR": "1875.00" },
    "pending_orders": 6
  }
}

Sample Request

{
  "idempotency_key": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "order_id": 8842,
  "amount": "285.00",
  "currency": "SAR",
  "method": "cash",
  "route_id": 4821,
  "otp_verified": true
}

Sample Response 200 OK

{
  "code": 200,
  "message": "Success",
  "data": {
    "id": 66120,
    "was_duplicate": false,
    "receipt_number": "RCPT-2026-066120"
  }
}

Sample Request

{
  "reason": "Recorded against the wrong order"
}

Sample Response 200 OK

{
  "code": 200,
  "message": "Success",
  "data": { "id": 66120, "status": "voided" }
}

Sample Response 200 OK

{
  "code": 200,
  "message": "Success",
  "data": [
    {
      "id": 66120,
      "order_id": 8842,
      "amount": "285.00",
      "currency": "SAR",
      "method": "cash",
      "collected_at": "2026-09-28T09:14:02Z"
    }
  ]
}

Sample Request

{
  "collection_ids": [66120, 66121, 66125],
  "method": "cash_handover",
  "declared_amount": "845.00"
}

Sample Response 200 OK

{
  "code": 200,
  "message": "Success",
  "data": {
    "id": 7710,
    "status": "submitted",
    "declared_amount": "845.00",
    "currency": "SAR"
  }
}

Sample Response 200 OK

{
  "code": 200,
  "message": "Success",
  "data": [
    { "id": 7710, "status": "submitted", "declared_amount": "845.00", "currency": "SAR" },
    { "id": 7698, "status": "verified", "declared_amount": "620.00", "currency": "SAR" }
  ]
}

Sample Response 200 OK

{
  "code": 200,
  "message": "Success",
  "data": {
    "id": 7710,
    "status": "submitted",
    "declared_amount": "845.00",
    "currency": "SAR",
    "collections": [66120, 66121, 66125]
  }
}

Sample Request

{
  "collections": [
    { "idempotency_key": "d290f1ee-...", "order_id": 8842, "amount": "285.00", "currency": "SAR" },
    { "idempotency_key": "b3c1a9f0-...", "order_id": 8851, "amount": "120.00", "currency": "SAR" }
  ]
}

Sample Response 200 OK

{
  "code": 200,
  "message": "Success",
  "data": {
    "results": [
      { "key": "d290f1ee-...", "status": "accepted" },
      { "key": "b3c1a9f0-...", "status": "duplicate" }
    ]
  }
}

Ready to try it live?

Open the interactive Swagger explorer to authenticate and call every endpoint directly from your browser.

Open Interactive Explorer