diff --git a/collections/apis/storefront-api/README.md b/collections/apis/storefront-api/README.md index 4e427f1..2cc5dee 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}}/...`. + +## Network keys and marketplace storefronts + +A Fleetbase Network is the Console resource used to create and manage a multi-store marketplace storefront. Use a `network_...` Storefront API key to serve that network through the Storefront API. The same public routes are used for store and network contexts, 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 network-scoped 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..3c5301f 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. Network 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..c171379 --- /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: "Network 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 network 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..0668e3b 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, network categories for a network key, or product categories for a selected network 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..cb6adc1 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. Network 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..563e4e3 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. Network cart 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..d915b1f 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: "Network 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..9e40b59 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 network. With a network key, 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..2146c42 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 for the authenticated storefront context. Network keys receive locations belonging to active member stores for network storefront 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: + 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..4638687 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: "Network category public ID assigned to a member store." + - name: without_category + type: boolean + description: "When true, return only member stores without a network 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 aaf2589..eca1eae 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,8 +1,6 @@ $kind: http-request description: |- - Lists the stores belonging to a network. - - This endpoint requires a NETWORK session: authenticate with a network key rather than a store key. A store key is rejected with "Stores cannot have stores!". + Lists active member stores for the authenticated Network. This endpoint requires a network key; a store key is rejected. Results are network-scoped and can be searched, filtered, distance-ranked, and paginated. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/stores" method: GET # A network key. The collection-level store key cannot reach this endpoint. @@ -22,7 +20,16 @@ auth: token: "{{network_key}}" 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/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