The phone lost signal or the app was closed

Situation #

A vehicle disappears from the live view or its track has a hole: the phone had no signal, the battery ran out, or the driver closed the app. The Fleet screens arrive with the web console, so the checks use the API.

What keeps working #

• The shift or trip itself, and every record the driver enters.
• Positions the phone kept while offline. It uploads them later in batches.
• Repeated uploads. A batch sent twice stores each position once.

Steps in order #

1. Ask the driver to open the app with signal. The phone sends what it holds with POST /fleet/positions, up to 1,000 fixes per batch, each with a device_id and a seq number.
2. Read the answer if you are testing: accepted, duplicates, rejected (each with the reason) and the tracking state. A position with the same device_id and seq as one already stored counts under duplicates and changes nothing.
3. Check that a shift or trip is open for the driver or the vehicle. Without one, positions come back in rejected with "Tracking runs only during a shift or a trip." Start the trip with POST /fleet/trips or have the driver start the shift, then upload again.
4. Look at the track: GET /fleet/assets/{id}/positions (add from and to to widen the default last 24 hours). The answer lists fixes in time order with gaps, the number of stretches longer than five minutes between consecutive fixes.
5. Accept the gap where it stays. Late positions fill it when the phone uploads. Positions that never reached the server cannot be recreated.

How to confirm it worked #

• GET /fleet/assets/{id}/positions shows fixes inside the stretch and a lower gaps count.
• GET /fleet/live shows the vehicle's latest position and last_ping_at. A late batch updates it only when it holds something newer than what is stored.

What to do afterwards #

• Treat estimated_distance_m (and estimated_distance_display) as an estimate. It sums straight lines between good fixes, so a gap shortens it.
• The odometer comes from a typed reading with POST /fleet/assets/{id}/meters, and positions never write it. Ask the driver to enter the reading at the end of the shift.
• Tell drivers to keep location permission on and the app open during a shift. See "Live map, consent and gaps".