Trip Lifecycle - Rodando Backend

This document describes the complete lifecycle of a trip from creation to completion, including all possible states and transitions.

Trip States

A trip progresses through multiple states during its lifecycle. Here are all possible states:

pending

Initial state when a trip is first created. The trip request has been received but driver matching has not yet started. Possible transitions:

assigning - When the matching system begins looking for available drivers
cancelled - If the passenger cancels before matching starts

assigning

The system is actively searching for and offering the trip to available drivers. Possible transitions:

accepted - When a driver accepts the trip assignment
no_drivers_found - If no drivers accept within the timeout period
cancelled - If the passenger cancels during matching

accepted

A driver has accepted the trip and is preparing to head to the pickup location. Possible transitions:

arriving - When the driver starts navigating to the pickup point
cancelled - If the passenger or driver cancels

arriving

The driver is en route to the pickup location. Possible transitions:

arriving (arrived at pickup) - When the driver reaches the pickup point
in_progress - When the passenger boards and the trip starts
cancelled - If the passenger or driver cancels

in_progress

The passenger is on board and the trip is actively underway to the destination. Possible transitions:

completed - When the trip reaches the final destination
cancelled - In rare cases (emergency, etc.)

completed

The trip has been successfully completed. This is a terminal state. No further transitions possible.

cancelled

The trip was cancelled by the passenger, driver, or system. This is a terminal state. No further transitions possible.

no_drivers_found

No available drivers accepted the trip within the matching timeout period. This is a terminal state. No further transitions possible.

State Transition Diagram

Lifecycle Timestamps

Each state transition is tracked with specific timestamp fields:

requestedAt

string

When the trip was initially requested (trip creation)

acceptedAt

string

When a driver accepted the trip assignment

pickupEtaAt

string

Estimated time when driver will arrive at pickup (set when entering arriving)

arrivedPickupAt

string

When the driver physically arrived at the pickup location

startedAt

string

When the trip started (passenger on board, entering in_progress)

completedAt

string

When the trip was successfully completed

canceledAt

string

When the trip was cancelled (if applicable)

API Endpoints for State Transitions

Each state transition is triggered by specific API endpoints:

pending → assigning

POST /trips/{id}/assign/start

curl -X POST https://api.rodando.com/trips/{id}/assign/start \
  -H "Content-Type: application/json" \
  -d '{
    "maxOffers": 5,
    "offerTimeoutSeconds": 30
  }'

Starts the driver matching process.

assigning → accepted

PATCH /trips/assignments/{assignmentId}/accept

curl -X PATCH https://api.rodando.com/trips/assignments/{assignmentId}/accept \
  -H "Authorization: Bearer {driver-token}"

Driver accepts a trip assignment.

accepted → arriving

POST /trips/{id}/arriving

curl -X POST https://api.rodando.com/trips/{id}/arriving \
  -H "Content-Type: application/json" \
  -d '{
    "driverId": "driver-uuid-456",
    "pickupEta": "2025-09-20T14:42:00Z"
  }'

Driver starts heading to pickup location.

arriving → arrived at pickup

POST /trips/{id}/arrived-pickup

curl -X POST https://api.rodando.com/trips/{id}/arrived-pickup \
  -H "Content-Type: application/json" \
  -d '{
    "driverId": "driver-uuid-456"
  }'

Driver marks arrival at pickup point.

arriving/arrived → in_progress

POST /trips/{id}/start

curl -X POST https://api.rodando.com/trips/{id}/start \
  -H "Content-Type: application/json" \
  -d '{
    "driverId": "driver-uuid-456"
  }'

Driver starts the trip (passenger on board).

in_progress → completed

POST /trips/{id}/complete

curl -X POST https://api.rodando.com/trips/{id}/complete \
  -H "Content-Type: application/json" \
  -d '{
    "driverId": "driver-uuid-456",
    "actualDistanceKm": 3.5,
    "actualDurationMin": 15,
    "completedAt": "2025-09-20T15:00:00Z"
  }'

Completes the trip and calculates final fare.

assigning → no_drivers_found

POST /trips/{id}/assign/no-drivers

curl -X POST https://api.rodando.com/trips/{id}/assign/no-drivers

Marks trip as having no available drivers (typically called automatically by the matching system).

Driver Assignment Flow

The assigning state involves a multi-step assignment process:

System creates assignments - Trip assignments are created for eligible drivers based on proximity, vehicle category, and availability
Drivers receive offers - Each assignment represents an offer sent to a driver with a timeout (typically 15-30 seconds)
Driver responds - Driver can:
- Accept - Trip moves to accepted, driver is assigned
- Reject - System continues offering to other drivers
- Timeout - If no response within timeout, offer expires and continues to next driver
Outcomes:
- If any driver accepts → Trip becomes accepted
- If all drivers reject/timeout → Trip becomes no_drivers_found
- If passenger cancels during matching → Trip becomes cancelled

Assignment Endpoints

POST /trips/{id}/reject

curl -X POST https://api.rodando.com/trips/{id}/reject \
  -H "Content-Type: application/json" \
  -d '{
    "driverId": "driver-uuid-789",
    "reason": "too_far"
  }'

Driver rejects a trip assignment.

POST /trips/{id}/expire

curl -X POST https://api.rodando.com/trips/{id}/expire

Marks an assignment as expired (called automatically when timeout is reached).

Events and Notifications

Each state transition triggers domain events that can be used for:

Real-time notifications - WebSocket updates to passenger and driver apps
Audit logging - Complete history of trip state changes
Analytics - Trip metrics and performance tracking
Integration hooks - Third-party system notifications

Event Types

TripRequestedEvent - Trip created (pending)
AssigningStartedEvent - Matching started (assigning)
DriverAcceptedEvent - Driver accepted assignment (accepted)
ArrivingStartedEvent - Driver en route (arriving)
DriverArrivedPickupEvent - Driver at pickup location
TripStartedEvent - Trip in progress (in_progress)
TripCompletedEvent - Trip finished (completed)
DriverRejectedEvent - Driver rejected offer
AssignmentExpiredEvent - Offer timeout
NoDriversFoundEvent - No drivers available (no_drivers_found)

Get Active Trip for Passenger

Path Parameters

string

required

Passenger user UUID

Response

success

boolean

Indicates if the operation was successful

message

string

Response message

data

object

The active trip object, or null if the passenger has no active trip

Example Request

curl https://api.rodando.com/trips/passengers/passenger-uuid-123/active-trip

Get Active Trip for Driver

Path Parameters

string

required

Driver UUID

Response

success

boolean

Indicates if the operation was successful

message

string

Response message

data

object

The active trip object, or null if the driver has no active trip

Example Request

curl https://api.rodando.com/trips/drivers/driver-uuid-456/active-trip

Accept Trip Assignment (Driver)

Path Parameters

string

required

Assignment UUID (not trip UUID)

Headers

Authorization

string

required

Bearer token for driver authentication. The driver ID is extracted from the JWT.

Response

success

boolean

Indicates if the operation was successful

message

string

Response message

data

object

Updated trip object in accepted status with driver assigned

Example Request

curl -X PATCH https://api.rodando.com/trips/assignments/assignment-uuid-789/accept \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Error Responses

401 Unauthorized: Invalid or missing JWT token
409 Conflict: Assignment not active or already responded to

Reject Trip Assignment

Path Parameters

string

required

Trip UUID

Body Parameters

driverId

string

required

UUID of the driver rejecting the assignment

reason

string

Reason for rejection (e.g., too_far, unavailable, other)

Response

success

boolean

Indicates if the operation was successful

message

string

Response message

data

object

Trip object (still in assigning status)

Example Request

curl -X POST https://api.rodando.com/trips/trip-uuid-123/reject \
  -H "Content-Type: application/json" \
  -d '{
    "driverId": "driver-uuid-789",
    "reason": "too_far"
  }'

Error Responses

409 Conflict: Assignment not active or already responded to
400 Bad Request: Validation error

Expire Trip Assignment

Path Parameters

string

required

Trip UUID

Response

success

boolean

Indicates if the operation was successful

message

string

Response message

data

object

Trip object. If more drivers are available, continues in assigning status. Otherwise may transition to no_drivers_found.

Example Request

curl -X POST https://api.rodando.com/trips/trip-uuid-123/expire

Error Responses

409 Conflict: Assignment not active or already responded to

Mark Trip as No Drivers Found

Path Parameters

string

required

Trip UUID

Response

success

boolean

Indicates if the operation was successful

message

string

Response message

data

object

Trip object in no_drivers_found status

Example Request

curl -X POST https://api.rodando.com/trips/trip-uuid-123/assign/no-drivers

Use Case

This endpoint is typically called automatically by the matching system when:

All eligible drivers have rejected the trip
All assignment offers have timed out
No drivers are available within the search radius

Viewing Trip Events

You can retrieve the complete audit trail of all events for a trip:

GET /trips/{id}/events

curl https://api.rodando.com/trips/{id}/events

Returns a chronological list of all state transitions and events with timestamps and metadata.

Business Rules

State Validation

State transitions are validated to ensure they follow the allowed flow
Invalid transitions (e.g., pending → completed) are rejected with HTTP 409 Conflict

Driver Assignment

Only the assigned driver can perform actions on trips in accepted, arriving, or in_progress states
Driver ID is validated on all driver action endpoints

Fare Calculation

fareEstimatedTotal is set when trip is created (based on pricing engine)
fareTotal is calculated when trip transitions to completed
Fare breakdown includes actual distance, duration, surge, and all fees

Cancellation

Trips can be cancelled at any non-terminal state
Cancellation policies may apply fees depending on trip state
Both passenger and driver may have cancellation rights with different rules

Authentication

Trip Management

Driver Management

User Management

Vehicles

Orders & Payments

Settings

​Trip States

​pending

​assigning

​accepted

​arriving

​in_progress

​completed

​cancelled

​no_drivers_found

​State Transition Diagram

​Lifecycle Timestamps

​API Endpoints for State Transitions

​pending → assigning

​assigning → accepted

​accepted → arriving

​arriving → arrived at pickup

​arriving/arrived → in_progress

​in_progress → completed

​assigning → no_drivers_found

​Driver Assignment Flow

​Assignment Endpoints

​Events and Notifications

​Event Types

​Get Active Trip for Passenger

​Path Parameters

​Response

​Example Request

​Get Active Trip for Driver

​Path Parameters

​Response

​Example Request

​Accept Trip Assignment (Driver)

​Path Parameters

​Headers

​Response

​Example Request

​Error Responses

​Reject Trip Assignment

​Path Parameters

​Body Parameters

​Response

​Example Request

​Error Responses

​Expire Trip Assignment

​Path Parameters

​Response

​Example Request

​Error Responses

​Mark Trip as No Drivers Found

​Path Parameters

​Response

​Example Request

​Use Case

​Viewing Trip Events

​Business Rules

​State Validation

​Driver Assignment

​Fare Calculation

​Cancellation

​See Also

Build docs developers (and LLMs) love

Trip States

pending

assigning

accepted

arriving

in_progress

completed

cancelled

no_drivers_found

State Transition Diagram

Lifecycle Timestamps

API Endpoints for State Transitions

pending → assigning

assigning → accepted

accepted → arriving

arriving → arrived at pickup

arriving/arrived → in_progress

in_progress → completed

assigning → no_drivers_found

Driver Assignment Flow

Assignment Endpoints

Events and Notifications

Event Types

Get Active Trip for Passenger

Path Parameters

Response

Example Request

Get Active Trip for Driver

Path Parameters

Response

Example Request

Accept Trip Assignment (Driver)

Path Parameters

Headers

Response

Example Request

Error Responses

Reject Trip Assignment

Path Parameters

Body Parameters

Response

Example Request

Error Responses

Expire Trip Assignment

Path Parameters

Response

Example Request

Error Responses

Mark Trip as No Drivers Found

Path Parameters

Response

Example Request

Use Case

Viewing Trip Events

Business Rules

State Validation

Driver Assignment

Fare Calculation

Cancellation

See Also