From 7bd65a03773d4959c2aa594ab6648663defa0cbd Mon Sep 17 00:00:00 2001 From: "Ronald A. Richardson" Date: Tue, 11 Aug 2026 23:33:00 +0800 Subject: [PATCH 1/2] docs: document marketplace API contracts --- collections/apis/storefront-api/README.md | 13 ++++++ .../Cart/Add Item to Cart.params.yaml | 2 +- .../Category/List categories.queryParams.yaml | 17 ++++++++ .../Category/List categories.request.yaml | 8 +++- .../Before \342\235\227.queryParams.yaml" | 4 +- ...rvice Quote \342\235\227.queryParams.yaml" | 4 +- .../Products/Query Products.queryParams.yaml | 19 ++++++++- .../Products/Query Products.request.yaml | 7 +++- .../Query Store Locations.queryParams.yaml | 29 +++++++++++++ .../Query Store Locations.request.yaml | 12 +++++- .../List Network Stores.queryParams.yaml | 41 +++++++++++++++---- .../Store/List Network Stores.request.yaml | 14 ++++++- scripts/lint-collections.sh | 7 +--- 13 files changed, 152 insertions(+), 25 deletions(-) create mode 100644 postman/collections/Fleetbase Storefront API/Category/List categories.queryParams.yaml create mode 100644 postman/collections/Fleetbase Storefront API/Store Locations/Query Store Locations.queryParams.yaml diff --git a/collections/apis/storefront-api/README.md b/collections/apis/storefront-api/README.md index 4e427f1..fc71173 100644 --- a/collections/apis/storefront-api/README.md +++ b/collections/apis/storefront-api/README.md @@ -16,3 +16,16 @@ Requests inherit bearer token authentication from the collection. Set `api_key` ## Coverage 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}}/...`. + +## Marketplace network keys + +Use a `network_...` Storefront API key to browse a marketplace. The same public routes are used for both editions, but the key determines the owner and access scope: + +- `GET /about` returns the network owner for a network key and the store owner for a store key. +- `GET /stores`, `GET /store-locations`, and `GET /tags` are marketplace network resources. +- Categories can represent the network's member-store taxonomy or, with `store`, a member store's product taxonomy. +- Products, reviews, stores, and locations are limited to active network membership; unavailable or foreign resources return the endpoint's normal not-found or validation response. +- Each cart line records its `store_id` and `store_location_id`. Multi-store checkout is accepted only when the network enables `multi_cart_enabled`; mixed currencies are rejected. +- A `Customer-Token` is authoritative at checkout. A conflicting `customer` parameter returns `403` instead of checking out as another customer. + +The collection deliberately uses placeholders and local environment variables. Do not save real network keys or customer tokens in collection files. diff --git a/postman/collections/Fleetbase Storefront API/Cart/Add Item to Cart.params.yaml b/postman/collections/Fleetbase Storefront API/Cart/Add Item to Cart.params.yaml index beaeb0d..e146a47 100644 --- a/postman/collections/Fleetbase Storefront API/Cart/Add Item to Cart.params.yaml +++ b/postman/collections/Fleetbase Storefront API/Cart/Add Item to Cart.params.yaml @@ -14,4 +14,4 @@ fields: description: "Scheduled fulfillment time for the line item." - name: store_location type: string - description: "Public ID of the store location to associate with the line item." + description: "Public ID of a location belonging to the product's store. Marketplace carts reject cross-store location substitution." diff --git a/postman/collections/Fleetbase Storefront API/Category/List categories.queryParams.yaml b/postman/collections/Fleetbase Storefront API/Category/List categories.queryParams.yaml new file mode 100644 index 0000000..b7616ac --- /dev/null +++ b/postman/collections/Fleetbase Storefront API/Category/List categories.queryParams.yaml @@ -0,0 +1,17 @@ +$kind: params +fields: + - name: store + type: string + description: "Marketplace member store public ID whose product categories should be returned." + - name: parent + type: string + description: "Parent category public ID used to return its direct children." + - name: parents_only + type: boolean + description: "Return only top-level categories." + - name: with_products + type: boolean + description: "Include published, available products for each returned store product category." + - name: with_stores + type: boolean + description: "For marketplace categories, include member stores assigned to each category." diff --git a/postman/collections/Fleetbase Storefront API/Category/List categories.request.yaml b/postman/collections/Fleetbase Storefront API/Category/List categories.request.yaml index d6e0d3d..aedf9fd 100644 --- a/postman/collections/Fleetbase Storefront API/Category/List categories.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Category/List categories.request.yaml @@ -1,6 +1,12 @@ $kind: http-request description: |- - Returns product categories available to the current storefront. Use this list to organize product browsing and filtering. + Returns product categories for a store key, marketplace categories for a network key, or product categories for a selected marketplace member store. Category and product expansion remains scoped to the authenticated storefront owner. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/categories" method: GET +queryParams: + store: "" + parent: "" + parents_only: "" + with_products: "" + with_stores: "" order: 1000 diff --git "a/postman/collections/Fleetbase Storefront API/Checkout/Before \342\235\227.queryParams.yaml" "b/postman/collections/Fleetbase Storefront API/Checkout/Before \342\235\227.queryParams.yaml" index 3a70ca9..fe98371 100644 --- "a/postman/collections/Fleetbase Storefront API/Checkout/Before \342\235\227.queryParams.yaml" +++ "b/postman/collections/Fleetbase Storefront API/Checkout/Before \342\235\227.queryParams.yaml" @@ -5,10 +5,10 @@ fields: description: "Payment gateway ID or code." - name: customer type: string - description: "Customer ID associated with the request." + description: "Customer public ID for guest checkout. When Customer-Token is present this value must identify the authenticated customer or checkout returns 403." - name: cart type: string - description: "Cart value for this checkout request." + description: "Cart public ID or unique identifier. Marketplace checkout validates member stores, online state, products, locations, currency consistency, and the network multi-cart policy before payment initialization." - name: service_quote type: string description: "Service quote ID used by the request." diff --git "a/postman/collections/Fleetbase Storefront API/Delivery Service Quote/Retrieve a Delivery Service Quote \342\235\227.queryParams.yaml" "b/postman/collections/Fleetbase Storefront API/Delivery Service Quote/Retrieve a Delivery Service Quote \342\235\227.queryParams.yaml" index 12df804..69208dc 100644 --- "a/postman/collections/Fleetbase Storefront API/Delivery Service Quote/Retrieve a Delivery Service Quote \342\235\227.queryParams.yaml" +++ "b/postman/collections/Fleetbase Storefront API/Delivery Service Quote/Retrieve a Delivery Service Quote \342\235\227.queryParams.yaml" @@ -2,10 +2,10 @@ $kind: params fields: - name: origin type: string - description: "Origin value for this delivery service quote request." + description: "Fallback store-location public ID, or comma-separated IDs for a multi-store cart. Cart line-item locations take precedence." - name: destination type: string description: "Destination value for this delivery service quote request." - name: cart type: string - description: "Cart value for this delivery service quote request." + description: "Cart public ID or unique identifier. Marketplace origins must belong to the corresponding member stores." diff --git a/postman/collections/Fleetbase Storefront API/Products/Query Products.queryParams.yaml b/postman/collections/Fleetbase Storefront API/Products/Query Products.queryParams.yaml index 280f1bd..b7d083e 100644 --- a/postman/collections/Fleetbase Storefront API/Products/Query Products.queryParams.yaml +++ b/postman/collections/Fleetbase Storefront API/Products/Query Products.queryParams.yaml @@ -1,5 +1,20 @@ $kind: params fields: - - name: offset + - name: query + type: string + description: "Search published products available through the current store or network." + - name: store type: string - description: "Offset value for this products request." + description: "Marketplace member store public ID. Ignored for store-scoped keys." + - name: category + type: string + description: "Product category public ID belonging to the selected store scope." + - name: with_store + type: boolean + description: "Include the product's hydrated member store and media." + - name: limit + type: integer + description: "Maximum number of products to return." + - name: offset + type: integer + description: "Number of matching products to skip." diff --git a/postman/collections/Fleetbase Storefront API/Products/Query Products.request.yaml b/postman/collections/Fleetbase Storefront API/Products/Query Products.request.yaml index d31143c..bcc2ffc 100644 --- a/postman/collections/Fleetbase Storefront API/Products/Query Products.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Products/Query Products.request.yaml @@ -1,8 +1,13 @@ $kind: http-request description: |- - Returns products available in the current storefront. Use pagination and filters to browse the catalog. + Returns published, available products for the authenticated store or marketplace network. In marketplace mode, products are restricted to active network members and can be scoped to a member store or one of that store's categories. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/products" method: GET queryParams: + query: "" + store: "" + category: "" + with_store: "true" + limit: "" offset: "" order: 1000 diff --git a/postman/collections/Fleetbase Storefront API/Store Locations/Query Store Locations.queryParams.yaml b/postman/collections/Fleetbase Storefront API/Store Locations/Query Store Locations.queryParams.yaml new file mode 100644 index 0000000..41efbb4 --- /dev/null +++ b/postman/collections/Fleetbase Storefront API/Store Locations/Query Store Locations.queryParams.yaml @@ -0,0 +1,29 @@ +$kind: params +fields: + - name: query + type: string + description: "Search member stores and return their matching locations." + - name: tagged + type: string + description: "Comma-separated member-store tags to match." + - name: ids + type: string + description: "Comma-separated store-location public IDs to include." + - name: exclude + type: string + description: "Comma-separated store-location public IDs to exclude." + - name: with_store + type: boolean + description: "Include the location's hydrated member store, logo, and backdrop." + - name: "location[latitude]" + type: number + description: "Customer latitude used to calculate and order location distance." + - name: "location[longitude]" + type: number + description: "Customer longitude used to calculate and order location distance." + - name: limit + type: integer + description: "Maximum number of locations to return; defaults to 30." + - name: offset + type: integer + description: "Number of matching locations to skip." diff --git a/postman/collections/Fleetbase Storefront API/Store Locations/Query Store Locations.request.yaml b/postman/collections/Fleetbase Storefront API/Store Locations/Query Store Locations.request.yaml index 1099ebe..97cec16 100644 --- a/postman/collections/Fleetbase Storefront API/Store Locations/Query Store Locations.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Store Locations/Query Store Locations.request.yaml @@ -1,6 +1,16 @@ $kind: http-request description: |- - Returns store locations available through the current storefront or network. Use these locations for browsing, pickup, and fulfillment selection. + Returns locations belonging to active member stores of the authenticated marketplace network. Use these locations for the marketplace map, pickup selection, and multi-store delivery origins. Store-scoped keys and non-network sessions receive an error. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/store-locations" method: GET +queryParams: + query: "" + tagged: "" + ids: "" + exclude: "" + with_store: "true" + "location[latitude]": "" + "location[longitude]": "" + limit: "" + offset: "" order: 1000 diff --git a/postman/collections/Fleetbase Storefront API/Store/List Network Stores.queryParams.yaml b/postman/collections/Fleetbase Storefront API/Store/List Network Stores.queryParams.yaml index 62e61b4..29b5302 100644 --- a/postman/collections/Fleetbase Storefront API/Store/List Network Stores.queryParams.yaml +++ b/postman/collections/Fleetbase Storefront API/Store/List Network Stores.queryParams.yaml @@ -2,13 +2,40 @@ $kind: params fields: - name: query type: string - description: "Query value for this store request." - - name: limit + description: "Search member store names and other searchable store fields." + - name: tagged type: string - description: "Limit value for this store request." - - name: offset + description: "Comma-separated store tags; a store matching any supplied tag is returned." + - name: category + type: string + description: "Marketplace category public ID assigned to a network member store." + - name: without_category + type: boolean + description: "When true, return only member stores without a marketplace category assignment." + - name: ids type: string - description: "Offset value for this store request." - - name: store + description: "Comma-separated store public IDs to include." + - name: exclude type: string - description: "Store value for this store request." + description: "Comma-separated store public IDs to exclude." + - name: online + type: boolean + description: "Filter by the store online state." + - name: sort + type: string + description: "Sort mode: highest_rated, lowest_rated, newest, oldest, popular, trending, or nearest." + - name: "location[latitude]" + type: number + description: "Customer latitude used by nearest sorting and distance filtering." + - name: "location[longitude]" + type: number + description: "Customer longitude used by nearest sorting and distance filtering." + - name: maximum_distance + type: number + description: "Maximum distance from location in meters. Stores without a valid location are omitted." + - name: limit + type: integer + description: "Maximum number of stores to return." + - name: offset + type: integer + description: "Number of matching stores to skip." diff --git a/postman/collections/Fleetbase Storefront API/Store/List Network Stores.request.yaml b/postman/collections/Fleetbase Storefront API/Store/List Network Stores.request.yaml index 212a093..51715bf 100644 --- a/postman/collections/Fleetbase Storefront API/Store/List Network Stores.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Store/List Network Stores.request.yaml @@ -1,10 +1,20 @@ $kind: http-request -description: List Network Stores +description: |- + Lists active member stores for the authenticated marketplace network key. Results are network-scoped and can be searched, filtered, distance-ranked, and paginated. A store-scoped key receives an error from this endpoint. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/stores" method: GET queryParams: query: "" + tagged: "" + category: "" + without_category: "" + ids: "" + exclude: "" + online: "true" + sort: "" + "location[latitude]": "" + "location[longitude]": "" + maximum_distance: "" limit: "" offset: "" - store: "" order: 2700 diff --git a/scripts/lint-collections.sh b/scripts/lint-collections.sh index f8497cd..59a4ff5 100755 --- a/scripts/lint-collections.sh +++ b/scripts/lint-collections.sh @@ -4,12 +4,7 @@ set -eu node ./scripts/validate-collections.js if command -v postman >/dev/null 2>&1; then - yaml_files="$(find ./postman/collections -name '*.yaml' -print)" - if [ -n "$yaml_files" ]; then - for yaml_file in $yaml_files; do - postman collection lint "$yaml_file" --fail-severity error - done - fi + postman collection lint ./postman/collections --fail-severity error else echo "Postman CLI not found; skipped v3 YAML schema lint." fi From ccdef2cec32bd63e6afb2e6333ce52a62b89d75c Mon Sep 17 00:00:00 2001 From: "Ronald A. Richardson" Date: Wed, 12 Aug 2026 00:01:43 +0800 Subject: [PATCH 2/2] docs: clarify storefront context contracts --- .../Store Locations/Query Store Locations.request.yaml | 2 +- .../Fleetbase Storefront API/Store/List Tags.request.yaml | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/postman/collections/Fleetbase Storefront API/Store Locations/Query Store Locations.request.yaml b/postman/collections/Fleetbase Storefront API/Store Locations/Query Store Locations.request.yaml index 97cec16..2151858 100644 --- a/postman/collections/Fleetbase Storefront API/Store Locations/Query Store Locations.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Store Locations/Query Store Locations.request.yaml @@ -1,6 +1,6 @@ $kind: http-request description: |- - Returns locations belonging to active member stores of the authenticated marketplace network. Use these locations for the marketplace map, pickup selection, and multi-store delivery origins. Store-scoped keys and non-network sessions receive an error. + Returns locations for the authenticated storefront context. Network keys receive locations belonging to active member stores for marketplace maps, pickup selection, and multi-store delivery origins; store keys receive only their own locations. Requests without a storefront context receive an error. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/store-locations" method: GET queryParams: diff --git a/postman/collections/Fleetbase Storefront API/Store/List Tags.request.yaml b/postman/collections/Fleetbase Storefront API/Store/List Tags.request.yaml index 3cd7672..678b552 100644 --- a/postman/collections/Fleetbase Storefront API/Store/List Tags.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Store/List Tags.request.yaml @@ -1,5 +1,6 @@ $kind: http-request -description: List Tags +description: |- + Returns unique storefront tags for the authenticated context. Network keys aggregate tags across active member stores, while store keys return tags from the current store only. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/tags" method: GET order: 2800