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
| Status | Znači | Kraj |
|---|---|---|
REQUESTED | Vožnja je naručena i čeka dodjelu | ne |
OFFERED | Ponuda je poslana vozaču i čeka prihvat | ne |
ASSIGNED | Vožnja ima vozača, ali ga vozač još nije potvrdio | ne |
ACCEPTED | Vozač je prihvatio | ne |
ARRIVING | Vozač je na putu do putnika | ne |
ARRIVED | Vozač je stigao; teče čekanje | ne |
IN_PROGRESS | Putnik je u vozilu | ne |
COMPLETED | Vožnja je završena; konačna cijena je poznata | da |
CANCELLED | Vožnja je otkazana (bilo koja strana) | da |
NO_SHOW | Vozač je stigao, putnika nije bilo | da |
FAILED | Vožnja nije uspjela iz tehničkog razloga | da |
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.
| Polje | Tip | Obavezno | Opis |
|---|---|---|---|
externalId | string (2–80) | — | Ključ idempotencije, jedinstven unutar tvrtke; isti zahtjev dvaput ne stvara dvije vožnje |
serviceTypeId | uuid | ✓ | Iz GET /v1/service-types |
vehicleClassId | uuid | — | Ako tvrtka koristi kategorije vozila |
paymentMethod | enum | — | CASH, CARD, TERMINAL, WALLET, CORPORATE_ACCOUNT, INVOICE |
passengerName | string (2–160) | — | Ime putnika za vozača i račun |
passengerPhone | string | — | Telefon u međunarodnom ili lokalnom obliku |
pickupAddress | string (2–300) | ✓ | Adresa preuzimanja koju vozač vidi |
pickupLatitude / pickupLongitude | number | ✓ | Koordinate preuzimanja (7 decimala) |
dropoffAddress | string (2–300) | — | Odredište; bez njega vožnja je „na otvoreno“ |
dropoffLatitude / dropoffLongitude | number | — | Koordinate odredišta |
distanceKm / durationMinutes | number | — | Ako ih pošaljete, poslužitelj ih ne računa ponovno |
scheduledAt | ISO 8601 | — | Vožnja unaprijed (modul addon.scheduled_rides) |
notes | string (≤1000) | — | Napomena za vozača |
couponCode | string (≤40) | — | Promo kod (modul addon.promo_codes) |
corporateAccountId / costCenterId | uuid | — | Poslovni račun i mjesto troška (modul addon.corporate_accounts) |
stops | array (≤16) | — | Međuzaustavljanja: address, latitude, longitude |
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"
}'
{
"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.
| Polje | Tip | Obavezno | Opis |
|---|---|---|---|
page / pageSize | integer | — | Straničenje; pageSize najviše 100, zadano 25 |
status | string | — | Jedan ili više statusa, odvojeni zarezom |
from / to | date | — | Raspon po vremenu narudžbe (YYYY-MM-DD) |
updatedSince | ISO 8601 | — | Sve vožnje promijenjene nakon tog trenutka — za sinkronizaciju |
serviceTypeId / driverId | uuid | — | Filtri po vrsti usluge i vozaču |
q | string | — | Pretraga po broju, adresi ili imenu putnika |
externalId | string | — | 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.
| Polje | Tip | Obavezno | Opis |
|---|---|---|---|
reason | string (≤200) | — | Razlog otkazivanja (npr. „Putnik je otkazao“) |
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
| Kod | Status | Uzrok |
|---|---|---|
errors.apiRideNeedsRoute | 400 | Nema dovoljno podataka za rutu (samo adresa bez koordinata) |
errors.invalidPhone | 400 | Telefon nije u prepoznatom obliku |
errors.externalIdInvalid | 400 | Vanjska oznaka ima nedopuštene znakove |
errors.tooManyStops | 400 | Više od 16 međuzaustavljanja |
errors.serviceTypeMissing | 400 | Vrsta usluge ne postoji ili nije aktivna (errors.serviceTypeInactive) |
errors.rideTransitionNotAllowed | 409 | Vožnja je u stanju iz kojeg se ne može otkazati (npr. već završena) |
errors.launchNotReady | 400 | Tvrtka još nije spremna za pogon (vidi kapiju spremnosti) |