2026-07-05 04:23:47 +04:00
|
|
|
# Business APIs
|
|
|
|
|
|
|
|
|
|
## 1. Scope
|
|
|
|
|
Business APIs provide transactional and catalog capabilities.
|
|
|
|
|
They must remain tenant-aware and must not return UI/layout/theme/widget configuration.
|
|
|
|
|
|
|
|
|
|
## 2. Immutable Rule
|
|
|
|
|
These APIs MUST NOT return:
|
|
|
|
|
- page composition
|
|
|
|
|
- layout mode
|
|
|
|
|
- widget metadata
|
|
|
|
|
- theme/footer/static page config
|
|
|
|
|
|
|
|
|
|
That data belongs to CONFIG DOMAIN (`/bootstrap`, `/pages/:slug`).
|
|
|
|
|
|
|
|
|
|
## 3. API Catalog
|
|
|
|
|
|
|
|
|
|
## /auth
|
|
|
|
|
Purpose:
|
|
|
|
|
- session creation/validation
|
|
|
|
|
- login/logout flows
|
|
|
|
|
- token refresh where applicable
|
|
|
|
|
|
|
|
|
|
High-level response shape:
|
|
|
|
|
- session/token metadata
|
|
|
|
|
- user identity claims
|
|
|
|
|
- permission scopes
|
|
|
|
|
|
|
|
|
|
Tenant rule:
|
|
|
|
|
- auth sessions are tenant-scoped by request context.
|
|
|
|
|
|
|
|
|
|
Must not change:
|
|
|
|
|
- authentication contract and downstream payment/auth integrations.
|
|
|
|
|
|
|
|
|
|
## /items
|
|
|
|
|
Purpose:
|
|
|
|
|
- list/fetch product items
|
|
|
|
|
- search/filter/sort
|
|
|
|
|
- item details and availability
|
|
|
|
|
|
|
|
|
|
High-level response shape:
|
|
|
|
|
- item arrays / item objects
|
|
|
|
|
- pagination metadata
|
|
|
|
|
- stock/price fields
|
|
|
|
|
|
|
|
|
|
Tenant rule:
|
|
|
|
|
- only items visible to tenant catalog policy.
|
|
|
|
|
|
|
|
|
|
Must not change:
|
|
|
|
|
- item identifiers/price semantics relied on frontend checkout/cart logic.
|
|
|
|
|
|
2026-07-09 00:55:50 +04:00
|
|
|
## /searchitems
|
|
|
|
|
Purpose:
|
|
|
|
|
- keyword-based product search for catalog/search pages.
|
|
|
|
|
|
|
|
|
|
High-level response shape:
|
|
|
|
|
- items array
|
|
|
|
|
- total count
|
|
|
|
|
|
|
|
|
|
Tenant rule:
|
|
|
|
|
- results must respect tenant catalog visibility and pricing policies.
|
|
|
|
|
|
|
|
|
|
## /search/suggestions (future-ready)
|
|
|
|
|
Purpose:
|
|
|
|
|
- return instant search suggestions for typed keywords.
|
|
|
|
|
|
|
|
|
|
High-level response shape:
|
|
|
|
|
- suggestion strings or objects with label/value and optional popularity/count.
|
|
|
|
|
|
|
|
|
|
Tenant rule:
|
|
|
|
|
- suggestions generated only from tenant-visible catalog corpus.
|
|
|
|
|
|
|
|
|
|
## /catalog/filters (future-ready)
|
|
|
|
|
Purpose:
|
|
|
|
|
- provide dynamic filter definitions and options for current search/category context.
|
|
|
|
|
|
|
|
|
|
High-level response shape:
|
|
|
|
|
- filter definitions
|
|
|
|
|
- option counts
|
|
|
|
|
- optional min/max ranges
|
|
|
|
|
|
|
|
|
|
Tenant rule:
|
|
|
|
|
- filter options/counts must be tenant-scoped and inventory-aware.
|
|
|
|
|
|
2026-07-09 00:45:36 +04:00
|
|
|
## /products/{id}/rating
|
|
|
|
|
Purpose:
|
|
|
|
|
- return product rating aggregate for engagement UI.
|
|
|
|
|
|
|
|
|
|
High-level response shape:
|
|
|
|
|
- average rating
|
|
|
|
|
- total reviews
|
|
|
|
|
- star distribution (5..1)
|
|
|
|
|
|
|
|
|
|
Tenant rule:
|
|
|
|
|
- aggregate must be computed only from tenant-visible reviews.
|
|
|
|
|
|
|
|
|
|
## /products/{id}/reviews
|
|
|
|
|
Purpose:
|
|
|
|
|
- paginated review feed for product page.
|
|
|
|
|
|
|
|
|
|
High-level response shape:
|
|
|
|
|
- review list
|
|
|
|
|
- page/pageSize/total metadata
|
|
|
|
|
|
|
|
|
|
Tenant rule:
|
|
|
|
|
- only tenant-allowed and moderation-approved reviews.
|
|
|
|
|
|
|
|
|
|
## /products/{id}/questions
|
|
|
|
|
Purpose:
|
|
|
|
|
- paginated questions and answers feed for product page.
|
|
|
|
|
|
|
|
|
|
High-level response shape:
|
|
|
|
|
- question list with answers
|
|
|
|
|
- page/pageSize/total metadata
|
|
|
|
|
|
|
|
|
|
Tenant rule:
|
|
|
|
|
- only tenant-visible questions/answers.
|
|
|
|
|
|
|
|
|
|
## /products/{id}/reviews (POST)
|
|
|
|
|
Purpose:
|
|
|
|
|
- create review (rating/title/text/anonymous).
|
|
|
|
|
|
|
|
|
|
Must not change:
|
|
|
|
|
- request validation semantics expected by frontend engagement form.
|
|
|
|
|
|
|
|
|
|
## /products/{id}/questions (POST)
|
|
|
|
|
Purpose:
|
|
|
|
|
- create product question (text/anonymous).
|
|
|
|
|
|
|
|
|
|
Must not change:
|
|
|
|
|
- acknowledgement contract expected by frontend engagement form.
|
|
|
|
|
|
2026-07-09 01:13:54 +04:00
|
|
|
## /me/wishlist (future-ready)
|
|
|
|
|
Purpose:
|
|
|
|
|
- authenticated wishlist synchronization across devices.
|
|
|
|
|
|
|
|
|
|
High-level response shape:
|
|
|
|
|
- wishlist product references
|
|
|
|
|
- optional addedAt metadata
|
|
|
|
|
|
|
|
|
|
Tenant rule:
|
|
|
|
|
- wishlist entries must remain tenant-scoped.
|
|
|
|
|
|
|
|
|
|
## /me/compare (future-ready)
|
|
|
|
|
Purpose:
|
|
|
|
|
- optional compare list synchronization for authenticated users.
|
|
|
|
|
|
|
|
|
|
High-level response shape:
|
|
|
|
|
- compared product references
|
|
|
|
|
- optional addedAt metadata
|
|
|
|
|
|
|
|
|
|
Tenant rule:
|
|
|
|
|
- compare list must be isolated by tenant + user.
|
|
|
|
|
|
|
|
|
|
## /me/saved-searches (future-ready)
|
|
|
|
|
Purpose:
|
|
|
|
|
- persist and restore saved search presets.
|
|
|
|
|
|
|
|
|
|
High-level response shape:
|
|
|
|
|
- saved query/filter/sort presets
|
|
|
|
|
- timestamps and id
|
|
|
|
|
|
|
|
|
|
Tenant rule:
|
|
|
|
|
- saved searches must be tenant-scoped and user-scoped.
|
|
|
|
|
|
|
|
|
|
## /me/recently-viewed (future-ready)
|
|
|
|
|
Purpose:
|
|
|
|
|
- synchronize recently viewed product history for authenticated users.
|
|
|
|
|
|
|
|
|
|
High-level response shape:
|
|
|
|
|
- product references + viewedAt metadata
|
|
|
|
|
|
|
|
|
|
Tenant rule:
|
|
|
|
|
- history must remain tenant-scoped and privacy-safe.
|
|
|
|
|
|
2026-07-05 04:23:47 +04:00
|
|
|
## /categories
|
|
|
|
|
Purpose:
|
|
|
|
|
- category tree retrieval
|
|
|
|
|
- category filtering metadata
|
|
|
|
|
|
|
|
|
|
High-level response shape:
|
|
|
|
|
- hierarchical or flat category collections
|
|
|
|
|
- visibility and ordering metadata
|
|
|
|
|
|
|
|
|
|
Tenant rule:
|
|
|
|
|
- category graph resolved per tenant catalog configuration.
|
|
|
|
|
|
|
|
|
|
Must not change:
|
|
|
|
|
- category IDs and parent linkage semantics consumed by frontend domain mapping.
|
|
|
|
|
|
|
|
|
|
## /orders
|
|
|
|
|
Purpose:
|
|
|
|
|
- create and track orders
|
|
|
|
|
- lifecycle state transitions
|
|
|
|
|
|
|
|
|
|
High-level response shape:
|
|
|
|
|
- order id
|
|
|
|
|
- status
|
|
|
|
|
- totals and line-items
|
|
|
|
|
|
|
|
|
|
Tenant rule:
|
|
|
|
|
- order creation/query restricted to tenant context.
|
|
|
|
|
|
|
|
|
|
Must not change:
|
|
|
|
|
- order status lifecycle contract integrated with payment and notification flows.
|
|
|
|
|
|
|
|
|
|
## /cart
|
|
|
|
|
Purpose:
|
|
|
|
|
- cart synchronization and server-side cart state where applicable
|
|
|
|
|
|
|
|
|
|
High-level response shape:
|
|
|
|
|
- cart items
|
|
|
|
|
- totals
|
|
|
|
|
- selected delivery/payment metadata
|
|
|
|
|
|
|
|
|
|
Tenant rule:
|
|
|
|
|
- cart state must be isolated by tenant + session/user.
|
|
|
|
|
|
|
|
|
|
Must not change:
|
|
|
|
|
- cart schema expected by checkout and payment request builders.
|
|
|
|
|
|
|
|
|
|
## /payments
|
|
|
|
|
Purpose:
|
|
|
|
|
- payment intent/QR/card flow initiation
|
|
|
|
|
- payment status querying
|
|
|
|
|
|
|
|
|
|
High-level response shape:
|
|
|
|
|
- payment id/reference
|
|
|
|
|
- redirect/QR links
|
|
|
|
|
- status fields
|
|
|
|
|
|
|
|
|
|
Tenant rule:
|
|
|
|
|
- payment credentials/routes resolved per tenant context on backend.
|
|
|
|
|
|
|
|
|
|
Must not change:
|
|
|
|
|
- existing payment provider contracts and callback/status semantics.
|
|
|
|
|
|
|
|
|
|
## 4. Governance for All Business APIs
|
|
|
|
|
- tenant derived from request context only
|
|
|
|
|
- strict repository-level tenant filtering
|
|
|
|
|
- no UI config payloads
|
|
|
|
|
- backward compatibility for existing frontend business flows
|
