Use the driver API
The term driver relates to the person that delivers the goods, usually by a bike or a car. The following endpoints provide data to support this task. See also other API endpoints for other needed information (like logon/logoff, order content , items etc).
All driver endpoints need a session authenticated with driver permissions; without it they return HTTP 403 access_error.
Every mutating endpoint accepts a dupcheck uuid: resending the same uuid within ~36 hours is ignored and
acknowledged with the result code <action>duplicate, so unstable mobile connections can safely retry.
Timestamps are passed as ISO8601 datetimes (with timezone offset). Most endpoints accept a dt parameter to
report the real event time when requests are sent delayed (offline queueing).
settings
A series of settings come from the backend. This ensures, all drivers do have the same settings.
tour info fetching
api/tours gives the list of all tours. Tours that are ready to be executed carry a counter > 0 in the field Ddate.ordercnt. Use ist >tours.id to fetch a specific tour plan using api/tour.
goods delivery activities
- /api/driver/dlvr1 — mark an order as delivered. Updates the tour delivery state and may notify the customer by mail, SMS or push.
- /api/driver/udlvr1 — revoke a delivery reported by mistake.
- /api/driver/boxexchange1 — report the number of boxes delivered to and returned by a customer.
- /api/driver/assign1 / /api/driver/deassign1 — assign a reusable box to a customer or remove that assignment. Box-level rejections are returned as DriverAssignResult result codes with HTTP 200.
- /api/driver/info1 — send an arbitrary driver note to the office.
- /api/driver/cadr1 — correct the delivery geo position (park position) of a customer address (power driver only).
- /api/driver/bpos1 — store the geo position where the box was placed (power driver only).
Most of these acknowledge with a generic DriverActionResult.
refund handling
- /api/driver/refund1 — hand over one or more refund bookings collected at
the door. Lines are passed positionally: repeat
position=nand passpid-n/amount-nper line. - /api/driver/urefund1 — revoke refund bookings (mistake correction); amounts are booked negatively.
improving accuracy of the delivery time
- /api/driver/state1 — report tour state changes (e.g.
starttour), optionally with car plate, temperature and mileage. - /api/driver/trck1 — upload GPS tracking data (one fix per line:
lat,lng,accuracy,timestamp[,km]). Feeds the delivery time prediction. - /api/driver/locate1 — last known driver positions as DriverPosition records; customers get the position of the tour currently delivering to them.
- /api/driver/reorder1 — hand over a re-ordered tour position sequence.
- /api/driver/setstart1 — set the start time of a tour run (with
ddate) or the general tour start (withtouridonly).
pauses
- /api/driver/pauses — list active pauses for a tour and date as DriverPause records.
- /api/driver/setpause1 — record a pause (by
lengthin minutes or an explicitendtime); returns a PauseResult. - /api/driver/delpause — delete a previously recorded pause.
charging stations
Since tour32, we provide Charging Locations for a driver app to consume.
legacy endpoints
The unversioned action names (/api/driver/dlvr, /api/driver/trck, ...) still exist and keep answering in
the old ad-hoc format {"action": ..., "result": ...}. New clients should use the versioned endpoints above.