From 5b02524aa97a7415adcfe16f324112fa9ed0dee2 Mon Sep 17 00:00:00 2001 From: "Ronald A. Richardson" Date: Sun, 23 Aug 2026 21:18:11 +0800 Subject: [PATCH] feat(fleetbase-api): driver manifests and driver password endpoints MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documents the consumable endpoints added in fleetops#304 and fleetops#305. Drivers gains three password requests. A password change is an authorisation decision rather than an attribute update, which is why it is not part of PUT /drivers/:id — that endpoint no longer accepts a password at all. The descriptions carry the two properties a caller needs to know about and cannot discover by trying: the reset request answers identically whether or not the identity exists, so it cannot be used to enumerate an organization's drivers, and a wrong code, an expired code and an unknown identity all return the same error. A new Manifests folder covers the route a driver actually drives — a manifest is an order-agnostic sequence of stops which may span several orders, or none the driver has seen as an order. Retrieve returns the stops in sequence with their places inline, so a route of twenty stops is one request rather than twenty-one. The optimize description says plainly what it is: a nearest-neighbour walk over road distances, usually a large improvement on an arbitrary order and not guaranteed optimal, which reorders the stops of one assigned manifest rather than allocating work across a fleet the way the orchestrator does. Completed and skipped stops keep their place. Listing a driver's manifests sits with the other driver-scoped requests rather than in the new folder, next to List Driver Organizations. No response examples yet: the endpoints are still in review on the fleetops release branch, and an example recorded against an unmerged branch would be a guess rather than verified behaviour. Happy to add them once merged. npm run postman:lint — 196 requests scanned in Fleetbase API, 0 errors, 0 warnings. --- package-lock.json | 13 +++++++++ .../Change Driver Password.params.yaml | 18 ++++++++++++ .../Change Driver Password.request.yaml | 26 +++++++++++++++++ .../List Driver Manifests.queryParams.yaml | 14 ++++++++++ .../List Driver Manifests.request.yaml | 16 +++++++++++ .../Request Driver Password Reset.params.yaml | 6 ++++ ...Request Driver Password Reset.request.yaml | 19 +++++++++++++ .../Drivers/Reset Driver Password.params.yaml | 14 ++++++++++ .../Reset Driver Password.request.yaml | 21 ++++++++++++++ .../Manifests/.resources/definition.yaml | 6 ++++ .../Manifests/.resources/object.yaml | 22 +++++++++++++++ .../Manifests/Optimize a Manifest.params.yaml | 10 +++++++ .../Optimize a Manifest.request.yaml | 28 +++++++++++++++++++ .../Retrieve a Manifest.request.yaml | 14 ++++++++++ .../Update a Manifest Stop.params.yaml | 10 +++++++ .../Update a Manifest Stop.request.yaml | 23 +++++++++++++++ 16 files changed, 260 insertions(+) create mode 100644 package-lock.json create mode 100644 postman/collections/Fleetbase API/Drivers/Change Driver Password.params.yaml create mode 100644 postman/collections/Fleetbase API/Drivers/Change Driver Password.request.yaml create mode 100644 postman/collections/Fleetbase API/Drivers/List Driver Manifests.queryParams.yaml create mode 100644 postman/collections/Fleetbase API/Drivers/List Driver Manifests.request.yaml create mode 100644 postman/collections/Fleetbase API/Drivers/Request Driver Password Reset.params.yaml create mode 100644 postman/collections/Fleetbase API/Drivers/Request Driver Password Reset.request.yaml create mode 100644 postman/collections/Fleetbase API/Drivers/Reset Driver Password.params.yaml create mode 100644 postman/collections/Fleetbase API/Drivers/Reset Driver Password.request.yaml create mode 100644 postman/collections/Fleetbase API/Manifests/.resources/definition.yaml create mode 100644 postman/collections/Fleetbase API/Manifests/.resources/object.yaml create mode 100644 postman/collections/Fleetbase API/Manifests/Optimize a Manifest.params.yaml create mode 100644 postman/collections/Fleetbase API/Manifests/Optimize a Manifest.request.yaml create mode 100644 postman/collections/Fleetbase API/Manifests/Retrieve a Manifest.request.yaml create mode 100644 postman/collections/Fleetbase API/Manifests/Update a Manifest Stop.params.yaml create mode 100644 postman/collections/Fleetbase API/Manifests/Update a Manifest Stop.request.yaml diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..59dc90b --- /dev/null +++ b/package-lock.json @@ -0,0 +1,13 @@ +{ + "name": "@fleetbase/postman", + "version": "0.1.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "@fleetbase/postman", + "version": "0.1.0", + "license": "Apache-2.0" + } + } +} diff --git a/postman/collections/Fleetbase API/Drivers/Change Driver Password.params.yaml b/postman/collections/Fleetbase API/Drivers/Change Driver Password.params.yaml new file mode 100644 index 0000000..f365666 --- /dev/null +++ b/postman/collections/Fleetbase API/Drivers/Change Driver Password.params.yaml @@ -0,0 +1,18 @@ +$kind: params +fields: + - name: current_password + type: string + required: true + description: The driver's existing password. The change is refused without it. + - name: password + type: string + required: true + description: The new password. Must be at least 8 characters. + - name: password_confirmation + type: string + required: false + description: When present, must match `password`. + - name: device_name + type: string + required: false + description: Name for the replacement token issued to the caller. Defaults to `navigator`. diff --git a/postman/collections/Fleetbase API/Drivers/Change Driver Password.request.yaml b/postman/collections/Fleetbase API/Drivers/Change Driver Password.request.yaml new file mode 100644 index 0000000..2414aa6 --- /dev/null +++ b/postman/collections/Fleetbase API/Drivers/Change Driver Password.request.yaml @@ -0,0 +1,26 @@ +$kind: http-request +name: "Change Driver Password" +description: |- + Changes the password of a driver who is signed in, proving the current one. + + A password change is an authorisation decision rather than an attribute update, which is why it is not part of `PUT /drivers/:id` — that endpoint does not accept a password at all. Supplying the wrong `current_password` is refused and changes nothing. + + Every other session is revoked when the password changes, and a fresh token is returned in the same response, so the caller keeps working while other devices are signed out. +url: "{{base_url}}/{{namespace}}/drivers/:id/change-password" +method: POST +pathVariables: + - key: id + value: "{{driver_id}}" + description: (Required) The driver whose password is being changed. + +body: + type: json + content: |- + { + "current_password": "{{driver_current_password}}", + "password": "{{driver_new_password}}", + "password_confirmation": "{{driver_new_password}}", + "device_name": "navigator" + } + +order: 13000 diff --git a/postman/collections/Fleetbase API/Drivers/List Driver Manifests.queryParams.yaml b/postman/collections/Fleetbase API/Drivers/List Driver Manifests.queryParams.yaml new file mode 100644 index 0000000..e871347 --- /dev/null +++ b/postman/collections/Fleetbase API/Drivers/List Driver Manifests.queryParams.yaml @@ -0,0 +1,14 @@ +$kind: queryParams +fields: + - name: status + type: string + required: false + description: Comma separated statuses to include, such as `pending,in_progress`. + - name: on + type: string + required: false + description: Only manifests scheduled on this date, as `YYYY-MM-DD`. + - name: limit + type: integer + required: false + description: Maximum manifests to return. Defaults to 30. diff --git a/postman/collections/Fleetbase API/Drivers/List Driver Manifests.request.yaml b/postman/collections/Fleetbase API/Drivers/List Driver Manifests.request.yaml new file mode 100644 index 0000000..4712fdf --- /dev/null +++ b/postman/collections/Fleetbase API/Drivers/List Driver Manifests.request.yaml @@ -0,0 +1,16 @@ +$kind: http-request +name: "List Driver Manifests" +description: |- + Lists the manifests assigned to a driver, newest first. + + A manifest is a driver's route: an order-agnostic sequence of stops which may span several orders, or none the driver has seen as an order. + + Defaults to a recent window rather than the driver's whole history. Use `status` and `on` to narrow it further. +url: "{{base_url}}/{{namespace}}/drivers/:id/manifests" +method: GET +pathVariables: + - key: id + value: "{{driver_id}}" + description: (Required) The driver whose manifests to list. + +order: 13300 diff --git a/postman/collections/Fleetbase API/Drivers/Request Driver Password Reset.params.yaml b/postman/collections/Fleetbase API/Drivers/Request Driver Password Reset.params.yaml new file mode 100644 index 0000000..256f89e --- /dev/null +++ b/postman/collections/Fleetbase API/Drivers/Request Driver Password Reset.params.yaml @@ -0,0 +1,6 @@ +$kind: params +fields: + - name: identity + type: string + required: true + description: The driver's email address or phone number. diff --git a/postman/collections/Fleetbase API/Drivers/Request Driver Password Reset.request.yaml b/postman/collections/Fleetbase API/Drivers/Request Driver Password Reset.request.yaml new file mode 100644 index 0000000..824808a --- /dev/null +++ b/postman/collections/Fleetbase API/Drivers/Request Driver Password Reset.request.yaml @@ -0,0 +1,19 @@ +$kind: http-request +name: "Request Driver Password Reset" +description: |- + Sends a password reset code to a driver who cannot sign in. + + The code goes by email or SMS depending on whether `identity` looks like an email address or a phone number. + + The response is the same whether or not the identity belongs to a driver. That is deliberate: an endpoint that answered differently for an unknown number would be a way to enumerate an organization's drivers. +url: "{{base_url}}/{{namespace}}/drivers/forgot-password" +method: POST + +body: + type: json + content: |- + { + "identity": "{{driver_email}}" + } + +order: 13100 diff --git a/postman/collections/Fleetbase API/Drivers/Reset Driver Password.params.yaml b/postman/collections/Fleetbase API/Drivers/Reset Driver Password.params.yaml new file mode 100644 index 0000000..da8fb06 --- /dev/null +++ b/postman/collections/Fleetbase API/Drivers/Reset Driver Password.params.yaml @@ -0,0 +1,14 @@ +$kind: params +fields: + - name: identity + type: string + required: true + description: The driver's email address or phone number — the same one the code was sent to. + - name: code + type: string + required: true + description: The verification code sent by `POST /drivers/forgot-password`. + - name: password + type: string + required: true + description: The new password. Must be at least 8 characters. diff --git a/postman/collections/Fleetbase API/Drivers/Reset Driver Password.request.yaml b/postman/collections/Fleetbase API/Drivers/Reset Driver Password.request.yaml new file mode 100644 index 0000000..90262f6 --- /dev/null +++ b/postman/collections/Fleetbase API/Drivers/Reset Driver Password.request.yaml @@ -0,0 +1,21 @@ +$kind: http-request +name: "Reset Driver Password" +description: |- + Sets a new password using the code sent by `POST /drivers/forgot-password`. + + A wrong code, an expired code and an unknown identity all return the same error, so the endpoint cannot be used to test which of the three happened. + + Every session is revoked on success. A reset is a recovery from losing control of an account, so nothing that was signed in stays signed in. +url: "{{base_url}}/{{namespace}}/drivers/reset-password" +method: POST + +body: + type: json + content: |- + { + "identity": "{{driver_email}}", + "code": "{{driver_password_reset_code}}", + "password": "{{driver_new_password}}" + } + +order: 13200 diff --git a/postman/collections/Fleetbase API/Manifests/.resources/definition.yaml b/postman/collections/Fleetbase API/Manifests/.resources/definition.yaml new file mode 100644 index 0000000..617546e --- /dev/null +++ b/postman/collections/Fleetbase API/Manifests/.resources/definition.yaml @@ -0,0 +1,6 @@ +$kind: collection +description: |- + A manifest is a driver's route: an order-agnostic sequence of stops which may span several orders, or none the driver has seen as an order. + + These endpoints are for the driver running the route. Creating, cancelling and deleting a manifest is dispatch work and is not part of the consumable API. +order: 8500 diff --git a/postman/collections/Fleetbase API/Manifests/.resources/object.yaml b/postman/collections/Fleetbase API/Manifests/.resources/object.yaml new file mode 100644 index 0000000..1a7ba5d --- /dev/null +++ b/postman/collections/Fleetbase API/Manifests/.resources/object.yaml @@ -0,0 +1,22 @@ +$kind: object +name: Manifest +description: |- + A route assigned to a driver for a day, made of ordered stops. +example: | + { + "id": "manifest_7KpQ2Rx9Vz", + "status": "in_progress", + "scheduled_date": "2026-08-23", + "started_at": "2026-08-23T07:12:04.000000Z", + "completed_at": null, + "total_distance_m": 41200, + "total_duration_s": 5400, + "stop_count": 8, + "completed_stops": 3, + "pending_stops": 5, + "driver_name": "Ron", + "vehicle_name": "EAS-01", + "notes": null, + "updated_at": "2026-08-23T09:02:00.000000Z", + "created_at": "2026-08-23T06:40:00.000000Z" + } diff --git a/postman/collections/Fleetbase API/Manifests/Optimize a Manifest.params.yaml b/postman/collections/Fleetbase API/Manifests/Optimize a Manifest.params.yaml new file mode 100644 index 0000000..8f30b0d --- /dev/null +++ b/postman/collections/Fleetbase API/Manifests/Optimize a Manifest.params.yaml @@ -0,0 +1,10 @@ +$kind: params +fields: + - name: latitude + type: number + required: false + description: The driver's current latitude. The walk starts here when both coordinates are given. + - name: longitude + type: number + required: false + description: The driver's current longitude. diff --git a/postman/collections/Fleetbase API/Manifests/Optimize a Manifest.request.yaml b/postman/collections/Fleetbase API/Manifests/Optimize a Manifest.request.yaml new file mode 100644 index 0000000..763b0a5 --- /dev/null +++ b/postman/collections/Fleetbase API/Manifests/Optimize a Manifest.request.yaml @@ -0,0 +1,28 @@ +$kind: http-request +name: "Optimize a Manifest" +description: |- + Re-sequences the stops a driver has not done yet, nearest first. + + This is the driver's optimise, not the orchestrator's. The orchestrator allocates orders across a fleet and produces manifests; this reorders the stops of one manifest that is already assigned. + + It is a nearest-neighbour walk over road distances: from the driver's position to the closest remaining stop, then the closest from there. That is usually a large improvement on an arbitrary order and is not guaranteed optimal. + + Completed and skipped stops keep their place — a route already driven is not re-planned. A manifest with fewer than three stops still to do is returned unchanged, since there is no ordering to find. + + Send `latitude` and `longitude` to start the walk from where the driver actually is. Without them it starts from the first stop still to do. +url: "{{base_url}}/{{namespace}}/manifests/:id/optimize" +method: POST +pathVariables: + - key: id + value: "{{manifest_id}}" + description: (Required) The manifest to re-sequence. + +body: + type: json + content: |- + { + "latitude": 1.3521, + "longitude": 103.8198 + } + +order: 2000 diff --git a/postman/collections/Fleetbase API/Manifests/Retrieve a Manifest.request.yaml b/postman/collections/Fleetbase API/Manifests/Retrieve a Manifest.request.yaml new file mode 100644 index 0000000..385a240 --- /dev/null +++ b/postman/collections/Fleetbase API/Manifests/Retrieve a Manifest.request.yaml @@ -0,0 +1,14 @@ +$kind: http-request +name: "Retrieve a Manifest" +description: |- + Retrieves a manifest with its stops, in the sequence they are to be driven. + + Each stop carries its place inline — a route of twenty stops is one request, not twenty-one — along with its status, estimated and actual arrival, and the distance and duration from the previous stop. +url: "{{base_url}}/{{namespace}}/manifests/:id" +method: GET +pathVariables: + - key: id + value: "{{manifest_id}}" + description: (Required) The manifest to retrieve. + +order: 1000 diff --git a/postman/collections/Fleetbase API/Manifests/Update a Manifest Stop.params.yaml b/postman/collections/Fleetbase API/Manifests/Update a Manifest Stop.params.yaml new file mode 100644 index 0000000..d5775bd --- /dev/null +++ b/postman/collections/Fleetbase API/Manifests/Update a Manifest Stop.params.yaml @@ -0,0 +1,10 @@ +$kind: params +fields: + - name: status + type: string + required: false + description: One of `arrived`, `completed` or `skipped`. Anything else is refused. + - name: meta + type: object + required: false + description: Arbitrary metadata to store against the stop, such as a note left on arrival. diff --git a/postman/collections/Fleetbase API/Manifests/Update a Manifest Stop.request.yaml b/postman/collections/Fleetbase API/Manifests/Update a Manifest Stop.request.yaml new file mode 100644 index 0000000..c126ce7 --- /dev/null +++ b/postman/collections/Fleetbase API/Manifests/Update a Manifest Stop.request.yaml @@ -0,0 +1,23 @@ +$kind: http-request +name: "Update a Manifest Stop" +description: |- + Marks a stop on a manifest as arrived, completed or skipped. + + Status changes run through the manifest's own transitions rather than writing a column, so arrival and completion timestamps are recorded and a manifest completes itself when its last stop does. + + Any other status is refused and changes nothing. +url: "{{base_url}}/{{namespace}}/manifest-stops/:id" +method: PATCH +pathVariables: + - key: id + value: "{{manifest_stop_id}}" + description: (Required) The stop to update. + +body: + type: json + content: |- + { + "status": "arrived" + } + +order: 3000