Driveoskatalog platforme

Vožnje

Naručivanje vožnje iz drugog programa: kako se šalje, kako se ne udvostruči i kako se prati dok ne završi.

Kad gost hotela, pacijent ili zaposlenik treba vožnju, a narudžba nastaje u drugom programu, vožnja ipak mora ući u isti red kao i sve ostale — bez gubljenja i bez dvostrukog unosa.

Statusi vožnje

StatusZnačiKraj
REQUESTEDVožnja je naručena i čeka dodjelune
OFFEREDPonuda je poslana vozaču i čeka prihvatne
ASSIGNEDVožnja ima vozača, ali ga vozač još nije potvrdione
ACCEPTEDVozač je prihvatione
ARRIVINGVozač je na putu do putnikane
ARRIVEDVozač je stigao; teče čekanjene
IN_PROGRESSPutnik je u vozilune
COMPLETEDVožnja je završena; konačna cijena je poznatada
CANCELLEDVožnja je otkazana (bilo koja strana)da
NO_SHOWVozač je stigao, putnika nije biloda
FAILEDVožnja nije uspjela iz tehničkog razlogada
Ne pogađajte statusStatus je uvijek onaj koji vrati poslužitelj. Integracija koja zaključuje da je vožnja „sigurno završena“ jer je prošlo vrijeme pogriješit će kod produženog čekanja ili prekida veze.

Naručivanje vožnje

POST/api/v1/rides

Stvara vožnju. Opseg book. Kad su poslane obje koordinate, udaljenost i trajanje nisu obavezni — poslužitelj ih izračuna rutom.

PoljeTipObaveznoOpis
externalIdstring (2–80)—Ključ idempotencije, jedinstven unutar tvrtke; isti zahtjev dvaput ne stvara dvije vožnje
serviceTypeIduuid✓Iz GET /v1/service-types
vehicleClassIduuid—Ako tvrtka koristi kategorije vozila
paymentMethodenum—CASH, CARD, TERMINAL, WALLET, CORPORATE_ACCOUNT, INVOICE
passengerNamestring (2–160)—Ime putnika za vozača i račun
passengerPhonestring—Telefon u međunarodnom ili lokalnom obliku
pickupAddressstring (2–300)✓Adresa preuzimanja koju vozač vidi
pickupLatitude / pickupLongitudenumber✓Koordinate preuzimanja (7 decimala)
dropoffAddressstring (2–300)—Odredište; bez njega vožnja je „na otvoreno“
dropoffLatitude / dropoffLongitudenumber—Koordinate odredišta
distanceKm / durationMinutesnumber—Ako ih pošaljete, poslužitelj ih ne računa ponovno
scheduledAtISO 8601—Vožnja unaprijed (modul addon.scheduled_rides)
notesstring (≤1000)—Napomena za vozača
couponCodestring (≤40)—Promo kod (modul addon.promo_codes)
corporateAccountId / costCenterIduuid—Poslovni račun i mjesto troška (modul addon.corporate_accounts)
stopsarray (≤16)—Međuzaustavljanja: 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
}
Idempotencija: isti zahtjev, jedna vožnjaAko pošaljete isti externalId drugi put, odgovor je replayed: true i ista vožnja — ne nastaje nova. To je jedini siguran način da ponovite zahtjev nakon prekida veze, a da ne udvostručite vožnju.

Popis i detalj

GET/api/v1/rides

Popis vožnji tvrtke. Opseg rides. Bez filtera vraća zadnjih 25 po vremenu narudžbe.

PoljeTipObaveznoOpis
page / pageSizeinteger—Straničenje; pageSize najviše 100, zadano 25
statusstring—Jedan ili više statusa, odvojeni zarezom
from / todate—Raspon po vremenu narudžbe (YYYY-MM-DD)
updatedSinceISO 8601—Sve vožnje promijenjene nakon tog trenutka — za sinkronizaciju
serviceTypeId / driverIduuid—Filtri po vrsti usluge i vozaču
qstring—Pretraga po broju, adresi ili imenu putnika
externalIdstring—Točan vanjski identifikator
GET/api/v1/rides/{number}

Detalj vožnje s međuzaustavljanjima i tijekom statusa. Opseg rides. Vožnja druge tvrtke vraća 404, ne 403.

Otkazivanje

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

Otkazivanje vožnje. Opseg book. Završena vožnja vraća 409. Razlog je neobavezan, ali se bilježi u povijesti i vidi dispečeru.

PoljeTipObaveznoOpis
reasonstring (≤200)—Razlog otkazivanja (npr. „Putnik je otkazao“)
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"}'

Najčešće greške

KodStatusUzrok
errors.apiRideNeedsRoute400Nema dovoljno podataka za rutu (samo adresa bez koordinata)
errors.invalidPhone400Telefon nije u prepoznatom obliku
errors.externalIdInvalid400Vanjska oznaka ima nedopuštene znakove
errors.tooManyStops400Više od 16 međuzaustavljanja
errors.serviceTypeMissing400Vrsta usluge ne postoji ili nije aktivna (errors.serviceTypeInactive)
errors.rideTransitionNotAllowed409Vožnja je u stanju iz kojeg se ne može otkazati (npr. već završena)
errors.launchNotReady400Tvrtka još nije spremna za pogon (vidi kapiju spremnosti)