Polish API collection content for docs generation

.postman/resources.yaml

@@ -5,6 +5,8 @@ workspace:
 localResources:
   collections:
     - ../postman/collections/Fleetbase API
+    - ../postman/collections/Fleetbase Core API
+    - ../postman/collections/Fleetbase Ledger API
     - ../postman/collections/Fleetbase Storefront API
     - ../postman/collections/Fleetbase Integrated Vendor Flow
   environments:

README.md

@@ -14,15 +14,16 @@ Official Git-first Postman workspace for Fleetbase API collections and workflow
 
 | Collection | Path | Purpose |
 | --- | --- | --- |
-| Fleetbase API | `postman/collections/fleetbase-api.postman_collection.json` | Core Fleetbase platform API requests. |
-| Storefront API | `postman/collections/storefront-api.postman_collection.json` | Storefront and customer-facing commerce API requests. |
-| Ledger API | `collections/apis/ledger-api/collection.yaml` | Ledger, balances, accounts, and transaction API requests. |
-| Integrated Vendor | `postman/collections/integrated-vendor-flow.postman_collection.json` | End-to-end vendor integration workflow examples. |
+| Fleetbase API | `postman/collections/Fleetbase API` | FleetOps API and platform logistics requests. |
+| Fleetbase Core API | `postman/collections/Fleetbase Core API` | Core API requests shared across Fleetbase modules. |
+| Storefront API | `postman/collections/Fleetbase Storefront API` | Storefront and customer-facing commerce API requests. |
+| Ledger API | `postman/collections/Fleetbase Ledger API` | Public Ledger wallet, invoice payment, and gateway webhook requests. |
+| Integrated Vendor | `postman/collections/Fleetbase Integrated Vendor Flow` | End-to-end vendor integration workflow examples. |
 
 ## Getting Started
 
 1. Install the Postman CLI.
-2. Import one of the environment templates from `environments/`.
+2. Select one of the environments from `postman/environments/`.
 3. Fill local values in Postman or use Postman Vault for secrets.
 4. Run linting locally:
 
@@ -33,14 +34,14 @@ npm run postman:lint
 Run a collection with an environment template or local environment copy:
 
 ```sh
-npm run postman:run:fleetbase -- --environment postman/environments/local.postman_environment.json
+npm run postman:run:fleetbase -- --environment postman/environments/local.environment.yaml
 ```
 
 Workflow collections can also use iteration data:
 
 ```sh
 npm run postman:run:integrated-vendor -- \
-  --environment postman/environments/local.postman_environment.json \
+  --environment postman/environments/local.environment.yaml \
   --iteration-data collections/workflows/integrated-vendor/data/happy-path.example.json
 ```
 
@@ -50,10 +51,16 @@ Use collection or environment variables instead of hard-coded values:
 
 - `base_url`
 - `namespace`
+- `api_prefix`
 - `api_key`
 
+Collection-level `api_prefix` values handle package routing while keeping shared environments simple:
+
+- Storefront API uses `api_prefix=storefront`, producing `/storefront/{{namespace}}/...`.
+- Ledger API uses `api_prefix=ledger`, producing `/ledger/{{namespace}}/...` for wallet routes and `/ledger/public/...` or `/ledger/webhooks/...` for non-versioned public routes.
+
 Do not commit real tokens, keys, IDs, cookies, exported Vault data, or production credentials.
 
 ## Format
 
-The imported Fleetbase API, Storefront API, and Integrated Vendor Flow collections are currently Postman v2.1 JSON exports. They should remain normalized to snake_case variables. Future migrations to Postman v3 YAML should be generated from these canonical collection exports with Postman CLI.
+The source format for Local Mode is Postman v3 YAML / Native Git layout under `postman/`. JSON exports are treated as import/export artifacts only.

collections/apis/ledger-api/README.md

@@ -5,13 +5,14 @@ Reference collection for Fleetbase Ledger API requests.
 ## Variables
 
 - `base_url`
+- `namespace`
+- `api_prefix`
 - `api_key`
-- `ledger_account_id`
 
 ## Auth
 
 Requests inherit bearer token authentication from the collection. Store real API keys locally or in Postman Vault.
 
-## Starter Coverage
+## Coverage
 
-This collection starts with account and transaction placeholders for the ledger surface.
+The editable Postman Local Mode collection lives at `postman/collections/Fleetbase Ledger API`. It uses `api_prefix=ledger`, so wallet URLs resolve as `{{base_url}}/{{api_prefix}}/{{namespace}}/...`, while public invoice and webhook URLs resolve under `/ledger/public/...` and `/ledger/webhooks/...`.

collections/apis/ledger-api/collection.yaml

@@ -1,6 +1,7 @@
 type: collection
 name: Ledger API
 version: 1.0.0
+description: Legacy single-file placeholder. The editable Postman Local Mode collection lives at postman/collections/Fleetbase Ledger API.
 auth:
   type: bearer
   bearer:
@@ -10,18 +11,46 @@ auth:
 variables:
   - key: base_url
     value: "{{base_url}}"
-  - key: ledger_account_id
-    value: "{{ledger_account_id}}"
+  - key: namespace
+    value: "{{namespace}}"
+  - key: api_prefix
+    value: ledger
 items:
-  - name: Accounts
+  - name: Wallet
     items:
-      - name: Get Ledger Account
+      - name: Get Wallet
         request:
           method: GET
-          url: "{{base_url}}/ledger/accounts/{{ledger_account_id}}"
-  - name: Transactions
+          url: "{{base_url}}/{{api_prefix}}/{{namespace}}/wallet"
+      - name: Get Wallet Balance
+        request:
+          method: GET
+          url: "{{base_url}}/{{api_prefix}}/{{namespace}}/wallet/balance"
+      - name: List Wallet Transactions
+        request:
+          method: GET
+          url: "{{base_url}}/{{api_prefix}}/{{namespace}}/wallet/transactions"
+      - name: Top Up Wallet
+        request:
+          method: POST
+          url: "{{base_url}}/{{api_prefix}}/{{namespace}}/wallet/topup"
+  - name: Public Invoices
     items:
-      - name: List Transactions
+      - name: Get Public Invoice
         request:
           method: GET
-          url: "{{base_url}}/ledger/accounts/{{ledger_account_id}}/transactions"
+          url: "{{base_url}}/{{api_prefix}}/public/invoices/{{invoice_public_id}}"
+      - name: List Public Invoice Gateways
+        request:
+          method: GET
+          url: "{{base_url}}/{{api_prefix}}/public/invoices/{{invoice_public_id}}/gateways"
+      - name: Pay Public Invoice
+        request:
+          method: POST
+          url: "{{base_url}}/{{api_prefix}}/public/invoices/{{invoice_public_id}}/pay"
+  - name: Webhooks
+    items:
+      - name: Handle Gateway Webhook
+        request:
+          method: POST
+          url: "{{base_url}}/{{api_prefix}}/webhooks/{{gateway_driver}}"

collections/apis/storefront-api/README.md

@@ -6,6 +6,7 @@ Reference collection for Fleetbase Storefront API requests.
 
 - `base_url`
 - `namespace`
+- `api_prefix`
 - `api_key`
 
 ## Auth
@@ -14,4 +15,4 @@ Requests inherit bearer token authentication from the collection. Set `api_key`
 
 ## Coverage
 
-This collection is based on the exported Fleetbase Storefront API Postman collection and uses `{{base_url}}/{{namespace}}` for request URLs.
+The editable Postman Local Mode collection lives at `postman/collections/Fleetbase Storefront API`. It uses `api_prefix=storefront`, so versioned request URLs resolve as `{{base_url}}/{{api_prefix}}/{{namespace}}/...`.

package.json

@@ -6,10 +6,11 @@
   "scripts": {
     "postman:lint": "./scripts/lint-collections.sh",
     "postman:run": "./scripts/run-collection.sh",
-    "postman:run:fleetbase": "./scripts/run-collection.sh postman/collections/fleetbase-api.postman_collection.json",
-    "postman:run:storefront": "./scripts/run-collection.sh postman/collections/storefront-api.postman_collection.json",
-    "postman:run:ledger": "./scripts/run-collection.sh collections/apis/ledger-api/collection.yaml",
-    "postman:run:integrated-vendor": "./scripts/run-collection.sh postman/collections/integrated-vendor-flow.postman_collection.json"
+    "postman:run:fleetbase": "./scripts/run-collection.sh postman/collections/Fleetbase API",
+    "postman:run:core": "./scripts/run-collection.sh postman/collections/Fleetbase Core API",
+    "postman:run:storefront": "./scripts/run-collection.sh postman/collections/Fleetbase Storefront API",
+    "postman:run:ledger": "./scripts/run-collection.sh postman/collections/Fleetbase Ledger API",
+    "postman:run:integrated-vendor": "./scripts/run-collection.sh postman/collections/Fleetbase Integrated Vendor Flow"
   },
   "keywords": [
     "fleetbase",

postman.config.json

@@ -1,8 +1,8 @@
 {
-  "collectionFormat": "postman-v2.1-json",
+  "collectionFormat": "postman-v3-yaml-native-git",
   "collectionsRoot": "postman/collections",
   "environmentsRoot": "postman/environments",
-  "defaultEnvironment": "postman/environments/local.postman_environment.json",
+  "defaultEnvironment": "postman/environments/local.environment.yaml",
   "secretPolicy": {
     "commitTemplatesOnly": true,
     "usePostmanVaultForSecrets": true

postman/collections/Fleetbase API/Contacts/Create a Contact.params.yaml

@@ -0,0 +1,19 @@
+$kind: params
+fields:
+  - name: name
+    type: string
+    required: true
+    description: "Display name for the resource."
+  - name: type
+    type: enum
+    values: ["customer", "vendor", "driver"]
+    description: "Classification used to group or process the resource."
+  - name: title
+    type: string
+    description: "Optional title associated with the contact or person."
+  - name: email
+    type: string
+    description: "Email address for the person or customer."
+  - name: phone
+    type: string
+    description: "Phone number for the person or customer."

postman/collections/Fleetbase API/Contacts/Query Contacts.queryParams.yaml

@@ -0,0 +1,14 @@
+$kind: params
+fields:
+  - name: query
+    type: string
+    description: "Query value for this contacts request."
+  - name: limit
+    type: string
+    description: "Limit value for this contacts request."
+  - name: offset
+    type: string
+    description: "Offset value for this contacts request."
+  - name: sort
+    type: string
+    description: "Sort value for this contacts request."

postman/collections/Fleetbase API/Contacts/Query Contacts.request.yaml

@@ -1,21 +1,14 @@
 $kind: http-request
-description: Returns a list of your contacts. The contacts are returned sorted by creation date, with the most recent customers appearing first.
-url: "{{base_url}}/{{namespace}}/contacts?query={{contact_name}}&limit=25&offset=0&sort=created_at"
+description: |-
+  Returns a paginated list of contacts for the current organization. Use filters such as `query`, `limit`, `offset`, and `sort` to narrow and order the results.
+url: "{{base_url}}/{{namespace}}/contacts"
 method: GET
 headers:
   Accept: application/json
-queryParams:
-  - key: query
-    value: "{{contact_name}}"
-    description: This parameter allows you to filter the results by their name.
-  - key: limit
-    value: "25"
-    description: A cursor for use in pagination. A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
-  - key: offset
-    value: "0"
-    description: A cursor for use in pagination. A offset for the results, when the offset is supplied the results will start from the offset.
-  - key: sort
-    value: created_at
-    description: A cursor used to sort results. Sort can be any property of the object, to sort descending sort must append the minus symbol. To sort by created date descending sort would be `-created_at` to sort in ascending order the sort would be `created_at`.
 examples: ./.resources/Query Contacts.resources/examples
+queryParams:
+  query: "{{contact_name}}"
+  limit: "25"
+  offset: "0"
+  sort: "created_at"
 order: 2000

postman/collections/Fleetbase API/Contacts/Update a Contact.params.yaml

@@ -0,0 +1,21 @@
+$kind: params
+fields:
+  - name: name
+    type: string
+    description: "Display name for the resource."
+  - name: title
+    type: string
+    description: "Optional title associated with the contact or person."
+  - name: email
+    type: string
+    description: "Email address for the person or customer."
+  - name: phone
+    type: string
+    description: "Phone number for the person or customer."
+  - name: type
+    type: enum
+    values: ["customer", "vendor", "driver"]
+    description: "Classification used to group or process the resource."
+  - name: slug
+    type: string
+    description: "URL-friendly identifier for the resource."

postman/collections/Fleetbase API/Drivers/Create a Driver.params.yaml

@@ -0,0 +1,16 @@
+$kind: params
+fields:
+  - name: name
+    type: string
+    required: true
+    description: "Display name for the resource."
+  - name: description
+    type: string
+    description: "Human-readable description of the resource."
+  - name: status
+    type: enum
+    values: ["active", "inactive"]
+    description: "Lifecycle status to apply to the resource."
+  - name: meta
+    type: string
+    description: "Arbitrary metadata stored with the resource."

postman/collections/Fleetbase API/Drivers/Get Driver Current Organization.request.yaml

@@ -0,0 +1,10 @@
+$kind: http-request
+name: "Get Driver Current Organization"
+description: "Returns the driver current organization."
+url: "{{base_url}}/{{namespace}}/drivers/:id/current-organization"
+method: GET
+pathVariables:
+  - key: id
+    value: "{{driver_id}}"
+
+order: 12800

postman/collections/Fleetbase API/Drivers/List Driver Organizations.request.yaml

@@ -0,0 +1,10 @@
+$kind: http-request
+name: "List Driver Organizations"
+description: "Lists organizations a driver belongs to."
+url: "{{base_url}}/{{namespace}}/drivers/:id/organizations"
+method: GET
+pathVariables:
+  - key: id
+    value: "{{driver_id}}"
+
+order: 12700

postman/collections/Fleetbase API/Drivers/Login Driver.request.yaml

@@ -0,0 +1,14 @@
+$kind: http-request
+name: "Login Driver"
+description: "Authenticates a driver with email/phone and password."
+url: "{{base_url}}/{{namespace}}/drivers/login"
+method: POST
+body:
+  type: json
+  content: |-
+    {
+      "identity": "{{driver_identity}}",
+      "password": "{{driver_password}}"
+    }
+
+order: 12000

postman/collections/Fleetbase API/Drivers/Query Drivers.request.yaml

@@ -1,12 +1,10 @@
 $kind: http-request
 description: This endpoint allows you to retrieve a driver object to view it's details.
-url: "{{base_url}}/{{namespace}}/drivers?id={{driver_id}}"
+url: "{{base_url}}/{{namespace}}/drivers"
 method: GET
 headers:
   Accept: application/json
-queryParams:
-  - key: id
-    value: "{{driver_id}}"
-    description: The id of the driver you want to retrieve.
 examples: ./.resources/Query Drivers.resources/examples
+queryParams:
+  id: "{{driver_id}}"
 order: 2000

postman/collections/Fleetbase API/Drivers/Register Device.request.yaml

@@ -0,0 +1,14 @@
+$kind: http-request
+name: "Register Device"
+description: "Registers a driver device token through the non-id route."
+url: "{{base_url}}/{{namespace}}/drivers/register-device"
+method: POST
+body:
+  type: json
+  content: |-
+    {
+      "token": "{{device_token}}",
+      "platform": "ios"
+    }
+
+order: 12400

postman/collections/Fleetbase API/Drivers/Register Driver Device.request.yaml

@@ -0,0 +1,18 @@
+$kind: http-request
+name: "Register Driver Device"
+description: "Registers a device token for a specific driver."
+url: "{{base_url}}/{{namespace}}/drivers/:id/register-device"
+method: POST
+pathVariables:
+  - key: id
+    value: "{{driver_id}}"
+
+body:
+  type: json
+  content: |-
+    {
+      "token": "{{device_token}}",
+      "platform": "ios"
+    }
+
+order: 12300

postman/collections/Fleetbase API/Drivers/Request Driver Login SMS.request.yaml

@@ -0,0 +1,13 @@
+$kind: http-request
+name: "Request Driver Login SMS"
+description: "Starts driver SMS verification login."
+url: "{{base_url}}/{{namespace}}/drivers/login-with-sms"
+method: POST
+body:
+  type: json
+  content: |-
+    {
+      "phone": "{{driver_phone}}"
+    }
+
+order: 12100