# Transporter API Sequence Roadmap

Last updated: 2026-04-14

This document defines the recommended API call order for frontend integration across Passenger and Driver apps, including real-time ride updates.

## 1) Authentication and Session Flow

Use this for both Passenger and Driver users.

1. `POST /api/v1/auth/send-otp`
2. `POST /api/v1/auth/verify-otp`
3. Branch after verify:
   - New/incomplete profile -> `POST /api/v1/auth/register`
   - Existing profile -> proceed to app home
4. Session maintenance:
   - `POST /api/v1/auth/refresh-token` when access token expires
5. Profile APIs:
   - `GET /api/v1/auth/me`
   - `PUT /api/v1/auth/profile` (partial update; only send changed fields)
6. Logout:
   - `POST /api/v1/auth/logout`

## 2) Passenger Booking Flow (Primary Ride Journey)

This is the expected sequence for booking and completing a ride.

1. Load categories:
   - `GET /api/v1/rides/categories`
2. Fare preview:
   - `POST /api/v1/rides/estimate`
   - Call repeatedly when user changes pickup/dropoff/vehicle/time/passengers
3. Create ride request:
   - `POST /api/v1/rides/book`
4. Check active ride:
   - `GET /api/v1/passenger/rides/active`
5. Ride details:
   - `GET /api/v1/rides/{ride_id}`
6. Bidding:
   - `GET /api/v1/rides/{ride_id}/bids`
   - `POST /api/v1/rides/{ride_id}/bids/{bid_id}/accept`
7. Ride lifecycle:
   - Track via websocket (preferred), REST fallback with `GET /api/v1/rides/{ride_id}`
8. Optional cancel:
   - `POST /api/v1/rides/{ride_id}/cancel`
9. History:
   - `GET /api/v1/passenger/rides`

## 3) Driver Operations Flow

Driver does not call `estimate` or `book` in normal flow.

1. Profile:
   - `GET /api/v1/driver/profile`
   - `PUT /api/v1/driver/profile`
2. Availability:
   - `PUT /api/v1/driver/status` (`is_online`)
3. Location heartbeat:
   - `PUT /api/v1/driver/location`
4. Ride discovery:
   - `GET /api/v1/driver/rides/nearby`
5. Bid:
   - `POST /api/v1/driver/rides/{ride_id}/bid`
6. Active ride:
   - `GET /api/v1/driver/rides/active`
7. Status progression:
   - `PUT /api/v1/rides/{ride_id}/status`
   - Typical transitions:
     - `accepted` -> `driver_arrived`
     - `driver_arrived` -> `started`
     - `started` -> `completed`
8. Earnings:
   - `GET /api/v1/driver/earnings`

## 4) Real-Time WebSocket Flow

Connect after successful login:

- `ws://<host>/api/v1/ws/rides/live?token=<access_token>`

Expected event types:

- `ride_requested`
- `bid_submitted`
- `ride_accepted`
- `ride_status_changed`
- `ride_cancelled`
- `driver_location`
- `ride_snapshot` (initial sync on connect)

Recommended client behavior:

- Keep websocket active while app is foregrounded.
- Send periodic `{"type":"ping"}`.
- On disconnect/reconnect, call `GET /api/v1/passenger/rides/active` or `GET /api/v1/driver/rides/active` to resync.

## 5) Booking Tabs to API Mapping

### Ride Tab (One Way / Round Trip)

- `ride_type`: `one_way` or `round_trip`
- Optional fields:
  - `return_location`
  - `return_scheduled_at`

### Per Hour Tab

- `ride_type`: `per_hour`
- Required:
  - `duration_minutes`
- Optional:
  - `end_scheduled_at`

### Delivery Tab

- `ride_type`: `delivery`
- Uses same estimate/book endpoints.
- Delivery-specific package fields can be added later if product requires them.

## 6) Current Contract Notes

### `POST /api/v1/rides/estimate`

Purpose:

- Calculates estimated distance, duration, and fare breakdown.
- Does not create a ride.

Important fields:

- `pickup`, `dropoff`
- `vehicle_category_id`
- `ride_type`
- `passenger_count`
- `children`
- `duration_minutes` (required for `per_hour`)
- `promo_code`

### `POST /api/v1/rides/book`

Purpose:

- Creates ride request and starts matching/bidding flow.

Important fields:

- `pickup`, `dropoff`
- `vehicle_category_id`
- `payment_method`
- `ride_type`
- `passenger_count`
- `children`
- `return_scheduled_at` (round trip if used)
- `duration_minutes` (required for `per_hour`)
- `end_scheduled_at` (optional)

### `GET /api/v1/rides/categories`

Now includes:

- `max_passengers`
- `max_luggage`
- `luggage_capacity`
- fare components (`base_fare`, `per_km_rate`, `per_minute_rate`, `minimum_fare`)

## 7) Minimal Payload Examples

### Estimate (One Way)

```json
{
  "pickup": { "address": "A", "latitude": 33.7000, "longitude": 73.0400 },
  "dropoff": { "address": "B", "latitude": 33.7200, "longitude": 73.1000 },
  "ride_type": "one_way",
  "vehicle_category_id": 1,
  "passenger_count": 1,
  "children": 0
}
```

### Estimate (Per Hour)

```json
{
  "pickup": { "address": "A", "latitude": 33.7000, "longitude": 73.0400 },
  "dropoff": { "address": "B", "latitude": 33.7200, "longitude": 73.1000 },
  "ride_type": "per_hour",
  "vehicle_category_id": 1,
  "passenger_count": 1,
  "children": 1,
  "duration_minutes": 60
}
```

### Book (One Way)

```json
{
  "pickup": { "address": "A", "latitude": 33.7000, "longitude": 73.0400 },
  "dropoff": { "address": "B", "latitude": 33.7200, "longitude": 73.1000 },
  "ride_type": "one_way",
  "vehicle_category_id": 1,
  "payment_method": "cash",
  "passenger_count": 1,
  "children": 0
}
```

### Book (Round Trip with Return DateTime)

```json
{
  "pickup": { "address": "A", "latitude": 33.7000, "longitude": 73.0400 },
  "dropoff": { "address": "B", "latitude": 33.7200, "longitude": 73.1000 },
  "return_location": { "address": "A", "latitude": 33.7000, "longitude": 73.0400 },
  "ride_type": "round_trip",
  "return_scheduled_at": "2026-04-15T18:00:00Z",
  "vehicle_category_id": 1,
  "payment_method": "wallet",
  "passenger_count": 2,
  "children": 1
}
```

## 8) QA Checklist (Happy Path)

1. OTP auth works (`send-otp` -> `verify-otp`).
2. New user can register and existing user can skip register.
3. Categories load.
4. Estimate works for:
   - one-way
   - per-hour (`duration_minutes`)
   - delivery
5. Booking succeeds and returns ride ID/code.
6. Driver sees nearby ride and submits bid.
7. Passenger receives bid and accepts.
8. Ride status transitions complete to `completed`.
9. Passenger history and driver earnings reflect the ride.
10. Websocket emits ride lifecycle events throughout.