From 5678c7e7dea19df2d510691a09784f014b0aeaa9 Mon Sep 17 00:00:00 2001 From: "Ronald A. Richardson" Date: Sun, 17 May 2026 11:10:03 +0800 Subject: [PATCH] Document orchestrator consumable API --- .../examples/OK.example.yaml | 38 ++++++++++ ...Multi-phase Prior Assignments.example.yaml | 50 ++++++++++++++ .../Native Capacity Allocation.example.yaml | 69 +++++++++++++++++++ ...Single-phase VROOM Allocation.example.yaml | 63 +++++++++++++++++ ...ROOM Capacity Only Allocation.example.yaml | 61 ++++++++++++++++ .../Orchestrator/.resources/definition.yaml | 8 +++ .../Commit Orchestrator Plan.params.yaml | 33 +++++++++ .../Commit Orchestrator Plan.request.yaml | 29 ++++++++ .../Orchestrator/Run Orchestrator.params.yaml | 58 ++++++++++++++++ .../Run Orchestrator.request.yaml | 44 ++++++++++++ 10 files changed, 453 insertions(+) create mode 100644 postman/collections/Fleetbase API/Orchestrator/.resources/Commit Orchestrator Plan.resources/examples/OK.example.yaml create mode 100644 postman/collections/Fleetbase API/Orchestrator/.resources/Run Orchestrator.resources/examples/Multi-phase Prior Assignments.example.yaml create mode 100644 postman/collections/Fleetbase API/Orchestrator/.resources/Run Orchestrator.resources/examples/Native Capacity Allocation.example.yaml create mode 100644 postman/collections/Fleetbase API/Orchestrator/.resources/Run Orchestrator.resources/examples/Single-phase VROOM Allocation.example.yaml create mode 100644 postman/collections/Fleetbase API/Orchestrator/.resources/Run Orchestrator.resources/examples/VROOM Capacity Only Allocation.example.yaml create mode 100644 postman/collections/Fleetbase API/Orchestrator/.resources/definition.yaml create mode 100644 postman/collections/Fleetbase API/Orchestrator/Commit Orchestrator Plan.params.yaml create mode 100644 postman/collections/Fleetbase API/Orchestrator/Commit Orchestrator Plan.request.yaml create mode 100644 postman/collections/Fleetbase API/Orchestrator/Run Orchestrator.params.yaml create mode 100644 postman/collections/Fleetbase API/Orchestrator/Run Orchestrator.request.yaml diff --git a/postman/collections/Fleetbase API/Orchestrator/.resources/Commit Orchestrator Plan.resources/examples/OK.example.yaml b/postman/collections/Fleetbase API/Orchestrator/.resources/Commit Orchestrator Plan.resources/examples/OK.example.yaml new file mode 100644 index 0000000..239360a --- /dev/null +++ b/postman/collections/Fleetbase API/Orchestrator/.resources/Commit Orchestrator Plan.resources/examples/OK.example.yaml @@ -0,0 +1,38 @@ +$kind: http-example +request: + url: "{{base_url}}/{{namespace}}/orchestrator/commit" + method: POST + headers: + Content-Type: application/json + Accept: application/json + body: + type: json + content: |- + { + "scheduled_date": "2026-05-16", + "assignments": [ + { + "order_id": "order_7YqM3KpL2n", + "vehicle_id": "vehicle_Q1w2E3r4T5", + "driver_id": "driver_A1b2C3d4E5", + "sequence": 1, + "arrival": 1778918400, + "duration": 900, + "distance": 4200 + } + ] + } +response: + statusCode: 200 + statusText: OK + headers: + Content-Type: application/json + body: + type: json + content: |- + { + "committed": ["order_7YqM3KpL2n"], + "failed": [], + "manifests": ["manifest_P9qR8sT7uV"] + } +order: 1000 diff --git a/postman/collections/Fleetbase API/Orchestrator/.resources/Run Orchestrator.resources/examples/Multi-phase Prior Assignments.example.yaml b/postman/collections/Fleetbase API/Orchestrator/.resources/Run Orchestrator.resources/examples/Multi-phase Prior Assignments.example.yaml new file mode 100644 index 0000000..fb383e9 --- /dev/null +++ b/postman/collections/Fleetbase API/Orchestrator/.resources/Run Orchestrator.resources/examples/Multi-phase Prior Assignments.example.yaml @@ -0,0 +1,50 @@ +$kind: http-example +request: + url: "{{base_url}}/{{namespace}}/orchestrator/run" + method: POST + headers: + Content-Type: application/json + Accept: application/json + body: + type: json + content: |- + { + "mode": "assign_drivers", + "order_ids": ["order_7YqM3KpL2n"], + "vehicle_ids": ["vehicle_Q1w2E3r4T5"], + "prior_assignments": [ + { + "order_id": "order_7YqM3KpL2n", + "vehicle_id": "vehicle_Q1w2E3r4T5", + "sequence": 1 + } + ], + "options": { + "respect_skills": true, + "require_active_shift": false + } + } +response: + statusCode: 200 + statusText: OK + headers: + Content-Type: application/json + body: + type: json + content: |- + { + "assignments": [ + { + "order_id": "order_7YqM3KpL2n", + "vehicle_id": "vehicle_Q1w2E3r4T5", + "driver_id": "driver_A1b2C3d4E5", + "sequence": null + } + ], + "unassigned": [], + "summary": { + "drivers_assigned": 1, + "vehicles_assigned": 0 + } + } +order: 2000 diff --git a/postman/collections/Fleetbase API/Orchestrator/.resources/Run Orchestrator.resources/examples/Native Capacity Allocation.example.yaml b/postman/collections/Fleetbase API/Orchestrator/.resources/Run Orchestrator.resources/examples/Native Capacity Allocation.example.yaml new file mode 100644 index 0000000..411f224 --- /dev/null +++ b/postman/collections/Fleetbase API/Orchestrator/.resources/Run Orchestrator.resources/examples/Native Capacity Allocation.example.yaml @@ -0,0 +1,69 @@ +$kind: http-example +request: + url: "{{base_url}}/{{namespace}}/orchestrator/run" + method: POST + headers: + Content-Type: application/json + Accept: application/json + body: + type: json + content: |- + { + "mode": "assign_vehicles", + "order_ids": ["order_heavy_01", "order_cold_02", "order_oversized_04"], + "vehicle_ids": ["vehicle_capacity_truck_01", "vehicle_cold_van_01"], + "prior_assignments": [], + "options": { + "engine": "capacity", + "respect_capacity": true, + "respect_skills": true, + "balance_workload": false + } + } +response: + statusCode: 200 + statusText: OK + headers: + Content-Type: application/json + body: + type: json + content: |- + { + "assignments": [ + { + "order_id": "order_heavy_01", + "vehicle_id": "vehicle_capacity_truck_01", + "driver_id": null, + "sequence": 1, + "arrival": null, + "duration": null, + "distance": null + }, + { + "order_id": "order_cold_02", + "vehicle_id": "vehicle_cold_van_01", + "driver_id": null, + "sequence": 1, + "arrival": null, + "duration": null, + "distance": null + } + ], + "unassigned": ["order_oversized_04"], + "summary": { + "engine": "capacity", + "allocation_strategy": "capacity_only", + "assigned": 2, + "unassigned": 1, + "unassigned_reasons": [ + { + "order_id": "order_oversized_04", + "reason": "capacity_exceeded" + } + ], + "respect_capacity": true, + "respect_skills": true, + "balance_workload": false + } + } +order: 1200 diff --git a/postman/collections/Fleetbase API/Orchestrator/.resources/Run Orchestrator.resources/examples/Single-phase VROOM Allocation.example.yaml b/postman/collections/Fleetbase API/Orchestrator/.resources/Run Orchestrator.resources/examples/Single-phase VROOM Allocation.example.yaml new file mode 100644 index 0000000..9027345 --- /dev/null +++ b/postman/collections/Fleetbase API/Orchestrator/.resources/Run Orchestrator.resources/examples/Single-phase VROOM Allocation.example.yaml @@ -0,0 +1,63 @@ +$kind: http-example +request: + url: "{{base_url}}/{{namespace}}/orchestrator/run" + method: POST + headers: + Content-Type: application/json + Accept: application/json + body: + type: json + content: |- + { + "mode": "assign_vehicles", + "order_ids": ["order_7YqM3KpL2n", "order_8AkN4LqP9x"], + "vehicle_ids": ["vehicle_Q1w2E3r4T5", "vehicle_A9s8D7f6G5"], + "options": { + "engine": "vroom", + "allocation_strategy": "route_aware", + "geometry": false, + "respect_capacity": true, + "respect_skills": true + } + } +response: + statusCode: 200 + statusText: OK + headers: + Content-Type: application/json + body: + type: json + content: |- + { + "assignments": [ + { + "order_id": "order_7YqM3KpL2n", + "vehicle_id": "vehicle_Q1w2E3r4T5", + "driver_id": null, + "sequence": 1, + "arrival": 1778918400, + "duration": 900, + "distance": 4200 + }, + { + "order_id": "order_8AkN4LqP9x", + "vehicle_id": "vehicle_A9s8D7f6G5", + "driver_id": null, + "sequence": 1, + "arrival": 1778919300, + "duration": 780, + "distance": 3600 + } + ], + "unassigned": [], + "summary": { + "engine": "vroom", + "allocation_strategy": "route_aware", + "cost": 7800, + "routes": 2, + "unassigned": 0, + "duration": 1680, + "distance": 7800 + } + } +order: 1000 diff --git a/postman/collections/Fleetbase API/Orchestrator/.resources/Run Orchestrator.resources/examples/VROOM Capacity Only Allocation.example.yaml b/postman/collections/Fleetbase API/Orchestrator/.resources/Run Orchestrator.resources/examples/VROOM Capacity Only Allocation.example.yaml new file mode 100644 index 0000000..8193089 --- /dev/null +++ b/postman/collections/Fleetbase API/Orchestrator/.resources/Run Orchestrator.resources/examples/VROOM Capacity Only Allocation.example.yaml @@ -0,0 +1,61 @@ +$kind: http-example +request: + url: "{{base_url}}/{{namespace}}/orchestrator/run" + method: POST + headers: + Content-Type: application/json + Accept: application/json + body: + type: json + content: |- + { + "mode": "assign_vehicles", + "order_ids": ["order_heavy_01", "order_cold_02", "order_parcel_03"], + "vehicle_ids": ["vehicle_capacity_truck_01", "vehicle_cold_van_01"], + "prior_assignments": [], + "options": { + "engine": "vroom", + "allocation_strategy": "capacity_only", + "respect_capacity": true, + "respect_skills": true, + "balance_workload": true + } + } +response: + statusCode: 200 + statusText: OK + headers: + Content-Type: application/json + body: + type: json + content: |- + { + "assignments": [ + { + "order_id": "order_heavy_01", + "vehicle_id": "vehicle_capacity_truck_01", + "driver_id": null, + "sequence": 1, + "arrival": 0, + "duration": 0, + "distance": 0 + }, + { + "order_id": "order_cold_02", + "vehicle_id": "vehicle_cold_van_01", + "driver_id": null, + "sequence": 1, + "arrival": 0, + "duration": 0, + "distance": 0 + } + ], + "unassigned": ["order_parcel_03"], + "summary": { + "engine": "vroom", + "allocation_strategy": "capacity_only", + "routes": 2, + "unassigned": 1 + } + } +order: 1100 diff --git a/postman/collections/Fleetbase API/Orchestrator/.resources/definition.yaml b/postman/collections/Fleetbase API/Orchestrator/.resources/definition.yaml new file mode 100644 index 0000000..9595480 --- /dev/null +++ b/postman/collections/Fleetbase API/Orchestrator/.resources/definition.yaml @@ -0,0 +1,8 @@ +$kind: collection +description: |- + Orchestrator endpoints generate and commit FleetOps resource assignment plans. All resource identifiers accepted and returned by the consumable API are public IDs. + + `POST /orchestrator/run` supports route-aware VROOM allocation, VROOM capacity-only allocation, native Fleetbase capacity-only allocation, driver assignment, route optimization, and multi-phase prior-assignment flows. + + Capacity-only allocation is for clients who need to answer which vehicles can carry selected orders by weight, volume, pallet count, parcel count, skills, and task limits without relying on vehicle GPS positions. +order: 8500 diff --git a/postman/collections/Fleetbase API/Orchestrator/Commit Orchestrator Plan.params.yaml b/postman/collections/Fleetbase API/Orchestrator/Commit Orchestrator Plan.params.yaml new file mode 100644 index 0000000..a3c7b59 --- /dev/null +++ b/postman/collections/Fleetbase API/Orchestrator/Commit Orchestrator Plan.params.yaml @@ -0,0 +1,33 @@ +$kind: params +fields: + - name: scheduled_date + type: date + description: Manifest scheduled date. Defaults to the current date when omitted. + - name: assignments + type: array of objects + description: Proposed assignment records to commit. All IDs are public resource IDs. + fields: + - name: order_id + type: string + description: Public order ID. + - name: vehicle_id + type: string + description: Public vehicle ID. + - name: driver_id + type: string + description: Public driver ID, when a driver is assigned. + - name: sequence + type: integer + description: Stop sequence for the order within the vehicle route. + - name: arrival + type: integer + description: Estimated arrival time as a Unix timestamp. + - name: duration + type: integer + description: Duration from the previous stop in seconds. + - name: distance + type: integer + description: Distance from the previous stop in meters. + - name: waypoint_sequence + type: array of strings + description: Optional ordered waypoint public IDs for multi-stop route updates. diff --git a/postman/collections/Fleetbase API/Orchestrator/Commit Orchestrator Plan.request.yaml b/postman/collections/Fleetbase API/Orchestrator/Commit Orchestrator Plan.request.yaml new file mode 100644 index 0000000..93ba20f --- /dev/null +++ b/postman/collections/Fleetbase API/Orchestrator/Commit Orchestrator Plan.request.yaml @@ -0,0 +1,29 @@ +$kind: http-request +description: |- + Commits a proposed orchestrator plan by creating manifests and applying vehicle and driver assignments to orders. Assignment records must use public resource IDs. + + This endpoint is engine-agnostic: commit the `assignments` returned by route-aware VROOM, VROOM capacity-only, native capacity-only, or multi-phase orchestration runs. Do not submit internal UUIDs or database IDs. +url: "{{base_url}}/{{namespace}}/orchestrator/commit" +method: POST +headers: + Content-Type: application/json + Accept: application/json +body: + type: json + content: | + { + "scheduled_date": "2026-05-16", + "assignments": [ + { + "order_id": "{{order_id}}", + "vehicle_id": "{{vehicle_id}}", + "driver_id": "{{driver_id}}", + "sequence": 1, + "arrival": 1778918400, + "duration": 900, + "distance": 4200 + } + ] + } +examples: ./.resources/Commit Orchestrator Plan.resources/examples +order: 2000 diff --git a/postman/collections/Fleetbase API/Orchestrator/Run Orchestrator.params.yaml b/postman/collections/Fleetbase API/Orchestrator/Run Orchestrator.params.yaml new file mode 100644 index 0000000..4d471e2 --- /dev/null +++ b/postman/collections/Fleetbase API/Orchestrator/Run Orchestrator.params.yaml @@ -0,0 +1,58 @@ +$kind: params +fields: + - name: mode + type: string + description: Orchestration phase to run. Supported values include `assign_vehicles`, `assign_drivers`, `optimize_routes`, and `allocate`. + - name: order_ids + type: array of strings + description: Public order IDs to include. When omitted, Fleetbase selects eligible orders for the requested mode. + - name: vehicle_ids + type: array of strings + description: Public vehicle IDs to include. + - name: driver_ids + type: array of strings + description: Public driver IDs used to filter eligible vehicle/driver resources. + - name: prior_assignments + type: array of objects + description: Public-ID assignment records from earlier orchestration phases that have not been committed yet. + fields: + - name: order_id + type: string + description: Public order ID. + - name: vehicle_id + type: string + description: Public vehicle ID. + - name: driver_id + type: string + description: Public driver ID, when assigned. + - name: sequence + type: integer + description: Proposed route sequence from the prior phase. + - name: options + type: object + description: Engine and constraint options for this run. Unknown options are ignored by engines that do not use them. + fields: + - name: engine + type: string + description: Optional engine identifier. Use `vroom` for VROOM, `capacity` for Fleetbase's built-in capacity-only engine, or `greedy` for the built-in nearest-vehicle engine. + - name: allocation_strategy + type: string + description: Allocation strategy for engines that support multiple modes. Use `route_aware` for normal route-aware VROOM allocation, or `capacity_only` with `engine: vroom` to run VROOM with a synthetic matrix and no vehicle locations. + - name: geometry + type: boolean + description: Whether supported engines should request route geometry. + - name: respect_capacity + type: boolean + description: Whether capacity constraints should be respected by supported engines. Capacity is evaluated as `[weight_kg, volume_litres, pallets, parcels]`. + - name: respect_skills + type: boolean + description: Whether skill constraints should be respected by supported engines. + - name: max_tasks + type: integer + description: Optional task limit per vehicle when supported by the selected engine or vehicle configuration. + - name: balance_workload + type: boolean + description: When supported, distributes orders across eligible vehicles instead of packing the first feasible vehicles. + - name: return_to_depot + type: boolean + description: Whether supported route-aware engines should plan routes returning to the vehicle depot. This is ignored by capacity-only allocation. diff --git a/postman/collections/Fleetbase API/Orchestrator/Run Orchestrator.request.yaml b/postman/collections/Fleetbase API/Orchestrator/Run Orchestrator.request.yaml new file mode 100644 index 0000000..84a46c6 --- /dev/null +++ b/postman/collections/Fleetbase API/Orchestrator/Run Orchestrator.request.yaml @@ -0,0 +1,44 @@ +$kind: http-request +description: |- + Runs an orchestration phase and returns a proposed assignment plan without committing changes. Use `options.engine` to force an engine such as `vroom`, `capacity`, or `greedy`; otherwise Fleetbase uses the orchestrator engine configured in admin settings. + + For normal route-aware VROOM allocation, send `options.engine: "vroom"` and omit `allocation_strategy` or set it to `route_aware`. Vehicles must have usable positions because VROOM will solve against route coordinates. + + For capacity-only VROOM allocation, send `options.engine: "vroom"` and `options.allocation_strategy: "capacity_only"`. This mode answers which vehicles can carry the selected orders by weight, volume, pallets, parcels, skills, and task limits without requiring vehicle locations. + + For Fleetbase's deterministic built-in capacity allocation, send `options.engine: "capacity"`. This native engine is useful as a fallback and debugging baseline for capacity-only allocation without VROOM. + + The consumable API accepts and returns public IDs only. Use `order_ids`, `vehicle_ids`, `driver_ids`, `prior_assignments.*_id`, and response `*_id` values as public IDs. Do not submit internal UUIDs. +url: "{{base_url}}/{{namespace}}/orchestrator/run" +method: POST +headers: + Content-Type: application/json + Accept: application/json +body: + type: json + content: | + { + "mode": "assign_vehicles", + "order_ids": ["{{order_id}}"], + "vehicle_ids": ["{{vehicle_id}}"], + "driver_ids": [], + "prior_assignments": [], + "options": { + "engine": "vroom", + "allocation_strategy": "route_aware", + "geometry": false, + "respect_capacity": true, + "respect_skills": true, + "return_to_depot": false + } + } +scripts: + - type: afterResponse + code: |- + const json = pm.response.json(); + if (Array.isArray(json.assignments) && json.assignments.length) { + pm.environment.set("orchestrator_assignments", JSON.stringify(json.assignments)); + } + language: text/javascript +examples: ./.resources/Run Orchestrator.resources/examples +order: 1000