Driveosplatform catalogue

Rides

Booking a ride from another system: how it is sent, how not to duplicate it and how to follow it until it finishes.

When a hotel guest, a patient or an employee needs a ride and the booking starts in another system, the ride still has to enter the same queue as all the others — without losing or duplicating anything.

Ride statuses

StatusMeansFinal
REQUESTEDThe ride is booked and waits for assignmentno
OFFEREDAn offer was sent to a driver and waits for acceptanceno
ASSIGNEDThe ride has a driver who has not confirmed yetno
ACCEPTEDThe driver acceptedno
ARRIVINGThe driver is on the way to the passengerno
ARRIVEDThe driver arrived; waiting time runsno
IN_PROGRESSThe passenger is on boardno
COMPLETEDThe ride is finished; the final price is knownyes
CANCELLEDThe ride was cancelled (by either side)yes
NO_SHOWThe driver arrived, the passenger was not thereyes
FAILEDThe ride failed for a technical reasonyes
Do not guess the statusThe status is always the one the server returns. An integration that concludes a ride “must be finished” because time passed will be wrong with extended waiting or a dropped connection.

Booking a ride

POST/api/v1/rides

Creates a ride. Scope book. When both coordinates are sent, distance and duration are optional — the server computes them from the route.

FieldTypeRequiredDescription
externalIdstring (2–80)—Idempotency key, unique inside the company; the same request twice does not create two rides
serviceTypeIduuid✓From GET /v1/service-types
vehicleClassIduuid—If the company uses vehicle classes
paymentMethodenum—CASH, CARD, TERMINAL, WALLET, CORPORATE_ACCOUNT, INVOICE
passengerNamestring (2–160)—Passenger name for the driver and the receipt
passengerPhonestring—Phone in international or local format
pickupAddressstring (2–300)✓The pickup address the driver sees
pickupLatitude / pickupLongitudenumber✓Pickup coordinates (7 decimals)
dropoffAddressstring (2–300)—Destination; without it the ride is open-ended
dropoffLatitude / dropoffLongitudenumber—Destination coordinates
distanceKm / durationMinutesnumber—If sent, the server does not compute them again
scheduledAtISO 8601—A ride booked ahead (module addon.scheduled_rides)
notesstring (≤1000)—A note for the driver
couponCodestring (≤40)—Promo code (module addon.promo_codes)
corporateAccountId / costCenterIduuid—Corporate account and cost centre (module addon.corporate_accounts)
stopsarray (≤16)—Intermediate stops: address, latitude, longitude
bashnaručivanje s idempotencijom
curl -s -X POST https://driveos.eu/api/v1/rides \
  -H "X-API-Key: $DEMO_TAXI_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "externalId": "erp-2026-000417",
    "serviceTypeId": "8f1c2a6e-6d4b-4f2a-9d31-2a7c1b6e5f01",
    "paymentMethod": "CARD",
    "passengerName": "Ana Anić",
    "passengerPhone": "+385 91 555 0100",
    "pickupAddress": "Ilica 42, 10000 Zagreb",
    "pickupLatitude": 45.8127,
    "pickupLongitude": 15.9700,
    "dropoffAddress": "Zračna luka Zagreb, 10150 Zagreb",
    "dropoffLatitude": 45.7429,
    "dropoffLongitude": 16.0688,
    "notes": "Dva kofera",
    "scheduledAt": "2026-11-18T04:30:00Z"
  }'
json201 — vožnja je stvorena (`replayed: false`)
{
  "ride": {
    "number": "R-2026-000417",
    "status": "REQUESTED",
    "channel": "API",
    "requestedAt": "2026-11-17T08:12:00.000Z",
    "scheduledAt": "2026-11-18T04:30:00.000Z",
    "pickupAddress": "Ilica 42, 10000 Zagreb",
    "dropoffAddress": "Zračna luka Zagreb, 10150 Zagreb",
    "estimatedPrice": 24.80,
    "finalPrice": null,
    "currencyCode": "EUR",
    "externalId": "erp-2026-000417",
    "serviceType": { "code": "STANDARD", "name": "Standard" },
    "driver": null
  },
  "replayed": false
}
Idempotency: the same request, one rideSending the same externalId again returns replayed: true and the same ride — no new one is created. That is the only safe way to repeat a request after a dropped connection without duplicating a ride.

List and detail

GET/api/v1/rides

The company’s ride list. Scope rides. Without filters it returns the latest 25 by booking time.

FieldTypeRequiredDescription
page / pageSizeinteger—Pagination; pageSize at most 100, default 25
statusstring—One or more statuses, comma separated
from / todate—Range by booking time (YYYY-MM-DD)
updatedSinceISO 8601—Every ride changed after that moment — for sync
serviceTypeId / driverIduuid—Filters by service type and driver
qstring—Search by number, address or passenger name
externalIdstring—An exact external identifier
GET/api/v1/rides/{number}

Ride detail with stops and the status timeline. Scope rides. A ride of another company returns 404, not 403.

Cancellation

POST/api/v1/rides/{number}/cancel

Cancels a ride. Scope book. A finished ride returns 409. The reason is optional but is recorded in history and shown to the dispatcher.

FieldTypeRequiredDescription
reasonstring (≤200)—Cancellation reason (e.g. “Passenger cancelled”)
bash
curl -s -X POST https://driveos.eu/api/v1/rides/R-2026-000417/cancel \
  -H "X-API-Key: $DEMO_TAXI_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"reason":"Putnik je otkazao"}'

Common errors

CodeStatusCause
errors.apiRideNeedsRoute400Not enough data for a route (an address without coordinates)
errors.invalidPhone400The phone is not in a recognised format
errors.externalIdInvalid400The external id contains disallowed characters
errors.tooManyStops400More than 16 intermediate stops
errors.serviceTypeMissing400The service type does not exist or is not active (errors.serviceTypeInactive)
errors.rideTransitionNotAllowed409The ride is in a state from which it cannot be cancelled (e.g. already finished)
errors.launchNotReady400The company is not ready to operate yet (see the readiness gate)