Stops

Base URL: /api/stops · Port 3001 in development.

Stops are the individual delivery points within a Route. Each stop is linked to one package and carries an estimated arrival time (set during route creation) and an optional actual arrival time (set by the distributor on delivery).

PATCH /api/stops/reorder

Auth required: Yes — admin only

Reorders stops within a route by assigning a new order_index to each stop. All stop IDs provided must belong to the specified route. No two stops may share the same order_index.

Request body

Field	Type	Required	Description
`route_id`	number	✓	Route ID (positive integer)
`stops`	array	✓	Non-empty array of stop order items
`stops[].stop_id`	number	✓	Stop ID (positive integer)
`stops[].order_index`	number	✓	New order position (positive integer, unique within request)

{
  "route_id": 5,
  "stops": [
    { "stop_id": 21, "order_index": 1 },
    { "stop_id": 22, "order_index": 2 },
    { "stop_id": 23, "order_index": 3 }
  ]
}

Response 200 — array of updated stops

[
  {
    "id": 21,
    "route_id": 5,
    "package_id": 42,
    "stop_order": 1,
    "estimated_arrival": "09:30:00",
    "actual_arrival": null
  },
  {
    "id": 22,
    "route_id": 5,
    "package_id": 43,
    "stop_order": 2,
    "estimated_arrival": "10:00:00",
    "actual_arrival": null
  }
]

Errors

Status	Message	Condition
400	`"route_id is required and must be a positive integer"`	Missing or invalid `route_id`
400	`"stops is required and must be a non-empty array"`	Empty or missing `stops`
400	`"Each stop must have a positive integer stop_id and order_index"`	Invalid item in `stops`
400	`"order_index values must not contain duplicates"`	Duplicate `order_index` values
400	`"Stop {id} does not belong to route {id}"`	Stop ID not in the given route
401	`"Authorization header is missing"`	No token
403	`"You do not have permission to access this resource"`	Caller is not `admin`
404	`"Route {id} not found"`	No route with that ID
500	`"Internal server error"`	Unhandled exception

PATCH /api/stops/updateArrival

Auth required: Yes — distributor only

Records the actual arrival time for a stop. Called when the distributor arrives at a delivery point. Sets actual_arrival to the current server timestamp.

Request body

Field	Type	Required	Description
`stop_id`	number	✓	Stop ID (positive integer)

{ "stop_id": 21 }

Response 200

{
  "id": 21,
  "route_id": 5,
  "package_id": 42,
  "stop_order": 1,
  "estimated_arrival": "09:30:00",
  "actual_arrival": "09:28:00"
}

Errors

Status	Message	Condition
400	`"stop_id is required and must be a positive integer"`	Missing or invalid `stop_id`
401	`"Authorization header is missing"`	No token
403	`"You do not have permission to access this resource"`	Caller is not `distributor`
404	`"Stop not found"`	No stop with that ID
500	`"Internal server error"`	Unhandled exception