Balora

Balora App API

Mobile developer guide · best-scenario test flow

Phase 1 — Mobile (USER) happy path

Use this page to understand the recommended call order, request shapes, and what is live vs stubbed. Base path:

Envelope: { success, data, message? } Errors: { success:false, code, message, errors? } Auth header: Bearer <token> Locale: Accept-Language: en | ar
Dev OTP: when Otp:UseStaticCode=true (Development), verify with code 1234. Production uses real SMS — enter the code you receive.

Best scenario (recommended order)

  1. Request OTP live POST /api/app/auth/otp/request → save challengeId
  2. Verify OTP live POST /api/app/auth/otp/verify → save data.token + data.refreshToken (new phone → isFirst: true)
  3. Optional signup complete live POST /api/app/auth/signup/complete with Bearer — set fullName (skippable)
  4. Profile + address live GET /api/app/profile then POST /api/app/profile/addresses
  5. Payment method live POST /api/app/profile/payment-methods → save id for booking
  6. Rides home live GET /api/app/home → activeTrip (in-progress ride or null) + latestTrips (up to 5 recent completed/canceled)
  7. Compare ride offers live POST /api/app/rides/compare → pick an offerId before it expires
  8. Book ride live POST /api/app/rides with offerId + paymentMethodRefId
  9. Get / cancel / rate live GET /rides/{id} · cancel while Processing · rate only after Completed
  10. Public content live GET /api/app/ads?screen=Home · GET /api/app/pages · GET /api/app/pages/about-us
  11. Refresh / logout live POST /api/app/auth/refresh then POST /api/app/auth/logout (last)
Do not cancel and rate the same ride in one pass — cancel needs a cancellable status; rating needs Completed.

Live try panel

Runs against this host. Token is kept in sessionStorage only.

No session yet.
Ready.

Endpoint map (mobile)

Area Method / path Status Notes
Auth POST /api/app/auth/otp/request live { phoneCode, phone, purpose: "login" }
Auth POST /api/app/auth/otp/verify live Returns flat token (not accessToken)
Auth POST /api/app/auth/signup/complete live Bearer USER · optional
Auth POST /api/app/auth/refresh live { refreshToken } → TokenPair
Auth POST /api/app/auth/logout live Bearer · revokes refresh tokens
Profile GET/PATCH /api/app/profile live + addresses, payment-methods, devices, prefs
Rides GET /api/app/home live Bearer · activeTrip + latestTrips (see sample below)
Rides POST /api/app/rides/compare live Riyadh sample coords work well
Rides POST /api/app/rides live { offerId, paymentMethodRefId }
Rides GET /api/app/rides?status=&page=&pageSize= live Paginated ride history · optional RideStatus filter
Rides GET/cancel/rating /api/app/rides/{id} live Status rules apply
Eats discover/order GET restaurants · POST orders… stub 501 Phase 1: not implemented yet
Eats GET /api/app/eats/orders/{id} partial Works when an order exists
Promo POST /api/app/promo/validate live Try code BALORA10 / EATS15
Loyalty GET /api/app/loyalty/balance live Bearer required
Support POST /api/app/issues live Link to ride/order id
Contact POST /api/contact-us live Public · no auth
Content GET /api/app/ads · /api/app/pages live Public
Countries GET /api/app/countries live Public · phone picker (dial, length, start digit)
Geo GET /api/app/geo/autocomplete|reverse stub 501 Until Places vendor is wired
Attachments POST /api/attachments live multipart · Bearer

Sample payloads

OTP request

{
  "phoneCode": "+966",
  "phone": "500000010",
  "purpose": "login"
}

OTP verify

{
  "challengeId": "<from request>",
  "code": "1234",
  "deviceToken": "dev-device-token",
  "deviceType": "android"
}

Ride compare (Riyadh)

{
  "pickupLat": 24.7136,
  "pickupLng": 46.6753,
  "pickupText": "Riyadh - Central",
  "dropoffLat": 24.7743,
  "dropoffLng": 46.7386,
  "dropoffText": "Riyadh - West",
  "rideCategory": "standard",
  "passengerCount": 1
}

Book ride

{
  "offerId": "<from compare.offers[0].offerId>",
  "paymentMethodRefId": 1,
  "noteToDriver": "Gate A",
  "promoCode": "BALORA10"
}

Home response GET /api/app/home

{
  "success": true,
  "data": {
    "activeTrip": {
      "id": 42,
      "providerId": 1,
      "providerName": "Uber",
      "providerRideRef": "uber-ride-abc123",
      "status": "Arriving",
      "source": "Integration",
      "rideType": "UberX",
      "passengerCount": 2,
      "pickupText": "12 Nile St, Cairo",
      "dropoffText": "Cairo International Airport",
      "fareEstimate": { "amount": 185.50, "currency": "EGP" },
      "finalFare": null,
      "driver": {
        "name": "Ahmed Hassan",
        "photoUrl": "https://cdn.example.com/drivers/ahmed.jpg",
        "vehicle": "Toyota Corolla",
        "plate": "ABC 1234",
        "rating": 4.8,
        "lat": 30.0442,
        "lng": 31.2357
      },
      "promoApplied": {
        "code": "BALORA10",
        "discount": { "amount": 18.55, "currency": "EGP" }
      },
      "requestedAt": "2026-07-27T12:15:30Z"
    },
    "latestTrips": [
      {
        "id": 38,
        "providerId": 1,
        "providerName": "Uber",
        "providerRideRef": "uber-ride-xyz789",
        "status": "Completed",
        "source": "Integration",
        "rideType": "UberX",
        "passengerCount": 1,
        "pickupText": "Maadi, Cairo",
        "dropoffText": "Downtown Cairo",
        "fareEstimate": { "amount": 95.00, "currency": "EGP" },
        "finalFare": { "amount": 92.50, "currency": "EGP" },
        "driver": null,
        "promoApplied": null,
        "requestedAt": "2026-07-25T18:40:00Z"
      }
    ]
  },
  "message": null
}

When no ride is in progress, activeTrip is null. latestTrips returns up to 5 terminal rides (Completed, RiderCanceled, DriverCanceled, NoDriversAvailable).