From ed8eac7543bd2644ade71a4148c51dac66116619 Mon Sep 17 00:00:00 2001 From: "Ronald A. Richardson" Date: Sun, 30 Aug 2026 20:21:19 +0800 Subject: [PATCH] docs: align storefront auth and checkout contracts --- collections/apis/storefront-api/README.md | 6 ++++++ .../Checkout/Capture checkout as order.request.yaml | 4 +++- .../Customer/Update Contact Customer Alias.request.yaml | 4 +++- .../Customer/Update a Customer.request.yaml | 4 +++- 4 files changed, 15 insertions(+), 3 deletions(-) diff --git a/collections/apis/storefront-api/README.md b/collections/apis/storefront-api/README.md index 4e427f1..4c0d190 100644 --- a/collections/apis/storefront-api/README.md +++ b/collections/apis/storefront-api/README.md @@ -13,6 +13,12 @@ Reference collection for Fleetbase Storefront API requests. Requests inherit bearer token authentication from the collection. Set `api_key` locally or through Postman Vault. +The bearer token identifies the storefront. Customer-scoped requests additionally send the customer session token as `Customer-Token`. Profile update requests require that token and reject attempts to update a different customer. + +## Checkout capture + +`Capture checkout as order` is idempotent and verifies Stripe payments on the server. Confirm the PaymentIntent returned by checkout initialization before capture; Fleetbase uses the PaymentIntent linked to the checkout and rejects incomplete, missing, or mismatched payments. A concurrent capture can return `409` while the first request is still in progress and can be retried with the same checkout token. + ## 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}}/...`. diff --git a/postman/collections/Fleetbase Storefront API/Checkout/Capture checkout as order.request.yaml b/postman/collections/Fleetbase Storefront API/Checkout/Capture checkout as order.request.yaml index d8283a8..2e44462 100644 --- a/postman/collections/Fleetbase Storefront API/Checkout/Capture checkout as order.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Checkout/Capture checkout as order.request.yaml @@ -1,6 +1,8 @@ $kind: http-request description: |- - Captures a checkout token and creates the corresponding order. The response returns the completed order or the existing order when the checkout was already captured. + Captures a checkout token and creates the corresponding order. Capture is idempotent: an already completed checkout returns its existing order, while a concurrent capture still in progress returns `409` so the client can retry safely. + + Stripe checkouts are captured only after Fleetbase retrieves the server-linked PaymentIntent and verifies that it succeeded and matches the checkout amount, currency, customer, and live/test mode. An incomplete payment returns `402`, a missing or mismatched PaymentIntent returns `422`, and a temporary Stripe verification failure returns `502`. Clients must confirm the PaymentIntent before calling this endpoint and must not send or trust a client-selected PaymentIntent ID during capture. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/checkouts/capture" method: POST headers: diff --git a/postman/collections/Fleetbase Storefront API/Customer/Update Contact Customer Alias.request.yaml b/postman/collections/Fleetbase Storefront API/Customer/Update Contact Customer Alias.request.yaml index 5242e3b..9413a02 100644 --- a/postman/collections/Fleetbase Storefront API/Customer/Update Contact Customer Alias.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Customer/Update Contact Customer Alias.request.yaml @@ -1,9 +1,11 @@ $kind: http-request description: |- - Updates a storefront customer through the legacy contact alias route. The request is handled by the same customer update controller as `/customers/{id}`. + Updates the authenticated storefront customer through the legacy contact alias route. The `Customer-Token` must belong to the customer addressed by `customer_id`; missing or mismatched customer credentials return `403 Not authorized to update customer.` The request is handled by the same customer update controller as `/customers/{id}`. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/contacts/{{customer_id}}" method: PUT headers: + - key: Customer-Token + value: "{{customer_token}}" - key: Content-Type value: application/json body: diff --git a/postman/collections/Fleetbase Storefront API/Customer/Update a Customer.request.yaml b/postman/collections/Fleetbase Storefront API/Customer/Update a Customer.request.yaml index 3580ac2..67b380f 100644 --- a/postman/collections/Fleetbase Storefront API/Customer/Update a Customer.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Customer/Update a Customer.request.yaml @@ -1,9 +1,11 @@ $kind: http-request description: |- - Updates a storefront customer profile. The response returns the customer with the new values applied. + Updates the authenticated storefront customer's profile. The `Customer-Token` must belong to the customer addressed by `customer_id`; missing or mismatched customer credentials return `403 Not authorized to update customer.` The response returns the customer with the new values applied. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/customers/{{customer_id}}" method: PUT headers: + - key: Customer-Token + value: "{{customer_token}}" - key: Content-Type value: application/json body: