# eBay-Style Marketplace Backend Version : 1.1.10 ebaycClone is a comprehensive backend for an online marketplace supporting auctions and fixed-price sales of physical goods, with role-based access, public user registration, Stripe payments, notifications, and robust ownership enforcement. ## How to Use Project Documents The `Ebaycclone` project has been designed and generated using **Mindbricks**, a powerful microservice-based backend generation platform. All documentation is automatically produced by the **Mindbricks Genesis Engine**, based on the high-level architectural patterns defined by the user or inferred by AI. This documentation set is intended for both **AI agents** and **human developers**—including frontend and backend engineers—who need precise and structured information about how to interact with the backend services of this project. Each document reflects the live architecture of the system, providing a reliable reference for API consumption, data models, authentication flows, and business logic. By following this documentation, developers can seamlessly integrate with the backend, while AI agents can use it to reason about the service structure, make accurate decisions, or even generate compatible client-side code. ## Accessing Project Services Each service generated by Mindbricks is exposed via a **dedicated REST API** endpoint. Every service documentation set includes the **base URL** of that service along with the **specific API paths** for each available route. Before consuming any API, developers or agents must understand the service URL structure and environment-specific endpoints. ### Service Endpoint Structure | Environment | URL Pattern Example | |-------------|---------------------| | **Preview** | `https://ebaycclone.prw.mindbricks.com/auth-api` | | **Staging** | `https://ebaycclone-stage.mindbricks.co/auth-api` | | **Production** | `https://ebaycclone.mindbricks.co/auth-api` | Replace `auth` with the actual service name as lower case (e.g., `order-api`, `bff-service`, customermanagement-api etc.). ### Environment Usage Notes * **Preview APIs** become accessible after a project is previewed inside the Mindbricks platform. These are ideal for development and testing. * **Staging** and **Production** APIs are only accessible after the project is deployed to cloud environments provisioned via Mindbricks. * In some cases, the project owner may choose to deploy services on their **own infrastructure**. In such scenarios, the service base URLs will be **custom** and should be communicated manually by the project owner to developers or AI agents. > **Frontend applications** should be designed to **easily switch between environments**, allowing dynamic endpoint targeting for Preview, Staging, and Production. ## Getting Started: Use the Auth Service First Before interacting with other services in the `Ebaycclone` project, **AI agents and developers should begin by integrating with the Auth Service**. Mindbricks automatically generates a dedicated authentication microservice based on the project’s authentication definitions provided by the architect. This service provides the essential user and access management foundation for the project. Agents should first utilize the Auth Service to: * Register and authenticate users (login) * Manage users, roles, and permissions * Handle user groups (if defined) * Support multi-tenancy logic (if configured) * Perform Policy-Based Access Control (PBAC), if activated by the architect ### Auth Service Documentation Use the following resources to understand and integrate the Auth Service: * **REST API Guide** – ideal for frontend and direct HTTP usage * **Event Guide** – helpful for event-driven or cross-service integrations * **Service Design Document** – overall structure, patterns, and logic > **Note:** For most frontend use cases, the **REST API Guide** will be the primary source. The **Event Guide** and **Service Design** documents are especially useful when integrating with other backend microservices or building systems that interact with the auth service indirectly. ## Using the BFF (Backend-for-Frontend) Service In Mindbricks, all backend services are designed with an advanced **CQRS (Command Query Responsibility Segregation)** architecture. Within this architecture, **business services** are responsible for managing their respective domains and ensuring the accuracy and freshness of domain data. The **BFF service** complements these business services by providing a **read-only** aggregation and query layer tailored specifically for frontend and client-side applications. ### Key Principles of the BFF Service * **Elasticsearch Replicas for Fast Queries:** Each data object managed by a business service is automatically replicated as an **Elasticsearch index**, making it accessible for fast, frontend-oriented queries through the BFF. * **Cross-Service Data Aggregation:** The BFF offers an **aggregation layer** capable of combining data across multiple services, enabling complex filters, searches, and unified views of related data. * **Read-Only by Design:** The BFF service is **strictly read-only**. All create, update, or delete operations must be performed through the relevant business services, or via event-driven sagas if designed. ### BFF Service Documentation * **REST API Guide** – querying aggregated and indexed data * **Event Guide** – syncing strategies across replicas * **Service Design** – aggregation patterns and index structures > **Tip:** Use the BFF service as the **main entry point for all frontend data queries**. It simplifies access, reduces round-trips, and ensures that data is shaped appropriately for the UI layer. ## Business Services Overview The `eBay-Style Marketplace Backend` project consists of multiple **business services**, each responsible for managing a specific domain within the system. These services expose their own REST APIs and documentation sets, and are accessible based on the environment (Preview, Staging, Production). ### Usage Guidance Business services are primarily designed to: * Handle the **state and operations of domain data** * Offer **Create, Update, Delete** operations over owned entities * Serve **direct data queries** (`get`, `list`) for their own objects when needed For advanced query needs across multiple services or aggregated views, prefer using the [BFF service](#using-the-bff-backend-for-frontend-service). ### Available Business Services ### auctionOffer Service **Description:** Handles auction bids and fixed-price offers for product listings, enforces real-time auction state, handles strict offer workflows including counter-offers, and triggers domain events for bid/offer notifications. No payment or frontend aggregation logic included. **Documentation:** * [REST API Guide](https://ebaycclone.prw.mindbricks.com/document/auctionOffer-service/rest-api-guide) * [Event Guide](https://ebaycclone.prw.mindbricks.com/document/auctionOffer-service/event-guide) * [Service Design](https://ebaycclone.prw.mindbricks.com/document/auctionOffer-service/service-design) **Base URL Examples:** | Environment | URL | |-------------|---------------------| | **Preview** | `https://ebaycclone.prw.mindbricks.com/auctionoffer-api` | | **Staging** | `https://ebaycclone-stage.mindbricks.co/auctionoffer-api` | | **Production** | `https://ebaycclone.mindbricks.co/auctionoffer-api` | ### categoryManagement Service **Description:** Handles product categories and subcategories for marketplace browsing and classification, supporting public discovery plus admin-only management. **Documentation:** * [REST API Guide](https://ebaycclone.prw.mindbricks.com/document/categoryManagement-service/rest-api-guide) * [Event Guide](https://ebaycclone.prw.mindbricks.com/document/categoryManagement-service/event-guide) * [Service Design](https://ebaycclone.prw.mindbricks.com/document/categoryManagement-service/service-design) **Base URL Examples:** | Environment | URL | |-------------|---------------------| | **Preview** | `https://ebaycclone.prw.mindbricks.com/categorymanagement-api` | | **Staging** | `https://ebaycclone-stage.mindbricks.co/categorymanagement-api` | | **Production** | `https://ebaycclone.mindbricks.co/categorymanagement-api` | ### messaging Service **Description:** In-app messaging service for direct user-to-user text messages (buyers/sellers). Stores, retrieves, and manages user conversations. Launch version: text-only. **Documentation:** * [REST API Guide](https://ebaycclone.prw.mindbricks.com/document/messaging-service/rest-api-guide) * [Event Guide](https://ebaycclone.prw.mindbricks.com/document/messaging-service/event-guide) * [Service Design](https://ebaycclone.prw.mindbricks.com/document/messaging-service/service-design) **Base URL Examples:** | Environment | URL | |-------------|---------------------| | **Preview** | `https://ebaycclone.prw.mindbricks.com/messaging-api` | | **Staging** | `https://ebaycclone-stage.mindbricks.co/messaging-api` | | **Production** | `https://ebaycclone.mindbricks.co/messaging-api` | ### notificationManagement Service **Description:** Handles storage, management, and event-driven delivery of in-app and email notifications for user-impacting system events (bids, offers, orders, feedback, messaging, etc.). Supports marking notifications as read/unread, structured filtering by event type/channel, and always returns in-app notifications ordered by recency. **Documentation:** * [REST API Guide](https://ebaycclone.prw.mindbricks.com/document/notificationManagement-service/rest-api-guide) * [Event Guide](https://ebaycclone.prw.mindbricks.com/document/notificationManagement-service/event-guide) * [Service Design](https://ebaycclone.prw.mindbricks.com/document/notificationManagement-service/service-design) **Base URL Examples:** | Environment | URL | |-------------|---------------------| | **Preview** | `https://ebaycclone.prw.mindbricks.com/notificationmanagement-api` | | **Staging** | `https://ebaycclone-stage.mindbricks.co/notificationmanagement-api` | | **Production** | `https://ebaycclone.mindbricks.co/notificationmanagement-api` | ### searchIndexing Service **Description:** Maintains the denormalized search index (materialized view) for global, public search across products, sellers, categories, and subcategories. Handles indexing in response to entity events and exposes optimized query endpoints for BFF/aggregator. **Documentation:** * [REST API Guide](https://ebaycclone.prw.mindbricks.com/document/searchIndexing-service/rest-api-guide) * [Event Guide](https://ebaycclone.prw.mindbricks.com/document/searchIndexing-service/event-guide) * [Service Design](https://ebaycclone.prw.mindbricks.com/document/searchIndexing-service/service-design) **Base URL Examples:** | Environment | URL | |-------------|---------------------| | **Preview** | `https://ebaycclone.prw.mindbricks.com/searchindexing-api` | | **Staging** | `https://ebaycclone-stage.mindbricks.co/searchindexing-api` | | **Production** | `https://ebaycclone.mindbricks.co/searchindexing-api` | ### adminModeration Service **Description:** Administrative backend service for moderation and manual override actions. Responsible for logging all admin interventions (user/product/feedback/media/category/order/notification/searchindex moderation), triggering corrections via interservice calls, and providing comprehensive audit trails for compliance. **Documentation:** * [REST API Guide](https://ebaycclone.prw.mindbricks.com/document/adminModeration-service/rest-api-guide) * [Event Guide](https://ebaycclone.prw.mindbricks.com/document/adminModeration-service/event-guide) * [Service Design](https://ebaycclone.prw.mindbricks.com/document/adminModeration-service/service-design) **Base URL Examples:** | Environment | URL | |-------------|---------------------| | **Preview** | `https://ebaycclone.prw.mindbricks.com/adminmoderation-api` | | **Staging** | `https://ebaycclone-stage.mindbricks.co/adminmoderation-api` | | **Production** | `https://ebaycclone.mindbricks.co/adminmoderation-api` | ### watchlistCart Service **Description:** Handles user watchlists (with custom folders) and shopping cart preparation for checkout, strictly enforcing only fixed-price products in carts, supporting item moves/bulk operations, and robust default/folder logic.. **Documentation:** * [REST API Guide](https://ebaycclone.prw.mindbricks.com/document/watchlistCart-service/rest-api-guide) * [Event Guide](https://ebaycclone.prw.mindbricks.com/document/watchlistCart-service/event-guide) * [Service Design](https://ebaycclone.prw.mindbricks.com/document/watchlistCart-service/service-design) **Base URL Examples:** | Environment | URL | |-------------|---------------------| | **Preview** | `https://ebaycclone.prw.mindbricks.com/watchlistcart-api` | | **Staging** | `https://ebaycclone-stage.mindbricks.co/watchlistcart-api` | | **Production** | `https://ebaycclone.mindbricks.co/watchlistcart-api` | ### productListing Service **Description:** Handles product listings (both auction and fixed-price), image/media storage with validations, enforces immutable type, soft-delete, and public product discovery. **Documentation:** * [REST API Guide](https://ebaycclone.prw.mindbricks.com/document/productListing-service/rest-api-guide) * [Event Guide](https://ebaycclone.prw.mindbricks.com/document/productListing-service/event-guide) * [Service Design](https://ebaycclone.prw.mindbricks.com/document/productListing-service/service-design) **Base URL Examples:** | Environment | URL | |-------------|---------------------| | **Preview** | `https://ebaycclone.prw.mindbricks.com/productlisting-api` | | **Staging** | `https://ebaycclone-stage.mindbricks.co/productlisting-api` | | **Production** | `https://ebaycclone.mindbricks.co/productlisting-api` | ### orderManagement Service **Description:** Handles all marketplace orders, manual checkout flows for fixed-price/offer/auction settlements, Stripe payment processing and webhook reconciliation, explicit status updates (shipping, delivery, cancellation), and feedback eligibility via orderItems. **Documentation:** * [REST API Guide](https://ebaycclone.prw.mindbricks.com/document/orderManagement-service/rest-api-guide) * [Event Guide](https://ebaycclone.prw.mindbricks.com/document/orderManagement-service/event-guide) * [Service Design](https://ebaycclone.prw.mindbricks.com/document/orderManagement-service/service-design) **Base URL Examples:** | Environment | URL | |-------------|---------------------| | **Preview** | `https://ebaycclone.prw.mindbricks.com/ordermanagement-api` | | **Staging** | `https://ebaycclone-stage.mindbricks.co/ordermanagement-api` | | **Production** | `https://ebaycclone.mindbricks.co/ordermanagement-api` | ### feedback Service **Description:** Handles feedback for order items: one feedback per buyer/orderItem, attached to sellerId for analytical feedback/rating aggregation and reputation tracking. Enables querying feedbacks received/given for sellers and buyers. test **Documentation:** * [REST API Guide](https://ebaycclone.prw.mindbricks.com/document/feedback-service/rest-api-guide) * [Event Guide](https://ebaycclone.prw.mindbricks.com/document/feedback-service/event-guide) * [Service Design](https://ebaycclone.prw.mindbricks.com/document/feedback-service/service-design) **Base URL Examples:** | Environment | URL | |-------------|---------------------| | **Preview** | `https://ebaycclone.prw.mindbricks.com/feedback-api` | | **Staging** | `https://ebaycclone-stage.mindbricks.co/feedback-api` | | **Production** | `https://ebaycclone.mindbricks.co/feedback-api` | ## Conclusion This documentation set provides a comprehensive guide for understanding and consuming the `eBay-Style Marketplace Backend` backend, generated by the Mindbricks platform. It is structured to support both AI agents and human developers in navigating authentication, data access, service responsibilities, and system architecture. To summarize: * Start with the **Auth Service** to manage users, roles, sessions, and permissions. * Use the **BFF Service** for optimized, read-only data queries and cross-service aggregation. * Refer to the **Business Services** when you need to manage domain-specific data or perform direct CRUD operations. Each service offers a complete set of documentation—REST API guides, event interface definitions, and design insights—to help you integrate efficiently and confidently. Whether you are building a frontend application, configuring an automation agent, or simply exploring the architecture, this documentation is your primary reference for working with the backend of this project. > For environment-specific access, ensure you're using the correct base URLs (Preview, Staging, Production), and coordinate with the project owner for any custom deployments. # EVENT GUIDE ## ebaycclone-adminmoderation-service Administrative backend service for moderation and manual override actions. Responsible for logging all admin interventions (user/product/feedback/media/category/order/notification/searchindex moderation), triggering corrections via interservice calls, and providing comprehensive audit trails for compliance. ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to: Email: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. # Documentation Scope Welcome to the official documentation for the `AdminModeration` Service Event descriptions. This guide is dedicated to detailing how to subscribe to and listen for state changes within the `AdminModeration` Service, offering an exclusive focus on event subscription mechanisms. **Intended Audience** This documentation is aimed at developers and integrators looking to monitor `AdminModeration` Service state changes. It is especially relevant for those wishing to implement or enhance business logic based on interactions with `AdminModeration` objects. **Overview** This section provides detailed instructions on monitoring service events, covering payload structures and demonstrating typical use cases through examples. # Authentication and Authorization Access to the `AdminModeration` service's events is facilitated through the project's Kafka server, which is not accessible to the public. Subscription to a Kafka topic requires being on the same network and possessing valid Kafka user credentials. This document presupposes that readers have existing access to the Kafka server. Additionally, the service offers a public subscription option via REST for real-time data management in frontend applications, secured through REST API authentication and authorization mechanisms. To subscribe to service events via the REST API, please consult the Realtime REST API Guide. # Database Events Database events are triggered at the database layer, automatically and atomically, in response to any modifications at the data level. These events serve to notify subscribers about the creation, update, or deletion of objects within the database, distinct from any overarching business logic. Listening to database events is particularly beneficial for those focused on tracking changes at the database level. A typical use case for subscribing to database events is to replicate the data store of one service within another service's scope, ensuring data consistency and syncronization across services. For example, while a business operation such as "approve membership" might generate a high-level business event like `membership-approved`, the underlying database changes could involve multiple state updates to different entities. These might be published as separate events, such as `dbevent-member-updated` and `dbevent-user-updated`, reflecting the granular changes at the database level. Such detailed eventing provides a robust foundation for building responsive, data-driven applications, enabling fine-grained observability and reaction to the dynamics of the data landscape. It also facilitates the architectural pattern of event sourcing, where state changes are captured as a sequence of events, allowing for high-fidelity data replication and history replay for analytical or auditing purposes. ## DbEvent moderationAction-created **Event topic**: `ebaycclone-adminmoderation-service-dbevent-moderationaction-created` This event is triggered upon the creation of a `moderationAction` data object in the database. The event payload encompasses the newly created data, encapsulated within the root of the paylod. **Event payload**: ```json {"id":"ID","adminId":"ID","entityId":"ID","actionTimestamp":"Date","entityType":"Enum","entityType_idx":"Integer","reason":"String","actionType":"Enum","actionType_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent moderationAction-updated **Event topic**: `ebaycclone-adminmoderation-service-dbevent-moderationaction-updated` Activation of this event follows the update of a `moderationAction` data object. The payload contains the updated information under the `moderationAction` attribute, along with the original data prior to update, labeled as `old_moderationAction` and also you can find the old and new versions of updated-only portion of the data.. **Event payload**: ```json { old_moderationAction:{"id":"ID","adminId":"ID","entityId":"ID","actionTimestamp":"Date","entityType":"Enum","entityType_idx":"Integer","reason":"String","actionType":"Enum","actionType_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, moderationAction:{"id":"ID","adminId":"ID","entityId":"ID","actionTimestamp":"Date","entityType":"Enum","entityType_idx":"Integer","reason":"String","actionType":"Enum","actionType_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, oldDataValues, newDataValues } ``` ## DbEvent moderationAction-deleted **Event topic**: `ebaycclone-adminmoderation-service-dbevent-moderationaction-deleted` This event announces the deletion of a `moderationAction` data object, covering both hard deletions (permanent removal) and soft deletions (where the `isActive` attribute is set to false). Regardless of the deletion type, the event payload will present the data as it was immediately before deletion, highlighting an `isActive` status of false for soft deletions. **Event payload**: ```json {"id":"ID","adminId":"ID","entityId":"ID","actionTimestamp":"Date","entityType":"Enum","entityType_idx":"Integer","reason":"String","actionType":"Enum","actionType_idx":"Integer","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` # ElasticSearch Index Events Within the `AdminModeration` service, most data objects are mirrored in ElasticSearch indices, ensuring these indices remain syncronized with their database counterparts through creation, updates, and deletions. These indices serve dual purposes: they act as a data source for external services and furnish aggregated data tailored to enhance frontend user experiences. Consequently, an ElasticSearch index might encapsulate data in its original form or aggregate additional information from other data objects. These aggregations can include both one-to-one and one-to-many relationships not only with database objects within the same service but also across different services. This capability allows developers to access comprehensive, aggregated data efficiently. By subscribing to ElasticSearch index events, developers are notified when an index is updated and can directly obtain the aggregated entity within the event payload, bypassing the need for separate ElasticSearch queries. It's noteworthy that some services may augment another service's index by appending to the entity’s `extends` object. In such scenarios, an `*-extended` event will contain only the newly added data. Should you require the complete dataset, you would need to retrieve the full ElasticSearch index entity using the provided ID. This approach to indexing and event handling facilitates a modular, interconnected architecture where services can seamlessly integrate and react to changes, enriching the overall data ecosystem and enabling more dynamic, responsive applications. ## Index Event moderationaction-created **Event topic**: `elastic-index-ebaycclone_moderationaction-created` **Event payload**: ```json {"id":"ID","adminId":"ID","entityId":"ID","actionTimestamp":"Date","entityType":"Enum","entityType_idx":"Integer","reason":"String","actionType":"Enum","actionType_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event moderationaction-updated **Event topic**: `elastic-index-ebaycclone_moderationaction-created` **Event payload**: ```json {"id":"ID","adminId":"ID","entityId":"ID","actionTimestamp":"Date","entityType":"Enum","entityType_idx":"Integer","reason":"String","actionType":"Enum","actionType_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event moderationaction-deleted **Event topic**: `elastic-index-ebaycclone_moderationaction-deleted` **Event payload**: ```json {"id":"ID","adminId":"ID","entityId":"ID","actionTimestamp":"Date","entityType":"Enum","entityType_idx":"Integer","reason":"String","actionType":"Enum","actionType_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event moderationaction-extended **Event topic**: `elastic-index-ebaycclone_moderationaction-extended` **Event payload**: ```js { id: id, extends: { [extendName]: "Object", [extendName + "_count"]: "Number", }, } ``` # Route Events Route events are emitted following the successful execution of a route. While most routes perform CRUD (Create, Read, Update, Delete) operations on data objects, resulting in route events that closely resemble database events, there are distinctions worth noting. A single route execution might trigger multiple CRUD actions and ElasticSearch indexing operations. However, for those primarily concerned with the overarching business logic and its outcomes, listening to the consolidated route event, published once at the conclusion of the route's execution, is more pertinent. Moreover, routes often deliver aggregated data beyond the primary database object, catering to specific client needs. For instance, creating a data object via a route might not only return the entity's data but also route-specific metrics, such as the executing user's permissions related to the entity. Alternatively, a route might automatically generate default child entities following the creation of a parent object. Consequently, the route event encapsulates a unified dataset encompassing both the parent and its children, in contrast to individual events triggered for each entity created. Therefore, subscribing to route events can offer a richer, more contextually relevant set of information aligned with business logic. The payload of a route event mirrors the REST response JSON of the route, providing a direct and comprehensive reflection of the data and metadata communicated to the client. This ensures that subscribers to route events receive a payload that encapsulates both the primary data involved and any additional information deemed significant at the business level, facilitating a deeper understanding and integration of the service's functional outcomes. ## Route Event moderationaction-retrived **Event topic** : `ebaycclone-adminmoderation-service-moderationaction-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `moderationAction` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`moderationAction`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"moderationAction","method":"GET","action":"get","appVersion":"Version","rowCount":1,"moderationAction":{"id":"ID","adminId":"ID","entityId":"ID","actionTimestamp":"Date","entityType":"Enum","entityType_idx":"Integer","reason":"String","actionType":"Enum","actionType_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event moderationaction-deleted **Event topic** : `ebaycclone-adminmoderation-service-moderationaction-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `moderationAction` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`moderationAction`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"moderationAction","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"moderationAction":{"id":"ID","adminId":"ID","entityId":"ID","actionTimestamp":"Date","entityType":"Enum","entityType_idx":"Integer","reason":"String","actionType":"Enum","actionType_idx":"Integer","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event moderationaction-created **Event topic** : `ebaycclone-adminmoderation-service-moderationaction-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `moderationAction` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`moderationAction`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"moderationAction","method":"POST","action":"create","appVersion":"Version","rowCount":1,"moderationAction":{"id":"ID","adminId":"ID","entityId":"ID","actionTimestamp":"Date","entityType":"Enum","entityType_idx":"Integer","reason":"String","actionType":"Enum","actionType_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event moderationactions-listed **Event topic** : `ebaycclone-adminmoderation-service-moderationactions-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `moderationActions` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`moderationActions`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"moderationActions","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","moderationActions":[{"id":"ID","adminId":"ID","entityId":"ID","actionTimestamp":"Date","entityType":"Enum","entityType_idx":"Integer","reason":"String","actionType":"Enum","actionType_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event moderationaction-updated **Event topic** : `ebaycclone-adminmoderation-service-moderationaction-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `moderationAction` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`moderationAction`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"moderationAction","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"moderationAction":{"id":"ID","adminId":"ID","entityId":"ID","actionTimestamp":"Date","entityType":"Enum","entityType_idx":"Integer","reason":"String","actionType":"Enum","actionType_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` # Copyright All sources, documents and other digital materials are copyright of . # About Us For more information please visit our website: . . . # **EBAYCCLONE** FRONTEND GUIDE FOR AI CODING AGENTS This document is a rest api guide for the ebaycclone project. The document is designed for AI agents who will generate frontend code that will consume the project backend. The project has got 1 auth service, 1 notification service, 1 bff service and business services. Each service is a separate microservice application and listens the HTTP request from different service urls. The services may be in preview server, staging server or real production server. So each service have got 3 acess urls. Frontend application should support all deployemnt servers in the development phase, and user should be able to select the target api server in the login page. ## Project Introduction ebaycClone is a comprehensive backend for an online marketplace supporting auctions and fixed-price sales of physical goods, with role-based access, public user registration, Stripe payments, notifications, and robust ownership enforcement. ## API Structure ### Object Structure of a Successfull Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client. **HTTP Status Codes:** - **200 OK**: This status code is returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request has been processed successfully. - **201 Created**: This status code is specific to CREATE operations, signifying that the requested resource has been successfully created. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling the successful execution of the request. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` - **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation performed. ### Additional Data Each api may have include addtional data other than the main data object according to the business logic of the API. They will be given in each API's response signature. ### Error Response If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity: - **400 Bad Request**: The request was improperly formatted or contained invalid parameters, preventing the server from processing it. - **401 Unauthorized**: The request lacked valid authentication token , login required - **403 Forbidden Error** Curent token provided do not grant access to the requested resource. - **404 Not Found**: The requested resource was not found on the server. - **500 Internal Server Error**: The server encountered an unexpected condition that prevented it from fulfilling the request. Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Accessing the backend Each service of the backend has got its own url according to the deployment environement. User may want to test the frontend in one of the 3 deployments of the application, preview, staging and production. Please ensure that register and login pages do have a deployemnt server selection option, so as the frontned coding agent you can arrange the base url path of all services. The base url of the application in each environment is as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com` * **Staging:** `https://ebaycclone-stage.mindbricks.co` * **Production:** `https://ebaycclone.mindbricks.co` For the auth service the base url is as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` For each other service, the service base url will be given in service sections. Any login requied request to the backend should have a valid token, when a user makes a successfull login, the ressponse JSON includes a JWT access token in the `accessToken`fields. In normal conditions, this token is also set to the cookie and then consumed automatically, but since AI coding agents preview options may fail to use cookies, please ensure that in each request include the access token in the bearer auth header. ## Registration Management First of all please ensure that register and login pages do have a deployemnt server selection option, so as the frontned coding agent you can arrange the base url path of all services. Start with a landing page and arranging register, verification and login flow. So at the first step, you need a general knowledge of the application to make a good landing page and the authetication flow. ### How To Register Using `registeruser` route of auth api, send the required fields to the backend in your registration page. The registerUser api in in `auth` service, is described with request and response structure below. Note that since `registerUser` api is a business api, it has a version control, so please call it with the given version like `/v1/registeruser` ### `Register User` API This api is used by public users to register themselves **Rest Route** The `registerUser` API REST controller can be triggered via the following route: `/v1/registeruser` **Rest Request Parameters** The `registerUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **password** : The password defined by the the user that is being registered. **fullname** : The fullname defined by the the user that is being registered. **email** : The email defined by the the user that is being registered. **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` After a successful registration, frontend code should handle the verification needs. The registration response will have a `user` object in the root envelope, this object will have user information with an `id` parameter. ### Email Verification In the registration response, you should check the property `emailVerificationNeeded` in the reponse root, and if this property is true you should start the email verification flow. After login process, if you get an HTTP error status, and if there is an `errCode` property in the response with `EmailVerificationNeeded` value, you should start the email verification flow. 1. Call the email verification `start` route of the backend (described below) with the user email, backend will send a secret code to the given email adresss. **Backend can send the email message if the architect defined a real mail service or smtp server, so during the development time backend will send the secret code also to the frontend. You can get this secret code from the response within the `secretCode` property**. 2. The secret code in the sent email message will be a 6 digits code , and you should arrange an input page so that the user can paste this code to the frontend application. Please navigate to this input page after you start the verification process. **If the secretCode is sent to the frontend for test purposes, then you should show it as info in the input page, so that user can copy and paste it**. 3. There is a `codeIndex` property in the start response, please show it's value on the input page, so that user can match the index in the message with the one on the screen. 4. When the user submits the code, please complete the email verification using the `complete` route of the backend (described below) with the user email and the secret code. 5. After you get a successful response from email verification, you can navigate to the login page. Here is the `start`and `complete` routes of email verification. These are system routes , so they dont have a version control. #### `POST /verification-services/email-verification/start` **Purpose:** Starts the email verification by generating and sending a secret code. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `email` | String | Yes | User’s email address to verify | **Example Request** ```json { "email": "user@example.com" } ``` **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ In production, `secretCode` is **not** returned — only sent via email. **Error Responses** * `400 Bad Request`: Already verified * `403 Forbidden`: Too many attempts (rate limit) --- #### `POST /verification-services/email-verification/complete` **Purpose:** Completes the verification using the received code. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `email` | String | Yes | User’s email | | `secretCode` | String | Yes | Verification code | **Success Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` **Error Responses** * `403 Forbidden`: Code expired or mismatched * `404 Not Found`: No verification in progress --- ## Login Management After a successfull login and completing required verifications, user can now login. Please make a fancy minimal login page where user can enter his email and password. ## Bucket Management This application has a bucket service and is used to store user or other objects related files. Bucket service is login agnostic, so when accessing for write or private read, you should insert a bucket token (given by services) to your request authorization header as bearer token. **User Bucket** This bucket is used to store public user files for each user. When a user logs in, or in /currentuser response there is `userBucketToken` to be used when sending user related public files to the bucket service. To upload `POST {baseUrl}/bucket/upload` Request body is form data which includes the bucketId and the file as binary in `files` property. ```js { bucketId: "{userId}-public-user-bucket", files: {binary} } ``` Response status is 200 on succesfull result, eg body: ```json { "success": true, "data": [ { "fileId": "9da03f6d-0409-41ad-bb06-225a244ae408", "originalName": "test (10).png", "mimeType": "image/png", "size": 604063, "status": "uploaded", "bucketName": "f7103b85-fcda-4dec-92c6-c336f71fd3a2-public-user-bucket", "isPublic": true, "downloadUrl": "https://babilcom.mindbricks.co/bucket/download/9da03f6d-0409-41ad-bb06-225a244ae408" } ] } ``` To download a file from the bucket, you should know its fileId, so if youupload an avatar or something else, be sure that the download url or the fileId is stored in backend. Bucket is mostly used, in object creations where alos demands an addtional file like a product image or user avatar. So after you upload your image to the bucket, insert the returned download url to the related property in the related object creation. **Application Bucket** This Ebaycclone application alos has common public bucket which everybody has a read access, but only users who have `superAdmin`, `admin` or `saasAdmin` roles can write (upload) to the bucket. The common public project bucket id is `"ebaycclone-public-common-bucket"` and in certain areas like product image uploads, since the user will already have the admin bucket token, he will be able to upload realted object images. Please make your UI arrangements as able to upload files to the bucket using these bucket tokens. **Object Buckets** Some objects may return also a bucket token, to upload or access related files with object. For example, when you get a project's data in a project management application, if there is a public or private bucket token, this is provided mostly for uploading project related files or downloading them with the token. These buckets will be used according to the descriptions given along with the object definitions. ## Role Management This Ebaycclone may have different role names defined fro different business logic. But unless another case is asked by the user, respect to the admin roles which may be `superAdmin`, `admin` or `saasAdmin` in the currentuser or login response given with the `roleId`property. ```json { // ... "roleId":"superAdmin", // ... } ``` If the application needs an admin panel, or any admin related page, please use these roleId's to decide if the user can access those pages or not. ## 1. Authentication Routes ### 1.1 `POST /login` — User Login **Purpose:** Verifies user credentials and creates an authenticated session with a JWT access token. **Access Routes:** * `GET /login`: Returns a minimal HTML login page (for browser-based testing). * `POST /login`: Authenticates user credentials and returns an access token and session. #### Request Parameters | Parameter | Type | Required | Source | | ---------- | ------ | -------- | ----------------------- | | `username` | String | Yes | `request.body.username` | | `password` | String | Yes | `request.body.password` | #### Behavior * Authenticates credentials and returns a session object. * Sets cookie: `projectname-access-token[-tenantCodename]` * Adds the same token in response headers. * Accepts either `username` or `email` fields (if both exist, `username` is prioritized). #### Example ```js axios.post("/login", { username: "user@example.com", password: "securePassword" }); ``` #### Success Response ```json { "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", //... } ``` #### Error Responses * `401 Unauthorized`: Invalid credentials * `403 Forbidden`: Email/mobile verification or 2FA pending * `400 Bad Request`: Missing parameters --- ### 1.2 `POST /logout` — User Logout **Purpose:** Terminates the current session and clears associated authentication tokens. #### Behavior * Invalidates session (if exists). * Clears cookie `projectname-access-token[-tenantCodename]`. * Returns a confirmation response (always `200 OK`). #### Example ```js axios.post("/logout", {}, { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` #### Notes * Can be called without a session (idempotent behavior). * Works for both cookie-based and token-based sessions. #### Success Response ```json { "status": "OK", "message": "User logged out successfully" } ``` --- ## 2. Verification Services Overview All verification routes are grouped under the `/verification-services` base path. They follow a **two-step verification pattern**: `start` → `complete`. --- ## 3. Email Verification ### 3.1 Trigger Scenarios * After registration (`emailVerificationRequiredForLogin` = true) * When updating email address * When login fails due to unverified email ### 3.2 Flow Summary 1. `/start` → Generate & send code via email. 2. `/complete` → Verify code and mark email as verified. ** PLEASE NOTE ** Email verification is a frontend triiggered process. After user registers, the frontend should start the email verification process and navigate to its code input page. --- ### 3.3 `POST /verification-services/email-verification/start` **Purpose:** Starts the email verification by generating and sending a secret code. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `email` | String | Yes | User’s email address to verify | **Example Request** ```json { "email": "user@example.com" } ``` **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ In production, `secretCode` is **not** returned — only sent via email. **Error Responses** * `400 Bad Request`: Already verified * `403 Forbidden`: Too many attempts (rate limit) --- ### 3.4 `POST /verification-services/email-verification/complete` **Purpose:** Completes the verification using the received code. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `email` | String | Yes | User’s email | | `secretCode` | String | Yes | Verification code | **Success Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` **Error Responses** * `403 Forbidden`: Code expired or mismatched * `404 Not Found`: No verification in progress --- ### 3.5 Behavioral Notes * **Resend Cooldown:** `resendTimeWindow` (e.g. 60s) * **Expiration:** Codes expire after `expireTimeWindow` (e.g. 1 day) * **Single Active Session:** One verification per user --- ## 4. Mobile Verification ### 4.1 Trigger Scenarios * After registration (`mobileVerificationRequiredForLogin` = true) * When updating phone number * On login requiring mobile verification ### 4.2 Flow 1. `/start` → Sends verification code via SMS 2. `/complete` → Validates code and confirms number --- ### 4.3 `POST /verification-services/mobile-verification/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------ | | `email` | String | Yes | User’s email to locate mobile record | **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 180, "verificationType": "byCode", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ `secretCode` returned only in development. **Errors** * `400 Bad Request`: Already verified * `403 Forbidden`: Rate-limited --- ### 4.4 `POST /verification-services/mobile-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------------- | | `email` | String | Yes | Associated email | | `secretCode` | String | Yes | Code received via SMS | **Success Response** ```json { "status": "OK", "isVerified": true, "mobile": "+1 333 ...", // in testMode "userId": "user-uuid", } ``` --- ### 4.5 Behavioral Notes * **Cooldown:** One code per minute * **Expiration:** Codes valid for 1 day * **One Session Per User** --- ## 5. Two-Factor Authentication (2FA) ### 5.1 Email 2FA **Flow** 1. `/start` → Generates and sends email code 2. `/complete` → Verifies code and updates session --- #### `POST /verification-services/email-2factor-verification/start` | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ---------------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Current session | | `client` | String | No | Optional context | | `reason` | String | No | Reason for 2FA | **Response** ```json { "status": "OK", "sessionId": "user session id UUID", "userId": "user-uuid", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", } ``` --- #### `POST /verification-services/email-2factor-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `secretCode` | String | Yes | Code from email | **Response** ```json { // user session data "sessionId": "session-uuid", // ... } ``` --- ### 5.2 Mobile 2FA **Flow** 1. `/start` → Sends SMS code 2. `/complete` → Validates and finalizes session --- #### `POST /verification-services/mobile-2factor-verification/start` | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ----------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `client` | String | No | Context | | `reason` | String | No | Reason | **Response** ```json { "status": "OK", "sessionId": "user session id UUID", "userId": "user-uuid", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", } ``` --- #### `POST /verification-services/mobile-2factor-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------ | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `secretCode` | String | Yes | Code via SMS | **Response** ```json { // user session data "sessionId": "session-uuid", // ... } ``` --- ### 5.3 2FA Behavioral Notes * One active code per session * Cooldown: `resendTimeWindow` (e.g., 60s) * Expiration: `expireTimeWindow` (e.g., 5m) --- ## 6. Password Reset ### 6.1 By Email **Flow** 1. `/start` → Sends verification code via email 2. `/complete` → Validates and resets password --- #### `POST /verification-services/password-reset-by-email/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------- | | `email` | String | Yes | User email | **Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` #### `POST /verification-services/password-reset-by-email/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------- | | `email` | String | Yes | User email | | `secretCode` | String | Yes | Code received | | `password` | String | Yes | New password | **Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` --- ### 6.2 By Mobile **Flow** 1. `/start` → Sends SMS code 2. `/complete` → Validates and resets password --- #### `POST /verification-services/password-reset-by-mobile/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------- | | `mobile` | String | Yes | Mobile number | **Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` #### `POST /verification-services/password-reset-by-mobile/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ---------------- | | `email` | String | Yes | Associated email | | `secretCode` | String | Yes | Code via SMS | | `password` | String | Yes | New password | **Response** ```json { "status": "OK", "isVerified": true, "mobile": "+1 444 ....", // in testMode "userId": "user-uuid", } ``` --- ### 6.3 Behavioral Notes * Cooldown: 60s resend * Expiration: 24h * One session per user * Works without an active login session --- ## 7. Verification Method Types ### 7.1 `byCode` User manually enters the 6-digit code in frontend. ### 7.2 `byLink` Frontend handles a one-click verification via email/SMS link containing code parameters. ## 8) `GET /currentuser` — Current Session **Purpose** Return the currently authenticated user’s session. **Route Type** `sessionInfo` **Authentication** Requires a valid access token (header or cookie). ### Request *No parameters.* ### Example ```js axios.get("/currentuser", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) Returns the session object (identity, tenancy, token metadata): ```json { "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", "roleId": "user", "tenantId": "abc123", "accessToken": "jwt-token-string", "...": "..." } ``` ### Errors * **401 Unauthorized** — No active session/token ```json { "status": "ERR", "message": "No login found" } ``` **Notes** * Commonly called by web/mobile clients after login to hydrate session state. * Includes key identity/tenant fields and a token reference (if applicable). * Ensure a valid token is supplied to receive a 200 response. --- ## 9) `GET /permissions` — List Effective Permissions **Purpose** Return all effective permission grants for the current user. **Route Type** `permissionFetch` **Authentication** Requires a valid access token. ### Request *No parameters.* ### Example ```js axios.get("/permissions", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) Array of permission grants (aligned with `givenPermissions`): ```json [ { "id": "perm1", "permissionName": "adminPanel.access", "roleId": "admin", "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" }, { "id": "perm2", "permissionName": "orders.manage", "roleId": null, "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" } ] ``` **Field meanings (per item):** * `permissionName`: Granted permission key. * `roleId`: Present if granted via role. * `subjectUserId`: Present if granted directly to the user. * `subjectUserGroupId`: Present if granted via group. * `objectId`: Present if scoped to a specific object (OBAC). * `canDo`: `true` if enabled, `false` if restricted. ### Errors * **401 Unauthorized** — No active session ```json { "status": "ERR", "message": "No login found" } ``` * **500 Internal Server Error** — Unexpected failure **Notes** * Available on all Mindbricks-generated services (not only Auth). * **Auth service:** Reads live `givenPermissions` from DB. * **Other services:** Typically respond from a cached/projected view (e.g., ElasticSearch) for faster checks. > **Tip:** Cache permission results client-side/server-side and refresh after login or permission updates. --- ## 10) `GET /permissions/:permissionName` — Check Permission Scope **Purpose** Check whether the current user has a specific permission and return any scoped object exceptions/inclusions. **Route Type** `permissionScopeCheck` **Authentication** Requires a valid access token. ### Path Parameters | Name | Type | Required | Source | | ---------------- | ------ | -------- | ------------------------------- | | `permissionName` | String | Yes | `request.params.permissionName` | ### Example ```js axios.get("/permissions/orders.manage", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) ```json { "canDo": true, "exceptions": [ "a1f2e3d4-xxxx-yyyy-zzzz-object1", "b2c3d4e5-xxxx-yyyy-zzzz-object2" ] } ``` **Interpretation** * If `canDo: true`: permission is generally granted **except** the listed `exceptions` (restrictions). * If `canDo: false`: permission is generally **not** granted, **only** allowed for the listed `exceptions` (selective overrides). * `exceptions` contains object IDs (UUID strings) from the relevant domain model. ### Errors * **401 Unauthorized** — No active session/token. ## Services And Data Object ## Auth Service Authentication service for the project ### Auth Service Data Objects **User** A data object that stores the user information and handles login settings. ### Auth Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` ### `Get User` API This api is used by admin roles or the users themselves to get the user profile information. **Rest Route** The `getUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `getUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users/:userId** ```js axios({ method: 'GET', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update User` API This route is used by admins to update user profiles. **Rest Route** The `updateUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `updateUser` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/users/:userId** ```js axios({ method: 'PATCH', url: `/v1/users/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Profile` API This route is used by users to update their profiles. **Rest Route** The `updateProfile` API REST controller can be triggered via the following route: `/v1/profile/:userId` **Rest Request Parameters** The `updateProfile` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/profile/:userId** ```js axios({ method: 'PATCH', url: `/v1/profile/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create User` API This api is used by admin roles to create a new user manually from admin panels **Rest Route** The `createUser` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `createUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | email | String | true | request.body?.email | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **email** : A string value to represent the user's email. **password** : A string value to represent the user's password. It will be stored as hashed. **fullname** : A string value to represent the fullname of the user **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/users** ```js axios({ method: 'POST', url: '/v1/users', data: { avatar:"String", email:"String", password:"String", fullname:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete User` API This api is used by admins to delete user profiles. **Rest Route** The `deleteUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `deleteUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/users/:userId** ```js axios({ method: 'DELETE', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Archive Profile` API This api is used by users to archive their profiles. **Rest Route** The `archiveProfile` API REST controller can be triggered via the following route: `/v1/archiveprofile/:userId` **Rest Request Parameters** The `archiveProfile` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/archiveprofile/:userId** ```js axios({ method: 'DELETE', url: `/v1/archiveprofile/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Users` API The list of users is filtered by the tenantId. **Rest Route** The `listUsers` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `listUsers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users** ```js axios({ method: 'GET', url: '/v1/users', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Search Users` API The list of users is filtered by the tenantId. **Rest Route** The `searchUsers` API REST controller can be triggered via the following route: `/v1/searchusers` **Rest Request Parameters** The `searchUsers` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | keyword | String | true | request.query?.keyword | **keyword** : **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchusers** ```js axios({ method: 'GET', url: '/v1/searchusers', data: { }, params: { keyword:'"String"', } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Userrole` API This route is used by admin roles to update the user role.The default role is user when a user is registered. A user's role can be updated by superAdmin or admin **Rest Route** The `updateUserRole` API REST controller can be triggered via the following route: `/v1/userrole/:userId` **Rest Request Parameters** The `updateUserRole` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | roleId | String | true | request.body?.roleId | **userId** : This id paremeter is used to select the required data object that will be updated **roleId** : The new roleId of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userrole/:userId** ```js axios({ method: 'PATCH', url: `/v1/userrole/${userId}`, data: { roleId:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpassword` API This route is used to update the password of users in the profile page by users themselves **Rest Route** The `updateUserPassword` API REST controller can be triggered via the following route: `/v1/userpassword/:userId` **Rest Request Parameters** The `updateUserPassword` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | oldPassword | String | true | request.body?.oldPassword | | newPassword | String | true | request.body?.newPassword | **userId** : This id paremeter is used to select the required data object that will be updated **oldPassword** : The old password of the user that will be overridden bu the new one. Send for double check. **newPassword** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpassword/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpassword/${userId}`, data: { oldPassword:"String", newPassword:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpasswordbyadmin` API This route is used to change any user password by admins only. Superadmin can chnage all passwords, admins can change only nonadmin passwords **Rest Route** The `updateUserPasswordByAdmin` API REST controller can be triggered via the following route: `/v1/userpasswordbyadmin/:userId` **Rest Request Parameters** The `updateUserPasswordByAdmin` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | password | String | true | request.body?.password | **userId** : This id paremeter is used to select the required data object that will be updated **password** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpasswordbyadmin/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpasswordbyadmin/${userId}`, data: { password:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Briefuser` API This route is used by public to get simple user profile information. **Rest Route** The `getBriefUser` API REST controller can be triggered via the following route: `/v1/briefuser/:userId` **Rest Request Parameters** The `getBriefUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/briefuser/:userId** ```js axios({ method: 'GET', url: `/v1/briefuser/${userId}`, data: { }, params: { } }); ``` **REST Response** This route's response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "fullname": "String", "avatar": "String", "isActive": true } } ``` ### `Register User` API This api is used by public users to register themselves **Rest Route** The `registerUser` API REST controller can be triggered via the following route: `/v1/registeruser` **Rest Request Parameters** The `registerUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **password** : The password defined by the the user that is being registered. **fullname** : The fullname defined by the the user that is being registered. **email** : The email defined by the the user that is being registered. **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## AuctionOffer Service Handles auction bids and fixed-price offers for product listings, enforces real-time auction state, handles strict offer workflows including counter-offers, and triggers domain events for bid/offer notifications. No payment or frontend aggregation logic included. ### AuctionOffer Service Data Objects **AuctionOfferOffer** Represents an offer (best offer/counter-offer) made on a fixed-price product. Tracks buyer, seller, amounts, currency, state transitions, counter-offers, and expiry. **AuctionOfferBid** Represents an individual bid placed on an auction-type product. Linked to product and user, tracks bid amount, currency, status (ACTIVE, WON, LOST, CANCELLED), and time placed. ### AuctionOffer Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auctionoffer-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auctionoffer-api` * **Production:** `https://ebaycclone.mindbricks.co/auctionoffer-api` ### `Update Auctionofferoffer` API Updates offer: accepts/declines/counters by seller, withdraws by buyer before response. Enforces status transition rules, sets respondedAt. Triggers event. **Rest Route** The `updateAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `updateAuctionOfferOffer` api has got 8 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | message | String | false | request.body?.message | | status | Enum | false | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | **auctionOfferOfferId** : This id paremeter is used to select the required data object that will be updated **counterOfferId** : References another offer (counter-offer chain). **counterMessage** : Message accompanying seller's counter-offer (optional). **counterAmount** : Counter-offer amount (when offer is COUNTERED). **message** : Message/special notes from buyer (optional). **status** : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). **expiresAt** : When this offer expires (optional). **respondedAt** : When the seller (or buyer, for counter-offer) responded/updated the offer status. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Auctionofferbid` API Creates a new bid for an auction product. Validates auction status, not seller, product type, bid window, and ensures min. increment. Updates product.currentBid and product.highestBidderId atomically. Triggers notification event. **Rest Route** The `createAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids` **Rest Request Parameters** The `createAuctionOfferBid` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | bidAmount | Double | true | request.body?.bidAmount | | currency | String | true | request.body?.currency | | status | Enum | true | request.body?.status | | productId | ID | true | request.body?.productId | **bidAmount** : Bid amount placed by the user. **currency** : ISO currency for the bid (e.g., USD, EUR). **status** : Bid status: ACTIVE, WON, LOST, CANCELLED. **productId** : Product being bid on (must be AUCTION type). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/auctionofferbids** ```js axios({ method: 'POST', url: '/v1/auctionofferbids', data: { bidAmount:"Double", currency:"String", status:"Enum", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Auctionofferbid` API Gets a single bid (only visible to owner/admin or for auction history). **Rest Route** The `getAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `getAuctionOfferBid` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | **auctionOfferBidId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'GET', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Auctionofferoffer` API Gets a single offer (shown to buyer/seller or admin). **Rest Route** The `getAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `getAuctionOfferOffer` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | **auctionOfferOfferId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'GET', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Auctionofferoffers` API Lists offers by product, user, status, or counterOffer chain. **Rest Route** The `listAuctionOfferOffers` API REST controller can be triggered via the following route: `/v1/auctionofferoffers` **Rest Request Parameters** The `listAuctionOfferOffers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers** ```js axios({ method: 'GET', url: '/v1/auctionofferoffers', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferOffers": [ { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Auctionofferbid` API Updates a bid’s status (allow only status update, e.g. CANCELLED, WIN/LOSE on admin settlement). Only owner/admin, and only if auction not ended or not settled. Triggers notification event. **Rest Route** The `updateAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `updateAuctionOfferBid` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | | status | Enum | false | request.body?.status | **auctionOfferBidId** : This id paremeter is used to select the required data object that will be updated **status** : Bid status: ACTIVE, WON, LOST, CANCELLED. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { status:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Auctionofferoffer` API Creates a new offer for a fixed-price product, validating acceptOffers, type, eligibility, and product/seller/buyer active. Defaults to PENDING state. Triggers notification event. **Rest Route** The `createAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers` **Rest Request Parameters** The `createAuctionOfferOffer` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | productId | ID | true | request.body?.productId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | offerAmount | Double | true | request.body?.offerAmount | | message | String | false | request.body?.message | | status | Enum | true | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | **currency** : ISO currency (e.g., USD, EUR) for the offer. **productId** : Product the offer applies to (must be fixed-price, acceptOffers true). **counterOfferId** : References another offer (counter-offer chain). **counterMessage** : Message accompanying seller's counter-offer (optional). **counterAmount** : Counter-offer amount (when offer is COUNTERED). **offerAmount** : Primary offer amount from buyer. **message** : Message/special notes from buyer (optional). **status** : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). **expiresAt** : When this offer expires (optional). **respondedAt** : When the seller (or buyer, for counter-offer) responded/updated the offer status. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/auctionofferoffers** ```js axios({ method: 'POST', url: '/v1/auctionofferoffers', data: { currency:"String", productId:"ID", counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", offerAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Auctionofferbids` API Lists bids by product, user, or auction, supports history/analytics. **Rest Route** The `listAuctionOfferBids` API REST controller can be triggered via the following route: `/v1/auctionofferbids` **Rest Request Parameters** The `listAuctionOfferBids` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids** ```js axios({ method: 'GET', url: '/v1/auctionofferbids', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBids", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferBids": [ { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Auctionofferbid` API Soft-deletes a bid (for admin or self before auction ends). **Rest Route** The `deleteAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `deleteAuctionOfferBid` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | **auctionOfferBidId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Auctionofferoffer` API Soft-deletes an offer (allowed only in non-accepted/expired state). **Rest Route** The `deleteAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `deleteAuctionOfferOffer` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | **auctionOfferOfferId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## CategoryManagement Service Handles product categories and subcategories for marketplace browsing and classification, supporting public discovery plus admin-only management. ### CategoryManagement Service Data Objects **Category** Represents a product category in the marketplace (e.g., Electronics, Clothing, Toys), used for browsing, filtering, and discovery. Admins manage categories. **Subcategory** Represents a subcategory within a parent category (e.g., 'Smartphones' under 'Electronics'). Used for more granular product discovery and navigation. 'group' categorizes special display logic. ### CategoryManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/categorymanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/categorymanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/categorymanagement-api` ### `Delete Category` API Soft-delete a category (admin-only). **Rest Route** The `deleteCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `deleteCategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | **categoryId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/categories/:categoryId** ```js axios({ method: 'DELETE', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Subcategory` API Get a subcategory by ID. Public - only active subcategories returned except for admin. **Rest Route** The `getSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `getSubcategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | **subcategoryId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/subcategories/:subcategoryId** ```js axios({ method: 'GET', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Category` API Get a single category by ID. Public - only active categories returned (for non-admins). **Rest Route** The `getCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `getCategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | **categoryId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/categories/:categoryId** ```js axios({ method: 'GET', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Subcategory` API Update subcategory (admin-only), including group enum change. **Rest Route** The `updateSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `updateSubcategory` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | name | String | false | request.body?.name | | group | Enum | false | request.body?.group | **subcategoryId** : This id paremeter is used to select the required data object that will be updated **categoryId** : Reference to the parent category (category.id). **name** : Display name of the subcategory. **group** : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/subcategories/:subcategoryId** ```js axios({ method: 'PATCH', url: `/v1/subcategories/${subcategoryId}`, data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Subcategories` API List all subcategories for browsing/filtering, with support for group enum and parent category queries. Only active subcategories shown to public/non-admin users. **Rest Route** The `listSubcategories` API REST controller can be triggered via the following route: `/v1/subcategories` **Rest Request Parameters** The `listSubcategories` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/subcategories** ```js axios({ method: 'GET', url: '/v1/subcategories', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "subcategories": [ { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Subcategory` API Soft-delete a subcategory (admin-only). **Rest Route** The `deleteSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `deleteSubcategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | **subcategoryId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/subcategories/:subcategoryId** ```js axios({ method: 'DELETE', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Categories` API List all categories for browsing and filtering. Only active categories shown to public/non-admin users. **Rest Route** The `listCategories` API REST controller can be triggered via the following route: `/v1/categories` **Rest Request Parameters** The `listCategories` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/categories** ```js axios({ method: 'GET', url: '/v1/categories', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "categories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "categories": [ { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Category` API Update category details (admin-only). **Rest Route** The `updateCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `updateCategory` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | false | request.body?.title | **categoryId** : This id paremeter is used to select the required data object that will be updated **imageUrl** : URL for category image/avatar (optional, used for homepage visuals). **subtitle** : Optional short description for UI/tooltips. **title** : Display name of the category. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/categories/:categoryId** ```js axios({ method: 'PATCH', url: `/v1/categories/${categoryId}`, data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Subcategory` API Create a new subcategory under a given category (admin-only), with enum group constraint. **Rest Route** The `createSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories` **Rest Request Parameters** The `createSubcategory` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.body?.categoryId | | name | String | true | request.body?.name | | group | Enum | true | request.body?.group | **categoryId** : Reference to the parent category (category.id). **name** : Display name of the subcategory. **group** : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/subcategories** ```js axios({ method: 'POST', url: '/v1/subcategories', data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Category` API Create a new category (admin-only) for product classification. **Rest Route** The `createCategory` API REST controller can be triggered via the following route: `/v1/categories` **Rest Request Parameters** The `createCategory` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | true | request.body?.title | **imageUrl** : URL for category image/avatar (optional, used for homepage visuals). **subtitle** : Optional short description for UI/tooltips. **title** : Display name of the category. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/categories** ```js axios({ method: 'POST', url: '/v1/categories', data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## Messaging Service In-app messaging service for direct user-to-user text messages (buyers/sellers). Stores, retrieves, and manages user conversations. Launch version: text-only. ### Messaging Service Data Objects **MessagingMessage** A direct, text-only in-app message between two users (buyer/seller); stores sender, recipient, content, read status, and timestamp. ### Messaging Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/messaging-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/messaging-api` * **Production:** `https://ebaycclone.mindbricks.co/messaging-api` ### `List Messagingmessages` API List all messages in the conversation between the logged-in user and another party, ordered by sentAt descending. Can filter unread with isRead. Returns only messages visible to user (isActive). **Rest Route** The `listMessagingMessages` API REST controller can be triggered via the following route: `/v1/messagingmessages` **Rest Request Parameters** The `listMessagingMessages` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages** ```js axios({ method: 'GET', url: '/v1/messagingmessages', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessages", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "messagingMessages": [ { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Messagingmessage` API Send a new text message from the logged-in user to a recipient. Sender is set from session. Launch version supports only text content. **Rest Route** The `createMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages` **Rest Request Parameters** The `createMessagingMessage` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | toUserId | ID | true | request.body?.toUserId | | content | String | true | request.body?.content | | isRead | Boolean | true | request.body?.isRead | **toUserId** : Recipient (user) of this message. **content** : Text content of the message. No files or attachments for launch. **isRead** : If true, recipient has marked this message as read. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/messagingmessages** ```js axios({ method: 'POST', url: '/v1/messagingmessages', data: { toUserId:"ID", content:"String", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Messagingmessage` API Update a message (mark as read/unread). Only the recipient or admin can change isRead. No content edits. Sender, content, sentAt are immutable. **Rest Route** The `updateMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `updateMessagingMessage` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | | isRead | Boolean | false | request.body?.isRead | **messagingMessageId** : This id paremeter is used to select the required data object that will be updated **isRead** : If true, recipient has marked this message as read. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'PATCH', url: `/v1/messagingmessages/${messagingMessageId}`, data: { isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Messagingmessage` API Get a message by ID. Only accessible to the sender, the recipient, or an admin. Used for message detail view or reading a single message in a thread. **Rest Route** The `getMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `getMessagingMessage` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | **messagingMessageId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'GET', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Messagingmessage` API Delete a message (soft-delete). Only sender, recipient, or admin may delete a message. Deletion only hides it for the user; not a full erase unless both delete. **Rest Route** The `deleteMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `deleteMessagingMessage` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | **messagingMessageId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'DELETE', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## NotificationManagement Service Handles storage, management, and event-driven delivery of in-app and email notifications for user-impacting system events (bids, offers, orders, feedback, messaging, etc.). Supports marking notifications as read/unread, structured filtering by event type/channel, and always returns in-app notifications ordered by recency. ### NotificationManagement Service Data Objects **Notification** Stores and manages in-app and email notifications tied to user-facing events like bids, offers, orders, messaging, shipment, and feedback. Includes event type (notificationType) for filter/search, arbitrary event payload, and delivery channel. Soft-delete enforced. In-app notifications always sorted by createdAt DESC on retrieval. ### NotificationManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/notificationmanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/notificationmanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/notificationmanagement-api` ### `Create Notification` API Creates a notification entry in response to a system/business event. Only allowed for system/event processes and admins (not standard user/action). Typically event-driven, receives userId, notificationType, payload, and channel. **Rest Route** The `createNotification` API REST controller can be triggered via the following route: `/v1/notifications` **Rest Request Parameters** The `createNotification` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationType | Enum | true | request.body?.notificationType | | userId | ID | true | request.body?.userId | | channel | Enum | true | request.body?.channel | | payload | Object | true | request.body?.payload | | isRead | Boolean | true | request.body?.isRead | **notificationType** : Type of event triggering notification (e.g., BID_UPDATED, ORDER_SHIPPED, MESSAGE_RECEIVED, etc.). Used for display/icon and query filter. **userId** : User receiving the notification (recipient). **channel** : Channel by which notification is delivered: IN_APP or EMAIL. **payload** : Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. **isRead** : Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/notifications** ```js axios({ method: 'POST', url: '/v1/notifications', data: { notificationType:"Enum", userId:"ID", channel:"Enum", payload:"Object", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Notification` API Updates a notification (mark as read/unread, payload patch for e.g. admin fix). Only receiver (userId) or admins may update. isRead is primary update scenario; others very limited. **Rest Route** The `updateNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `updateNotification` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | | payload | Object | false | request.body?.payload | | isRead | Boolean | false | request.body?.isRead | **notificationId** : This id paremeter is used to select the required data object that will be updated **payload** : Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. **isRead** : Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/notifications/:notificationId** ```js axios({ method: 'PATCH', url: `/v1/notifications/${notificationId}`, data: { payload:"Object", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Notifications` API Returns filtered list of notifications for a user, with optional filters: notificationType, isRead, channel. Always sorted by createdAt (descending) for in-app notifications. Only retrieval allowed for owner/admin. **Rest Route** The `listNotifications` API REST controller can be triggered via the following route: `/v1/notifications` **Rest Request Parameters** The `listNotifications` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/notifications** ```js axios({ method: 'GET', url: '/v1/notifications', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notifications", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "notifications": [ { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Notification` API Soft-delete a notification record. Only receiver or admin may delete. **Rest Route** The `deleteNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `deleteNotification` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | **notificationId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/notifications/:notificationId** ```js axios({ method: 'DELETE', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Notification` API Retrieves a notification for the receiver or admin. Used to populate content on detail/expanded view. **Rest Route** The `getNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `getNotification` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | **notificationId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/notifications/:notificationId** ```js axios({ method: 'GET', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## SearchIndexing Service Maintains the denormalized search index (materialized view) for global, public search across products, sellers, categories, and subcategories. Handles indexing in response to entity events and exposes optimized query endpoints for BFF/aggregator. ### SearchIndexing Service Data Objects **SearchIndex** Materialized/denormalized search index record for a marketplace entity (product, seller, category, subcategory). Used exclusively for high-speed querying in BFF global/public search. ### SearchIndexing Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/searchindexing-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/searchindexing-api` * **Production:** `https://ebaycclone.mindbricks.co/searchindexing-api` ### `List Searchindexes` API List/search search index entries by type or referenceId (used by BFF/global search). Always excludes inactive (soft-deleted) records. Supports filtering and full-text search filters by documentType/referenceId for admin/maintenance use. **Rest Route** The `listSearchIndexes` API REST controller can be triggered via the following route: `/v1/searchindexes` **Rest Request Parameters** The `listSearchIndexes` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchindexes** ```js axios({ method: 'GET', url: '/v1/searchindexes', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndices", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "searchIndices": [ { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Searchindex` API Update an existing searchIndex record (by (documentType, referenceId) or id). Used in response to events (entity edit, data change); internal/automation/admin only. **Rest Route** The `updateSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `updateSearchIndex` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | | documentType | Enum | false | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | false | request.body?.indexedAt | **searchIndexId** : This id paremeter is used to select the required data object that will be updated **documentType** : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY **document** : Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. **referenceId** : ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. **indexedAt** : Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/searchindexs/:searchIndexId** ```js axios({ method: 'PATCH', url: `/v1/searchindexs/${searchIndexId}`, data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Searchindex` API Soft-delete a searchIndex record (by id or by (documentType, referenceId)). Typical use: in response to entity soft-delete; internal/automation/admin only. **Rest Route** The `deleteSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `deleteSearchIndex` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | **searchIndexId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/searchindexs/:searchIndexId** ```js axios({ method: 'DELETE', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Searchindex` API Create a new searchIndex record (internal, used by event triggers and admin tools only). Typically called when a new product/seller/category/subcategory is created. **Rest Route** The `createSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs` **Rest Request Parameters** The `createSearchIndex` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | documentType | Enum | true | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | true | request.body?.indexedAt | **documentType** : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY **document** : Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. **referenceId** : ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. **indexedAt** : Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/searchindexs** ```js axios({ method: 'POST', url: '/v1/searchindexs', data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Searchindex` API Get a single denormalized index record (by id, or documentType+referenceId). Used by BFF for full entity search. Always excludes inactive records unless forced (admin only path). **Rest Route** The `getSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `getSearchIndex` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | **searchIndexId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchindexs/:searchIndexId** ```js axios({ method: 'GET', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## AdminModeration Service Administrative backend service for moderation and manual override actions. Responsible for logging all admin interventions (user/product/feedback/media/category/order/notification/searchindex moderation), triggering corrections via interservice calls, and providing comprehensive audit trails for compliance. ### AdminModeration Service Data Objects **ModerationAction** Audit record for all admin moderation/override actions affecting core business entities. Links to admin, timestamp, entity type/ID, action performed, and reason. ### AdminModeration Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/adminmoderation-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/adminmoderation-api` * **Production:** `https://ebaycclone.mindbricks.co/adminmoderation-api` ### `Get Moderationaction` API Get a single moderation action log by ID. Used to review admin audit trails; accessible only to platform admins. **Rest Route** The `getModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `getModerationAction` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | **moderationActionId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/moderationactions/:moderationActionId** ```js axios({ method: 'GET', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Moderationaction` API Soft-deletes a moderation action log record (dangerous; allowed only to superadmins or strict manual correction), primarily for audit correction or internal error cleanup. Usually, moderation logs are immutable. **Rest Route** The `deleteModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `deleteModerationAction` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | **moderationActionId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/moderationactions/:moderationActionId** ```js axios({ method: 'DELETE', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Moderationaction` API Logs an admin moderation or override action in the system for audit and traceability. Requires admin login, takes context from session, and creates an audit entry for any admin operation over any entity type. **Rest Route** The `createModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions` **Rest Request Parameters** The `createModerationAction` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | entityId | ID | true | request.body?.entityId | | entityType | Enum | true | request.body?.entityType | | reason | String | true | request.body?.reason | | actionType | Enum | true | request.body?.actionType | **entityId** : ID of target entity affected by moderation (user/product/etc). **entityType** : Type of entity affected (USER, PRODUCT, FEEDBACK, MEDIA, CATEGORY, NOTIFICATION, ORDER, SEARCHINDEX). **reason** : Explanation or justification for the moderation action performed. **actionType** : Type of moderation action (e.g., SOFT_DELETE, RESTORE, UPDATE_ROLE, MANUAL_CORRECTION, MEDIA_FLAG, INDEX_REBUILD, PAYMENT_FIX, FEEDBACK_OVERRIDE, ADMIN_NOTE). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/moderationactions** ```js axios({ method: 'POST', url: '/v1/moderationactions', data: { entityId:"ID", entityType:"Enum", reason:"String", actionType:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Moderationactions` API List moderation actions for admin dashboard/audit search. Supports filtering by admin, entityType, entityId, actionType, and date. Always sorted by most recent action. **Rest Route** The `listModerationActions` API REST controller can be triggered via the following route: `/v1/moderationactions` **Rest Request Parameters** The `listModerationActions` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/moderationactions** ```js axios({ method: 'GET', url: '/v1/moderationactions', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationActions", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "moderationActions": [ { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Moderationaction` API Allows update of explanation/note on a moderation action for correction (typically by admin or superadmin only). No entity/type/admin may be changed after creation; only 'reason' is editable for audit consistency. **Rest Route** The `updateModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `updateModerationAction` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | | reason | String | false | request.body?.reason | **moderationActionId** : This id paremeter is used to select the required data object that will be updated **reason** : Explanation or justification for the moderation action performed. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/moderationactions/:moderationActionId** ```js axios({ method: 'PATCH', url: `/v1/moderationactions/${moderationActionId}`, data: { reason:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## WatchlistCart Service Handles user watchlists (with custom folders) and shopping cart preparation for checkout, strictly enforcing only fixed-price products in carts, supporting item moves/bulk operations, and robust default/folder logic.. ### WatchlistCart Service Data Objects **WatchlistItem** Item in a user’s watchlist, optionally in a named folder; references product and user. **CartItem** Single product pending checkout in a user’s cart. Only fixed-price products permitted; quantity supported for multi-unit purchases (if allowed). **WatchlistList** A named folder/list in a user’s watchlist. Default list exists for all users. Custom lists may be created and deleted. ### WatchlistCart Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/watchlistcart-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/watchlistcart-api` * **Production:** `https://ebaycclone.mindbricks.co/watchlistcart-api` ### `List Watchlistlist` API List all lists in user’s watchlists. Supports listing by listId for folders. **Rest Route** The `listWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists` **Rest Request Parameters** The `listWatchlistList` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/watchlistlists** ```js axios({ method: 'GET', url: '/v1/watchlistlists', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Cartitems` API List all cart items for a user (pending checkout). **Rest Route** The `listCartItems` API REST controller can be triggered via the following route: `/v1/cartitems` **Rest Request Parameters** The `listCartItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/cartitems** ```js axios({ method: 'GET', url: '/v1/cartitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "price": "Double", "title": "String", "type": "Enum", "type_idx": "Integer", "mediaAssetIds": "ID" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Cartitem` API Remove an item from the user’s cart. **Rest Route** The `deleteCartItem` API REST controller can be triggered via the following route: `/v1/cartitems/:cartItemId` **Rest Request Parameters** The `deleteCartItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | **cartItemId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/cartitems/:cartItemId** ```js axios({ method: 'DELETE', url: `/v1/cartitems/${cartItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Watchlistitem` API Add product to user’s watchlist (default or target list/folder). One (user, product, list) per item enforced. Block duplicates. **Rest Route** The `createWatchlistItem` API REST controller can be triggered via the following route: `/v1/watchlistitems` **Rest Request Parameters** The `createWatchlistItem` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | productId | ID | true | request.body?.productId | | listId | ID | false | request.body?.listId | **addedAt** : Timestamp watchlist item created. **productId** : Referenced product in the watchlist. **listId** : Owning watchlistList; null if in default watchlist. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/watchlistitems** ```js axios({ method: 'POST', url: '/v1/watchlistitems', data: { addedAt:"Date", productId:"ID", listId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Watchlistitems` API List all products in user’s watchlists. Supports listing by listId for folders. **Rest Route** The `listWatchlistItems` API REST controller can be triggered via the following route: `/v1/watchlistitems` **Rest Request Parameters** The `listWatchlistItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/watchlistitems** ```js axios({ method: 'GET', url: '/v1/watchlistitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Cartitemquantity` API Change the quantity for a cart item. User must own the item. **Rest Route** The `updateCartItemQuantity` API REST controller can be triggered via the following route: `/v1/cartitemquantity/:cartItemId` **Rest Request Parameters** The `updateCartItemQuantity` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | | quantity | Integer | false | request.body?.quantity | **cartItemId** : This id paremeter is used to select the required data object that will be updated **quantity** : How many units (if product allows). **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/cartitemquantity/:cartItemId** ```js axios({ method: 'PATCH', url: `/v1/cartitemquantity/${cartItemId}`, data: { quantity:"Integer", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Watchlistlist` API Create a new custom watchlist folder. Name must be unique per user; ‘Default’ is reserved for system. **Rest Route** The `createWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists` **Rest Request Parameters** The `createWatchlistList` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | name | String | true | request.body?.name | **name** : Custom folder or list name. 'Default' is reserved (non-deletable for each user). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/watchlistlists** ```js axios({ method: 'POST', url: '/v1/watchlistlists', data: { name:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Watchlistlist` API Delete a custom watchlist (folder). Items are reassigned to user’s default list. Cannot delete default list. **Rest Route** The `deleteWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists/:watchlistListId` **Rest Request Parameters** The `deleteWatchlistList` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistListId | ID | true | request.params?.watchlistListId | **watchlistListId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistlists/:watchlistListId** ```js axios({ method: 'DELETE', url: `/v1/watchlistlists/${watchlistListId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Watchlistitem` API Remove a product from a user’s watchlist. **Rest Route** The `deleteWatchlistItem` API REST controller can be triggered via the following route: `/v1/watchlistitems/:watchlistItemId` **Rest Request Parameters** The `deleteWatchlistItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistItemId | ID | true | request.params?.watchlistItemId | **watchlistItemId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistitems/:watchlistItemId** ```js axios({ method: 'DELETE', url: `/v1/watchlistitems/${watchlistItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Cartitem` API Add an item to the user’s cart. Only fixed-price products allowed. Duplicates not permitted. **Rest Route** The `createCartItem` API REST controller can be triggered via the following route: `/v1/cartitems` **Rest Request Parameters** The `createCartItem` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | **addedAt** : Timestamp added to cart. **quantity** : How many units (if product allows). **productId** : Product being checked out. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/cartitems** ```js axios({ method: 'POST', url: '/v1/cartitems', data: { addedAt:"Date", quantity:"Integer", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Do Userwatchlist` API userwatchlist **Rest Route** The `userwatchlist` API REST controller can be triggered via the following route: `/v1/userwatchlist` **Rest Request Parameters** The `userwatchlist` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userwatchlist** ```js axios({ method: 'GET', url: '/v1/userwatchlist', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Usercartitems` API list all cart items adde by user **Rest Route** The `listUserCartItems` API REST controller can be triggered via the following route: `/v1/usercartitems` **Rest Request Parameters** The `listUserCartItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/usercartitems** ```js axios({ method: 'GET', url: '/v1/usercartitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "shipping": "Double" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Do Userwatchlistlists` API list all watch lists created by user **Rest Route** The `userwatchlistlists` API REST controller can be triggered via the following route: `/v1/userwatchlistlists` **Rest Request Parameters** The `userwatchlistlists` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userwatchlistlists** ```js axios({ method: 'GET', url: '/v1/userwatchlistlists', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ## ProductListing Service Handles product listings (both auction and fixed-price), image/media storage with validations, enforces immutable type, soft-delete, and public product discovery. ### ProductListing Service Data Objects **ProductListingMedia** Stores and manages images/media associated with products, including secure URL, MIME type, and size validation. Each asset can be used by multiple products. **ProductListingProduct** Represents a single product listing (fixed-price or auction) in the marketplace, with seller, category, type, price information, shipping details, media references, and dynamic auction fields. ### ProductListing Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/productlisting-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/productlisting-api` * **Production:** `https://ebaycclone.mindbricks.co/productlisting-api` ### `List Productlistingmedia` API List all media assets (admin or for media management/bulk preview). **Rest Route** The `listProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias` **Rest Request Parameters** The `listProductListingMedia` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias** ```js axios({ method: 'GET', url: '/v1/productlistingmedias', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedias", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingMedias": [ { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Productlistingproduct` API Get a single product listing. Checks isActive and public status. Includes media, category, subcategory, and seller info via joins. **Rest Route** The `getProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `getProductListingProduct` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | **productListingProductId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'GET', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Productlistingownproducts` API listing the loggedin user's products **Rest Route** The `listProductListingOwnProducts` API REST controller can be triggered via the following route: `/v1/productlistingownproducts` **Rest Request Parameters** The `listProductListingOwnProducts` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingownproducts** ```js axios({ method: 'GET', url: '/v1/productlistingownproducts', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Productlistingmedia` API Get a single media asset by ID (for admin or to display in product UI). **Rest Route** The `getProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` **Rest Request Parameters** The `getProductListingMedia` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | **productListingMediaId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'GET', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Productlistingproducts` API List public product listings. Only isActive=true records are returned. Includes category, subcategory, seller, media joins. Supports filtering. **Rest Route** The `listProductListingProducts` API REST controller can be triggered via the following route: `/v1/productlistingproducts` **Rest Request Parameters** The `listProductListingProducts` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts** ```js axios({ method: 'GET', url: '/v1/productlistingproducts', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Productlistingproduct` API Soft-delete a product listing. Only owner or admin can delete. **Rest Route** The `deleteProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `deleteProductListingProduct` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | **productListingProductId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'DELETE', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Productlistingproduct` API Update a product listing. Product type cannot be changed (immutable). **Rest Route** The `updateProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `updateProductListingProduct` api has got 21 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | | currency | String | false | request.body?.currency | | description | Text | false | request.body?.description | | condition | Enum | false | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | false | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | false | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | false | request.body?.shippingMethod | | shipping | Double | false | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | false | request.body?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | **productListingProductId** : This id paremeter is used to select the required data object that will be updated **currency** : ISO currency code (e.g. USD, EUR) **description** : Product detailed description **condition** : Condition of product: BRAND_NEW, NEW, or USED **startBid** : The opening bid value (for auction type products) **endPrice** : Optional immediate sale/upper end price for auction (if AUCTION type) **price** : Product price (required if fixed price type) **title** : Product title **startPrice** : Minimum starting price for auction (required if AUCTION type) **endBid** : The upper (max) bid value for auction products (if any) **estimatedDelivery** : Estimated delivery date for this product **shippingCurrency** : Currency code for shipping cost **mediaAssetIds** : References to associated product/media assets **shippingMethod** : Shipping option for product: STANDARD, EXPRESS, or FREE **shipping** : Shipping cost for this product **startBidDate** : Date/time when auction bidding begins **subcategoryId** : Reference to subcategory **categoryId** : Reference to parent category **endBidDate** : Date/time when auction bidding ends **currentBid** : Current highest bid for auction-type product (updated atomically on bid placement) **highestBidderId** : User ID of current highest bidder (auction-only, updated by auction microservice) **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'PATCH', url: `/v1/productlistingproducts/${productListingProductId}`, data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Productlistingproduct` API Create a new product listing (fixed or auction), conditioned on product type. Type is immutable after creation. **Rest Route** The `createProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts` **Rest Request Parameters** The `createProductListingProduct` api has got 21 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | description | Text | true | request.body?.description | | condition | Enum | true | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | true | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | type | Enum | true | request.body?.type | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | true | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | true | request.body?.shippingMethod | | shipping | Double | true | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | true | request.body?.subcategoryId | | categoryId | ID | true | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | **currency** : ISO currency code (e.g. USD, EUR) **description** : Product detailed description **condition** : Condition of product: BRAND_NEW, NEW, or USED **startBid** : The opening bid value (for auction type products) **endPrice** : Optional immediate sale/upper end price for auction (if AUCTION type) **price** : Product price (required if fixed price type) **title** : Product title **startPrice** : Minimum starting price for auction (required if AUCTION type) **type** : Product listing type, either FIXED or AUCTION (immutable after creation) **endBid** : The upper (max) bid value for auction products (if any) **estimatedDelivery** : Estimated delivery date for this product **shippingCurrency** : Currency code for shipping cost **mediaAssetIds** : References to associated product/media assets **shippingMethod** : Shipping option for product: STANDARD, EXPRESS, or FREE **shipping** : Shipping cost for this product **startBidDate** : Date/time when auction bidding begins **subcategoryId** : Reference to subcategory **categoryId** : Reference to parent category **endBidDate** : Date/time when auction bidding ends **currentBid** : Current highest bid for auction-type product (updated atomically on bid placement) **highestBidderId** : User ID of current highest bidder (auction-only, updated by auction microservice) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/productlistingproducts** ```js axios({ method: 'POST', url: '/v1/productlistingproducts', data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", type:"Enum", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Productlistingmedia` API Soft-delete a media asset (typically by admin or media owner for flagged/invalid content). **Rest Route** The `deleteProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` **Rest Request Parameters** The `deleteProductListingMedia` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | **productListingMediaId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'DELETE', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Productlistingmedia` API Create a new media asset record after validation. Used mainly by edge controller after upload. **Rest Route** The `createProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias` **Rest Request Parameters** The `createProductListingMedia` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | mimeType | String | true | request.body?.mimeType | | productId | ID | false | request.body?.productId | | url | String | true | request.body?.url | | size | Integer | true | request.body?.size | **mimeType** : MIME type of the uploaded media (e.g., image/jpeg) **productId** : ID of product associated with this media asset **url** : Secure, validated URL for the media asset (S3 or equivalent) **size** : Media size in bytes (for validation and quota) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/productlistingmedias** ```js axios({ method: 'POST', url: '/v1/productlistingmedias', data: { mimeType:"String", productId:"ID", url:"String", size:"Integer", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## OrderManagement Service Handles all marketplace orders, manual checkout flows for fixed-price/offer/auction settlements, Stripe payment processing and webhook reconciliation, explicit status updates (shipping, delivery, cancellation), and feedback eligibility via orderItems. ### OrderManagement Service Data Objects **OrderManagementOrder** Marketplace order record. Stores buyer, shipping, status, items, Stripe payment data, and manual shipment/delivery events. Only accessible to admins or the buyer/seller of order items. **OrderManagementOrderItem** Order line item representing purchase of a single product from a specific seller as part of an order. Enables feedback, delivery, and per-seller analytics. Immutable after order creation. **Sys_orderManagementOrderPayment** A payment storage object to store the payment life cyle of orders based on orderManagementOrder object. It is autocreated based on the source object's checkout config **Sys_paymentCustomer** A payment storage object to store the customer values of the payment platform **Sys_paymentMethod** A payment storage object to store the payment methods of the platform customers ### OrderManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/ordermanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/ordermanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/ordermanagement-api` ### `List Ordermanagementorders` API List orders, filtered for buyer and/or seller, or by admin. Includes select orderItems. **Rest Route** The `listOrderManagementOrders` API REST controller can be triggered via the following route: `/v1/ordermanagementorders` **Rest Request Parameters** The `listOrderManagementOrders` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ordermanagementorders', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Ordermanagementorderitem` API Get a specific order item (for feedback/business logic). **Rest Route** The `getOrderManagementOrderItem` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems/:orderManagementOrderItemId` **Rest Request Parameters** The `getOrderManagementOrderItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderItemId | ID | true | request.params?.orderManagementOrderItemId | **orderManagementOrderItemId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems/:orderManagementOrderItemId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderitems/${orderManagementOrderItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Ordermanagementorder` API Soft-delete/cancel order by admin or eligible actor prior to shipment. Sets status to CANCELLED and cancels active payment intent if pending. Irreversible and blocks feedback. **Rest Route** The `deleteOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` **Rest Request Parameters** The `deleteOrderManagementOrder` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorder` API Get single order by ID. Only accessible to admin, buyer, or relevant sellers of items within this order. Includes all orderItems. **Rest Route** The `getOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` **Rest Request Parameters** The `getOrderManagementOrder` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | **orderManagementOrderId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Ordermanagementorderstatus` API Update order status (manual shipment, delivery, cancellation/refund). Restricted: only seller of all items can mark as shipped, only buyer can confirm delivery, only admin can set refund/cancelled. Timestamps updated as per business rule. **Rest Route** The `updateOrderManagementOrderStatus` API REST controller can be triggered via the following route: `/v1/ordermanagementorderstatus/:orderManagementOrderId` **Rest Request Parameters** The `updateOrderManagementOrderStatus` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **status** : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderstatus/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderstatus/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Complete Orderstripewebhook` API Webhook endpoint called by Stripe to reconcile payment state and update order status based on paymentIntentId and event data. No authentication required (Stripe IPs only). **Rest Route** The `completeOrderStripeWebhook` API REST controller can be triggered via the following route: `/v1/completeorderstripewebhook/:orderManagementOrderId` **Rest Request Parameters** The `completeOrderStripeWebhook` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **status** : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/completeorderstripewebhook/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/completeorderstripewebhook/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderbyproductid` API get orders by productId **Rest Route** The `getOrderManagementOrderByProductId` API REST controller can be triggered via the following route: `/v1/ordermanagementorderbyproductid/:items` **Rest Request Parameters** The `getOrderManagementOrderByProductId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | items | String | true | request.params?.items | **orderManagementOrderId** : This id paremeter is used to query the required data object. **items** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderbyproductid/:items** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderbyproductid/${items}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Ordermanagementorder` API Creates an order and initiates Stripe payment. Validates that all products in the order are fixed-price, populates orderItems, saves Stripe customer/paymentMethod/paymentIntentId for reconciliation. Only accessible to buyers for own checkouts and only allows fixed-price product checkout (no auction). **Rest Route** The `createOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders` **Rest Request Parameters** The `createOrderManagementOrder` api has got 14 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderNumber | String | true | request.body?.orderNumber | | items | ID | false | request.body?.items | | paymentMethodId | String | true | request.body?.paymentMethodId | | stripeCustomerId | String | true | request.body?.stripeCustomerId | | paymentIntentId | String | false | request.body?.paymentIntentId | | shippingAddress | Object | true | request.body?.shippingAddress | | summary | Object | true | request.body?.summary | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderNumber** : Unique, human-friendly order number (displayed to users); enforced unique. **items** : Array of orderManagementOrderItem ids representing items in this order. **paymentMethodId** : Stripe paymentMethodId used for payment. Not stored if cash or other payment (future). **stripeCustomerId** : Stripe customerId of buyer; enables saved/paymentMethodId flows. **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **shippingAddress** : Shipping address for the order (copy of buyer address at purchase time). **summary** : Object with total, subtotal, currency, shipping, discount breakdown as snapshot of order at time of purchase. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorders** ```js axios({ method: 'POST', url: '/v1/ordermanagementorders', data: { orderNumber:"String", items:"ID", paymentMethodId:"String", stripeCustomerId:"String", paymentIntentId:"String", shippingAddress:"Object", summary:"Object", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderitems` API List order items for a given order or for buyer/seller analytics. Used for feedback management. **Rest Route** The `listOrderManagementOrderItems` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems` **Rest Request Parameters** The `listOrderManagementOrderItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Ownordermanagementorders` API list the loggedin user orders **Rest Route** The `listOwnOrderManagementOrders` API REST controller can be triggered via the following route: `/v1/ownordermanagementorders` **Rest Request Parameters** The `listOwnOrderManagementOrders` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ownordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ownordermanagementorders', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Lis Ordermanagementownorderitem` API list the loggedin user's order items **Rest Route** The `lisOrderManagementOwnOrderItem` API REST controller can be triggered via the following route: `/v1/lisordermanagementownorderitem` **Rest Request Parameters** The `lisOrderManagementOwnOrderItem` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/lisordermanagementownorderitem** ```js axios({ method: 'GET', url: '/v1/lisordermanagementownorderitem', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Ordermanagementorderitem` API create order item **Rest Route** The `createOrderManagementOrderItem` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems` **Rest Request Parameters** The `createOrderManagementOrderItem` api has got 8 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | shipping | Double | true | request.body?.shipping | | orderId | ID | true | request.body?.orderId | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | | price | Double | true | request.body?.price | | sellerId | ID | true | request.body?.sellerId | | title | String | true | request.body?.title | | currency | String | true | request.body?.currency | **shipping** : Shipping cost for this product (may be 0 for free shipping). **orderId** : Parent order this item belongs to; enables join and lifecycle tracking. **quantity** : Number of units purchased for this product. **productId** : ID of product purchased in this line item. **price** : Unit price for this product at purchase time. **sellerId** : UserId of seller (owner of product at purchase time). **title** : Product title at purchase time (copied for convenience/audit). **currency** : Currency code for price/shipping (ISO 4217). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderitems** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderitems', data: { shipping:"Double", orderId:"ID", quantity:"Integer", productId:"ID", price:"Double", sellerId:"ID", title:"String", currency:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpayment2` API This route is used to get the payment information by ID. **Rest Route** The `getOrderManagementOrderPayment2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `getOrderManagementOrderPayment2` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderpayments2` API This route is used to list all payments. **Rest Route** The `listOrderManagementOrderPayments2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayments2` **Rest Request Parameters** The `listOrderManagementOrderPayments2` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Ordermanagementorderpayment` API This route is used to create a new payment. **Rest Route** The `createOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment` **Rest Request Parameters** The `createOrderManagementOrderPayment` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderId | ID | true | request.body?.orderId | | paymentId | String | true | request.body?.paymentId | | paymentStatus | String | true | request.body?.paymentStatus | | statusLiteral | String | true | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | **orderId** : an ID value to represent the orderId which is the ID parameter of the source orderManagementOrder object **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderpayment', data: { orderId:"ID", paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Ordermanagementorderpayment` API This route is used to update an existing payment. **Rest Route** The `updateOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `updateOrderManagementOrderPayment` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | false | request.body?.paymentId | | paymentStatus | String | false | request.body?.paymentStatus | | statusLiteral | String | false | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | **sys_orderManagementOrderPaymentId** : This id paremeter is used to select the required data object that will be updated **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Ordermanagementorderpayment` API This route is used to delete a payment. **Rest Route** The `deleteOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `deleteOrderManagementOrderPayment` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderpayments2` API This route is used to list all payments. **Rest Route** The `listOrderManagementOrderPayments2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayments2` **Rest Request Parameters** The `listOrderManagementOrderPayments2` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Ordermanagementorderpaymentbyorderid` API This route is used to get the payment information by order id. **Rest Route** The `getOrderManagementOrderPaymentByOrderId` API REST controller can be triggered via the following route: `/v1/orderManagementOrderpaymentbyorderid/:orderId` **Rest Request Parameters** The `getOrderManagementOrderPaymentByOrderId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | orderId | String | true | request.params?.orderId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **orderId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbyorderid/:orderId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbyorderid/${orderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpaymentbypaymentid` API This route is used to get the payment information by payment id. **Rest Route** The `getOrderManagementOrderPaymentByPaymentId` API REST controller can be triggered via the following route: `/v1/orderManagementOrderpaymentbypaymentid/:paymentId` **Rest Request Parameters** The `getOrderManagementOrderPaymentByPaymentId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | true | request.params?.paymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **paymentId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbypaymentid/:paymentId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbypaymentid/${paymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpayment2` API This route is used to get the payment information by ID. **Rest Route** The `getOrderManagementOrderPayment2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `getOrderManagementOrderPayment2` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Start Ordermanagementorderpayment` API Start payment for orderManagementOrder **Rest Route** The `startOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/startordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `startOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to start a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/startordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/startordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Refresh Ordermanagementorderpayment` API Refresh payment info for orderManagementOrder from Stripe **Rest Route** The `refreshOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/refreshordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `refreshOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to refresh a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/refreshordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/refreshordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Callback Ordermanagementorderpayment` API Refresh payment values by gateway webhook call for orderManagementOrder **Rest Route** The `callbackOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/callbackordermanagementorderpayment` **Rest Request Parameters** The `callbackOrderManagementOrderPayment` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.body?.orderManagementOrderId | **orderManagementOrderId** : The order id parameter that will be read from webhook callback params **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/callbackordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/callbackordermanagementorderpayment', data: { orderManagementOrderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Get Paymentcustomerbyuserid` API This route is used to get the payment customer information by user id. **Rest Route** The `getPaymentCustomerByUserId` API REST controller can be triggered via the following route: `/v1/paymentcustomers/:userId` **Rest Request Parameters** The `getPaymentCustomerByUserId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_paymentCustomerId | ID | true | request.params?.sys_paymentCustomerId | | userId | String | true | request.params?.userId | **sys_paymentCustomerId** : This id paremeter is used to query the required data object. **userId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomers/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_paymentCustomer": { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Paymentcustomers` API This route is used to list all payment customers. **Rest Route** The `listPaymentCustomers` API REST controller can be triggered via the following route: `/v1/paymentcustomers` **Rest Request Parameters** The `listPaymentCustomers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers** ```js axios({ method: 'GET', url: '/v1/paymentcustomers', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentCustomers": [ { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Paymentcustomermethods` API This route is used to list all payment customer methods. **Rest Route** The `listPaymentCustomerMethods` API REST controller can be triggered via the following route: `/v1/paymentcustomermethods/:userId` **Rest Request Parameters** The `listPaymentCustomerMethods` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | String | true | request.params?.userId | **userId** : This parameter will be used to select the data objects that want to be listed **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomermethods/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomermethods/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentMethods", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentMethods": [ { "id": "ID", "paymentMethodId": "String", "userId": "ID", "customerId": "String", "cardHolderName": "String", "cardHolderZip": "String", "platform": "String", "cardInfo": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ## Feedback Service Handles feedback for order items: one feedback per buyer/orderItem, attached to sellerId for analytical feedback/rating aggregation and reputation tracking. Enables querying feedbacks received/given for sellers and buyers. test ### Feedback Service Data Objects **Feedback** One feedback per (buyer, orderItem). Stores rating (1-5), comment, ties to seller for analytics. Created only after delivery confirmed on order item. ### Feedback Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/feedback-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/feedback-api` * **Production:** `https://ebaycclone.mindbricks.co/feedback-api` ### `List Feedbacks` API List feedback with filtering by buyerId (given), sellerId (received), productId, or orderItemId. Used for showing seller profile, buyer profile, or order analytics. **Rest Route** The `listFeedbacks` API REST controller can be triggered via the following route: `/v1/feedbacks` **Rest Request Parameters** The `listFeedbacks` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/feedbacks** ```js axios({ method: 'GET', url: '/v1/feedbacks', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedbacks", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "feedbacks": [ { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Feedback` API Get a single feedback by id. Accessible to public (for seller profile, product, or audit views). **Rest Route** The `getFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `getFeedback` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | **feedbackId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/feedbacks/:feedbackId** ```js axios({ method: 'GET', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Feedback` API Update feedback (comment/rating) for existing feedback record (buyer only). Admin can update as override. **Rest Route** The `updateFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `updateFeedback` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | | rating | Integer | false | request.body?.rating | | comment | String | false | request.body?.comment | **feedbackId** : This id paremeter is used to select the required data object that will be updated **rating** : Rating (1-5 stars) submitted by buyer. Required. **comment** : Optional textual feedback comment, max ~500 chars. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/feedbacks/:feedbackId** ```js axios({ method: 'PATCH', url: `/v1/feedbacks/${feedbackId}`, data: { rating:"Integer", comment:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Feedback` API Delete (soft-delete) feedback (by buyer or admin). Only feedback owner or admin. **Rest Route** The `deleteFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `deleteFeedback` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | **feedbackId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/feedbacks/:feedbackId** ```js axios({ method: 'DELETE', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Feedback` API Buyer creates feedback for a delivered order item. Only allowed once per (buyer, orderItemId). Allowed only once order item is delivered. **Rest Route** The `createFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks` **Rest Request Parameters** The `createFeedback` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | rating | Integer | true | request.body?.rating | | orderId | ID | true | request.body?.orderId | | orderItemId | ID | true | request.body?.orderItemId | | sellerId | ID | true | request.body?.sellerId | | comment | String | false | request.body?.comment | | productId | ID | true | request.body?.productId | **rating** : Rating (1-5 stars) submitted by buyer. Required. **orderId** : Order containing this purchased item. Used for aggregation and validation. **orderItemId** : Purchased item (line item) in order. Feedback is per (buyer, orderItem). **sellerId** : Seller of product for analytics/aggregation. Not author; used for querying feedback about sellers. **comment** : Optional textual feedback comment, max ~500 chars. **productId** : The product listing being reviewed (snapshot at order time). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/feedbacks** ```js axios({ method: 'POST', url: '/v1/feedbacks', data: { rating:"Integer", orderId:"ID", orderItemId:"ID", sellerId:"ID", comment:"String", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # REST API GUIDE ## ebaycclone-adminmoderation-service Administrative backend service for moderation and manual override actions. Responsible for logging all admin interventions (user/product/feedback/media/category/order/notification/searchindex moderation), triggering corrections via interservice calls, and providing comprehensive audit trails for compliance. ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to: Email: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. ## Documentation Scope Welcome to the official documentation for the AdminModeration Service's REST API. This document is designed to provide a comprehensive guide to interfacing with our AdminModeration Service exclusively through RESTful API endpoints. **Intended Audience** This documentation is intended for developers and integrators who are looking to interact with the AdminModeration Service via HTTP requests for purposes such as creating, updating, deleting and querying AdminModeration objects. **Overview** Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases. Beyond REST It's important to note that the AdminModeration Service also supports alternative methods of interaction, such as gRPC and messaging via a Message Broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation. ## Authentication And Authorization To ensure secure access to the AdminModeration service's protected endpoints, a project-wide access token is required. This token serves as the primary method for authenticating requests to our service. However, it's important to note that access control varies across different routes: **Protected API**: Certain API (routes) require specific authorization levels. Access to these routes is contingent upon the possession of a valid access token that meets the route-specific authorization criteria. Unauthorized requests to these routes will be rejected. **Public API **: The service also includes public API (routes) that are accessible without authentication. These public endpoints are designed for open access and do not require an access token. ### Token Locations When including your access token in a request, ensure it is placed in one of the following specified locations. The service will sequentially search these locations for the token, utilizing the first one it encounters. | Location | Token Name / Param Name | | ---------------------- | ---------------------------- | | Query | access_token | | Authorization Header | Bearer | | Header | ebaycclone-access-token| | Cookie | ebaycclone-access-token| Please ensure the token is correctly placed in one of these locations, using the appropriate label as indicated. The service prioritizes these locations in the order listed, processing the first token it successfully identifies. ## Api Definitions This section outlines the API endpoints available within the AdminModeration service. Each endpoint can receive parameters through various methods, meticulously described in the following definitions. It's important to understand the flexibility in how parameters can be included in requests to effectively interact with the AdminModeration service. This service is configured to listen for HTTP requests on port `3006`, serving both the main API interface and default administrative endpoints. The following routes are available by default: * **API Test Interface (API Face):** `/` * **Swagger Documentation:** `/swagger` * **Postman Collection Download:** `/getPostmanCollection` * **Health Checks:** `/health` and `/admin/health` * **Current Session Info:** `/currentuser` * **Favicon:** `/favicon.ico` This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/adminmoderation-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/adminmoderation-api` * **Production:** `https://ebaycclone.mindbricks.co/adminmoderation-api` **Parameter Inclusion Methods:** Parameters can be incorporated into API requests in several ways, each with its designated location. Understanding these methods is crucial for correctly constructing your requests: **Query Parameters:** Included directly in the URL's query string. **Path Parameters:** Embedded within the URL's path. **Body Parameters:** Sent within the JSON body of the request. **Session Parameters:** Automatically read from the session object. This method is used for parameters that are intrinsic to the user's session, such as userId. When using an API that involves session parameters, you can omit these from your request. The service will automatically bind them to the API layer, provided that a session is associated with your request. **Note on Session Parameters:** Session parameters represent a unique method of parameter inclusion, relying on the context of the user's session. A common example of a session parameter is userId, which the service automatically associates with your request when a session exists. This feature ensures seamless integration of user-specific data without manual input for each request. By adhering to the specified parameter inclusion methods, you can effectively utilize the AdminModeration service's API endpoints. For detailed information on each endpoint, including required parameters and their accepted locations, refer to the individual API definitions below. ### Common Parameters The `AdminModeration` service's business API support several common parameters designed to modify and enhance the behavior of API requests. These parameters are not individually listed in the API route definitions to avoid repetition. Instead, refer to this section to understand how to leverage these common behaviors across different routes. Note that all common parameters should be included in the query part of the URL. ### Supported Common Parameters: - **getJoins (BOOLEAN)**: Controls whether to retrieve associated objects along with the main object. By default, `getJoins` is assumed to be `true`. Set it to `false` if you prefer to receive only the main fields of an object, excluding its associations. - **excludeCQRS (BOOLEAN)**: Applicable only when `getJoins` is `true`. By default, `excludeCQRS` is set to `false`. Enabling this parameter (`true`) omits non-local associations, which are typically more resource-intensive as they require querying external services like ElasticSearch for additional information. Use this to optimize response times and resource usage. - **requestId (String)**: Identifies a request to enable tracking through the service's log chain. A random hex string of 32 characters is assigned by default. If you wish to use a custom `requestId`, simply include it in your query parameters. - **caching (BOOLEAN)**: Determines the use of caching for query API. By default, caching is enabled (`true`). To ensure the freshest data directly from the database, set this parameter to `false`, bypassing the cache. - **cacheTTL (Integer)**: Specifies the Time-To-Live (TTL) for query caching, in seconds. This is particularly useful for adjusting the default caching duration (5 minutes) for `get list` queries. Setting a custom `cacheTTL` allows you to fine-tune the cache lifespan to meet your needs. - **pageNumber (Integer)**: For paginated `get list` API's, this parameter selects which page of results to retrieve. The default is `1`, indicating the first page. To disable pagination and retrieve all results, set `pageNumber` to `0`. - **pageRowCount (Integer)**: In conjunction with paginated API's, this parameter defines the number of records per page. The default value is `25`. Adjusting `pageRowCount` allows you to control the volume of data returned in a single request. By utilizing these common parameters, you can tailor the behavior of API requests to suit your specific requirements, ensuring optimal performance and usability of the `AdminModeration` service. ### Error Response If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity: - **400 Bad Request**: The request was improperly formatted or contained invalid parameters, preventing the server from processing it. - **401 Unauthorized**: The request lacked valid authentication credentials or the credentials provided do not grant access to the requested resource. - **404 Not Found**: The requested resource was not found on the server. - **500 Internal Server Error**: The server encountered an unexpected condition that prevented it from fulfilling the request. Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ### Object Structure of a Successfull Response When the `AdminModeration` service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client. **Key Characteristics of the Response Envelope:** - **Data Presentation**: Depending on the nature of the request, the service returns either a single data object or an array of objects encapsulated within the JSON envelope. - **Creation and Update API**: These API routes return the unmodified (pure) form of the data object(s), without any associations to other data objects. - **Delete API**: Even though the data is removed from the database, the last known state of the data object(s) is returned in its pure form. - **Get Requests**: A single data object is returned in JSON format. - **Get List Requests**: An array of data objects is provided, reflecting a collection of resources. - **Data Structure and Joins**: The complexity of the data structure in the response can vary based on the API's architectural design and the join options specified in the request. The architecture might inherently limit join operations, or they might be dynamically controlled through query parameters. - **Pure Data Forms**: In some cases, the response mirrors the exact structure found in the primary data table, without extensions. - **Extended Data Forms**: Alternatively, responses might include data extended through joins with tables within the same service or aggregated from external sources, such as ElasticSearch indices related to other services. - **Join Varieties**: The extensions might involve one-to-one joins, resulting in single object associations, or one-to-many joins, leading to an array of objects. In certain instances, the data might even feature nested inclusions from other data objects. **Design Considerations**: The structure of a API's response data is meticulously crafted during the service's architectural planning. This design ensures that responses adequately reflect the intended data relationships and service logic, providing clients with rich and meaningful information. **Brief Data**: Certain API's return a condensed version of the object data, intentionally selecting only specific fields deemed useful for that request. In such instances, the API documentation will detail the properties included in the response, guiding developers on what to expect. ### API Response Structure The API utilizes a standardized JSON envelope to encapsulate responses. This envelope is designed to consistently deliver both the requested data and essential metadata, ensuring that clients can efficiently interpret and utilize the response. **HTTP Status Codes:** - **200 OK**: This status code is returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request has been processed successfully. - **201 Created**: This status code is specific to CREATE operations, signifying that the requested resource has been successfully created. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling the successful execution of the request. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3 "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` - **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation performed. **Handling Errors:** For details on handling error scenarios and understanding the structure of error responses, please refer to the "Error Response" section provided earlier in this documentation. It outlines how error conditions are communicated, including the use of HTTP status codes and standardized JSON structures for error messages. ## Resources AdminModeration service provides the following resources which are stored in its own database as a data object. Note that a resource for an api access is a data object for the service. ### ModerationAction resource *Resource Definition* : Audit record for all admin moderation/override actions affecting core business entities. Links to admin, timestamp, entity type/ID, action performed, and reason. *ModerationAction Resource Properties* | Name | Type | Required | Default | Definition | | ---- | ---- | -------- | ------- | ---------- | | **adminId** | ID | | | *ID of admin performing moderation action.* | | **entityId** | ID | | | *ID of target entity affected by moderation (user/product/etc).* | | **actionTimestamp** | Date | | | *Timestamp moderation action was performed/logged.* | | **entityType** | Enum | | | *Type of entity affected (USER, PRODUCT, FEEDBACK, MEDIA, CATEGORY, NOTIFICATION, ORDER, SEARCHINDEX).* | | **reason** | String | | | *Explanation or justification for the moderation action performed.* | | **actionType** | Enum | | | *Type of moderation action (e.g., SOFT_DELETE, RESTORE, UPDATE_ROLE, MANUAL_CORRECTION, MEDIA_FLAG, INDEX_REBUILD, PAYMENT_FIX, FEEDBACK_OVERRIDE, ADMIN_NOTE).* | #### Enum Properties Enum properties are represented as strings in the database. The values are mapped to their corresponding names in the application layer. ##### entityType Enum Property *Property Definition* : Type of entity affected (USER, PRODUCT, FEEDBACK, MEDIA, CATEGORY, NOTIFICATION, ORDER, SEARCHINDEX).*Enum Options* | Name | Value | Index | | ---- | ----- | ----- | | **USER** | `"USER""` | 0 | | **PRODUCT** | `"PRODUCT""` | 1 | | **FEEDBACK** | `"FEEDBACK""` | 2 | | **MEDIA** | `"MEDIA""` | 3 | | **CATEGORY** | `"CATEGORY""` | 4 | | **NOTIFICATION** | `"NOTIFICATION""` | 5 | | **ORDER** | `"ORDER""` | 6 | | **SEARCHINDEX** | `"SEARCHINDEX""` | 7 | ##### actionType Enum Property *Property Definition* : Type of moderation action (e.g., SOFT_DELETE, RESTORE, UPDATE_ROLE, MANUAL_CORRECTION, MEDIA_FLAG, INDEX_REBUILD, PAYMENT_FIX, FEEDBACK_OVERRIDE, ADMIN_NOTE).*Enum Options* | Name | Value | Index | | ---- | ----- | ----- | | **SOFT_DELETE** | `"SOFT_DELETE""` | 0 | | **RESTORE** | `"RESTORE""` | 1 | | **UPDATE_ROLE** | `"UPDATE_ROLE""` | 2 | | **MANUAL_CORRECTION** | `"MANUAL_CORRECTION""` | 3 | | **MEDIA_FLAG** | `"MEDIA_FLAG""` | 4 | | **INDEX_REBUILD** | `"INDEX_REBUILD""` | 5 | | **PAYMENT_FIX** | `"PAYMENT_FIX""` | 6 | | **FEEDBACK_OVERRIDE** | `"FEEDBACK_OVERRIDE""` | 7 | | **ADMIN_NOTE** | `"ADMIN_NOTE""` | 8 | ## Business Api ### Get Moderationaction API *API Definition* : Get a single moderation action log by ID. Used to review admin audit trails; accessible only to platform admins. *API Crud Type* : get *Default access route* : *GET* `/v1/moderationactions/:moderationActionId` #### Parameters The getModerationAction api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | To access the api you can use the **REST** controller with the path **GET /v1/moderationactions/:moderationActionId** ```js axios({ method: 'GET', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`moderationAction`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"moderationAction","method":"GET","action":"get","appVersion":"Version","rowCount":1,"moderationAction":{"id":"ID","adminId":"ID","entityId":"ID","actionTimestamp":"Date","entityType":"Enum","entityType_idx":"Integer","reason":"String","actionType":"Enum","actionType_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Get Moderationaction](businessApi/getModerationAction). ### Delete Moderationaction API *API Definition* : Soft-deletes a moderation action log record (dangerous; allowed only to superadmins or strict manual correction), primarily for audit correction or internal error cleanup. Usually, moderation logs are immutable. *API Crud Type* : delete *Default access route* : *DELETE* `/v1/moderationactions/:moderationActionId` #### Parameters The deleteModerationAction api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | To access the api you can use the **REST** controller with the path **DELETE /v1/moderationactions/:moderationActionId** ```js axios({ method: 'DELETE', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`moderationAction`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"moderationAction","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"moderationAction":{"id":"ID","adminId":"ID","entityId":"ID","actionTimestamp":"Date","entityType":"Enum","entityType_idx":"Integer","reason":"String","actionType":"Enum","actionType_idx":"Integer","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Delete Moderationaction](businessApi/deleteModerationAction). ### Create Moderationaction API *API Definition* : Logs an admin moderation or override action in the system for audit and traceability. Requires admin login, takes context from session, and creates an audit entry for any admin operation over any entity type. *API Crud Type* : create *Default access route* : *POST* `/v1/moderationactions` #### Parameters The createModerationAction api has got 4 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | entityId | ID | true | request.body?.entityId | | entityType | Enum | true | request.body?.entityType | | reason | String | true | request.body?.reason | | actionType | Enum | true | request.body?.actionType | To access the api you can use the **REST** controller with the path **POST /v1/moderationactions** ```js axios({ method: 'POST', url: '/v1/moderationactions', data: { entityId:"ID", entityType:"Enum", reason:"String", actionType:"Enum", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`moderationAction`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"moderationAction","method":"POST","action":"create","appVersion":"Version","rowCount":1,"moderationAction":{"id":"ID","adminId":"ID","entityId":"ID","actionTimestamp":"Date","entityType":"Enum","entityType_idx":"Integer","reason":"String","actionType":"Enum","actionType_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Create Moderationaction](businessApi/createModerationAction). ### List Moderationactions API *API Definition* : List moderation actions for admin dashboard/audit search. Supports filtering by admin, entityType, entityId, actionType, and date. Always sorted by most recent action. *API Crud Type* : list *Default access route* : *GET* `/v1/moderationactions` The listModerationActions api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/moderationactions** ```js axios({ method: 'GET', url: '/v1/moderationactions', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`moderationActions`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"moderationActions","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","moderationActions":[{"id":"ID","adminId":"ID","entityId":"ID","actionTimestamp":"Date","entityType":"Enum","entityType_idx":"Integer","reason":"String","actionType":"Enum","actionType_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For List Moderationactions](businessApi/listModerationActions). ### Update Moderationaction API *API Definition* : Allows update of explanation/note on a moderation action for correction (typically by admin or superadmin only). No entity/type/admin may be changed after creation; only 'reason' is editable for audit consistency. *API Crud Type* : update *Default access route* : *PATCH* `/v1/moderationactions/:moderationActionId` #### Parameters The updateModerationAction api has got 2 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | | reason | String | false | request.body?.reason | To access the api you can use the **REST** controller with the path **PATCH /v1/moderationactions/:moderationActionId** ```js axios({ method: 'PATCH', url: `/v1/moderationactions/${moderationActionId}`, data: { reason:"String", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`moderationAction`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"moderationAction","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"moderationAction":{"id":"ID","adminId":"ID","entityId":"ID","actionTimestamp":"Date","entityType":"Enum","entityType_idx":"Integer","reason":"String","actionType":"Enum","actionType_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Update Moderationaction](businessApi/updateModerationAction). ### Authentication Specific Routes ### Common Routes ### Route: currentuser *Route Definition*: Retrieves the currently authenticated user's session information. *Route Type*: sessionInfo *Access Route*: `GET /currentuser` #### Parameters This route does **not** require any request parameters. #### Behavior - Returns the authenticated session object associated with the current access token. - If no valid session exists, responds with a 401 Unauthorized. ```js // Sample GET /currentuser call axios.get("/currentuser", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** Returns the session object, including user-related data and token information. ``` { "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", "roleId": "user", "tenantId": "abc123", "accessToken": "jwt-token-string", ... } ``` **Error Response** **401 Unauthorized:** No active session found. ``` { "status": "ERR", "message": "No login found" } ``` **Notes** * This route is typically used by frontend or mobile applications to fetch the current session state after login. * The returned session includes key user identity fields, tenant information (if applicable), and the access token for further authenticated requests. * Always ensure a valid access token is provided in the request to retrieve the session. ### Route: permissions `*Route Definition*`: Retrieves all effective permission records assigned to the currently authenticated user. `*Route Type*`: permissionFetch *Access Route*: `GET /permissions` #### Parameters This route does **not** require any request parameters. #### Behavior - Fetches all active permission records (`givenPermissions` entries) associated with the current user session. - Returns a full array of permission objects. - Requires a valid session (`access token`) to be available. ```js // Sample GET /permissions call axios.get("/permissions", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** Returns an array of permission objects. ```json [ { "id": "perm1", "permissionName": "adminPanel.access", "roleId": "admin", "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" }, { "id": "perm2", "permissionName": "orders.manage", "roleId": null, "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" } ] ``` Each object reflects a single permission grant, aligned with the givenPermissions model: - `**permissionName**`: The permission the user has. - `**roleId**`: If the permission was granted through a role. -` **subjectUserId**`: If directly granted to the user. - `**subjectUserGroupId**`: If granted through a group. - `**objectId**`: If tied to a specific object (OBAC). - `**canDo**`: True or false flag to represent if permission is active or restricted. **Error Responses** * **401 Unauthorized**: No active session found. ```json { "status": "ERR", "message": "No login found" } ``` * **500 Internal Server Error**: Unexpected error fetching permissions. **Notes** * The /permissions route is available across all backend services generated by Mindbricks, not just the auth service. * Auth service: Fetches permissions freshly from the live database (givenPermissions table). * Other services: Typically use a cached or projected view of permissions stored in a common ElasticSearch store, optimized for faster authorization checks. > **Tip**: > Applications can cache permission results client-side or server-side, but should occasionally refresh by calling this endpoint, especially after login or permission-changing operations. ### Route: permissions/:permissionName *Route Definition*: Checks whether the current user has access to a specific permission, and provides a list of scoped object exceptions or inclusions. *Route Type*: permissionScopeCheck *Access Route*: `GET /permissions/:permissionName` #### Parameters | Parameter | Type | Required | Population | |------------------|--------|----------|------------------------| | permissionName | String | Yes | `request.params.permissionName` | #### Behavior - Evaluates whether the current user **has access** to the given `permissionName`. - Returns a structured object indicating: - Whether the permission is generally granted (`canDo`) - Which object IDs are explicitly included or excluded from access (`exceptions`) - Requires a valid session (`access token`). ```js // Sample GET /permissions/orders.manage axios.get("/permissions/orders.manage", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** ```json { "canDo": true, "exceptions": [ "a1f2e3d4-xxxx-yyyy-zzzz-object1", "b2c3d4e5-xxxx-yyyy-zzzz-object2" ] } ``` * If `canDo` is `true`, the user generally has the permission, but not for the objects listed in `exceptions` (i.e., restrictions). * If `canDo` is `false`, the user does not have the permission by default — but only for the objects in `exceptions`, they do have permission (i.e., selective overrides). * The exceptions array contains valid **UUID strings**, each corresponding to an object ID (typically from the data model targeted by the permission). ## Copyright All sources, documents and other digital materials are copyright of . ## About Us For more information please visit our website: . . . # Service Design Specification **ebaycclone-adminmoderation-service** documentation -Version:**`1.0.0`** ## Scope This document provides a structured architectural overview of the `adminModeration` microservice, detailing its configuration, data model, authorization logic, business rules, and API design. It has been automatically generated based on the service definition within Mindbricks, ensuring that the information reflects the source of truth used during code generation and deployment. The document is intended to serve multiple audiences: * **Service architects** can use it to validate design decisions and ensure alignment with broader architectural goals. * **Developers and maintainers** will find it useful for understanding the structure and behavior of the service, facilitating easier debugging, feature extension, and integration with other systems. * **Stakeholders and reviewers** can use it to gain a clear understanding of the service's capabilities and domain logic. > **Note for Frontend Developers**: While this document is valuable for understanding business logic and data interactions, please refer to the [Service API Documentation](#) for endpoint-level specifications and integration details. > **Note for Backend Developers**: Since the code for this service is automatically generated by Mindbricks, you typically won't need to implement or modify it manually. However, this document is especially valuable when you're building other services—whether within Mindbricks or externally—that need to interact with or depend on this service. It provides a clear reference to the service's data contracts, business rules, and API structure, helping ensure compatibility and correct integration. ## `AdminModeration` Service Settings [**Edit**](adminmoderation/serviceSettings) Administrative backend service for moderation and manual override actions. Responsible for logging all admin interventions (user/product/feedback/media/category/order/notification/searchindex moderation), triggering corrections via interservice calls, and providing comprehensive audit trails for compliance. ### Service Overview This service is configured to listen for HTTP requests on port `3006`, serving both the main API interface and default administrative endpoints. The following routes are available by default: * **API Test Interface (API Face):** `/` * **Swagger Documentation:** `/swagger` * **Postman Collection Download:** `/getPostmanCollection` * **Health Checks:** `/health` and `/admin/health` * **Current Session Info:** `/currentuser` * **Favicon:** `/favicon.ico` The service uses a **PostgreSQL** database for data storage, with the database name set to `ebaycclone-adminmoderation-service`. This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/adminmoderation-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/adminmoderation-api` * **Production:** `https://ebaycclone.mindbricks.co/adminmoderation-api` ### Authentication & Security - **Login Required**: Yes This service requires user authentication for access. It supports both JWT and RSA-based authentication mechanisms, ensuring secure user sessions and data integrity. If a crud route also is configured to require login, it will check a valid JWT token in the request query/header/bearer/cookie. If the token is valid, it will extract the user information from the token and make the fetched session data available in the request context. ### Service Data Objects The service uses a **PostgreSQL** database for data storage, with the database name set to `ebaycclone-adminmoderation-service`. Data deletion is managed using a **soft delete** strategy. Instead of removing records from the database, they are flagged as inactive by setting the `isActive` field to `false`. | Object Name | Description | Public Access | |-------------|-------------|---------------| | `moderationAction` | Audit record for all admin moderation/override actions affecting core business entities. Links to admin, timestamp, entity type/ID, action performed, and reason. | accessProtected | ## moderationAction Data Object ### Object Overview **Description:** Audit record for all admin moderation/override actions affecting core business entities. Links to admin, timestamp, entity type/ID, action performed, and reason. This object represents a core data structure within the service and acts as the blueprint for database interaction, API generation, and business logic enforcement. It is defined using the `ObjectSettings` pattern, which governs its behavior, access control, caching strategy, and integration points with other systems such as Stripe and Redis. ### Core Configuration - **Soft Delete:** Enabled — Determines whether records are marked inactive (`isActive = false`) instead of being physically deleted. - **Public Access:** accessProtected — If enabled, anonymous users may access this object’s data depending on API-level rules. ### Composite Indexes - **moderation_admin_entity**: [adminId, entityType, entityId] This composite index is defined to optimize query performance for complex queries involving multiple fields. The index also defines a conflict resolution strategy for duplicate key violations. When a new record would violate this composite index, the following action will be taken: **On Duplicate**: `doInsert` The new record will be inserted without checking for duplicates. This means that the composite index is designed for search purposes only. ### Properties Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `adminId` | ID | Yes | ID of admin performing moderation action. | | `entityId` | ID | Yes | ID of target entity affected by moderation (user/product/etc). | | `actionTimestamp` | Date | Yes | Timestamp moderation action was performed/logged. | | `entityType` | Enum | Yes | Type of entity affected (USER, PRODUCT, FEEDBACK, MEDIA, CATEGORY, NOTIFICATION, ORDER, SEARCHINDEX). | | `reason` | String | Yes | Explanation or justification for the moderation action performed. | | `actionType` | Enum | Yes | Type of moderation action (e.g., SOFT_DELETE, RESTORE, UPDATE_ROLE, MANUAL_CORRECTION, MEDIA_FLAG, INDEX_REBUILD, PAYMENT_FIX, FEEDBACK_OVERRIDE, ADMIN_NOTE). | * Required properties are mandatory for creating objects and must be provided in the request body if no default value is set. ### Default Values Default values are automatically assigned to properties when a new object is created, if no value is provided in the request body. Since default values are applied on db level, they should be literal values, not expressions.If you want to use expressions, you can use transposed parameters in any business API to set default values dynamically. - **adminId**: '00000000-0000-0000-0000-000000000000' - **entityId**: '00000000-0000-0000-0000-000000000000' - **actionTimestamp**: new Date() - **entityType**: "USER" - **reason**: 'default' - **actionType**: "SOFT_DELETE" ### Constant Properties `adminId` `entityId` `actionTimestamp` `entityType` `actionType` Constant properties are defined to be immutable after creation, meaning they cannot be updated or changed once set. They are typically used for properties that should remain constant throughout the object's lifecycle. A property is set to be constant if the `Allow Update` option is set to `false`. ### Auto Update Properties `reason` An update crud API created with the option `Auto Params` enabled will automatically update these properties with the provided values in the request body. If you want to update any property in your own business logic not by user input, you can set the `Allow Auto Update` option to false. These properties will be added to the update API's body parameters and can be updated by the user if any value is provided in the request body. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an addtional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the index property to sort by the enum value or when your enum options represent a sequence of values. - **entityType**: [USER, PRODUCT, FEEDBACK, MEDIA, CATEGORY, NOTIFICATION, ORDER, SEARCHINDEX] - **actionType**: [SOFT_DELETE, RESTORE, UPDATE_ROLE, MANUAL_CORRECTION, MEDIA_FLAG, INDEX_REBUILD, PAYMENT_FIX, FEEDBACK_OVERRIDE, ADMIN_NOTE] ### Elastic Search Indexing `adminId` `entityId` `actionTimestamp` `entityType` `reason` `actionType` Properties that are indexed in Elastic Search will be searchable via the Elastic Search API. While all properties are stored in the elastic search index of the data object, only those marked for Elastic Search indexing will be available for search queries. ### Database Indexing `adminId` `entityId` `entityType` `actionType` Properties that are indexed in the database will be optimized for query performance, allowing for faster data retrieval. Make a property indexed in the database if you want to use it frequently in query filters or sorting. ### Relation Properties `adminId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. You can define relations in the data object properties, which will be used to create foreign key constraints in the database. For complex joins operations, Mindbricks supportsa BFF pattern, where you can view dynamic and static views based on Elastic Search Indexes. Use db level relations for simple one-to-one or one-to-many relationships, and use BFF views for complex joins that require multiple data objects to be joined together. - **adminId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes ### Session Data Properties `adminId` Session data properties are used to store data that is specific to the user session, allowing for personalized experiences and temporary data storage. If a property is configured as session data, it will be automatically mapped to the related field in the user session during CRUD operations. Note that session data properties can not be mutated by the user, but only by the system. - **adminId**: ID property will be mapped to the session parameter `userId`. ### Formula Properties `actionTimestamp` Formula properties are used to define calculated fields that derive their values from other properties or external data. These properties are automatically calculated based on the defined formula and can be used for dynamic data retrieval. - **actionTimestamp**: Date - Formula: `Date.now()` - Calculate After Instance: No ## Business Logic adminModeration has got 5 Business APIs to manage its internal and crud logic. For the details of each business API refer to its chapter. * [Get Moderationaction](/businessLogic/getmoderationaction) * [Delete Moderationaction](/businessLogic/deletemoderationaction) * [Create Moderationaction](/businessLogic/createmoderationaction) * [List Moderationactions](/businessLogic/listmoderationactions) * [Update Moderationaction](/businessLogic/updatemoderationaction) ## Edge Controllers ### rebuildSearchIndex **Configuration:** - **Function Name**: `rebuildSearchIndex` - **Login Required**: Yes **REST Settings:** - **Path**: `/rebuild-search-index` - **Method**: --- ### fixPaymentRecord **Configuration:** - **Function Name**: `fixPaymentRecord` - **Login Required**: Yes **REST Settings:** - **Path**: `/fix-payment-record` - **Method**: --- ### overrideFeedback **Configuration:** - **Function Name**: `overrideFeedback` - **Login Required**: Yes **REST Settings:** - **Path**: `/override-feedback` - **Method**: --- ### flagMediaAsset **Configuration:** - **Function Name**: `flagMediaAsset` - **Login Required**: Yes **REST Settings:** - **Path**: `/flag-media-asset` - **Method**: --- ### restoreSoftDeletedEntity **Configuration:** - **Function Name**: `restoreSoftDeletedEntity` - **Login Required**: Yes **REST Settings:** - **Path**: `/restore-soft-deleted-entity` - **Method**: --- --- ## Service Library ### Functions No general functions defined. ### Hook Functions No hook functions defined. ### Edge Functions #### rebuildSearchIndex.js ```js module.exports = async (request, {LIB, context}) => { /* Only for admins; triggers a search index rebuild/correction via the searchIndexing microservice. Records a moderationAction. */ const session = request.session; if (!session || session.roleId !== 'admin') throw {status:403,message:'Forbidden'}; // Rebuild search index by calling searchIndexing:listSearchIndexes + create/update as needed (simulating event trigger) // (In practice: publish event or call BFF to orchestrate) // Here, just log an audit entry: await LIB.createModerationAction({ adminId: session.userId, entityType: 'SEARCHINDEX', entityId: 'ALL', actionType: 'INDEX_REBUILD', reason: request.body?.reason || 'Manual search index rebuild', actionTimestamp: new Date().toISOString() }); return {status:200,message:'Triggered search index rebuild & logged action.'}; } ``` #### fixPaymentRecord.js ```js module.exports = async (request, {LIB, context}) => { // Only admins can invoke. Fixes payment (order) record in orderManagement. const session = request.session; if (!session || session.roleId !== 'admin') throw {status:403,message:'Forbidden'}; const {orderId, fixParams, reason} = request.body; // Call orderManagement:updateOrderManagementOrderStatus via interservice call (not implemented in this stub) // Log moderationAction: await LIB.createModerationAction({ adminId: session.userId, entityType: 'ORDER', entityId: orderId, actionType: 'PAYMENT_FIX', reason: reason || 'Manual payment status correction', actionTimestamp: new Date().toISOString() }); return {status:200,message:'Order payment correction logged. (See audit trail)'}; } ``` #### overrideFeedback.js ```js module.exports = async (request, {LIB, context}) => { // Only admins; manually override feedback for order item const session = request.session; if (!session || session.roleId !== 'admin') throw {status:403,message:'Forbidden'}; const {feedbackId, updateParams, reason} = request.body; // Call feedback:updateFeedback via interservice call (not implemented in this stub) await LIB.createModerationAction({ adminId: session.userId, entityType: 'FEEDBACK', entityId: feedbackId, actionType: 'FEEDBACK_OVERRIDE', reason: reason || 'Feedback manually corrected by admin', actionTimestamp: new Date().toISOString() }); return {status:200,message:'Feedback override performed & logged.'}; } ``` #### flagMediaAsset.js ```js module.exports = async (request, {LIB, context}) => { // Admin flags a media asset for review or removal const session = request.session; if (!session || session.roleId !== 'admin') throw {status:403,message:'Forbidden'}; const {mediaAssetId, reason} = request.body; // Call productListing:deleteProductListingMedia (not implemented in this stub) await LIB.createModerationAction({ adminId: session.userId, entityType: 'MEDIA', entityId: mediaAssetId, actionType: 'MEDIA_FLAG', reason: reason || 'Media flagged & removed by admin', actionTimestamp: new Date().toISOString() }); return {status:200,message:'Media asset flagged/removed and moderation action logged.'}; } ``` #### restoreSoftDeletedEntity.js ```js module.exports = async (request, {LIB, context}) => { // Only admins; restores a soft-deleted entity (user/product/feedback/etc.) const session = request.session; if (!session || session.roleId !== 'admin') throw {status:403,message:'Forbidden'}; const {entityType, entityId, reason} = request.body; // Would call appropriate service restore API await LIB.createModerationAction({ adminId: session.userId, entityType, entityId, actionType: 'RESTORE', reason: reason || 'Entity manually restored by admin', actionTimestamp: new Date().toISOString() }); return {status:200,message:'Entity restore triggered and audit logged.'}; } ``` ### Templates No templates defined. ### Assets No assets defined. ### Public Assets No public assets defined. --- ### Event Emission --- ## Integration Patterns ## Deployment Considerations ### Environment Configuration - **HTTP Port**: `3006` - **Database Type**: MongoDB - **Global Soft Delete**: Enabled ## Implementation Guidelines ### Development Workflow 1. **Data Model Implementation**: Generate database schema from data object definitions 2. **CRUD Route Generation**: Implement auto-generated routes with custom logic 3. **Custom Logic Integration**: Implement hook functions and edge functions 4. **Authentication Integration**: Configure with project-level authentication 5. **Testing**: Unit and integration testing for all components ### Code Generation Expectations - **Database Schema**: Auto-generated from data objects and relationships - **API Routes**: REST endpoints with customizable behavior - **Validation Logic**: Input validation from property definitions - **Access Control**: Authentication and authorization middleware ### Custom Code Integration Points - **Hook Functions**: Lifecycle-specific custom logic - **Edge Functions**: Full request/response control - **Library Functions**: Reusable business logic - **Templates**: Dynamic content rendering ### Testing Strategy #### Unit Testing - Test all custom library functions - Test validation logic and business rules - Test hook function implementations #### Integration Testing - Test API endpoints with authentication scenarios - Test database operations and transactions - Test external integrations - Test event emission and Kafka integration #### Performance Testing - Load test high-traffic endpoints - Test caching effectiveness - Monitor database query performance - Test scalability under load --- ## Appendices ### Data Type Reference | Type | Description | Storage | |------|-------------|---------| | ID | Unique identifier | UUID (SQL) / ObjectID (NoSQL) | | String | Short text (≤255 chars) | VARCHAR | | Text | Long-form text | TEXT | | Integer | 32-bit whole numbers | INT | | Boolean | True/false values | BOOLEAN | | Double | 64-bit floating point | DOUBLE | | Float | 32-bit floating point | FLOAT | | Short | 16-bit integers | SMALLINT | | Object | JSON object | JSONB (PostgreSQL) / Object (MongoDB) | | Date | ISO 8601 timestamp | TIMESTAMP | | Enum | Fixed numeric values | SMALLINT with lookup | ### Enum Value Mappings #### Request Locations - `0`: Bearer token in Authorization header - `1`: Cookie value - `2`: Custom HTTP header - `3`: Query parameter - `4`: Request body property - `5`: URL path parameter - `6`: Session data - `7`: Root request object #### HTTP Methods - `0`: GET - `1`: POST - `2`: PUT - `3`: PATCH - `4`: DELETE ### Edge Function Signature ```javascript async function edgeFunction(request) { // Custom request processing // Return response object or throw error return { data: {}, status: 200, message: "Success" }; } ``` --- *This document was generated from the service architecture definition and should be kept in sync with implementation changes.* # EVENT GUIDE ## ebaycclone-auctionoffer-service Handles auction bids and fixed-price offers for product listings, enforces real-time auction state, handles strict offer workflows including counter-offers, and triggers domain events for bid/offer notifications. No payment or frontend aggregation logic included. ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to: Email: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. # Documentation Scope Welcome to the official documentation for the `AuctionOffer` Service Event descriptions. This guide is dedicated to detailing how to subscribe to and listen for state changes within the `AuctionOffer` Service, offering an exclusive focus on event subscription mechanisms. **Intended Audience** This documentation is aimed at developers and integrators looking to monitor `AuctionOffer` Service state changes. It is especially relevant for those wishing to implement or enhance business logic based on interactions with `AuctionOffer` objects. **Overview** This section provides detailed instructions on monitoring service events, covering payload structures and demonstrating typical use cases through examples. # Authentication and Authorization Access to the `AuctionOffer` service's events is facilitated through the project's Kafka server, which is not accessible to the public. Subscription to a Kafka topic requires being on the same network and possessing valid Kafka user credentials. This document presupposes that readers have existing access to the Kafka server. Additionally, the service offers a public subscription option via REST for real-time data management in frontend applications, secured through REST API authentication and authorization mechanisms. To subscribe to service events via the REST API, please consult the Realtime REST API Guide. # Database Events Database events are triggered at the database layer, automatically and atomically, in response to any modifications at the data level. These events serve to notify subscribers about the creation, update, or deletion of objects within the database, distinct from any overarching business logic. Listening to database events is particularly beneficial for those focused on tracking changes at the database level. A typical use case for subscribing to database events is to replicate the data store of one service within another service's scope, ensuring data consistency and syncronization across services. For example, while a business operation such as "approve membership" might generate a high-level business event like `membership-approved`, the underlying database changes could involve multiple state updates to different entities. These might be published as separate events, such as `dbevent-member-updated` and `dbevent-user-updated`, reflecting the granular changes at the database level. Such detailed eventing provides a robust foundation for building responsive, data-driven applications, enabling fine-grained observability and reaction to the dynamics of the data landscape. It also facilitates the architectural pattern of event sourcing, where state changes are captured as a sequence of events, allowing for high-fidelity data replication and history replay for analytical or auditing purposes. ## DbEvent auctionOfferOffer-created **Event topic**: `ebaycclone-auctionoffer-service-dbevent-auctionofferoffer-created` This event is triggered upon the creation of a `auctionOfferOffer` data object in the database. The event payload encompasses the newly created data, encapsulated within the root of the paylod. **Event payload**: ```json {"id":"ID","buyerId":"ID","currency":"String","productId":"ID","counterOfferId":"ID","counterMessage":"String","counterAmount":"Double","offerAmount":"Double","message":"String","sellerId":"ID","status":"Enum","status_idx":"Integer","expiresAt":"Date","respondedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent auctionOfferOffer-updated **Event topic**: `ebaycclone-auctionoffer-service-dbevent-auctionofferoffer-updated` Activation of this event follows the update of a `auctionOfferOffer` data object. The payload contains the updated information under the `auctionOfferOffer` attribute, along with the original data prior to update, labeled as `old_auctionOfferOffer` and also you can find the old and new versions of updated-only portion of the data.. **Event payload**: ```json { old_auctionOfferOffer:{"id":"ID","buyerId":"ID","currency":"String","productId":"ID","counterOfferId":"ID","counterMessage":"String","counterAmount":"Double","offerAmount":"Double","message":"String","sellerId":"ID","status":"Enum","status_idx":"Integer","expiresAt":"Date","respondedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, auctionOfferOffer:{"id":"ID","buyerId":"ID","currency":"String","productId":"ID","counterOfferId":"ID","counterMessage":"String","counterAmount":"Double","offerAmount":"Double","message":"String","sellerId":"ID","status":"Enum","status_idx":"Integer","expiresAt":"Date","respondedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, oldDataValues, newDataValues } ``` ## DbEvent auctionOfferOffer-deleted **Event topic**: `ebaycclone-auctionoffer-service-dbevent-auctionofferoffer-deleted` This event announces the deletion of a `auctionOfferOffer` data object, covering both hard deletions (permanent removal) and soft deletions (where the `isActive` attribute is set to false). Regardless of the deletion type, the event payload will present the data as it was immediately before deletion, highlighting an `isActive` status of false for soft deletions. **Event payload**: ```json {"id":"ID","buyerId":"ID","currency":"String","productId":"ID","counterOfferId":"ID","counterMessage":"String","counterAmount":"Double","offerAmount":"Double","message":"String","sellerId":"ID","status":"Enum","status_idx":"Integer","expiresAt":"Date","respondedAt":"Date","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent auctionOfferBid-created **Event topic**: `ebaycclone-auctionoffer-service-dbevent-auctionofferbid-created` This event is triggered upon the creation of a `auctionOfferBid` data object in the database. The event payload encompasses the newly created data, encapsulated within the root of the paylod. **Event payload**: ```json {"id":"ID","userId":"ID","bidAmount":"Double","placedAt":"Date","currency":"String","status":"Enum","status_idx":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent auctionOfferBid-updated **Event topic**: `ebaycclone-auctionoffer-service-dbevent-auctionofferbid-updated` Activation of this event follows the update of a `auctionOfferBid` data object. The payload contains the updated information under the `auctionOfferBid` attribute, along with the original data prior to update, labeled as `old_auctionOfferBid` and also you can find the old and new versions of updated-only portion of the data.. **Event payload**: ```json { old_auctionOfferBid:{"id":"ID","userId":"ID","bidAmount":"Double","placedAt":"Date","currency":"String","status":"Enum","status_idx":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, auctionOfferBid:{"id":"ID","userId":"ID","bidAmount":"Double","placedAt":"Date","currency":"String","status":"Enum","status_idx":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, oldDataValues, newDataValues } ``` ## DbEvent auctionOfferBid-deleted **Event topic**: `ebaycclone-auctionoffer-service-dbevent-auctionofferbid-deleted` This event announces the deletion of a `auctionOfferBid` data object, covering both hard deletions (permanent removal) and soft deletions (where the `isActive` attribute is set to false). Regardless of the deletion type, the event payload will present the data as it was immediately before deletion, highlighting an `isActive` status of false for soft deletions. **Event payload**: ```json {"id":"ID","userId":"ID","bidAmount":"Double","placedAt":"Date","currency":"String","status":"Enum","status_idx":"Integer","productId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` # ElasticSearch Index Events Within the `AuctionOffer` service, most data objects are mirrored in ElasticSearch indices, ensuring these indices remain syncronized with their database counterparts through creation, updates, and deletions. These indices serve dual purposes: they act as a data source for external services and furnish aggregated data tailored to enhance frontend user experiences. Consequently, an ElasticSearch index might encapsulate data in its original form or aggregate additional information from other data objects. These aggregations can include both one-to-one and one-to-many relationships not only with database objects within the same service but also across different services. This capability allows developers to access comprehensive, aggregated data efficiently. By subscribing to ElasticSearch index events, developers are notified when an index is updated and can directly obtain the aggregated entity within the event payload, bypassing the need for separate ElasticSearch queries. It's noteworthy that some services may augment another service's index by appending to the entity’s `extends` object. In such scenarios, an `*-extended` event will contain only the newly added data. Should you require the complete dataset, you would need to retrieve the full ElasticSearch index entity using the provided ID. This approach to indexing and event handling facilitates a modular, interconnected architecture where services can seamlessly integrate and react to changes, enriching the overall data ecosystem and enabling more dynamic, responsive applications. ## Index Event auctionofferoffer-created **Event topic**: `elastic-index-ebaycclone_auctionofferoffer-created` **Event payload**: ```json {"id":"ID","buyerId":"ID","currency":"String","productId":"ID","counterOfferId":"ID","counterMessage":"String","counterAmount":"Double","offerAmount":"Double","message":"String","sellerId":"ID","status":"Enum","status_idx":"Integer","expiresAt":"Date","respondedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event auctionofferoffer-updated **Event topic**: `elastic-index-ebaycclone_auctionofferoffer-created` **Event payload**: ```json {"id":"ID","buyerId":"ID","currency":"String","productId":"ID","counterOfferId":"ID","counterMessage":"String","counterAmount":"Double","offerAmount":"Double","message":"String","sellerId":"ID","status":"Enum","status_idx":"Integer","expiresAt":"Date","respondedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event auctionofferoffer-deleted **Event topic**: `elastic-index-ebaycclone_auctionofferoffer-deleted` **Event payload**: ```json {"id":"ID","buyerId":"ID","currency":"String","productId":"ID","counterOfferId":"ID","counterMessage":"String","counterAmount":"Double","offerAmount":"Double","message":"String","sellerId":"ID","status":"Enum","status_idx":"Integer","expiresAt":"Date","respondedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event auctionofferoffer-extended **Event topic**: `elastic-index-ebaycclone_auctionofferoffer-extended` **Event payload**: ```js { id: id, extends: { [extendName]: "Object", [extendName + "_count"]: "Number", }, } ``` # Route Events Route events are emitted following the successful execution of a route. While most routes perform CRUD (Create, Read, Update, Delete) operations on data objects, resulting in route events that closely resemble database events, there are distinctions worth noting. A single route execution might trigger multiple CRUD actions and ElasticSearch indexing operations. However, for those primarily concerned with the overarching business logic and its outcomes, listening to the consolidated route event, published once at the conclusion of the route's execution, is more pertinent. Moreover, routes often deliver aggregated data beyond the primary database object, catering to specific client needs. For instance, creating a data object via a route might not only return the entity's data but also route-specific metrics, such as the executing user's permissions related to the entity. Alternatively, a route might automatically generate default child entities following the creation of a parent object. Consequently, the route event encapsulates a unified dataset encompassing both the parent and its children, in contrast to individual events triggered for each entity created. Therefore, subscribing to route events can offer a richer, more contextually relevant set of information aligned with business logic. The payload of a route event mirrors the REST response JSON of the route, providing a direct and comprehensive reflection of the data and metadata communicated to the client. This ensures that subscribers to route events receive a payload that encapsulates both the primary data involved and any additional information deemed significant at the business level, facilitating a deeper understanding and integration of the service's functional outcomes. ## Route Event auctionofferoffer-updated **Event topic** : `ebaycclone-auctionoffer-service-auctionofferoffer-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `auctionOfferOffer` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`auctionOfferOffer`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferOffer","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"auctionOfferOffer":{"id":"ID","buyerId":"ID","currency":"String","productId":"ID","counterOfferId":"ID","counterMessage":"String","counterAmount":"Double","offerAmount":"Double","message":"String","sellerId":"ID","status":"Enum","status_idx":"Integer","expiresAt":"Date","respondedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event auctionofferbid-created **Event topic** : `ebaycclone-auctionoffer-service-auctionofferbid-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `auctionOfferBid` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`auctionOfferBid`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferBid","method":"POST","action":"create","appVersion":"Version","rowCount":1,"auctionOfferBid":{"id":"ID","userId":"ID","bidAmount":"Double","placedAt":"Date","currency":"String","status":"Enum","status_idx":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event auctionofferbid-retrived **Event topic** : `ebaycclone-auctionoffer-service-auctionofferbid-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `auctionOfferBid` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`auctionOfferBid`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferBid","method":"GET","action":"get","appVersion":"Version","rowCount":1,"auctionOfferBid":{"id":"ID","userId":"ID","bidAmount":"Double","placedAt":"Date","currency":"String","status":"Enum","status_idx":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event auctionofferoffer-retrived **Event topic** : `ebaycclone-auctionoffer-service-auctionofferoffer-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `auctionOfferOffer` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`auctionOfferOffer`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferOffer","method":"GET","action":"get","appVersion":"Version","rowCount":1,"auctionOfferOffer":{"id":"ID","buyerId":"ID","currency":"String","productId":"ID","counterOfferId":"ID","counterMessage":"String","counterAmount":"Double","offerAmount":"Double","message":"String","sellerId":"ID","status":"Enum","status_idx":"Integer","expiresAt":"Date","respondedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event auctionofferoffers-listed **Event topic** : `ebaycclone-auctionoffer-service-auctionofferoffers-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `auctionOfferOffers` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`auctionOfferOffers`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferOffers","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","auctionOfferOffers":[{"id":"ID","buyerId":"ID","currency":"String","productId":"ID","counterOfferId":"ID","counterMessage":"String","counterAmount":"Double","offerAmount":"Double","message":"String","sellerId":"ID","status":"Enum","status_idx":"Integer","expiresAt":"Date","respondedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event auctionofferbid-updated **Event topic** : `ebaycclone-auctionoffer-service-auctionofferbid-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `auctionOfferBid` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`auctionOfferBid`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferBid","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"auctionOfferBid":{"id":"ID","userId":"ID","bidAmount":"Double","placedAt":"Date","currency":"String","status":"Enum","status_idx":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event auctionofferoffer-created **Event topic** : `ebaycclone-auctionoffer-service-auctionofferoffer-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `auctionOfferOffer` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`auctionOfferOffer`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferOffer","method":"POST","action":"create","appVersion":"Version","rowCount":1,"auctionOfferOffer":{"id":"ID","buyerId":"ID","currency":"String","productId":"ID","counterOfferId":"ID","counterMessage":"String","counterAmount":"Double","offerAmount":"Double","message":"String","sellerId":"ID","status":"Enum","status_idx":"Integer","expiresAt":"Date","respondedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event auctionofferbids-listed **Event topic** : `ebaycclone-auctionoffer-service-auctionofferbids-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `auctionOfferBids` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`auctionOfferBids`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferBids","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","auctionOfferBids":[{"id":"ID","userId":"ID","bidAmount":"Double","placedAt":"Date","currency":"String","status":"Enum","status_idx":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event auctionofferbid-deleted **Event topic** : `ebaycclone-auctionoffer-service-auctionofferbid-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `auctionOfferBid` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`auctionOfferBid`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferBid","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"auctionOfferBid":{"id":"ID","userId":"ID","bidAmount":"Double","placedAt":"Date","currency":"String","status":"Enum","status_idx":"Integer","productId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event auctionofferoffer-deleted **Event topic** : `ebaycclone-auctionoffer-service-auctionofferoffer-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `auctionOfferOffer` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`auctionOfferOffer`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferOffer","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"auctionOfferOffer":{"id":"ID","buyerId":"ID","currency":"String","productId":"ID","counterOfferId":"ID","counterMessage":"String","counterAmount":"Double","offerAmount":"Double","message":"String","sellerId":"ID","status":"Enum","status_idx":"Integer","expiresAt":"Date","respondedAt":"Date","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Index Event auctionofferbid-created **Event topic**: `elastic-index-ebaycclone_auctionofferbid-created` **Event payload**: ```json {"id":"ID","userId":"ID","bidAmount":"Double","placedAt":"Date","currency":"String","status":"Enum","status_idx":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event auctionofferbid-updated **Event topic**: `elastic-index-ebaycclone_auctionofferbid-created` **Event payload**: ```json {"id":"ID","userId":"ID","bidAmount":"Double","placedAt":"Date","currency":"String","status":"Enum","status_idx":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event auctionofferbid-deleted **Event topic**: `elastic-index-ebaycclone_auctionofferbid-deleted` **Event payload**: ```json {"id":"ID","userId":"ID","bidAmount":"Double","placedAt":"Date","currency":"String","status":"Enum","status_idx":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event auctionofferbid-extended **Event topic**: `elastic-index-ebaycclone_auctionofferbid-extended` **Event payload**: ```js { id: id, extends: { [extendName]: "Object", [extendName + "_count"]: "Number", }, } ``` # Route Events Route events are emitted following the successful execution of a route. While most routes perform CRUD (Create, Read, Update, Delete) operations on data objects, resulting in route events that closely resemble database events, there are distinctions worth noting. A single route execution might trigger multiple CRUD actions and ElasticSearch indexing operations. However, for those primarily concerned with the overarching business logic and its outcomes, listening to the consolidated route event, published once at the conclusion of the route's execution, is more pertinent. Moreover, routes often deliver aggregated data beyond the primary database object, catering to specific client needs. For instance, creating a data object via a route might not only return the entity's data but also route-specific metrics, such as the executing user's permissions related to the entity. Alternatively, a route might automatically generate default child entities following the creation of a parent object. Consequently, the route event encapsulates a unified dataset encompassing both the parent and its children, in contrast to individual events triggered for each entity created. Therefore, subscribing to route events can offer a richer, more contextually relevant set of information aligned with business logic. The payload of a route event mirrors the REST response JSON of the route, providing a direct and comprehensive reflection of the data and metadata communicated to the client. This ensures that subscribers to route events receive a payload that encapsulates both the primary data involved and any additional information deemed significant at the business level, facilitating a deeper understanding and integration of the service's functional outcomes. ## Route Event auctionofferoffer-updated **Event topic** : `ebaycclone-auctionoffer-service-auctionofferoffer-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `auctionOfferOffer` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`auctionOfferOffer`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferOffer","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"auctionOfferOffer":{"id":"ID","buyerId":"ID","currency":"String","productId":"ID","counterOfferId":"ID","counterMessage":"String","counterAmount":"Double","offerAmount":"Double","message":"String","sellerId":"ID","status":"Enum","status_idx":"Integer","expiresAt":"Date","respondedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event auctionofferbid-created **Event topic** : `ebaycclone-auctionoffer-service-auctionofferbid-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `auctionOfferBid` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`auctionOfferBid`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferBid","method":"POST","action":"create","appVersion":"Version","rowCount":1,"auctionOfferBid":{"id":"ID","userId":"ID","bidAmount":"Double","placedAt":"Date","currency":"String","status":"Enum","status_idx":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event auctionofferbid-retrived **Event topic** : `ebaycclone-auctionoffer-service-auctionofferbid-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `auctionOfferBid` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`auctionOfferBid`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferBid","method":"GET","action":"get","appVersion":"Version","rowCount":1,"auctionOfferBid":{"id":"ID","userId":"ID","bidAmount":"Double","placedAt":"Date","currency":"String","status":"Enum","status_idx":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event auctionofferoffer-retrived **Event topic** : `ebaycclone-auctionoffer-service-auctionofferoffer-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `auctionOfferOffer` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`auctionOfferOffer`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferOffer","method":"GET","action":"get","appVersion":"Version","rowCount":1,"auctionOfferOffer":{"id":"ID","buyerId":"ID","currency":"String","productId":"ID","counterOfferId":"ID","counterMessage":"String","counterAmount":"Double","offerAmount":"Double","message":"String","sellerId":"ID","status":"Enum","status_idx":"Integer","expiresAt":"Date","respondedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event auctionofferoffers-listed **Event topic** : `ebaycclone-auctionoffer-service-auctionofferoffers-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `auctionOfferOffers` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`auctionOfferOffers`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferOffers","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","auctionOfferOffers":[{"id":"ID","buyerId":"ID","currency":"String","productId":"ID","counterOfferId":"ID","counterMessage":"String","counterAmount":"Double","offerAmount":"Double","message":"String","sellerId":"ID","status":"Enum","status_idx":"Integer","expiresAt":"Date","respondedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event auctionofferbid-updated **Event topic** : `ebaycclone-auctionoffer-service-auctionofferbid-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `auctionOfferBid` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`auctionOfferBid`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferBid","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"auctionOfferBid":{"id":"ID","userId":"ID","bidAmount":"Double","placedAt":"Date","currency":"String","status":"Enum","status_idx":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event auctionofferoffer-created **Event topic** : `ebaycclone-auctionoffer-service-auctionofferoffer-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `auctionOfferOffer` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`auctionOfferOffer`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferOffer","method":"POST","action":"create","appVersion":"Version","rowCount":1,"auctionOfferOffer":{"id":"ID","buyerId":"ID","currency":"String","productId":"ID","counterOfferId":"ID","counterMessage":"String","counterAmount":"Double","offerAmount":"Double","message":"String","sellerId":"ID","status":"Enum","status_idx":"Integer","expiresAt":"Date","respondedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event auctionofferbids-listed **Event topic** : `ebaycclone-auctionoffer-service-auctionofferbids-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `auctionOfferBids` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`auctionOfferBids`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferBids","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","auctionOfferBids":[{"id":"ID","userId":"ID","bidAmount":"Double","placedAt":"Date","currency":"String","status":"Enum","status_idx":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event auctionofferbid-deleted **Event topic** : `ebaycclone-auctionoffer-service-auctionofferbid-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `auctionOfferBid` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`auctionOfferBid`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferBid","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"auctionOfferBid":{"id":"ID","userId":"ID","bidAmount":"Double","placedAt":"Date","currency":"String","status":"Enum","status_idx":"Integer","productId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event auctionofferoffer-deleted **Event topic** : `ebaycclone-auctionoffer-service-auctionofferoffer-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `auctionOfferOffer` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`auctionOfferOffer`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferOffer","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"auctionOfferOffer":{"id":"ID","buyerId":"ID","currency":"String","productId":"ID","counterOfferId":"ID","counterMessage":"String","counterAmount":"Double","offerAmount":"Double","message":"String","sellerId":"ID","status":"Enum","status_idx":"Integer","expiresAt":"Date","respondedAt":"Date","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` # Copyright All sources, documents and other digital materials are copyright of . # About Us For more information please visit our website: . . . # **EBAYCCLONE** FRONTEND GUIDE FOR AI CODING AGENTS This document is a rest api guide for the ebaycclone project. The document is designed for AI agents who will generate frontend code that will consume the project backend. The project has got 1 auth service, 1 notification service, 1 bff service and business services. Each service is a separate microservice application and listens the HTTP request from different service urls. The services may be in preview server, staging server or real production server. So each service have got 3 acess urls. Frontend application should support all deployemnt servers in the development phase, and user should be able to select the target api server in the login page. ## Project Introduction ebaycClone is a comprehensive backend for an online marketplace supporting auctions and fixed-price sales of physical goods, with role-based access, public user registration, Stripe payments, notifications, and robust ownership enforcement. ## API Structure ### Object Structure of a Successfull Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client. **HTTP Status Codes:** - **200 OK**: This status code is returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request has been processed successfully. - **201 Created**: This status code is specific to CREATE operations, signifying that the requested resource has been successfully created. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling the successful execution of the request. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` - **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation performed. ### Additional Data Each api may have include addtional data other than the main data object according to the business logic of the API. They will be given in each API's response signature. ### Error Response If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity: - **400 Bad Request**: The request was improperly formatted or contained invalid parameters, preventing the server from processing it. - **401 Unauthorized**: The request lacked valid authentication token , login required - **403 Forbidden Error** Curent token provided do not grant access to the requested resource. - **404 Not Found**: The requested resource was not found on the server. - **500 Internal Server Error**: The server encountered an unexpected condition that prevented it from fulfilling the request. Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Accessing the backend Each service of the backend has got its own url according to the deployment environement. User may want to test the frontend in one of the 3 deployments of the application, preview, staging and production. Please ensure that register and login pages do have a deployemnt server selection option, so as the frontned coding agent you can arrange the base url path of all services. The base url of the application in each environment is as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com` * **Staging:** `https://ebaycclone-stage.mindbricks.co` * **Production:** `https://ebaycclone.mindbricks.co` For the auth service the base url is as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` For each other service, the service base url will be given in service sections. Any login requied request to the backend should have a valid token, when a user makes a successfull login, the ressponse JSON includes a JWT access token in the `accessToken`fields. In normal conditions, this token is also set to the cookie and then consumed automatically, but since AI coding agents preview options may fail to use cookies, please ensure that in each request include the access token in the bearer auth header. ## Registration Management First of all please ensure that register and login pages do have a deployemnt server selection option, so as the frontned coding agent you can arrange the base url path of all services. Start with a landing page and arranging register, verification and login flow. So at the first step, you need a general knowledge of the application to make a good landing page and the authetication flow. ### How To Register Using `registeruser` route of auth api, send the required fields to the backend in your registration page. The registerUser api in in `auth` service, is described with request and response structure below. Note that since `registerUser` api is a business api, it has a version control, so please call it with the given version like `/v1/registeruser` ### `Register User` API This api is used by public users to register themselves **Rest Route** The `registerUser` API REST controller can be triggered via the following route: `/v1/registeruser` **Rest Request Parameters** The `registerUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **password** : The password defined by the the user that is being registered. **fullname** : The fullname defined by the the user that is being registered. **email** : The email defined by the the user that is being registered. **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` After a successful registration, frontend code should handle the verification needs. The registration response will have a `user` object in the root envelope, this object will have user information with an `id` parameter. ### Email Verification In the registration response, you should check the property `emailVerificationNeeded` in the reponse root, and if this property is true you should start the email verification flow. After login process, if you get an HTTP error status, and if there is an `errCode` property in the response with `EmailVerificationNeeded` value, you should start the email verification flow. 1. Call the email verification `start` route of the backend (described below) with the user email, backend will send a secret code to the given email adresss. **Backend can send the email message if the architect defined a real mail service or smtp server, so during the development time backend will send the secret code also to the frontend. You can get this secret code from the response within the `secretCode` property**. 2. The secret code in the sent email message will be a 6 digits code , and you should arrange an input page so that the user can paste this code to the frontend application. Please navigate to this input page after you start the verification process. **If the secretCode is sent to the frontend for test purposes, then you should show it as info in the input page, so that user can copy and paste it**. 3. There is a `codeIndex` property in the start response, please show it's value on the input page, so that user can match the index in the message with the one on the screen. 4. When the user submits the code, please complete the email verification using the `complete` route of the backend (described below) with the user email and the secret code. 5. After you get a successful response from email verification, you can navigate to the login page. Here is the `start`and `complete` routes of email verification. These are system routes , so they dont have a version control. #### `POST /verification-services/email-verification/start` **Purpose:** Starts the email verification by generating and sending a secret code. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `email` | String | Yes | User’s email address to verify | **Example Request** ```json { "email": "user@example.com" } ``` **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ In production, `secretCode` is **not** returned — only sent via email. **Error Responses** * `400 Bad Request`: Already verified * `403 Forbidden`: Too many attempts (rate limit) --- #### `POST /verification-services/email-verification/complete` **Purpose:** Completes the verification using the received code. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `email` | String | Yes | User’s email | | `secretCode` | String | Yes | Verification code | **Success Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` **Error Responses** * `403 Forbidden`: Code expired or mismatched * `404 Not Found`: No verification in progress --- ## Login Management After a successfull login and completing required verifications, user can now login. Please make a fancy minimal login page where user can enter his email and password. ## Bucket Management This application has a bucket service and is used to store user or other objects related files. Bucket service is login agnostic, so when accessing for write or private read, you should insert a bucket token (given by services) to your request authorization header as bearer token. **User Bucket** This bucket is used to store public user files for each user. When a user logs in, or in /currentuser response there is `userBucketToken` to be used when sending user related public files to the bucket service. To upload `POST {baseUrl}/bucket/upload` Request body is form data which includes the bucketId and the file as binary in `files` property. ```js { bucketId: "{userId}-public-user-bucket", files: {binary} } ``` Response status is 200 on succesfull result, eg body: ```json { "success": true, "data": [ { "fileId": "9da03f6d-0409-41ad-bb06-225a244ae408", "originalName": "test (10).png", "mimeType": "image/png", "size": 604063, "status": "uploaded", "bucketName": "f7103b85-fcda-4dec-92c6-c336f71fd3a2-public-user-bucket", "isPublic": true, "downloadUrl": "https://babilcom.mindbricks.co/bucket/download/9da03f6d-0409-41ad-bb06-225a244ae408" } ] } ``` To download a file from the bucket, you should know its fileId, so if youupload an avatar or something else, be sure that the download url or the fileId is stored in backend. Bucket is mostly used, in object creations where alos demands an addtional file like a product image or user avatar. So after you upload your image to the bucket, insert the returned download url to the related property in the related object creation. **Application Bucket** This Ebaycclone application alos has common public bucket which everybody has a read access, but only users who have `superAdmin`, `admin` or `saasAdmin` roles can write (upload) to the bucket. The common public project bucket id is `"ebaycclone-public-common-bucket"` and in certain areas like product image uploads, since the user will already have the admin bucket token, he will be able to upload realted object images. Please make your UI arrangements as able to upload files to the bucket using these bucket tokens. **Object Buckets** Some objects may return also a bucket token, to upload or access related files with object. For example, when you get a project's data in a project management application, if there is a public or private bucket token, this is provided mostly for uploading project related files or downloading them with the token. These buckets will be used according to the descriptions given along with the object definitions. ## Role Management This Ebaycclone may have different role names defined fro different business logic. But unless another case is asked by the user, respect to the admin roles which may be `superAdmin`, `admin` or `saasAdmin` in the currentuser or login response given with the `roleId`property. ```json { // ... "roleId":"superAdmin", // ... } ``` If the application needs an admin panel, or any admin related page, please use these roleId's to decide if the user can access those pages or not. ## 1. Authentication Routes ### 1.1 `POST /login` — User Login **Purpose:** Verifies user credentials and creates an authenticated session with a JWT access token. **Access Routes:** * `GET /login`: Returns a minimal HTML login page (for browser-based testing). * `POST /login`: Authenticates user credentials and returns an access token and session. #### Request Parameters | Parameter | Type | Required | Source | | ---------- | ------ | -------- | ----------------------- | | `username` | String | Yes | `request.body.username` | | `password` | String | Yes | `request.body.password` | #### Behavior * Authenticates credentials and returns a session object. * Sets cookie: `projectname-access-token[-tenantCodename]` * Adds the same token in response headers. * Accepts either `username` or `email` fields (if both exist, `username` is prioritized). #### Example ```js axios.post("/login", { username: "user@example.com", password: "securePassword" }); ``` #### Success Response ```json { "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", //... } ``` #### Error Responses * `401 Unauthorized`: Invalid credentials * `403 Forbidden`: Email/mobile verification or 2FA pending * `400 Bad Request`: Missing parameters --- ### 1.2 `POST /logout` — User Logout **Purpose:** Terminates the current session and clears associated authentication tokens. #### Behavior * Invalidates session (if exists). * Clears cookie `projectname-access-token[-tenantCodename]`. * Returns a confirmation response (always `200 OK`). #### Example ```js axios.post("/logout", {}, { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` #### Notes * Can be called without a session (idempotent behavior). * Works for both cookie-based and token-based sessions. #### Success Response ```json { "status": "OK", "message": "User logged out successfully" } ``` --- ## 2. Verification Services Overview All verification routes are grouped under the `/verification-services` base path. They follow a **two-step verification pattern**: `start` → `complete`. --- ## 3. Email Verification ### 3.1 Trigger Scenarios * After registration (`emailVerificationRequiredForLogin` = true) * When updating email address * When login fails due to unverified email ### 3.2 Flow Summary 1. `/start` → Generate & send code via email. 2. `/complete` → Verify code and mark email as verified. ** PLEASE NOTE ** Email verification is a frontend triiggered process. After user registers, the frontend should start the email verification process and navigate to its code input page. --- ### 3.3 `POST /verification-services/email-verification/start` **Purpose:** Starts the email verification by generating and sending a secret code. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `email` | String | Yes | User’s email address to verify | **Example Request** ```json { "email": "user@example.com" } ``` **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ In production, `secretCode` is **not** returned — only sent via email. **Error Responses** * `400 Bad Request`: Already verified * `403 Forbidden`: Too many attempts (rate limit) --- ### 3.4 `POST /verification-services/email-verification/complete` **Purpose:** Completes the verification using the received code. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `email` | String | Yes | User’s email | | `secretCode` | String | Yes | Verification code | **Success Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` **Error Responses** * `403 Forbidden`: Code expired or mismatched * `404 Not Found`: No verification in progress --- ### 3.5 Behavioral Notes * **Resend Cooldown:** `resendTimeWindow` (e.g. 60s) * **Expiration:** Codes expire after `expireTimeWindow` (e.g. 1 day) * **Single Active Session:** One verification per user --- ## 4. Mobile Verification ### 4.1 Trigger Scenarios * After registration (`mobileVerificationRequiredForLogin` = true) * When updating phone number * On login requiring mobile verification ### 4.2 Flow 1. `/start` → Sends verification code via SMS 2. `/complete` → Validates code and confirms number --- ### 4.3 `POST /verification-services/mobile-verification/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------ | | `email` | String | Yes | User’s email to locate mobile record | **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 180, "verificationType": "byCode", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ `secretCode` returned only in development. **Errors** * `400 Bad Request`: Already verified * `403 Forbidden`: Rate-limited --- ### 4.4 `POST /verification-services/mobile-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------------- | | `email` | String | Yes | Associated email | | `secretCode` | String | Yes | Code received via SMS | **Success Response** ```json { "status": "OK", "isVerified": true, "mobile": "+1 333 ...", // in testMode "userId": "user-uuid", } ``` --- ### 4.5 Behavioral Notes * **Cooldown:** One code per minute * **Expiration:** Codes valid for 1 day * **One Session Per User** --- ## 5. Two-Factor Authentication (2FA) ### 5.1 Email 2FA **Flow** 1. `/start` → Generates and sends email code 2. `/complete` → Verifies code and updates session --- #### `POST /verification-services/email-2factor-verification/start` | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ---------------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Current session | | `client` | String | No | Optional context | | `reason` | String | No | Reason for 2FA | **Response** ```json { "status": "OK", "sessionId": "user session id UUID", "userId": "user-uuid", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", } ``` --- #### `POST /verification-services/email-2factor-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `secretCode` | String | Yes | Code from email | **Response** ```json { // user session data "sessionId": "session-uuid", // ... } ``` --- ### 5.2 Mobile 2FA **Flow** 1. `/start` → Sends SMS code 2. `/complete` → Validates and finalizes session --- #### `POST /verification-services/mobile-2factor-verification/start` | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ----------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `client` | String | No | Context | | `reason` | String | No | Reason | **Response** ```json { "status": "OK", "sessionId": "user session id UUID", "userId": "user-uuid", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", } ``` --- #### `POST /verification-services/mobile-2factor-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------ | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `secretCode` | String | Yes | Code via SMS | **Response** ```json { // user session data "sessionId": "session-uuid", // ... } ``` --- ### 5.3 2FA Behavioral Notes * One active code per session * Cooldown: `resendTimeWindow` (e.g., 60s) * Expiration: `expireTimeWindow` (e.g., 5m) --- ## 6. Password Reset ### 6.1 By Email **Flow** 1. `/start` → Sends verification code via email 2. `/complete` → Validates and resets password --- #### `POST /verification-services/password-reset-by-email/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------- | | `email` | String | Yes | User email | **Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` #### `POST /verification-services/password-reset-by-email/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------- | | `email` | String | Yes | User email | | `secretCode` | String | Yes | Code received | | `password` | String | Yes | New password | **Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` --- ### 6.2 By Mobile **Flow** 1. `/start` → Sends SMS code 2. `/complete` → Validates and resets password --- #### `POST /verification-services/password-reset-by-mobile/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------- | | `mobile` | String | Yes | Mobile number | **Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` #### `POST /verification-services/password-reset-by-mobile/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ---------------- | | `email` | String | Yes | Associated email | | `secretCode` | String | Yes | Code via SMS | | `password` | String | Yes | New password | **Response** ```json { "status": "OK", "isVerified": true, "mobile": "+1 444 ....", // in testMode "userId": "user-uuid", } ``` --- ### 6.3 Behavioral Notes * Cooldown: 60s resend * Expiration: 24h * One session per user * Works without an active login session --- ## 7. Verification Method Types ### 7.1 `byCode` User manually enters the 6-digit code in frontend. ### 7.2 `byLink` Frontend handles a one-click verification via email/SMS link containing code parameters. ## 8) `GET /currentuser` — Current Session **Purpose** Return the currently authenticated user’s session. **Route Type** `sessionInfo` **Authentication** Requires a valid access token (header or cookie). ### Request *No parameters.* ### Example ```js axios.get("/currentuser", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) Returns the session object (identity, tenancy, token metadata): ```json { "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", "roleId": "user", "tenantId": "abc123", "accessToken": "jwt-token-string", "...": "..." } ``` ### Errors * **401 Unauthorized** — No active session/token ```json { "status": "ERR", "message": "No login found" } ``` **Notes** * Commonly called by web/mobile clients after login to hydrate session state. * Includes key identity/tenant fields and a token reference (if applicable). * Ensure a valid token is supplied to receive a 200 response. --- ## 9) `GET /permissions` — List Effective Permissions **Purpose** Return all effective permission grants for the current user. **Route Type** `permissionFetch` **Authentication** Requires a valid access token. ### Request *No parameters.* ### Example ```js axios.get("/permissions", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) Array of permission grants (aligned with `givenPermissions`): ```json [ { "id": "perm1", "permissionName": "adminPanel.access", "roleId": "admin", "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" }, { "id": "perm2", "permissionName": "orders.manage", "roleId": null, "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" } ] ``` **Field meanings (per item):** * `permissionName`: Granted permission key. * `roleId`: Present if granted via role. * `subjectUserId`: Present if granted directly to the user. * `subjectUserGroupId`: Present if granted via group. * `objectId`: Present if scoped to a specific object (OBAC). * `canDo`: `true` if enabled, `false` if restricted. ### Errors * **401 Unauthorized** — No active session ```json { "status": "ERR", "message": "No login found" } ``` * **500 Internal Server Error** — Unexpected failure **Notes** * Available on all Mindbricks-generated services (not only Auth). * **Auth service:** Reads live `givenPermissions` from DB. * **Other services:** Typically respond from a cached/projected view (e.g., ElasticSearch) for faster checks. > **Tip:** Cache permission results client-side/server-side and refresh after login or permission updates. --- ## 10) `GET /permissions/:permissionName` — Check Permission Scope **Purpose** Check whether the current user has a specific permission and return any scoped object exceptions/inclusions. **Route Type** `permissionScopeCheck` **Authentication** Requires a valid access token. ### Path Parameters | Name | Type | Required | Source | | ---------------- | ------ | -------- | ------------------------------- | | `permissionName` | String | Yes | `request.params.permissionName` | ### Example ```js axios.get("/permissions/orders.manage", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) ```json { "canDo": true, "exceptions": [ "a1f2e3d4-xxxx-yyyy-zzzz-object1", "b2c3d4e5-xxxx-yyyy-zzzz-object2" ] } ``` **Interpretation** * If `canDo: true`: permission is generally granted **except** the listed `exceptions` (restrictions). * If `canDo: false`: permission is generally **not** granted, **only** allowed for the listed `exceptions` (selective overrides). * `exceptions` contains object IDs (UUID strings) from the relevant domain model. ### Errors * **401 Unauthorized** — No active session/token. ## Services And Data Object ## Auth Service Authentication service for the project ### Auth Service Data Objects **User** A data object that stores the user information and handles login settings. ### Auth Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` ### `Get User` API This api is used by admin roles or the users themselves to get the user profile information. **Rest Route** The `getUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `getUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users/:userId** ```js axios({ method: 'GET', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update User` API This route is used by admins to update user profiles. **Rest Route** The `updateUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `updateUser` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/users/:userId** ```js axios({ method: 'PATCH', url: `/v1/users/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Profile` API This route is used by users to update their profiles. **Rest Route** The `updateProfile` API REST controller can be triggered via the following route: `/v1/profile/:userId` **Rest Request Parameters** The `updateProfile` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/profile/:userId** ```js axios({ method: 'PATCH', url: `/v1/profile/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create User` API This api is used by admin roles to create a new user manually from admin panels **Rest Route** The `createUser` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `createUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | email | String | true | request.body?.email | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **email** : A string value to represent the user's email. **password** : A string value to represent the user's password. It will be stored as hashed. **fullname** : A string value to represent the fullname of the user **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/users** ```js axios({ method: 'POST', url: '/v1/users', data: { avatar:"String", email:"String", password:"String", fullname:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete User` API This api is used by admins to delete user profiles. **Rest Route** The `deleteUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `deleteUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/users/:userId** ```js axios({ method: 'DELETE', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Archive Profile` API This api is used by users to archive their profiles. **Rest Route** The `archiveProfile` API REST controller can be triggered via the following route: `/v1/archiveprofile/:userId` **Rest Request Parameters** The `archiveProfile` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/archiveprofile/:userId** ```js axios({ method: 'DELETE', url: `/v1/archiveprofile/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Users` API The list of users is filtered by the tenantId. **Rest Route** The `listUsers` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `listUsers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users** ```js axios({ method: 'GET', url: '/v1/users', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Search Users` API The list of users is filtered by the tenantId. **Rest Route** The `searchUsers` API REST controller can be triggered via the following route: `/v1/searchusers` **Rest Request Parameters** The `searchUsers` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | keyword | String | true | request.query?.keyword | **keyword** : **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchusers** ```js axios({ method: 'GET', url: '/v1/searchusers', data: { }, params: { keyword:'"String"', } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Userrole` API This route is used by admin roles to update the user role.The default role is user when a user is registered. A user's role can be updated by superAdmin or admin **Rest Route** The `updateUserRole` API REST controller can be triggered via the following route: `/v1/userrole/:userId` **Rest Request Parameters** The `updateUserRole` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | roleId | String | true | request.body?.roleId | **userId** : This id paremeter is used to select the required data object that will be updated **roleId** : The new roleId of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userrole/:userId** ```js axios({ method: 'PATCH', url: `/v1/userrole/${userId}`, data: { roleId:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpassword` API This route is used to update the password of users in the profile page by users themselves **Rest Route** The `updateUserPassword` API REST controller can be triggered via the following route: `/v1/userpassword/:userId` **Rest Request Parameters** The `updateUserPassword` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | oldPassword | String | true | request.body?.oldPassword | | newPassword | String | true | request.body?.newPassword | **userId** : This id paremeter is used to select the required data object that will be updated **oldPassword** : The old password of the user that will be overridden bu the new one. Send for double check. **newPassword** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpassword/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpassword/${userId}`, data: { oldPassword:"String", newPassword:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpasswordbyadmin` API This route is used to change any user password by admins only. Superadmin can chnage all passwords, admins can change only nonadmin passwords **Rest Route** The `updateUserPasswordByAdmin` API REST controller can be triggered via the following route: `/v1/userpasswordbyadmin/:userId` **Rest Request Parameters** The `updateUserPasswordByAdmin` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | password | String | true | request.body?.password | **userId** : This id paremeter is used to select the required data object that will be updated **password** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpasswordbyadmin/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpasswordbyadmin/${userId}`, data: { password:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Briefuser` API This route is used by public to get simple user profile information. **Rest Route** The `getBriefUser` API REST controller can be triggered via the following route: `/v1/briefuser/:userId` **Rest Request Parameters** The `getBriefUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/briefuser/:userId** ```js axios({ method: 'GET', url: `/v1/briefuser/${userId}`, data: { }, params: { } }); ``` **REST Response** This route's response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "fullname": "String", "avatar": "String", "isActive": true } } ``` ### `Register User` API This api is used by public users to register themselves **Rest Route** The `registerUser` API REST controller can be triggered via the following route: `/v1/registeruser` **Rest Request Parameters** The `registerUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **password** : The password defined by the the user that is being registered. **fullname** : The fullname defined by the the user that is being registered. **email** : The email defined by the the user that is being registered. **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## AuctionOffer Service Handles auction bids and fixed-price offers for product listings, enforces real-time auction state, handles strict offer workflows including counter-offers, and triggers domain events for bid/offer notifications. No payment or frontend aggregation logic included. ### AuctionOffer Service Data Objects **AuctionOfferOffer** Represents an offer (best offer/counter-offer) made on a fixed-price product. Tracks buyer, seller, amounts, currency, state transitions, counter-offers, and expiry. **AuctionOfferBid** Represents an individual bid placed on an auction-type product. Linked to product and user, tracks bid amount, currency, status (ACTIVE, WON, LOST, CANCELLED), and time placed. ### AuctionOffer Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auctionoffer-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auctionoffer-api` * **Production:** `https://ebaycclone.mindbricks.co/auctionoffer-api` ### `Update Auctionofferoffer` API Updates offer: accepts/declines/counters by seller, withdraws by buyer before response. Enforces status transition rules, sets respondedAt. Triggers event. **Rest Route** The `updateAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `updateAuctionOfferOffer` api has got 8 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | message | String | false | request.body?.message | | status | Enum | false | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | **auctionOfferOfferId** : This id paremeter is used to select the required data object that will be updated **counterOfferId** : References another offer (counter-offer chain). **counterMessage** : Message accompanying seller's counter-offer (optional). **counterAmount** : Counter-offer amount (when offer is COUNTERED). **message** : Message/special notes from buyer (optional). **status** : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). **expiresAt** : When this offer expires (optional). **respondedAt** : When the seller (or buyer, for counter-offer) responded/updated the offer status. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Auctionofferbid` API Creates a new bid for an auction product. Validates auction status, not seller, product type, bid window, and ensures min. increment. Updates product.currentBid and product.highestBidderId atomically. Triggers notification event. **Rest Route** The `createAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids` **Rest Request Parameters** The `createAuctionOfferBid` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | bidAmount | Double | true | request.body?.bidAmount | | currency | String | true | request.body?.currency | | status | Enum | true | request.body?.status | | productId | ID | true | request.body?.productId | **bidAmount** : Bid amount placed by the user. **currency** : ISO currency for the bid (e.g., USD, EUR). **status** : Bid status: ACTIVE, WON, LOST, CANCELLED. **productId** : Product being bid on (must be AUCTION type). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/auctionofferbids** ```js axios({ method: 'POST', url: '/v1/auctionofferbids', data: { bidAmount:"Double", currency:"String", status:"Enum", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Auctionofferbid` API Gets a single bid (only visible to owner/admin or for auction history). **Rest Route** The `getAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `getAuctionOfferBid` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | **auctionOfferBidId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'GET', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Auctionofferoffer` API Gets a single offer (shown to buyer/seller or admin). **Rest Route** The `getAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `getAuctionOfferOffer` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | **auctionOfferOfferId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'GET', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Auctionofferoffers` API Lists offers by product, user, status, or counterOffer chain. **Rest Route** The `listAuctionOfferOffers` API REST controller can be triggered via the following route: `/v1/auctionofferoffers` **Rest Request Parameters** The `listAuctionOfferOffers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers** ```js axios({ method: 'GET', url: '/v1/auctionofferoffers', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferOffers": [ { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Auctionofferbid` API Updates a bid’s status (allow only status update, e.g. CANCELLED, WIN/LOSE on admin settlement). Only owner/admin, and only if auction not ended or not settled. Triggers notification event. **Rest Route** The `updateAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `updateAuctionOfferBid` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | | status | Enum | false | request.body?.status | **auctionOfferBidId** : This id paremeter is used to select the required data object that will be updated **status** : Bid status: ACTIVE, WON, LOST, CANCELLED. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { status:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Auctionofferoffer` API Creates a new offer for a fixed-price product, validating acceptOffers, type, eligibility, and product/seller/buyer active. Defaults to PENDING state. Triggers notification event. **Rest Route** The `createAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers` **Rest Request Parameters** The `createAuctionOfferOffer` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | productId | ID | true | request.body?.productId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | offerAmount | Double | true | request.body?.offerAmount | | message | String | false | request.body?.message | | status | Enum | true | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | **currency** : ISO currency (e.g., USD, EUR) for the offer. **productId** : Product the offer applies to (must be fixed-price, acceptOffers true). **counterOfferId** : References another offer (counter-offer chain). **counterMessage** : Message accompanying seller's counter-offer (optional). **counterAmount** : Counter-offer amount (when offer is COUNTERED). **offerAmount** : Primary offer amount from buyer. **message** : Message/special notes from buyer (optional). **status** : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). **expiresAt** : When this offer expires (optional). **respondedAt** : When the seller (or buyer, for counter-offer) responded/updated the offer status. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/auctionofferoffers** ```js axios({ method: 'POST', url: '/v1/auctionofferoffers', data: { currency:"String", productId:"ID", counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", offerAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Auctionofferbids` API Lists bids by product, user, or auction, supports history/analytics. **Rest Route** The `listAuctionOfferBids` API REST controller can be triggered via the following route: `/v1/auctionofferbids` **Rest Request Parameters** The `listAuctionOfferBids` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids** ```js axios({ method: 'GET', url: '/v1/auctionofferbids', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBids", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferBids": [ { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Auctionofferbid` API Soft-deletes a bid (for admin or self before auction ends). **Rest Route** The `deleteAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `deleteAuctionOfferBid` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | **auctionOfferBidId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Auctionofferoffer` API Soft-deletes an offer (allowed only in non-accepted/expired state). **Rest Route** The `deleteAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `deleteAuctionOfferOffer` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | **auctionOfferOfferId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## CategoryManagement Service Handles product categories and subcategories for marketplace browsing and classification, supporting public discovery plus admin-only management. ### CategoryManagement Service Data Objects **Category** Represents a product category in the marketplace (e.g., Electronics, Clothing, Toys), used for browsing, filtering, and discovery. Admins manage categories. **Subcategory** Represents a subcategory within a parent category (e.g., 'Smartphones' under 'Electronics'). Used for more granular product discovery and navigation. 'group' categorizes special display logic. ### CategoryManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/categorymanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/categorymanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/categorymanagement-api` ### `Delete Category` API Soft-delete a category (admin-only). **Rest Route** The `deleteCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `deleteCategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | **categoryId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/categories/:categoryId** ```js axios({ method: 'DELETE', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Subcategory` API Get a subcategory by ID. Public - only active subcategories returned except for admin. **Rest Route** The `getSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `getSubcategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | **subcategoryId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/subcategories/:subcategoryId** ```js axios({ method: 'GET', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Category` API Get a single category by ID. Public - only active categories returned (for non-admins). **Rest Route** The `getCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `getCategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | **categoryId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/categories/:categoryId** ```js axios({ method: 'GET', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Subcategory` API Update subcategory (admin-only), including group enum change. **Rest Route** The `updateSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `updateSubcategory` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | name | String | false | request.body?.name | | group | Enum | false | request.body?.group | **subcategoryId** : This id paremeter is used to select the required data object that will be updated **categoryId** : Reference to the parent category (category.id). **name** : Display name of the subcategory. **group** : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/subcategories/:subcategoryId** ```js axios({ method: 'PATCH', url: `/v1/subcategories/${subcategoryId}`, data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Subcategories` API List all subcategories for browsing/filtering, with support for group enum and parent category queries. Only active subcategories shown to public/non-admin users. **Rest Route** The `listSubcategories` API REST controller can be triggered via the following route: `/v1/subcategories` **Rest Request Parameters** The `listSubcategories` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/subcategories** ```js axios({ method: 'GET', url: '/v1/subcategories', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "subcategories": [ { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Subcategory` API Soft-delete a subcategory (admin-only). **Rest Route** The `deleteSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `deleteSubcategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | **subcategoryId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/subcategories/:subcategoryId** ```js axios({ method: 'DELETE', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Categories` API List all categories for browsing and filtering. Only active categories shown to public/non-admin users. **Rest Route** The `listCategories` API REST controller can be triggered via the following route: `/v1/categories` **Rest Request Parameters** The `listCategories` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/categories** ```js axios({ method: 'GET', url: '/v1/categories', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "categories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "categories": [ { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Category` API Update category details (admin-only). **Rest Route** The `updateCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `updateCategory` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | false | request.body?.title | **categoryId** : This id paremeter is used to select the required data object that will be updated **imageUrl** : URL for category image/avatar (optional, used for homepage visuals). **subtitle** : Optional short description for UI/tooltips. **title** : Display name of the category. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/categories/:categoryId** ```js axios({ method: 'PATCH', url: `/v1/categories/${categoryId}`, data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Subcategory` API Create a new subcategory under a given category (admin-only), with enum group constraint. **Rest Route** The `createSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories` **Rest Request Parameters** The `createSubcategory` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.body?.categoryId | | name | String | true | request.body?.name | | group | Enum | true | request.body?.group | **categoryId** : Reference to the parent category (category.id). **name** : Display name of the subcategory. **group** : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/subcategories** ```js axios({ method: 'POST', url: '/v1/subcategories', data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Category` API Create a new category (admin-only) for product classification. **Rest Route** The `createCategory` API REST controller can be triggered via the following route: `/v1/categories` **Rest Request Parameters** The `createCategory` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | true | request.body?.title | **imageUrl** : URL for category image/avatar (optional, used for homepage visuals). **subtitle** : Optional short description for UI/tooltips. **title** : Display name of the category. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/categories** ```js axios({ method: 'POST', url: '/v1/categories', data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## Messaging Service In-app messaging service for direct user-to-user text messages (buyers/sellers). Stores, retrieves, and manages user conversations. Launch version: text-only. ### Messaging Service Data Objects **MessagingMessage** A direct, text-only in-app message between two users (buyer/seller); stores sender, recipient, content, read status, and timestamp. ### Messaging Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/messaging-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/messaging-api` * **Production:** `https://ebaycclone.mindbricks.co/messaging-api` ### `List Messagingmessages` API List all messages in the conversation between the logged-in user and another party, ordered by sentAt descending. Can filter unread with isRead. Returns only messages visible to user (isActive). **Rest Route** The `listMessagingMessages` API REST controller can be triggered via the following route: `/v1/messagingmessages` **Rest Request Parameters** The `listMessagingMessages` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages** ```js axios({ method: 'GET', url: '/v1/messagingmessages', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessages", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "messagingMessages": [ { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Messagingmessage` API Send a new text message from the logged-in user to a recipient. Sender is set from session. Launch version supports only text content. **Rest Route** The `createMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages` **Rest Request Parameters** The `createMessagingMessage` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | toUserId | ID | true | request.body?.toUserId | | content | String | true | request.body?.content | | isRead | Boolean | true | request.body?.isRead | **toUserId** : Recipient (user) of this message. **content** : Text content of the message. No files or attachments for launch. **isRead** : If true, recipient has marked this message as read. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/messagingmessages** ```js axios({ method: 'POST', url: '/v1/messagingmessages', data: { toUserId:"ID", content:"String", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Messagingmessage` API Update a message (mark as read/unread). Only the recipient or admin can change isRead. No content edits. Sender, content, sentAt are immutable. **Rest Route** The `updateMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `updateMessagingMessage` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | | isRead | Boolean | false | request.body?.isRead | **messagingMessageId** : This id paremeter is used to select the required data object that will be updated **isRead** : If true, recipient has marked this message as read. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'PATCH', url: `/v1/messagingmessages/${messagingMessageId}`, data: { isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Messagingmessage` API Get a message by ID. Only accessible to the sender, the recipient, or an admin. Used for message detail view or reading a single message in a thread. **Rest Route** The `getMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `getMessagingMessage` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | **messagingMessageId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'GET', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Messagingmessage` API Delete a message (soft-delete). Only sender, recipient, or admin may delete a message. Deletion only hides it for the user; not a full erase unless both delete. **Rest Route** The `deleteMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `deleteMessagingMessage` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | **messagingMessageId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'DELETE', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## NotificationManagement Service Handles storage, management, and event-driven delivery of in-app and email notifications for user-impacting system events (bids, offers, orders, feedback, messaging, etc.). Supports marking notifications as read/unread, structured filtering by event type/channel, and always returns in-app notifications ordered by recency. ### NotificationManagement Service Data Objects **Notification** Stores and manages in-app and email notifications tied to user-facing events like bids, offers, orders, messaging, shipment, and feedback. Includes event type (notificationType) for filter/search, arbitrary event payload, and delivery channel. Soft-delete enforced. In-app notifications always sorted by createdAt DESC on retrieval. ### NotificationManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/notificationmanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/notificationmanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/notificationmanagement-api` ### `Create Notification` API Creates a notification entry in response to a system/business event. Only allowed for system/event processes and admins (not standard user/action). Typically event-driven, receives userId, notificationType, payload, and channel. **Rest Route** The `createNotification` API REST controller can be triggered via the following route: `/v1/notifications` **Rest Request Parameters** The `createNotification` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationType | Enum | true | request.body?.notificationType | | userId | ID | true | request.body?.userId | | channel | Enum | true | request.body?.channel | | payload | Object | true | request.body?.payload | | isRead | Boolean | true | request.body?.isRead | **notificationType** : Type of event triggering notification (e.g., BID_UPDATED, ORDER_SHIPPED, MESSAGE_RECEIVED, etc.). Used for display/icon and query filter. **userId** : User receiving the notification (recipient). **channel** : Channel by which notification is delivered: IN_APP or EMAIL. **payload** : Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. **isRead** : Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/notifications** ```js axios({ method: 'POST', url: '/v1/notifications', data: { notificationType:"Enum", userId:"ID", channel:"Enum", payload:"Object", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Notification` API Updates a notification (mark as read/unread, payload patch for e.g. admin fix). Only receiver (userId) or admins may update. isRead is primary update scenario; others very limited. **Rest Route** The `updateNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `updateNotification` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | | payload | Object | false | request.body?.payload | | isRead | Boolean | false | request.body?.isRead | **notificationId** : This id paremeter is used to select the required data object that will be updated **payload** : Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. **isRead** : Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/notifications/:notificationId** ```js axios({ method: 'PATCH', url: `/v1/notifications/${notificationId}`, data: { payload:"Object", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Notifications` API Returns filtered list of notifications for a user, with optional filters: notificationType, isRead, channel. Always sorted by createdAt (descending) for in-app notifications. Only retrieval allowed for owner/admin. **Rest Route** The `listNotifications` API REST controller can be triggered via the following route: `/v1/notifications` **Rest Request Parameters** The `listNotifications` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/notifications** ```js axios({ method: 'GET', url: '/v1/notifications', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notifications", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "notifications": [ { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Notification` API Soft-delete a notification record. Only receiver or admin may delete. **Rest Route** The `deleteNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `deleteNotification` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | **notificationId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/notifications/:notificationId** ```js axios({ method: 'DELETE', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Notification` API Retrieves a notification for the receiver or admin. Used to populate content on detail/expanded view. **Rest Route** The `getNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `getNotification` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | **notificationId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/notifications/:notificationId** ```js axios({ method: 'GET', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## SearchIndexing Service Maintains the denormalized search index (materialized view) for global, public search across products, sellers, categories, and subcategories. Handles indexing in response to entity events and exposes optimized query endpoints for BFF/aggregator. ### SearchIndexing Service Data Objects **SearchIndex** Materialized/denormalized search index record for a marketplace entity (product, seller, category, subcategory). Used exclusively for high-speed querying in BFF global/public search. ### SearchIndexing Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/searchindexing-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/searchindexing-api` * **Production:** `https://ebaycclone.mindbricks.co/searchindexing-api` ### `List Searchindexes` API List/search search index entries by type or referenceId (used by BFF/global search). Always excludes inactive (soft-deleted) records. Supports filtering and full-text search filters by documentType/referenceId for admin/maintenance use. **Rest Route** The `listSearchIndexes` API REST controller can be triggered via the following route: `/v1/searchindexes` **Rest Request Parameters** The `listSearchIndexes` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchindexes** ```js axios({ method: 'GET', url: '/v1/searchindexes', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndices", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "searchIndices": [ { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Searchindex` API Update an existing searchIndex record (by (documentType, referenceId) or id). Used in response to events (entity edit, data change); internal/automation/admin only. **Rest Route** The `updateSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `updateSearchIndex` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | | documentType | Enum | false | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | false | request.body?.indexedAt | **searchIndexId** : This id paremeter is used to select the required data object that will be updated **documentType** : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY **document** : Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. **referenceId** : ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. **indexedAt** : Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/searchindexs/:searchIndexId** ```js axios({ method: 'PATCH', url: `/v1/searchindexs/${searchIndexId}`, data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Searchindex` API Soft-delete a searchIndex record (by id or by (documentType, referenceId)). Typical use: in response to entity soft-delete; internal/automation/admin only. **Rest Route** The `deleteSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `deleteSearchIndex` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | **searchIndexId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/searchindexs/:searchIndexId** ```js axios({ method: 'DELETE', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Searchindex` API Create a new searchIndex record (internal, used by event triggers and admin tools only). Typically called when a new product/seller/category/subcategory is created. **Rest Route** The `createSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs` **Rest Request Parameters** The `createSearchIndex` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | documentType | Enum | true | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | true | request.body?.indexedAt | **documentType** : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY **document** : Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. **referenceId** : ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. **indexedAt** : Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/searchindexs** ```js axios({ method: 'POST', url: '/v1/searchindexs', data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Searchindex` API Get a single denormalized index record (by id, or documentType+referenceId). Used by BFF for full entity search. Always excludes inactive records unless forced (admin only path). **Rest Route** The `getSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `getSearchIndex` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | **searchIndexId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchindexs/:searchIndexId** ```js axios({ method: 'GET', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## AdminModeration Service Administrative backend service for moderation and manual override actions. Responsible for logging all admin interventions (user/product/feedback/media/category/order/notification/searchindex moderation), triggering corrections via interservice calls, and providing comprehensive audit trails for compliance. ### AdminModeration Service Data Objects **ModerationAction** Audit record for all admin moderation/override actions affecting core business entities. Links to admin, timestamp, entity type/ID, action performed, and reason. ### AdminModeration Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/adminmoderation-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/adminmoderation-api` * **Production:** `https://ebaycclone.mindbricks.co/adminmoderation-api` ### `Get Moderationaction` API Get a single moderation action log by ID. Used to review admin audit trails; accessible only to platform admins. **Rest Route** The `getModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `getModerationAction` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | **moderationActionId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/moderationactions/:moderationActionId** ```js axios({ method: 'GET', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Moderationaction` API Soft-deletes a moderation action log record (dangerous; allowed only to superadmins or strict manual correction), primarily for audit correction or internal error cleanup. Usually, moderation logs are immutable. **Rest Route** The `deleteModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `deleteModerationAction` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | **moderationActionId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/moderationactions/:moderationActionId** ```js axios({ method: 'DELETE', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Moderationaction` API Logs an admin moderation or override action in the system for audit and traceability. Requires admin login, takes context from session, and creates an audit entry for any admin operation over any entity type. **Rest Route** The `createModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions` **Rest Request Parameters** The `createModerationAction` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | entityId | ID | true | request.body?.entityId | | entityType | Enum | true | request.body?.entityType | | reason | String | true | request.body?.reason | | actionType | Enum | true | request.body?.actionType | **entityId** : ID of target entity affected by moderation (user/product/etc). **entityType** : Type of entity affected (USER, PRODUCT, FEEDBACK, MEDIA, CATEGORY, NOTIFICATION, ORDER, SEARCHINDEX). **reason** : Explanation or justification for the moderation action performed. **actionType** : Type of moderation action (e.g., SOFT_DELETE, RESTORE, UPDATE_ROLE, MANUAL_CORRECTION, MEDIA_FLAG, INDEX_REBUILD, PAYMENT_FIX, FEEDBACK_OVERRIDE, ADMIN_NOTE). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/moderationactions** ```js axios({ method: 'POST', url: '/v1/moderationactions', data: { entityId:"ID", entityType:"Enum", reason:"String", actionType:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Moderationactions` API List moderation actions for admin dashboard/audit search. Supports filtering by admin, entityType, entityId, actionType, and date. Always sorted by most recent action. **Rest Route** The `listModerationActions` API REST controller can be triggered via the following route: `/v1/moderationactions` **Rest Request Parameters** The `listModerationActions` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/moderationactions** ```js axios({ method: 'GET', url: '/v1/moderationactions', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationActions", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "moderationActions": [ { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Moderationaction` API Allows update of explanation/note on a moderation action for correction (typically by admin or superadmin only). No entity/type/admin may be changed after creation; only 'reason' is editable for audit consistency. **Rest Route** The `updateModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `updateModerationAction` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | | reason | String | false | request.body?.reason | **moderationActionId** : This id paremeter is used to select the required data object that will be updated **reason** : Explanation or justification for the moderation action performed. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/moderationactions/:moderationActionId** ```js axios({ method: 'PATCH', url: `/v1/moderationactions/${moderationActionId}`, data: { reason:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## WatchlistCart Service Handles user watchlists (with custom folders) and shopping cart preparation for checkout, strictly enforcing only fixed-price products in carts, supporting item moves/bulk operations, and robust default/folder logic.. ### WatchlistCart Service Data Objects **WatchlistItem** Item in a user’s watchlist, optionally in a named folder; references product and user. **CartItem** Single product pending checkout in a user’s cart. Only fixed-price products permitted; quantity supported for multi-unit purchases (if allowed). **WatchlistList** A named folder/list in a user’s watchlist. Default list exists for all users. Custom lists may be created and deleted. ### WatchlistCart Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/watchlistcart-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/watchlistcart-api` * **Production:** `https://ebaycclone.mindbricks.co/watchlistcart-api` ### `List Watchlistlist` API List all lists in user’s watchlists. Supports listing by listId for folders. **Rest Route** The `listWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists` **Rest Request Parameters** The `listWatchlistList` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/watchlistlists** ```js axios({ method: 'GET', url: '/v1/watchlistlists', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Cartitems` API List all cart items for a user (pending checkout). **Rest Route** The `listCartItems` API REST controller can be triggered via the following route: `/v1/cartitems` **Rest Request Parameters** The `listCartItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/cartitems** ```js axios({ method: 'GET', url: '/v1/cartitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "price": "Double", "title": "String", "type": "Enum", "type_idx": "Integer", "mediaAssetIds": "ID" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Cartitem` API Remove an item from the user’s cart. **Rest Route** The `deleteCartItem` API REST controller can be triggered via the following route: `/v1/cartitems/:cartItemId` **Rest Request Parameters** The `deleteCartItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | **cartItemId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/cartitems/:cartItemId** ```js axios({ method: 'DELETE', url: `/v1/cartitems/${cartItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Watchlistitem` API Add product to user’s watchlist (default or target list/folder). One (user, product, list) per item enforced. Block duplicates. **Rest Route** The `createWatchlistItem` API REST controller can be triggered via the following route: `/v1/watchlistitems` **Rest Request Parameters** The `createWatchlistItem` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | productId | ID | true | request.body?.productId | | listId | ID | false | request.body?.listId | **addedAt** : Timestamp watchlist item created. **productId** : Referenced product in the watchlist. **listId** : Owning watchlistList; null if in default watchlist. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/watchlistitems** ```js axios({ method: 'POST', url: '/v1/watchlistitems', data: { addedAt:"Date", productId:"ID", listId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Watchlistitems` API List all products in user’s watchlists. Supports listing by listId for folders. **Rest Route** The `listWatchlistItems` API REST controller can be triggered via the following route: `/v1/watchlistitems` **Rest Request Parameters** The `listWatchlistItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/watchlistitems** ```js axios({ method: 'GET', url: '/v1/watchlistitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Cartitemquantity` API Change the quantity for a cart item. User must own the item. **Rest Route** The `updateCartItemQuantity` API REST controller can be triggered via the following route: `/v1/cartitemquantity/:cartItemId` **Rest Request Parameters** The `updateCartItemQuantity` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | | quantity | Integer | false | request.body?.quantity | **cartItemId** : This id paremeter is used to select the required data object that will be updated **quantity** : How many units (if product allows). **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/cartitemquantity/:cartItemId** ```js axios({ method: 'PATCH', url: `/v1/cartitemquantity/${cartItemId}`, data: { quantity:"Integer", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Watchlistlist` API Create a new custom watchlist folder. Name must be unique per user; ‘Default’ is reserved for system. **Rest Route** The `createWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists` **Rest Request Parameters** The `createWatchlistList` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | name | String | true | request.body?.name | **name** : Custom folder or list name. 'Default' is reserved (non-deletable for each user). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/watchlistlists** ```js axios({ method: 'POST', url: '/v1/watchlistlists', data: { name:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Watchlistlist` API Delete a custom watchlist (folder). Items are reassigned to user’s default list. Cannot delete default list. **Rest Route** The `deleteWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists/:watchlistListId` **Rest Request Parameters** The `deleteWatchlistList` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistListId | ID | true | request.params?.watchlistListId | **watchlistListId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistlists/:watchlistListId** ```js axios({ method: 'DELETE', url: `/v1/watchlistlists/${watchlistListId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Watchlistitem` API Remove a product from a user’s watchlist. **Rest Route** The `deleteWatchlistItem` API REST controller can be triggered via the following route: `/v1/watchlistitems/:watchlistItemId` **Rest Request Parameters** The `deleteWatchlistItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistItemId | ID | true | request.params?.watchlistItemId | **watchlistItemId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistitems/:watchlistItemId** ```js axios({ method: 'DELETE', url: `/v1/watchlistitems/${watchlistItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Cartitem` API Add an item to the user’s cart. Only fixed-price products allowed. Duplicates not permitted. **Rest Route** The `createCartItem` API REST controller can be triggered via the following route: `/v1/cartitems` **Rest Request Parameters** The `createCartItem` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | **addedAt** : Timestamp added to cart. **quantity** : How many units (if product allows). **productId** : Product being checked out. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/cartitems** ```js axios({ method: 'POST', url: '/v1/cartitems', data: { addedAt:"Date", quantity:"Integer", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Do Userwatchlist` API userwatchlist **Rest Route** The `userwatchlist` API REST controller can be triggered via the following route: `/v1/userwatchlist` **Rest Request Parameters** The `userwatchlist` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userwatchlist** ```js axios({ method: 'GET', url: '/v1/userwatchlist', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Usercartitems` API list all cart items adde by user **Rest Route** The `listUserCartItems` API REST controller can be triggered via the following route: `/v1/usercartitems` **Rest Request Parameters** The `listUserCartItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/usercartitems** ```js axios({ method: 'GET', url: '/v1/usercartitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "shipping": "Double" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Do Userwatchlistlists` API list all watch lists created by user **Rest Route** The `userwatchlistlists` API REST controller can be triggered via the following route: `/v1/userwatchlistlists` **Rest Request Parameters** The `userwatchlistlists` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userwatchlistlists** ```js axios({ method: 'GET', url: '/v1/userwatchlistlists', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ## ProductListing Service Handles product listings (both auction and fixed-price), image/media storage with validations, enforces immutable type, soft-delete, and public product discovery. ### ProductListing Service Data Objects **ProductListingMedia** Stores and manages images/media associated with products, including secure URL, MIME type, and size validation. Each asset can be used by multiple products. **ProductListingProduct** Represents a single product listing (fixed-price or auction) in the marketplace, with seller, category, type, price information, shipping details, media references, and dynamic auction fields. ### ProductListing Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/productlisting-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/productlisting-api` * **Production:** `https://ebaycclone.mindbricks.co/productlisting-api` ### `List Productlistingmedia` API List all media assets (admin or for media management/bulk preview). **Rest Route** The `listProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias` **Rest Request Parameters** The `listProductListingMedia` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias** ```js axios({ method: 'GET', url: '/v1/productlistingmedias', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedias", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingMedias": [ { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Productlistingproduct` API Get a single product listing. Checks isActive and public status. Includes media, category, subcategory, and seller info via joins. **Rest Route** The `getProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `getProductListingProduct` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | **productListingProductId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'GET', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Productlistingownproducts` API listing the loggedin user's products **Rest Route** The `listProductListingOwnProducts` API REST controller can be triggered via the following route: `/v1/productlistingownproducts` **Rest Request Parameters** The `listProductListingOwnProducts` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingownproducts** ```js axios({ method: 'GET', url: '/v1/productlistingownproducts', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Productlistingmedia` API Get a single media asset by ID (for admin or to display in product UI). **Rest Route** The `getProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` **Rest Request Parameters** The `getProductListingMedia` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | **productListingMediaId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'GET', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Productlistingproducts` API List public product listings. Only isActive=true records are returned. Includes category, subcategory, seller, media joins. Supports filtering. **Rest Route** The `listProductListingProducts` API REST controller can be triggered via the following route: `/v1/productlistingproducts` **Rest Request Parameters** The `listProductListingProducts` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts** ```js axios({ method: 'GET', url: '/v1/productlistingproducts', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Productlistingproduct` API Soft-delete a product listing. Only owner or admin can delete. **Rest Route** The `deleteProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `deleteProductListingProduct` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | **productListingProductId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'DELETE', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Productlistingproduct` API Update a product listing. Product type cannot be changed (immutable). **Rest Route** The `updateProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `updateProductListingProduct` api has got 21 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | | currency | String | false | request.body?.currency | | description | Text | false | request.body?.description | | condition | Enum | false | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | false | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | false | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | false | request.body?.shippingMethod | | shipping | Double | false | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | false | request.body?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | **productListingProductId** : This id paremeter is used to select the required data object that will be updated **currency** : ISO currency code (e.g. USD, EUR) **description** : Product detailed description **condition** : Condition of product: BRAND_NEW, NEW, or USED **startBid** : The opening bid value (for auction type products) **endPrice** : Optional immediate sale/upper end price for auction (if AUCTION type) **price** : Product price (required if fixed price type) **title** : Product title **startPrice** : Minimum starting price for auction (required if AUCTION type) **endBid** : The upper (max) bid value for auction products (if any) **estimatedDelivery** : Estimated delivery date for this product **shippingCurrency** : Currency code for shipping cost **mediaAssetIds** : References to associated product/media assets **shippingMethod** : Shipping option for product: STANDARD, EXPRESS, or FREE **shipping** : Shipping cost for this product **startBidDate** : Date/time when auction bidding begins **subcategoryId** : Reference to subcategory **categoryId** : Reference to parent category **endBidDate** : Date/time when auction bidding ends **currentBid** : Current highest bid for auction-type product (updated atomically on bid placement) **highestBidderId** : User ID of current highest bidder (auction-only, updated by auction microservice) **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'PATCH', url: `/v1/productlistingproducts/${productListingProductId}`, data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Productlistingproduct` API Create a new product listing (fixed or auction), conditioned on product type. Type is immutable after creation. **Rest Route** The `createProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts` **Rest Request Parameters** The `createProductListingProduct` api has got 21 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | description | Text | true | request.body?.description | | condition | Enum | true | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | true | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | type | Enum | true | request.body?.type | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | true | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | true | request.body?.shippingMethod | | shipping | Double | true | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | true | request.body?.subcategoryId | | categoryId | ID | true | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | **currency** : ISO currency code (e.g. USD, EUR) **description** : Product detailed description **condition** : Condition of product: BRAND_NEW, NEW, or USED **startBid** : The opening bid value (for auction type products) **endPrice** : Optional immediate sale/upper end price for auction (if AUCTION type) **price** : Product price (required if fixed price type) **title** : Product title **startPrice** : Minimum starting price for auction (required if AUCTION type) **type** : Product listing type, either FIXED or AUCTION (immutable after creation) **endBid** : The upper (max) bid value for auction products (if any) **estimatedDelivery** : Estimated delivery date for this product **shippingCurrency** : Currency code for shipping cost **mediaAssetIds** : References to associated product/media assets **shippingMethod** : Shipping option for product: STANDARD, EXPRESS, or FREE **shipping** : Shipping cost for this product **startBidDate** : Date/time when auction bidding begins **subcategoryId** : Reference to subcategory **categoryId** : Reference to parent category **endBidDate** : Date/time when auction bidding ends **currentBid** : Current highest bid for auction-type product (updated atomically on bid placement) **highestBidderId** : User ID of current highest bidder (auction-only, updated by auction microservice) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/productlistingproducts** ```js axios({ method: 'POST', url: '/v1/productlistingproducts', data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", type:"Enum", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Productlistingmedia` API Soft-delete a media asset (typically by admin or media owner for flagged/invalid content). **Rest Route** The `deleteProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` **Rest Request Parameters** The `deleteProductListingMedia` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | **productListingMediaId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'DELETE', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Productlistingmedia` API Create a new media asset record after validation. Used mainly by edge controller after upload. **Rest Route** The `createProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias` **Rest Request Parameters** The `createProductListingMedia` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | mimeType | String | true | request.body?.mimeType | | productId | ID | false | request.body?.productId | | url | String | true | request.body?.url | | size | Integer | true | request.body?.size | **mimeType** : MIME type of the uploaded media (e.g., image/jpeg) **productId** : ID of product associated with this media asset **url** : Secure, validated URL for the media asset (S3 or equivalent) **size** : Media size in bytes (for validation and quota) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/productlistingmedias** ```js axios({ method: 'POST', url: '/v1/productlistingmedias', data: { mimeType:"String", productId:"ID", url:"String", size:"Integer", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## OrderManagement Service Handles all marketplace orders, manual checkout flows for fixed-price/offer/auction settlements, Stripe payment processing and webhook reconciliation, explicit status updates (shipping, delivery, cancellation), and feedback eligibility via orderItems. ### OrderManagement Service Data Objects **OrderManagementOrder** Marketplace order record. Stores buyer, shipping, status, items, Stripe payment data, and manual shipment/delivery events. Only accessible to admins or the buyer/seller of order items. **OrderManagementOrderItem** Order line item representing purchase of a single product from a specific seller as part of an order. Enables feedback, delivery, and per-seller analytics. Immutable after order creation. **Sys_orderManagementOrderPayment** A payment storage object to store the payment life cyle of orders based on orderManagementOrder object. It is autocreated based on the source object's checkout config **Sys_paymentCustomer** A payment storage object to store the customer values of the payment platform **Sys_paymentMethod** A payment storage object to store the payment methods of the platform customers ### OrderManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/ordermanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/ordermanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/ordermanagement-api` ### `List Ordermanagementorders` API List orders, filtered for buyer and/or seller, or by admin. Includes select orderItems. **Rest Route** The `listOrderManagementOrders` API REST controller can be triggered via the following route: `/v1/ordermanagementorders` **Rest Request Parameters** The `listOrderManagementOrders` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ordermanagementorders', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Ordermanagementorderitem` API Get a specific order item (for feedback/business logic). **Rest Route** The `getOrderManagementOrderItem` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems/:orderManagementOrderItemId` **Rest Request Parameters** The `getOrderManagementOrderItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderItemId | ID | true | request.params?.orderManagementOrderItemId | **orderManagementOrderItemId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems/:orderManagementOrderItemId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderitems/${orderManagementOrderItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Ordermanagementorder` API Soft-delete/cancel order by admin or eligible actor prior to shipment. Sets status to CANCELLED and cancels active payment intent if pending. Irreversible and blocks feedback. **Rest Route** The `deleteOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` **Rest Request Parameters** The `deleteOrderManagementOrder` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorder` API Get single order by ID. Only accessible to admin, buyer, or relevant sellers of items within this order. Includes all orderItems. **Rest Route** The `getOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` **Rest Request Parameters** The `getOrderManagementOrder` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | **orderManagementOrderId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Ordermanagementorderstatus` API Update order status (manual shipment, delivery, cancellation/refund). Restricted: only seller of all items can mark as shipped, only buyer can confirm delivery, only admin can set refund/cancelled. Timestamps updated as per business rule. **Rest Route** The `updateOrderManagementOrderStatus` API REST controller can be triggered via the following route: `/v1/ordermanagementorderstatus/:orderManagementOrderId` **Rest Request Parameters** The `updateOrderManagementOrderStatus` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **status** : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderstatus/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderstatus/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Complete Orderstripewebhook` API Webhook endpoint called by Stripe to reconcile payment state and update order status based on paymentIntentId and event data. No authentication required (Stripe IPs only). **Rest Route** The `completeOrderStripeWebhook` API REST controller can be triggered via the following route: `/v1/completeorderstripewebhook/:orderManagementOrderId` **Rest Request Parameters** The `completeOrderStripeWebhook` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **status** : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/completeorderstripewebhook/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/completeorderstripewebhook/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderbyproductid` API get orders by productId **Rest Route** The `getOrderManagementOrderByProductId` API REST controller can be triggered via the following route: `/v1/ordermanagementorderbyproductid/:items` **Rest Request Parameters** The `getOrderManagementOrderByProductId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | items | String | true | request.params?.items | **orderManagementOrderId** : This id paremeter is used to query the required data object. **items** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderbyproductid/:items** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderbyproductid/${items}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Ordermanagementorder` API Creates an order and initiates Stripe payment. Validates that all products in the order are fixed-price, populates orderItems, saves Stripe customer/paymentMethod/paymentIntentId for reconciliation. Only accessible to buyers for own checkouts and only allows fixed-price product checkout (no auction). **Rest Route** The `createOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders` **Rest Request Parameters** The `createOrderManagementOrder` api has got 14 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderNumber | String | true | request.body?.orderNumber | | items | ID | false | request.body?.items | | paymentMethodId | String | true | request.body?.paymentMethodId | | stripeCustomerId | String | true | request.body?.stripeCustomerId | | paymentIntentId | String | false | request.body?.paymentIntentId | | shippingAddress | Object | true | request.body?.shippingAddress | | summary | Object | true | request.body?.summary | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderNumber** : Unique, human-friendly order number (displayed to users); enforced unique. **items** : Array of orderManagementOrderItem ids representing items in this order. **paymentMethodId** : Stripe paymentMethodId used for payment. Not stored if cash or other payment (future). **stripeCustomerId** : Stripe customerId of buyer; enables saved/paymentMethodId flows. **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **shippingAddress** : Shipping address for the order (copy of buyer address at purchase time). **summary** : Object with total, subtotal, currency, shipping, discount breakdown as snapshot of order at time of purchase. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorders** ```js axios({ method: 'POST', url: '/v1/ordermanagementorders', data: { orderNumber:"String", items:"ID", paymentMethodId:"String", stripeCustomerId:"String", paymentIntentId:"String", shippingAddress:"Object", summary:"Object", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderitems` API List order items for a given order or for buyer/seller analytics. Used for feedback management. **Rest Route** The `listOrderManagementOrderItems` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems` **Rest Request Parameters** The `listOrderManagementOrderItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Ownordermanagementorders` API list the loggedin user orders **Rest Route** The `listOwnOrderManagementOrders` API REST controller can be triggered via the following route: `/v1/ownordermanagementorders` **Rest Request Parameters** The `listOwnOrderManagementOrders` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ownordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ownordermanagementorders', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Lis Ordermanagementownorderitem` API list the loggedin user's order items **Rest Route** The `lisOrderManagementOwnOrderItem` API REST controller can be triggered via the following route: `/v1/lisordermanagementownorderitem` **Rest Request Parameters** The `lisOrderManagementOwnOrderItem` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/lisordermanagementownorderitem** ```js axios({ method: 'GET', url: '/v1/lisordermanagementownorderitem', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Ordermanagementorderitem` API create order item **Rest Route** The `createOrderManagementOrderItem` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems` **Rest Request Parameters** The `createOrderManagementOrderItem` api has got 8 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | shipping | Double | true | request.body?.shipping | | orderId | ID | true | request.body?.orderId | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | | price | Double | true | request.body?.price | | sellerId | ID | true | request.body?.sellerId | | title | String | true | request.body?.title | | currency | String | true | request.body?.currency | **shipping** : Shipping cost for this product (may be 0 for free shipping). **orderId** : Parent order this item belongs to; enables join and lifecycle tracking. **quantity** : Number of units purchased for this product. **productId** : ID of product purchased in this line item. **price** : Unit price for this product at purchase time. **sellerId** : UserId of seller (owner of product at purchase time). **title** : Product title at purchase time (copied for convenience/audit). **currency** : Currency code for price/shipping (ISO 4217). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderitems** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderitems', data: { shipping:"Double", orderId:"ID", quantity:"Integer", productId:"ID", price:"Double", sellerId:"ID", title:"String", currency:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpayment2` API This route is used to get the payment information by ID. **Rest Route** The `getOrderManagementOrderPayment2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `getOrderManagementOrderPayment2` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderpayments2` API This route is used to list all payments. **Rest Route** The `listOrderManagementOrderPayments2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayments2` **Rest Request Parameters** The `listOrderManagementOrderPayments2` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Ordermanagementorderpayment` API This route is used to create a new payment. **Rest Route** The `createOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment` **Rest Request Parameters** The `createOrderManagementOrderPayment` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderId | ID | true | request.body?.orderId | | paymentId | String | true | request.body?.paymentId | | paymentStatus | String | true | request.body?.paymentStatus | | statusLiteral | String | true | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | **orderId** : an ID value to represent the orderId which is the ID parameter of the source orderManagementOrder object **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderpayment', data: { orderId:"ID", paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Ordermanagementorderpayment` API This route is used to update an existing payment. **Rest Route** The `updateOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `updateOrderManagementOrderPayment` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | false | request.body?.paymentId | | paymentStatus | String | false | request.body?.paymentStatus | | statusLiteral | String | false | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | **sys_orderManagementOrderPaymentId** : This id paremeter is used to select the required data object that will be updated **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Ordermanagementorderpayment` API This route is used to delete a payment. **Rest Route** The `deleteOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `deleteOrderManagementOrderPayment` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderpayments2` API This route is used to list all payments. **Rest Route** The `listOrderManagementOrderPayments2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayments2` **Rest Request Parameters** The `listOrderManagementOrderPayments2` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Ordermanagementorderpaymentbyorderid` API This route is used to get the payment information by order id. **Rest Route** The `getOrderManagementOrderPaymentByOrderId` API REST controller can be triggered via the following route: `/v1/orderManagementOrderpaymentbyorderid/:orderId` **Rest Request Parameters** The `getOrderManagementOrderPaymentByOrderId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | orderId | String | true | request.params?.orderId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **orderId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbyorderid/:orderId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbyorderid/${orderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpaymentbypaymentid` API This route is used to get the payment information by payment id. **Rest Route** The `getOrderManagementOrderPaymentByPaymentId` API REST controller can be triggered via the following route: `/v1/orderManagementOrderpaymentbypaymentid/:paymentId` **Rest Request Parameters** The `getOrderManagementOrderPaymentByPaymentId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | true | request.params?.paymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **paymentId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbypaymentid/:paymentId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbypaymentid/${paymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpayment2` API This route is used to get the payment information by ID. **Rest Route** The `getOrderManagementOrderPayment2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `getOrderManagementOrderPayment2` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Start Ordermanagementorderpayment` API Start payment for orderManagementOrder **Rest Route** The `startOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/startordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `startOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to start a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/startordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/startordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Refresh Ordermanagementorderpayment` API Refresh payment info for orderManagementOrder from Stripe **Rest Route** The `refreshOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/refreshordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `refreshOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to refresh a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/refreshordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/refreshordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Callback Ordermanagementorderpayment` API Refresh payment values by gateway webhook call for orderManagementOrder **Rest Route** The `callbackOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/callbackordermanagementorderpayment` **Rest Request Parameters** The `callbackOrderManagementOrderPayment` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.body?.orderManagementOrderId | **orderManagementOrderId** : The order id parameter that will be read from webhook callback params **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/callbackordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/callbackordermanagementorderpayment', data: { orderManagementOrderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Get Paymentcustomerbyuserid` API This route is used to get the payment customer information by user id. **Rest Route** The `getPaymentCustomerByUserId` API REST controller can be triggered via the following route: `/v1/paymentcustomers/:userId` **Rest Request Parameters** The `getPaymentCustomerByUserId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_paymentCustomerId | ID | true | request.params?.sys_paymentCustomerId | | userId | String | true | request.params?.userId | **sys_paymentCustomerId** : This id paremeter is used to query the required data object. **userId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomers/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_paymentCustomer": { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Paymentcustomers` API This route is used to list all payment customers. **Rest Route** The `listPaymentCustomers` API REST controller can be triggered via the following route: `/v1/paymentcustomers` **Rest Request Parameters** The `listPaymentCustomers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers** ```js axios({ method: 'GET', url: '/v1/paymentcustomers', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentCustomers": [ { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Paymentcustomermethods` API This route is used to list all payment customer methods. **Rest Route** The `listPaymentCustomerMethods` API REST controller can be triggered via the following route: `/v1/paymentcustomermethods/:userId` **Rest Request Parameters** The `listPaymentCustomerMethods` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | String | true | request.params?.userId | **userId** : This parameter will be used to select the data objects that want to be listed **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomermethods/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomermethods/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentMethods", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentMethods": [ { "id": "ID", "paymentMethodId": "String", "userId": "ID", "customerId": "String", "cardHolderName": "String", "cardHolderZip": "String", "platform": "String", "cardInfo": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ## Feedback Service Handles feedback for order items: one feedback per buyer/orderItem, attached to sellerId for analytical feedback/rating aggregation and reputation tracking. Enables querying feedbacks received/given for sellers and buyers. test ### Feedback Service Data Objects **Feedback** One feedback per (buyer, orderItem). Stores rating (1-5), comment, ties to seller for analytics. Created only after delivery confirmed on order item. ### Feedback Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/feedback-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/feedback-api` * **Production:** `https://ebaycclone.mindbricks.co/feedback-api` ### `List Feedbacks` API List feedback with filtering by buyerId (given), sellerId (received), productId, or orderItemId. Used for showing seller profile, buyer profile, or order analytics. **Rest Route** The `listFeedbacks` API REST controller can be triggered via the following route: `/v1/feedbacks` **Rest Request Parameters** The `listFeedbacks` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/feedbacks** ```js axios({ method: 'GET', url: '/v1/feedbacks', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedbacks", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "feedbacks": [ { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Feedback` API Get a single feedback by id. Accessible to public (for seller profile, product, or audit views). **Rest Route** The `getFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `getFeedback` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | **feedbackId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/feedbacks/:feedbackId** ```js axios({ method: 'GET', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Feedback` API Update feedback (comment/rating) for existing feedback record (buyer only). Admin can update as override. **Rest Route** The `updateFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `updateFeedback` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | | rating | Integer | false | request.body?.rating | | comment | String | false | request.body?.comment | **feedbackId** : This id paremeter is used to select the required data object that will be updated **rating** : Rating (1-5 stars) submitted by buyer. Required. **comment** : Optional textual feedback comment, max ~500 chars. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/feedbacks/:feedbackId** ```js axios({ method: 'PATCH', url: `/v1/feedbacks/${feedbackId}`, data: { rating:"Integer", comment:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Feedback` API Delete (soft-delete) feedback (by buyer or admin). Only feedback owner or admin. **Rest Route** The `deleteFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `deleteFeedback` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | **feedbackId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/feedbacks/:feedbackId** ```js axios({ method: 'DELETE', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Feedback` API Buyer creates feedback for a delivered order item. Only allowed once per (buyer, orderItemId). Allowed only once order item is delivered. **Rest Route** The `createFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks` **Rest Request Parameters** The `createFeedback` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | rating | Integer | true | request.body?.rating | | orderId | ID | true | request.body?.orderId | | orderItemId | ID | true | request.body?.orderItemId | | sellerId | ID | true | request.body?.sellerId | | comment | String | false | request.body?.comment | | productId | ID | true | request.body?.productId | **rating** : Rating (1-5 stars) submitted by buyer. Required. **orderId** : Order containing this purchased item. Used for aggregation and validation. **orderItemId** : Purchased item (line item) in order. Feedback is per (buyer, orderItem). **sellerId** : Seller of product for analytics/aggregation. Not author; used for querying feedback about sellers. **comment** : Optional textual feedback comment, max ~500 chars. **productId** : The product listing being reviewed (snapshot at order time). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/feedbacks** ```js axios({ method: 'POST', url: '/v1/feedbacks', data: { rating:"Integer", orderId:"ID", orderItemId:"ID", sellerId:"ID", comment:"String", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # REST API GUIDE ## ebaycclone-auctionoffer-service Handles auction bids and fixed-price offers for product listings, enforces real-time auction state, handles strict offer workflows including counter-offers, and triggers domain events for bid/offer notifications. No payment or frontend aggregation logic included. ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to: Email: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. ## Documentation Scope Welcome to the official documentation for the AuctionOffer Service's REST API. This document is designed to provide a comprehensive guide to interfacing with our AuctionOffer Service exclusively through RESTful API endpoints. **Intended Audience** This documentation is intended for developers and integrators who are looking to interact with the AuctionOffer Service via HTTP requests for purposes such as creating, updating, deleting and querying AuctionOffer objects. **Overview** Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases. Beyond REST It's important to note that the AuctionOffer Service also supports alternative methods of interaction, such as gRPC and messaging via a Message Broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation. ## Authentication And Authorization To ensure secure access to the AuctionOffer service's protected endpoints, a project-wide access token is required. This token serves as the primary method for authenticating requests to our service. However, it's important to note that access control varies across different routes: **Protected API**: Certain API (routes) require specific authorization levels. Access to these routes is contingent upon the possession of a valid access token that meets the route-specific authorization criteria. Unauthorized requests to these routes will be rejected. **Public API **: The service also includes public API (routes) that are accessible without authentication. These public endpoints are designed for open access and do not require an access token. ### Token Locations When including your access token in a request, ensure it is placed in one of the following specified locations. The service will sequentially search these locations for the token, utilizing the first one it encounters. | Location | Token Name / Param Name | | ---------------------- | ---------------------------- | | Query | access_token | | Authorization Header | Bearer | | Header | ebaycclone-access-token| | Cookie | ebaycclone-access-token| Please ensure the token is correctly placed in one of these locations, using the appropriate label as indicated. The service prioritizes these locations in the order listed, processing the first token it successfully identifies. ## Api Definitions This section outlines the API endpoints available within the AuctionOffer service. Each endpoint can receive parameters through various methods, meticulously described in the following definitions. It's important to understand the flexibility in how parameters can be included in requests to effectively interact with the AuctionOffer service. This service is configured to listen for HTTP requests on port `3002`, serving both the main API interface and default administrative endpoints. The following routes are available by default: * **API Test Interface (API Face):** `/` * **Swagger Documentation:** `/swagger` * **Postman Collection Download:** `/getPostmanCollection` * **Health Checks:** `/health` and `/admin/health` * **Current Session Info:** `/currentuser` * **Favicon:** `/favicon.ico` This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auctionoffer-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auctionoffer-api` * **Production:** `https://ebaycclone.mindbricks.co/auctionoffer-api` **Parameter Inclusion Methods:** Parameters can be incorporated into API requests in several ways, each with its designated location. Understanding these methods is crucial for correctly constructing your requests: **Query Parameters:** Included directly in the URL's query string. **Path Parameters:** Embedded within the URL's path. **Body Parameters:** Sent within the JSON body of the request. **Session Parameters:** Automatically read from the session object. This method is used for parameters that are intrinsic to the user's session, such as userId. When using an API that involves session parameters, you can omit these from your request. The service will automatically bind them to the API layer, provided that a session is associated with your request. **Note on Session Parameters:** Session parameters represent a unique method of parameter inclusion, relying on the context of the user's session. A common example of a session parameter is userId, which the service automatically associates with your request when a session exists. This feature ensures seamless integration of user-specific data without manual input for each request. By adhering to the specified parameter inclusion methods, you can effectively utilize the AuctionOffer service's API endpoints. For detailed information on each endpoint, including required parameters and their accepted locations, refer to the individual API definitions below. ### Common Parameters The `AuctionOffer` service's business API support several common parameters designed to modify and enhance the behavior of API requests. These parameters are not individually listed in the API route definitions to avoid repetition. Instead, refer to this section to understand how to leverage these common behaviors across different routes. Note that all common parameters should be included in the query part of the URL. ### Supported Common Parameters: - **getJoins (BOOLEAN)**: Controls whether to retrieve associated objects along with the main object. By default, `getJoins` is assumed to be `true`. Set it to `false` if you prefer to receive only the main fields of an object, excluding its associations. - **excludeCQRS (BOOLEAN)**: Applicable only when `getJoins` is `true`. By default, `excludeCQRS` is set to `false`. Enabling this parameter (`true`) omits non-local associations, which are typically more resource-intensive as they require querying external services like ElasticSearch for additional information. Use this to optimize response times and resource usage. - **requestId (String)**: Identifies a request to enable tracking through the service's log chain. A random hex string of 32 characters is assigned by default. If you wish to use a custom `requestId`, simply include it in your query parameters. - **caching (BOOLEAN)**: Determines the use of caching for query API. By default, caching is enabled (`true`). To ensure the freshest data directly from the database, set this parameter to `false`, bypassing the cache. - **cacheTTL (Integer)**: Specifies the Time-To-Live (TTL) for query caching, in seconds. This is particularly useful for adjusting the default caching duration (5 minutes) for `get list` queries. Setting a custom `cacheTTL` allows you to fine-tune the cache lifespan to meet your needs. - **pageNumber (Integer)**: For paginated `get list` API's, this parameter selects which page of results to retrieve. The default is `1`, indicating the first page. To disable pagination and retrieve all results, set `pageNumber` to `0`. - **pageRowCount (Integer)**: In conjunction with paginated API's, this parameter defines the number of records per page. The default value is `25`. Adjusting `pageRowCount` allows you to control the volume of data returned in a single request. By utilizing these common parameters, you can tailor the behavior of API requests to suit your specific requirements, ensuring optimal performance and usability of the `AuctionOffer` service. ### Error Response If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity: - **400 Bad Request**: The request was improperly formatted or contained invalid parameters, preventing the server from processing it. - **401 Unauthorized**: The request lacked valid authentication credentials or the credentials provided do not grant access to the requested resource. - **404 Not Found**: The requested resource was not found on the server. - **500 Internal Server Error**: The server encountered an unexpected condition that prevented it from fulfilling the request. Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ### Object Structure of a Successfull Response When the `AuctionOffer` service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client. **Key Characteristics of the Response Envelope:** - **Data Presentation**: Depending on the nature of the request, the service returns either a single data object or an array of objects encapsulated within the JSON envelope. - **Creation and Update API**: These API routes return the unmodified (pure) form of the data object(s), without any associations to other data objects. - **Delete API**: Even though the data is removed from the database, the last known state of the data object(s) is returned in its pure form. - **Get Requests**: A single data object is returned in JSON format. - **Get List Requests**: An array of data objects is provided, reflecting a collection of resources. - **Data Structure and Joins**: The complexity of the data structure in the response can vary based on the API's architectural design and the join options specified in the request. The architecture might inherently limit join operations, or they might be dynamically controlled through query parameters. - **Pure Data Forms**: In some cases, the response mirrors the exact structure found in the primary data table, without extensions. - **Extended Data Forms**: Alternatively, responses might include data extended through joins with tables within the same service or aggregated from external sources, such as ElasticSearch indices related to other services. - **Join Varieties**: The extensions might involve one-to-one joins, resulting in single object associations, or one-to-many joins, leading to an array of objects. In certain instances, the data might even feature nested inclusions from other data objects. **Design Considerations**: The structure of a API's response data is meticulously crafted during the service's architectural planning. This design ensures that responses adequately reflect the intended data relationships and service logic, providing clients with rich and meaningful information. **Brief Data**: Certain API's return a condensed version of the object data, intentionally selecting only specific fields deemed useful for that request. In such instances, the API documentation will detail the properties included in the response, guiding developers on what to expect. ### API Response Structure The API utilizes a standardized JSON envelope to encapsulate responses. This envelope is designed to consistently deliver both the requested data and essential metadata, ensuring that clients can efficiently interpret and utilize the response. **HTTP Status Codes:** - **200 OK**: This status code is returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request has been processed successfully. - **201 Created**: This status code is specific to CREATE operations, signifying that the requested resource has been successfully created. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling the successful execution of the request. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3 "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` - **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation performed. **Handling Errors:** For details on handling error scenarios and understanding the structure of error responses, please refer to the "Error Response" section provided earlier in this documentation. It outlines how error conditions are communicated, including the use of HTTP status codes and standardized JSON structures for error messages. ## Resources AuctionOffer service provides the following resources which are stored in its own database as a data object. Note that a resource for an api access is a data object for the service. ### AuctionOfferOffer resource *Resource Definition* : Represents an offer (best offer/counter-offer) made on a fixed-price product. Tracks buyer, seller, amounts, currency, state transitions, counter-offers, and expiry. *AuctionOfferOffer Resource Properties* | Name | Type | Required | Default | Definition | | ---- | ---- | -------- | ------- | ---------- | | **buyerId** | ID | | | *Buyer making the offer.* | | **currency** | String | | | *ISO currency (e.g., USD, EUR) for the offer.* | | **productId** | ID | | | *Product the offer applies to (must be fixed-price, acceptOffers true).* | | **counterOfferId** | ID | | | *References another offer (counter-offer chain).* | | **counterMessage** | String | | | *Message accompanying seller's counter-offer (optional).* | | **counterAmount** | Double | | | *Counter-offer amount (when offer is COUNTERED).* | | **offerAmount** | Double | | | *Primary offer amount from buyer.* | | **message** | String | | | *Message/special notes from buyer (optional).* | | **sellerId** | ID | | | *Seller of the product (recipient of offer; auto-fetched from product).* | | **status** | Enum | | | *Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED).* | | **expiresAt** | Date | | | *When this offer expires (optional).* | | **respondedAt** | Date | | | *When the seller (or buyer, for counter-offer) responded/updated the offer status.* | #### Enum Properties Enum properties are represented as strings in the database. The values are mapped to their corresponding names in the application layer. ##### status Enum Property *Property Definition* : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED).*Enum Options* | Name | Value | Index | | ---- | ----- | ----- | | **PENDING** | `"PENDING""` | 0 | | **ACCEPTED** | `"ACCEPTED""` | 1 | | **DECLINED** | `"DECLINED""` | 2 | | **COUNTERED** | `"COUNTERED""` | 3 | | **EXPIRED** | `"EXPIRED""` | 4 | | **CANCELLED** | `"CANCELLED""` | 5 | ### AuctionOfferBid resource *Resource Definition* : Represents an individual bid placed on an auction-type product. Linked to product and user, tracks bid amount, currency, status (ACTIVE, WON, LOST, CANCELLED), and time placed. *AuctionOfferBid Resource Properties* | Name | Type | Required | Default | Definition | | ---- | ---- | -------- | ------- | ---------- | | **userId** | ID | | | *User placing the bid.* | | **bidAmount** | Double | | | *Bid amount placed by the user.* | | **placedAt** | Date | | | *When the bid was placed.* | | **currency** | String | | | *ISO currency for the bid (e.g., USD, EUR).* | | **status** | Enum | | | *Bid status: ACTIVE, WON, LOST, CANCELLED.* | | **productId** | ID | | | *Product being bid on (must be AUCTION type).* | #### Enum Properties Enum properties are represented as strings in the database. The values are mapped to their corresponding names in the application layer. ##### status Enum Property *Property Definition* : Bid status: ACTIVE, WON, LOST, CANCELLED.*Enum Options* | Name | Value | Index | | ---- | ----- | ----- | | **ACTIVE** | `"ACTIVE""` | 0 | | **WON** | `"WON""` | 1 | | **LOST** | `"LOST""` | 2 | | **CANCELLED** | `"CANCELLED""` | 3 | ## Business Api ### Update Auctionofferoffer API *API Definition* : Updates offer: accepts/declines/counters by seller, withdraws by buyer before response. Enforces status transition rules, sets respondedAt. Triggers event. *API Crud Type* : update *Default access route* : *PATCH* `/v1/auctionofferoffers/:auctionOfferOfferId` #### Parameters The updateAuctionOfferOffer api has got 8 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | message | String | false | request.body?.message | | status | Enum | false | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`auctionOfferOffer`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferOffer","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"auctionOfferOffer":{"id":"ID","buyerId":"ID","currency":"String","productId":"ID","counterOfferId":"ID","counterMessage":"String","counterAmount":"Double","offerAmount":"Double","message":"String","sellerId":"ID","status":"Enum","status_idx":"Integer","expiresAt":"Date","respondedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Update Auctionofferoffer](businessApi/updateAuctionOfferOffer). ### Create Auctionofferbid API *API Definition* : Creates a new bid for an auction product. Validates auction status, not seller, product type, bid window, and ensures min. increment. Updates product.currentBid and product.highestBidderId atomically. Triggers notification event. *API Crud Type* : create *Default access route* : *POST* `/v1/auctionofferbids` #### Parameters The createAuctionOfferBid api has got 4 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | bidAmount | Double | true | request.body?.bidAmount | | currency | String | true | request.body?.currency | | status | Enum | true | request.body?.status | | productId | ID | true | request.body?.productId | To access the api you can use the **REST** controller with the path **POST /v1/auctionofferbids** ```js axios({ method: 'POST', url: '/v1/auctionofferbids', data: { bidAmount:"Double", currency:"String", status:"Enum", productId:"ID", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`auctionOfferBid`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferBid","method":"POST","action":"create","appVersion":"Version","rowCount":1,"auctionOfferBid":{"id":"ID","userId":"ID","bidAmount":"Double","placedAt":"Date","currency":"String","status":"Enum","status_idx":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Create Auctionofferbid](businessApi/createAuctionOfferBid). ### Get Auctionofferbid API *API Definition* : Gets a single bid (only visible to owner/admin or for auction history). *API Crud Type* : get *Default access route* : *GET* `/v1/auctionofferbids/:auctionOfferBidId` #### Parameters The getAuctionOfferBid api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'GET', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`auctionOfferBid`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferBid","method":"GET","action":"get","appVersion":"Version","rowCount":1,"auctionOfferBid":{"id":"ID","userId":"ID","bidAmount":"Double","placedAt":"Date","currency":"String","status":"Enum","status_idx":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Get Auctionofferbid](businessApi/getAuctionOfferBid). ### Get Auctionofferoffer API *API Definition* : Gets a single offer (shown to buyer/seller or admin). *API Crud Type* : get *Default access route* : *GET* `/v1/auctionofferoffers/:auctionOfferOfferId` #### Parameters The getAuctionOfferOffer api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'GET', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`auctionOfferOffer`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferOffer","method":"GET","action":"get","appVersion":"Version","rowCount":1,"auctionOfferOffer":{"id":"ID","buyerId":"ID","currency":"String","productId":"ID","counterOfferId":"ID","counterMessage":"String","counterAmount":"Double","offerAmount":"Double","message":"String","sellerId":"ID","status":"Enum","status_idx":"Integer","expiresAt":"Date","respondedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Get Auctionofferoffer](businessApi/getAuctionOfferOffer). ### List Auctionofferoffers API *API Definition* : Lists offers by product, user, status, or counterOffer chain. *API Crud Type* : list *Default access route* : *GET* `/v1/auctionofferoffers` The listAuctionOfferOffers api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers** ```js axios({ method: 'GET', url: '/v1/auctionofferoffers', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`auctionOfferOffers`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferOffers","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","auctionOfferOffers":[{"id":"ID","buyerId":"ID","currency":"String","productId":"ID","counterOfferId":"ID","counterMessage":"String","counterAmount":"Double","offerAmount":"Double","message":"String","sellerId":"ID","status":"Enum","status_idx":"Integer","expiresAt":"Date","respondedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For List Auctionofferoffers](businessApi/listAuctionOfferOffers). ### Update Auctionofferbid API *API Definition* : Updates a bid’s status (allow only status update, e.g. CANCELLED, WIN/LOSE on admin settlement). Only owner/admin, and only if auction not ended or not settled. Triggers notification event. *API Crud Type* : update *Default access route* : *PATCH* `/v1/auctionofferbids/:auctionOfferBidId` #### Parameters The updateAuctionOfferBid api has got 2 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | | status | Enum | false | request.body?.status | To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { status:"Enum", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`auctionOfferBid`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferBid","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"auctionOfferBid":{"id":"ID","userId":"ID","bidAmount":"Double","placedAt":"Date","currency":"String","status":"Enum","status_idx":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Update Auctionofferbid](businessApi/updateAuctionOfferBid). ### Create Auctionofferoffer API *API Definition* : Creates a new offer for a fixed-price product, validating acceptOffers, type, eligibility, and product/seller/buyer active. Defaults to PENDING state. Triggers notification event. *API Crud Type* : create *Default access route* : *POST* `/v1/auctionofferoffers` #### Parameters The createAuctionOfferOffer api has got 10 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | productId | ID | true | request.body?.productId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | offerAmount | Double | true | request.body?.offerAmount | | message | String | false | request.body?.message | | status | Enum | true | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | To access the api you can use the **REST** controller with the path **POST /v1/auctionofferoffers** ```js axios({ method: 'POST', url: '/v1/auctionofferoffers', data: { currency:"String", productId:"ID", counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", offerAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`auctionOfferOffer`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferOffer","method":"POST","action":"create","appVersion":"Version","rowCount":1,"auctionOfferOffer":{"id":"ID","buyerId":"ID","currency":"String","productId":"ID","counterOfferId":"ID","counterMessage":"String","counterAmount":"Double","offerAmount":"Double","message":"String","sellerId":"ID","status":"Enum","status_idx":"Integer","expiresAt":"Date","respondedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Create Auctionofferoffer](businessApi/createAuctionOfferOffer). ### List Auctionofferbids API *API Definition* : Lists bids by product, user, or auction, supports history/analytics. *API Crud Type* : list *Default access route* : *GET* `/v1/auctionofferbids` The listAuctionOfferBids api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids** ```js axios({ method: 'GET', url: '/v1/auctionofferbids', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`auctionOfferBids`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferBids","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","auctionOfferBids":[{"id":"ID","userId":"ID","bidAmount":"Double","placedAt":"Date","currency":"String","status":"Enum","status_idx":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For List Auctionofferbids](businessApi/listAuctionOfferBids). ### Delete Auctionofferbid API *API Definition* : Soft-deletes a bid (for admin or self before auction ends). *API Crud Type* : delete *Default access route* : *DELETE* `/v1/auctionofferbids/:auctionOfferBidId` #### Parameters The deleteAuctionOfferBid api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`auctionOfferBid`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferBid","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"auctionOfferBid":{"id":"ID","userId":"ID","bidAmount":"Double","placedAt":"Date","currency":"String","status":"Enum","status_idx":"Integer","productId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Delete Auctionofferbid](businessApi/deleteAuctionOfferBid). ### Delete Auctionofferoffer API *API Definition* : Soft-deletes an offer (allowed only in non-accepted/expired state). *API Crud Type* : delete *Default access route* : *DELETE* `/v1/auctionofferoffers/:auctionOfferOfferId` #### Parameters The deleteAuctionOfferOffer api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`auctionOfferOffer`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"auctionOfferOffer","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"auctionOfferOffer":{"id":"ID","buyerId":"ID","currency":"String","productId":"ID","counterOfferId":"ID","counterMessage":"String","counterAmount":"Double","offerAmount":"Double","message":"String","sellerId":"ID","status":"Enum","status_idx":"Integer","expiresAt":"Date","respondedAt":"Date","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Delete Auctionofferoffer](businessApi/deleteAuctionOfferOffer). ### Authentication Specific Routes ### Common Routes ### Route: currentuser *Route Definition*: Retrieves the currently authenticated user's session information. *Route Type*: sessionInfo *Access Route*: `GET /currentuser` #### Parameters This route does **not** require any request parameters. #### Behavior - Returns the authenticated session object associated with the current access token. - If no valid session exists, responds with a 401 Unauthorized. ```js // Sample GET /currentuser call axios.get("/currentuser", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** Returns the session object, including user-related data and token information. ``` { "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", "roleId": "user", "tenantId": "abc123", "accessToken": "jwt-token-string", ... } ``` **Error Response** **401 Unauthorized:** No active session found. ``` { "status": "ERR", "message": "No login found" } ``` **Notes** * This route is typically used by frontend or mobile applications to fetch the current session state after login. * The returned session includes key user identity fields, tenant information (if applicable), and the access token for further authenticated requests. * Always ensure a valid access token is provided in the request to retrieve the session. ### Route: permissions `*Route Definition*`: Retrieves all effective permission records assigned to the currently authenticated user. `*Route Type*`: permissionFetch *Access Route*: `GET /permissions` #### Parameters This route does **not** require any request parameters. #### Behavior - Fetches all active permission records (`givenPermissions` entries) associated with the current user session. - Returns a full array of permission objects. - Requires a valid session (`access token`) to be available. ```js // Sample GET /permissions call axios.get("/permissions", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** Returns an array of permission objects. ```json [ { "id": "perm1", "permissionName": "adminPanel.access", "roleId": "admin", "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" }, { "id": "perm2", "permissionName": "orders.manage", "roleId": null, "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" } ] ``` Each object reflects a single permission grant, aligned with the givenPermissions model: - `**permissionName**`: The permission the user has. - `**roleId**`: If the permission was granted through a role. -` **subjectUserId**`: If directly granted to the user. - `**subjectUserGroupId**`: If granted through a group. - `**objectId**`: If tied to a specific object (OBAC). - `**canDo**`: True or false flag to represent if permission is active or restricted. **Error Responses** * **401 Unauthorized**: No active session found. ```json { "status": "ERR", "message": "No login found" } ``` * **500 Internal Server Error**: Unexpected error fetching permissions. **Notes** * The /permissions route is available across all backend services generated by Mindbricks, not just the auth service. * Auth service: Fetches permissions freshly from the live database (givenPermissions table). * Other services: Typically use a cached or projected view of permissions stored in a common ElasticSearch store, optimized for faster authorization checks. > **Tip**: > Applications can cache permission results client-side or server-side, but should occasionally refresh by calling this endpoint, especially after login or permission-changing operations. ### Route: permissions/:permissionName *Route Definition*: Checks whether the current user has access to a specific permission, and provides a list of scoped object exceptions or inclusions. *Route Type*: permissionScopeCheck *Access Route*: `GET /permissions/:permissionName` #### Parameters | Parameter | Type | Required | Population | |------------------|--------|----------|------------------------| | permissionName | String | Yes | `request.params.permissionName` | #### Behavior - Evaluates whether the current user **has access** to the given `permissionName`. - Returns a structured object indicating: - Whether the permission is generally granted (`canDo`) - Which object IDs are explicitly included or excluded from access (`exceptions`) - Requires a valid session (`access token`). ```js // Sample GET /permissions/orders.manage axios.get("/permissions/orders.manage", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** ```json { "canDo": true, "exceptions": [ "a1f2e3d4-xxxx-yyyy-zzzz-object1", "b2c3d4e5-xxxx-yyyy-zzzz-object2" ] } ``` * If `canDo` is `true`, the user generally has the permission, but not for the objects listed in `exceptions` (i.e., restrictions). * If `canDo` is `false`, the user does not have the permission by default — but only for the objects in `exceptions`, they do have permission (i.e., selective overrides). * The exceptions array contains valid **UUID strings**, each corresponding to an object ID (typically from the data model targeted by the permission). ## Copyright All sources, documents and other digital materials are copyright of . ## About Us For more information please visit our website: . . . # Service Design Specification **ebaycclone-auctionoffer-service** documentation -Version:**`1.0.0`** ## Scope This document provides a structured architectural overview of the `auctionOffer` microservice, detailing its configuration, data model, authorization logic, business rules, and API design. It has been automatically generated based on the service definition within Mindbricks, ensuring that the information reflects the source of truth used during code generation and deployment. The document is intended to serve multiple audiences: * **Service architects** can use it to validate design decisions and ensure alignment with broader architectural goals. * **Developers and maintainers** will find it useful for understanding the structure and behavior of the service, facilitating easier debugging, feature extension, and integration with other systems. * **Stakeholders and reviewers** can use it to gain a clear understanding of the service's capabilities and domain logic. > **Note for Frontend Developers**: While this document is valuable for understanding business logic and data interactions, please refer to the [Service API Documentation](#) for endpoint-level specifications and integration details. > **Note for Backend Developers**: Since the code for this service is automatically generated by Mindbricks, you typically won't need to implement or modify it manually. However, this document is especially valuable when you're building other services—whether within Mindbricks or externally—that need to interact with or depend on this service. It provides a clear reference to the service's data contracts, business rules, and API structure, helping ensure compatibility and correct integration. ## `AuctionOffer` Service Settings [**Edit**](auctionoffer/serviceSettings) Handles auction bids and fixed-price offers for product listings, enforces real-time auction state, handles strict offer workflows including counter-offers, and triggers domain events for bid/offer notifications. No payment or frontend aggregation logic included. ### Service Overview This service is configured to listen for HTTP requests on port `3002`, serving both the main API interface and default administrative endpoints. The following routes are available by default: * **API Test Interface (API Face):** `/` * **Swagger Documentation:** `/swagger` * **Postman Collection Download:** `/getPostmanCollection` * **Health Checks:** `/health` and `/admin/health` * **Current Session Info:** `/currentuser` * **Favicon:** `/favicon.ico` The service uses a **PostgreSQL** database for data storage, with the database name set to `ebaycclone-auctionoffer-service`. This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auctionoffer-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auctionoffer-api` * **Production:** `https://ebaycclone.mindbricks.co/auctionoffer-api` ### Authentication & Security - **Login Required**: Yes This service requires user authentication for access. It supports both JWT and RSA-based authentication mechanisms, ensuring secure user sessions and data integrity. If a crud route also is configured to require login, it will check a valid JWT token in the request query/header/bearer/cookie. If the token is valid, it will extract the user information from the token and make the fetched session data available in the request context. ### Service Data Objects The service uses a **PostgreSQL** database for data storage, with the database name set to `ebaycclone-auctionoffer-service`. Data deletion is managed using a **soft delete** strategy. Instead of removing records from the database, they are flagged as inactive by setting the `isActive` field to `false`. | Object Name | Description | Public Access | |-------------|-------------|---------------| | `auctionOfferOffer` | Represents an offer (best offer/counter-offer) made on a fixed-price product. Tracks buyer, seller, amounts, currency, state transitions, counter-offers, and expiry. | accessPrivate | | `auctionOfferBid` | Represents an individual bid placed on an auction-type product. Linked to product and user, tracks bid amount, currency, status (ACTIVE, WON, LOST, CANCELLED), and time placed. | accessPrivate | ## auctionOfferOffer Data Object ### Object Overview **Description:** Represents an offer (best offer/counter-offer) made on a fixed-price product. Tracks buyer, seller, amounts, currency, state transitions, counter-offers, and expiry. This object represents a core data structure within the service and acts as the blueprint for database interaction, API generation, and business logic enforcement. It is defined using the `ObjectSettings` pattern, which governs its behavior, access control, caching strategy, and integration points with other systems such as Stripe and Redis. ### Core Configuration - **Soft Delete:** Enabled — Determines whether records are marked inactive (`isActive = false`) instead of being physically deleted. - **Public Access:** accessPrivate — If enabled, anonymous users may access this object’s data depending on API-level rules. ### Composite Indexes - **unique_pending_offer_per_buyer_product**: [productId, buyerId, status] This composite index is defined to optimize query performance for complex queries involving multiple fields. The index also defines a conflict resolution strategy for duplicate key violations. When a new record would violate this composite index, the following action will be taken: **On Duplicate**: `throwError` An error will be thrown, preventing the insertion of conflicting data. ### Properties Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `buyerId` | ID | Yes | Buyer making the offer. | | `currency` | String | Yes | ISO currency (e.g., USD, EUR) for the offer. | | `productId` | ID | Yes | Product the offer applies to (must be fixed-price, acceptOffers true). | | `counterOfferId` | ID | No | References another offer (counter-offer chain). | | `counterMessage` | String | No | Message accompanying seller's counter-offer (optional). | | `counterAmount` | Double | No | Counter-offer amount (when offer is COUNTERED). | | `offerAmount` | Double | Yes | Primary offer amount from buyer. | | `message` | String | No | Message/special notes from buyer (optional). | | `sellerId` | ID | Yes | Seller of the product (recipient of offer; auto-fetched from product). | | `status` | Enum | Yes | Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). | | `expiresAt` | Date | No | When this offer expires (optional). | | `respondedAt` | Date | No | When the seller (or buyer, for counter-offer) responded/updated the offer status. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value is set. ### Default Values Default values are automatically assigned to properties when a new object is created, if no value is provided in the request body. Since default values are applied on db level, they should be literal values, not expressions.If you want to use expressions, you can use transposed parameters in any business API to set default values dynamically. - **buyerId**: '00000000-0000-0000-0000-000000000000' - **currency**: 'default' - **productId**: '00000000-0000-0000-0000-000000000000' - **offerAmount**: 0.0 - **sellerId**: '00000000-0000-0000-0000-000000000000' - **status**: PENDING ### Constant Properties `buyerId` `currency` `productId` `offerAmount` `sellerId` Constant properties are defined to be immutable after creation, meaning they cannot be updated or changed once set. They are typically used for properties that should remain constant throughout the object's lifecycle. A property is set to be constant if the `Allow Update` option is set to `false`. ### Auto Update Properties `buyerId` `currency` `productId` `counterOfferId` `counterMessage` `counterAmount` `offerAmount` `message` `sellerId` `status` `expiresAt` `respondedAt` An update crud API created with the option `Auto Params` enabled will automatically update these properties with the provided values in the request body. If you want to update any property in your own business logic not by user input, you can set the `Allow Auto Update` option to false. These properties will be added to the update API's body parameters and can be updated by the user if any value is provided in the request body. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an addtional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the index property to sort by the enum value or when your enum options represent a sequence of values. - **status**: [PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED] ### Elastic Search Indexing `buyerId` `currency` `productId` `offerAmount` `sellerId` `status` `expiresAt` Properties that are indexed in Elastic Search will be searchable via the Elastic Search API. While all properties are stored in the elastic search index of the data object, only those marked for Elastic Search indexing will be available for search queries. ### Database Indexing `buyerId` `productId` `counterOfferId` `sellerId` `status` Properties that are indexed in the database will be optimized for query performance, allowing for faster data retrieval. Make a property indexed in the database if you want to use it frequently in query filters or sorting. ### Relation Properties `buyerId` `productId` `counterOfferId` `sellerId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. You can define relations in the data object properties, which will be used to create foreign key constraints in the database. For complex joins operations, Mindbricks supportsa BFF pattern, where you can view dynamic and static views based on Elastic Search Indexes. Use db level relations for simple one-to-one or one-to-many relationships, and use BFF views for complex joins that require multiple data objects to be joined together. - **buyerId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes - **productId**: ID Relation to `productListingProduct`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes - **counterOfferId**: ID Relation to `auctionOfferOffer`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: No - **sellerId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes ### Session Data Properties `buyerId` Session data properties are used to store data that is specific to the user session, allowing for personalized experiences and temporary data storage. If a property is configured as session data, it will be automatically mapped to the related field in the user session during CRUD operations. Note that session data properties can not be mutated by the user, but only by the system. - **buyerId**: ID property will be mapped to the session parameter `userId`. This property is also used to store the owner of the session data, allowing for ownership checks and access control. ### Filter Properties `buyerId` `currency` `productId` `offerAmount` `sellerId` `status` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's that have "Auto Params" enabled. - **buyerId**: ID has a filter named `buyerId` - **currency**: String has a filter named `currency` - **productId**: ID has a filter named `productId` - **offerAmount**: Double has a filter named `offerAmount` - **sellerId**: ID has a filter named `sellerId` - **status**: Enum has a filter named `status` ### Static Join Properties `sellerId` Static join properties are used to define static joins with other data objects, allowing for complex data retrieval patterns without the need for dynamic joins. A static join will be used in the create time, to populare this property with the data from the joined object through another data property. - **sellerId**: ID will be poulated from the `sellerId` of the `productListingProduct` object. The join will be done only once during the create operation, using the `productId` property of this object and the `id` property of the joined object. - Joint Source: `productListingProduct` - Joint Read: `sellerId` - Source Key: `id` - Foreign Key: `productId` ## auctionOfferBid Data Object ### Object Overview **Description:** Represents an individual bid placed on an auction-type product. Linked to product and user, tracks bid amount, currency, status (ACTIVE, WON, LOST, CANCELLED), and time placed. This object represents a core data structure within the service and acts as the blueprint for database interaction, API generation, and business logic enforcement. It is defined using the `ObjectSettings` pattern, which governs its behavior, access control, caching strategy, and integration points with other systems such as Stripe and Redis. ### Core Configuration - **Soft Delete:** Enabled — Determines whether records are marked inactive (`isActive = false`) instead of being physically deleted. - **Public Access:** accessPrivate — If enabled, anonymous users may access this object’s data depending on API-level rules. ### Composite Indexes - **bid_unique_user_product**: [userId, productId] This composite index is defined to optimize query performance for complex queries involving multiple fields. The index also defines a conflict resolution strategy for duplicate key violations. When a new record would violate this composite index, the following action will be taken: **On Duplicate**: `throwError` An error will be thrown, preventing the insertion of conflicting data. ### Properties Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `userId` | ID | Yes | User placing the bid. | | `bidAmount` | Double | Yes | Bid amount placed by the user. | | `placedAt` | Date | No | When the bid was placed. | | `currency` | String | Yes | ISO currency for the bid (e.g., USD, EUR). | | `status` | Enum | Yes | Bid status: ACTIVE, WON, LOST, CANCELLED. | | `productId` | ID | Yes | Product being bid on (must be AUCTION type). | * Required properties are mandatory for creating objects and must be provided in the request body if no default value is set. ### Default Values Default values are automatically assigned to properties when a new object is created, if no value is provided in the request body. Since default values are applied on db level, they should be literal values, not expressions.If you want to use expressions, you can use transposed parameters in any business API to set default values dynamically. - **userId**: '00000000-0000-0000-0000-000000000000' - **bidAmount**: 0.0 - **currency**: 'default' - **status**: ACTIVE - **productId**: '00000000-0000-0000-0000-000000000000' ### Constant Properties `userId` `bidAmount` `placedAt` `currency` `productId` Constant properties are defined to be immutable after creation, meaning they cannot be updated or changed once set. They are typically used for properties that should remain constant throughout the object's lifecycle. A property is set to be constant if the `Allow Update` option is set to `false`. ### Auto Update Properties `userId` `bidAmount` `placedAt` `currency` `status` `productId` An update crud API created with the option `Auto Params` enabled will automatically update these properties with the provided values in the request body. If you want to update any property in your own business logic not by user input, you can set the `Allow Auto Update` option to false. These properties will be added to the update API's body parameters and can be updated by the user if any value is provided in the request body. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an addtional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the index property to sort by the enum value or when your enum options represent a sequence of values. - **status**: [ACTIVE, WON, LOST, CANCELLED] ### Elastic Search Indexing `userId` `bidAmount` `placedAt` `currency` `status` `productId` Properties that are indexed in Elastic Search will be searchable via the Elastic Search API. While all properties are stored in the elastic search index of the data object, only those marked for Elastic Search indexing will be available for search queries. ### Database Indexing `userId` `productId` Properties that are indexed in the database will be optimized for query performance, allowing for faster data retrieval. Make a property indexed in the database if you want to use it frequently in query filters or sorting. ### Relation Properties `userId` `productId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. You can define relations in the data object properties, which will be used to create foreign key constraints in the database. For complex joins operations, Mindbricks supportsa BFF pattern, where you can view dynamic and static views based on Elastic Search Indexes. Use db level relations for simple one-to-one or one-to-many relationships, and use BFF views for complex joins that require multiple data objects to be joined together. - **userId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes - **productId**: ID Relation to `productListingProduct`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes ### Session Data Properties `userId` Session data properties are used to store data that is specific to the user session, allowing for personalized experiences and temporary data storage. If a property is configured as session data, it will be automatically mapped to the related field in the user session during CRUD operations. Note that session data properties can not be mutated by the user, but only by the system. - **userId**: ID property will be mapped to the session parameter `userId`. This property is also used to store the owner of the session data, allowing for ownership checks and access control. ### Formula Properties `placedAt` Formula properties are used to define calculated fields that derive their values from other properties or external data. These properties are automatically calculated based on the defined formula and can be used for dynamic data retrieval. - **placedAt**: Date - Formula: `this.createdAt` - Calculate After Instance: No ### Filter Properties `userId` `bidAmount` `currency` `status` `productId` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's that have "Auto Params" enabled. - **userId**: ID has a filter named `userId` - **bidAmount**: Double has a filter named `bidAmount` - **currency**: String has a filter named `currency` - **status**: Enum has a filter named `status` - **productId**: ID has a filter named `productId` ## Business Logic auctionOffer has got 10 Business APIs to manage its internal and crud logic. For the details of each business API refer to its chapter. * [Update Auctionofferoffer](/businessLogic/updateauctionofferoffer) * [Create Auctionofferbid](/businessLogic/createauctionofferbid) * [Get Auctionofferbid](/businessLogic/getauctionofferbid) * [Get Auctionofferoffer](/businessLogic/getauctionofferoffer) * [List Auctionofferoffers](/businessLogic/listauctionofferoffers) * [Update Auctionofferbid](/businessLogic/updateauctionofferbid) * [Create Auctionofferoffer](/businessLogic/createauctionofferoffer) * [List Auctionofferbids](/businessLogic/listauctionofferbids) * [Delete Auctionofferbid](/businessLogic/deleteauctionofferbid) * [Delete Auctionofferoffer](/businessLogic/deleteauctionofferoffer) ## Edge Controllers No edge controllers defined for this service. --- ## Service Library ### Functions No general functions defined. ### Hook Functions No hook functions defined. ### Edge Functions No edge functions defined. ### Templates No templates defined. ### Assets No assets defined. ### Public Assets No public assets defined. --- ### Event Emission --- ## Integration Patterns ## Deployment Considerations ### Environment Configuration - **HTTP Port**: `3002` - **Database Type**: MongoDB - **Global Soft Delete**: Enabled ## Implementation Guidelines ### Development Workflow 1. **Data Model Implementation**: Generate database schema from data object definitions 2. **CRUD Route Generation**: Implement auto-generated routes with custom logic 3. **Custom Logic Integration**: Implement hook functions and edge functions 4. **Authentication Integration**: Configure with project-level authentication 5. **Testing**: Unit and integration testing for all components ### Code Generation Expectations - **Database Schema**: Auto-generated from data objects and relationships - **API Routes**: REST endpoints with customizable behavior - **Validation Logic**: Input validation from property definitions - **Access Control**: Authentication and authorization middleware ### Custom Code Integration Points - **Hook Functions**: Lifecycle-specific custom logic - **Edge Functions**: Full request/response control - **Library Functions**: Reusable business logic - **Templates**: Dynamic content rendering ### Testing Strategy #### Unit Testing - Test all custom library functions - Test validation logic and business rules - Test hook function implementations #### Integration Testing - Test API endpoints with authentication scenarios - Test database operations and transactions - Test external integrations - Test event emission and Kafka integration #### Performance Testing - Load test high-traffic endpoints - Test caching effectiveness - Monitor database query performance - Test scalability under load --- ## Appendices ### Data Type Reference | Type | Description | Storage | |------|-------------|---------| | ID | Unique identifier | UUID (SQL) / ObjectID (NoSQL) | | String | Short text (≤255 chars) | VARCHAR | | Text | Long-form text | TEXT | | Integer | 32-bit whole numbers | INT | | Boolean | True/false values | BOOLEAN | | Double | 64-bit floating point | DOUBLE | | Float | 32-bit floating point | FLOAT | | Short | 16-bit integers | SMALLINT | | Object | JSON object | JSONB (PostgreSQL) / Object (MongoDB) | | Date | ISO 8601 timestamp | TIMESTAMP | | Enum | Fixed numeric values | SMALLINT with lookup | ### Enum Value Mappings #### Request Locations - `0`: Bearer token in Authorization header - `1`: Cookie value - `2`: Custom HTTP header - `3`: Query parameter - `4`: Request body property - `5`: URL path parameter - `6`: Session data - `7`: Root request object #### HTTP Methods - `0`: GET - `1`: POST - `2`: PUT - `3`: PATCH - `4`: DELETE ### Edge Function Signature ```javascript async function edgeFunction(request) { // Custom request processing // Return response object or throw error return { data: {}, status: 200, message: "Success" }; } ``` --- *This document was generated from the service architecture definition and should be kept in sync with implementation changes.* # EVENT GUIDE ## ebaycclone-auth-service Authentication service for the project ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to: Email: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. # Documentation Scope Welcome to the official documentation for the `Auth` Service Event descriptions. This guide is dedicated to detailing how to subscribe to and listen for state changes within the `Auth` Service, offering an exclusive focus on event subscription mechanisms. **Intended Audience** This documentation is aimed at developers and integrators looking to monitor `Auth` Service state changes. It is especially relevant for those wishing to implement or enhance business logic based on interactions with `Auth` objects. **Overview** This section provides detailed instructions on monitoring service events, covering payload structures and demonstrating typical use cases through examples. # Authentication and Authorization Access to the `Auth` service's events is facilitated through the project's Kafka server, which is not accessible to the public. Subscription to a Kafka topic requires being on the same network and possessing valid Kafka user credentials. This document presupposes that readers have existing access to the Kafka server. Additionally, the service offers a public subscription option via REST for real-time data management in frontend applications, secured through REST API authentication and authorization mechanisms. To subscribe to service events via the REST API, please consult the Realtime REST API Guide. # Database Events Database events are triggered at the database layer, automatically and atomically, in response to any modifications at the data level. These events serve to notify subscribers about the creation, update, or deletion of objects within the database, distinct from any overarching business logic. Listening to database events is particularly beneficial for those focused on tracking changes at the database level. A typical use case for subscribing to database events is to replicate the data store of one service within another service's scope, ensuring data consistency and syncronization across services. For example, while a business operation such as "approve membership" might generate a high-level business event like `membership-approved`, the underlying database changes could involve multiple state updates to different entities. These might be published as separate events, such as `dbevent-member-updated` and `dbevent-user-updated`, reflecting the granular changes at the database level. Such detailed eventing provides a robust foundation for building responsive, data-driven applications, enabling fine-grained observability and reaction to the dynamics of the data landscape. It also facilitates the architectural pattern of event sourcing, where state changes are captured as a sequence of events, allowing for high-fidelity data replication and history replay for analytical or auditing purposes. ## DbEvent user-created **Event topic**: `ebaycclone-auth-service-dbevent-user-created` This event is triggered upon the creation of a `user` data object in the database. The event payload encompasses the newly created data, encapsulated within the root of the paylod. **Event payload**: ```json {"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent user-updated **Event topic**: `ebaycclone-auth-service-dbevent-user-updated` Activation of this event follows the update of a `user` data object. The payload contains the updated information under the `user` attribute, along with the original data prior to update, labeled as `old_user` and also you can find the old and new versions of updated-only portion of the data.. **Event payload**: ```json { old_user:{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, user:{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, oldDataValues, newDataValues } ``` ## DbEvent user-deleted **Event topic**: `ebaycclone-auth-service-dbevent-user-deleted` This event announces the deletion of a `user` data object, covering both hard deletions (permanent removal) and soft deletions (where the `isActive` attribute is set to false). Regardless of the deletion type, the event payload will present the data as it was immediately before deletion, highlighting an `isActive` status of false for soft deletions. **Event payload**: ```json {"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` # ElasticSearch Index Events Within the `Auth` service, most data objects are mirrored in ElasticSearch indices, ensuring these indices remain syncronized with their database counterparts through creation, updates, and deletions. These indices serve dual purposes: they act as a data source for external services and furnish aggregated data tailored to enhance frontend user experiences. Consequently, an ElasticSearch index might encapsulate data in its original form or aggregate additional information from other data objects. These aggregations can include both one-to-one and one-to-many relationships not only with database objects within the same service but also across different services. This capability allows developers to access comprehensive, aggregated data efficiently. By subscribing to ElasticSearch index events, developers are notified when an index is updated and can directly obtain the aggregated entity within the event payload, bypassing the need for separate ElasticSearch queries. It's noteworthy that some services may augment another service's index by appending to the entity’s `extends` object. In such scenarios, an `*-extended` event will contain only the newly added data. Should you require the complete dataset, you would need to retrieve the full ElasticSearch index entity using the provided ID. This approach to indexing and event handling facilitates a modular, interconnected architecture where services can seamlessly integrate and react to changes, enriching the overall data ecosystem and enabling more dynamic, responsive applications. ## Index Event user-created **Event topic**: `elastic-index-ebaycclone_user-created` **Event payload**: ```json {"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event user-updated **Event topic**: `elastic-index-ebaycclone_user-created` **Event payload**: ```json {"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event user-deleted **Event topic**: `elastic-index-ebaycclone_user-deleted` **Event payload**: ```json {"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event user-extended **Event topic**: `elastic-index-ebaycclone_user-extended` **Event payload**: ```js { id: id, extends: { [extendName]: "Object", [extendName + "_count"]: "Number", }, } ``` # Route Events Route events are emitted following the successful execution of a route. While most routes perform CRUD (Create, Read, Update, Delete) operations on data objects, resulting in route events that closely resemble database events, there are distinctions worth noting. A single route execution might trigger multiple CRUD actions and ElasticSearch indexing operations. However, for those primarily concerned with the overarching business logic and its outcomes, listening to the consolidated route event, published once at the conclusion of the route's execution, is more pertinent. Moreover, routes often deliver aggregated data beyond the primary database object, catering to specific client needs. For instance, creating a data object via a route might not only return the entity's data but also route-specific metrics, such as the executing user's permissions related to the entity. Alternatively, a route might automatically generate default child entities following the creation of a parent object. Consequently, the route event encapsulates a unified dataset encompassing both the parent and its children, in contrast to individual events triggered for each entity created. Therefore, subscribing to route events can offer a richer, more contextually relevant set of information aligned with business logic. The payload of a route event mirrors the REST response JSON of the route, providing a direct and comprehensive reflection of the data and metadata communicated to the client. This ensures that subscribers to route events receive a payload that encapsulates both the primary data involved and any additional information deemed significant at the business level, facilitating a deeper understanding and integration of the service's functional outcomes. ## Route Event user-retrived **Event topic** : `ebaycclone-auth-service-user-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `user` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`user`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"user","method":"GET","action":"get","appVersion":"Version","rowCount":1,"user":{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event user-updated **Event topic** : `ebaycclone-auth-service-user-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `user` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`user`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"user","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"user":{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event profile-updated **Event topic** : `ebaycclone-auth-service-profile-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `user` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`user`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"user","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"user":{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event user-created **Event topic** : `ebaycclone-auth-service-user-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `user` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`user`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"user","method":"POST","action":"create","appVersion":"Version","rowCount":1,"user":{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event user-deleted **Event topic** : `ebaycclone-auth-service-user-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `user` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`user`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"user","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"user":{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event profile-archived **Event topic** : `ebaycclone-auth-service-profile-archived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `user` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`user`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"user","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"user":{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event users-listed **Event topic** : `ebaycclone-auth-service-users-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `users` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`users`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"users","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","users":[{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event users-searched **Event topic** : `ebaycclone-auth-service-users-searched` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `users` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`users`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"users","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","users":[{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event userrole-updated **Event topic** : `ebaycclone-auth-service-userrole-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `user` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`user`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"user","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"user":{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event userpassword-updated **Event topic** : `ebaycclone-auth-service-userpassword-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `user` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`user`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"user","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"user":{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event userpasswordbyadmin-updated **Event topic** : `ebaycclone-auth-service-userpasswordbyadmin-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `user` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`user`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"user","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"user":{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event briefuser-retrived **Event topic** : `ebaycclone-auth-service-briefuser-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `user` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`user`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"user","method":"GET","action":"get","appVersion":"Version","rowCount":1,"user":{"fullname":"String","avatar":"String","isActive":true}} ``` ## Route Event user-registered **Event topic** : `ebaycclone-auth-service-user-registered` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `user` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`user`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"user","method":"POST","action":"create","appVersion":"Version","rowCount":1,"user":{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` # Copyright All sources, documents and other digital materials are copyright of . # About Us For more information please visit our website: . . . # **EBAYCCLONE** FRONTEND GUIDE FOR AI CODING AGENTS This document is a rest api guide for the ebaycclone project. The document is designed for AI agents who will generate frontend code that will consume the project backend. The project has got 1 auth service, 1 notification service, 1 bff service and business services. Each service is a separate microservice application and listens the HTTP request from different service urls. The services may be in preview server, staging server or real production server. So each service have got 3 acess urls. Frontend application should support all deployemnt servers in the development phase, and user should be able to select the target api server in the login page. ## Project Introduction ebaycClone is a comprehensive backend for an online marketplace supporting auctions and fixed-price sales of physical goods, with role-based access, public user registration, Stripe payments, notifications, and robust ownership enforcement. ## API Structure ### Object Structure of a Successfull Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client. **HTTP Status Codes:** - **200 OK**: This status code is returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request has been processed successfully. - **201 Created**: This status code is specific to CREATE operations, signifying that the requested resource has been successfully created. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling the successful execution of the request. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` - **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation performed. ### Additional Data Each api may have include addtional data other than the main data object according to the business logic of the API. They will be given in each API's response signature. ### Error Response If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity: - **400 Bad Request**: The request was improperly formatted or contained invalid parameters, preventing the server from processing it. - **401 Unauthorized**: The request lacked valid authentication token , login required - **403 Forbidden Error** Curent token provided do not grant access to the requested resource. - **404 Not Found**: The requested resource was not found on the server. - **500 Internal Server Error**: The server encountered an unexpected condition that prevented it from fulfilling the request. Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Accessing the backend Each service of the backend has got its own url according to the deployment environement. User may want to test the frontend in one of the 3 deployments of the application, preview, staging and production. Please ensure that register and login pages do have a deployemnt server selection option, so as the frontned coding agent you can arrange the base url path of all services. The base url of the application in each environment is as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com` * **Staging:** `https://ebaycclone-stage.mindbricks.co` * **Production:** `https://ebaycclone.mindbricks.co` For the auth service the base url is as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` For each other service, the service base url will be given in service sections. Any login requied request to the backend should have a valid token, when a user makes a successfull login, the ressponse JSON includes a JWT access token in the `accessToken`fields. In normal conditions, this token is also set to the cookie and then consumed automatically, but since AI coding agents preview options may fail to use cookies, please ensure that in each request include the access token in the bearer auth header. ## Registration Management First of all please ensure that register and login pages do have a deployemnt server selection option, so as the frontned coding agent you can arrange the base url path of all services. Start with a landing page and arranging register, verification and login flow. So at the first step, you need a general knowledge of the application to make a good landing page and the authetication flow. ### How To Register Using `registeruser` route of auth api, send the required fields to the backend in your registration page. The registerUser api in in `auth` service, is described with request and response structure below. Note that since `registerUser` api is a business api, it has a version control, so please call it with the given version like `/v1/registeruser` ### `Register User` API This api is used by public users to register themselves **Rest Route** The `registerUser` API REST controller can be triggered via the following route: `/v1/registeruser` **Rest Request Parameters** The `registerUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **password** : The password defined by the the user that is being registered. **fullname** : The fullname defined by the the user that is being registered. **email** : The email defined by the the user that is being registered. **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` After a successful registration, frontend code should handle the verification needs. The registration response will have a `user` object in the root envelope, this object will have user information with an `id` parameter. ### Email Verification In the registration response, you should check the property `emailVerificationNeeded` in the reponse root, and if this property is true you should start the email verification flow. After login process, if you get an HTTP error status, and if there is an `errCode` property in the response with `EmailVerificationNeeded` value, you should start the email verification flow. 1. Call the email verification `start` route of the backend (described below) with the user email, backend will send a secret code to the given email adresss. **Backend can send the email message if the architect defined a real mail service or smtp server, so during the development time backend will send the secret code also to the frontend. You can get this secret code from the response within the `secretCode` property**. 2. The secret code in the sent email message will be a 6 digits code , and you should arrange an input page so that the user can paste this code to the frontend application. Please navigate to this input page after you start the verification process. **If the secretCode is sent to the frontend for test purposes, then you should show it as info in the input page, so that user can copy and paste it**. 3. There is a `codeIndex` property in the start response, please show it's value on the input page, so that user can match the index in the message with the one on the screen. 4. When the user submits the code, please complete the email verification using the `complete` route of the backend (described below) with the user email and the secret code. 5. After you get a successful response from email verification, you can navigate to the login page. Here is the `start`and `complete` routes of email verification. These are system routes , so they dont have a version control. #### `POST /verification-services/email-verification/start` **Purpose:** Starts the email verification by generating and sending a secret code. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `email` | String | Yes | User’s email address to verify | **Example Request** ```json { "email": "user@example.com" } ``` **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ In production, `secretCode` is **not** returned — only sent via email. **Error Responses** * `400 Bad Request`: Already verified * `403 Forbidden`: Too many attempts (rate limit) --- #### `POST /verification-services/email-verification/complete` **Purpose:** Completes the verification using the received code. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `email` | String | Yes | User’s email | | `secretCode` | String | Yes | Verification code | **Success Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` **Error Responses** * `403 Forbidden`: Code expired or mismatched * `404 Not Found`: No verification in progress --- ## Login Management After a successfull login and completing required verifications, user can now login. Please make a fancy minimal login page where user can enter his email and password. ## Bucket Management This application has a bucket service and is used to store user or other objects related files. Bucket service is login agnostic, so when accessing for write or private read, you should insert a bucket token (given by services) to your request authorization header as bearer token. **User Bucket** This bucket is used to store public user files for each user. When a user logs in, or in /currentuser response there is `userBucketToken` to be used when sending user related public files to the bucket service. To upload `POST {baseUrl}/bucket/upload` Request body is form data which includes the bucketId and the file as binary in `files` property. ```js { bucketId: "{userId}-public-user-bucket", files: {binary} } ``` Response status is 200 on succesfull result, eg body: ```json { "success": true, "data": [ { "fileId": "9da03f6d-0409-41ad-bb06-225a244ae408", "originalName": "test (10).png", "mimeType": "image/png", "size": 604063, "status": "uploaded", "bucketName": "f7103b85-fcda-4dec-92c6-c336f71fd3a2-public-user-bucket", "isPublic": true, "downloadUrl": "https://babilcom.mindbricks.co/bucket/download/9da03f6d-0409-41ad-bb06-225a244ae408" } ] } ``` To download a file from the bucket, you should know its fileId, so if youupload an avatar or something else, be sure that the download url or the fileId is stored in backend. Bucket is mostly used, in object creations where alos demands an addtional file like a product image or user avatar. So after you upload your image to the bucket, insert the returned download url to the related property in the related object creation. **Application Bucket** This Ebaycclone application alos has common public bucket which everybody has a read access, but only users who have `superAdmin`, `admin` or `saasAdmin` roles can write (upload) to the bucket. The common public project bucket id is `"ebaycclone-public-common-bucket"` and in certain areas like product image uploads, since the user will already have the admin bucket token, he will be able to upload realted object images. Please make your UI arrangements as able to upload files to the bucket using these bucket tokens. **Object Buckets** Some objects may return also a bucket token, to upload or access related files with object. For example, when you get a project's data in a project management application, if there is a public or private bucket token, this is provided mostly for uploading project related files or downloading them with the token. These buckets will be used according to the descriptions given along with the object definitions. ## Role Management This Ebaycclone may have different role names defined fro different business logic. But unless another case is asked by the user, respect to the admin roles which may be `superAdmin`, `admin` or `saasAdmin` in the currentuser or login response given with the `roleId`property. ```json { // ... "roleId":"superAdmin", // ... } ``` If the application needs an admin panel, or any admin related page, please use these roleId's to decide if the user can access those pages or not. ## 1. Authentication Routes ### 1.1 `POST /login` — User Login **Purpose:** Verifies user credentials and creates an authenticated session with a JWT access token. **Access Routes:** * `GET /login`: Returns a minimal HTML login page (for browser-based testing). * `POST /login`: Authenticates user credentials and returns an access token and session. #### Request Parameters | Parameter | Type | Required | Source | | ---------- | ------ | -------- | ----------------------- | | `username` | String | Yes | `request.body.username` | | `password` | String | Yes | `request.body.password` | #### Behavior * Authenticates credentials and returns a session object. * Sets cookie: `projectname-access-token[-tenantCodename]` * Adds the same token in response headers. * Accepts either `username` or `email` fields (if both exist, `username` is prioritized). #### Example ```js axios.post("/login", { username: "user@example.com", password: "securePassword" }); ``` #### Success Response ```json { "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", //... } ``` #### Error Responses * `401 Unauthorized`: Invalid credentials * `403 Forbidden`: Email/mobile verification or 2FA pending * `400 Bad Request`: Missing parameters --- ### 1.2 `POST /logout` — User Logout **Purpose:** Terminates the current session and clears associated authentication tokens. #### Behavior * Invalidates session (if exists). * Clears cookie `projectname-access-token[-tenantCodename]`. * Returns a confirmation response (always `200 OK`). #### Example ```js axios.post("/logout", {}, { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` #### Notes * Can be called without a session (idempotent behavior). * Works for both cookie-based and token-based sessions. #### Success Response ```json { "status": "OK", "message": "User logged out successfully" } ``` --- ## 2. Verification Services Overview All verification routes are grouped under the `/verification-services` base path. They follow a **two-step verification pattern**: `start` → `complete`. --- ## 3. Email Verification ### 3.1 Trigger Scenarios * After registration (`emailVerificationRequiredForLogin` = true) * When updating email address * When login fails due to unverified email ### 3.2 Flow Summary 1. `/start` → Generate & send code via email. 2. `/complete` → Verify code and mark email as verified. ** PLEASE NOTE ** Email verification is a frontend triiggered process. After user registers, the frontend should start the email verification process and navigate to its code input page. --- ### 3.3 `POST /verification-services/email-verification/start` **Purpose:** Starts the email verification by generating and sending a secret code. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `email` | String | Yes | User’s email address to verify | **Example Request** ```json { "email": "user@example.com" } ``` **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ In production, `secretCode` is **not** returned — only sent via email. **Error Responses** * `400 Bad Request`: Already verified * `403 Forbidden`: Too many attempts (rate limit) --- ### 3.4 `POST /verification-services/email-verification/complete` **Purpose:** Completes the verification using the received code. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `email` | String | Yes | User’s email | | `secretCode` | String | Yes | Verification code | **Success Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` **Error Responses** * `403 Forbidden`: Code expired or mismatched * `404 Not Found`: No verification in progress --- ### 3.5 Behavioral Notes * **Resend Cooldown:** `resendTimeWindow` (e.g. 60s) * **Expiration:** Codes expire after `expireTimeWindow` (e.g. 1 day) * **Single Active Session:** One verification per user --- ## 4. Mobile Verification ### 4.1 Trigger Scenarios * After registration (`mobileVerificationRequiredForLogin` = true) * When updating phone number * On login requiring mobile verification ### 4.2 Flow 1. `/start` → Sends verification code via SMS 2. `/complete` → Validates code and confirms number --- ### 4.3 `POST /verification-services/mobile-verification/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------ | | `email` | String | Yes | User’s email to locate mobile record | **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 180, "verificationType": "byCode", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ `secretCode` returned only in development. **Errors** * `400 Bad Request`: Already verified * `403 Forbidden`: Rate-limited --- ### 4.4 `POST /verification-services/mobile-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------------- | | `email` | String | Yes | Associated email | | `secretCode` | String | Yes | Code received via SMS | **Success Response** ```json { "status": "OK", "isVerified": true, "mobile": "+1 333 ...", // in testMode "userId": "user-uuid", } ``` --- ### 4.5 Behavioral Notes * **Cooldown:** One code per minute * **Expiration:** Codes valid for 1 day * **One Session Per User** --- ## 5. Two-Factor Authentication (2FA) ### 5.1 Email 2FA **Flow** 1. `/start` → Generates and sends email code 2. `/complete` → Verifies code and updates session --- #### `POST /verification-services/email-2factor-verification/start` | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ---------------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Current session | | `client` | String | No | Optional context | | `reason` | String | No | Reason for 2FA | **Response** ```json { "status": "OK", "sessionId": "user session id UUID", "userId": "user-uuid", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", } ``` --- #### `POST /verification-services/email-2factor-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `secretCode` | String | Yes | Code from email | **Response** ```json { // user session data "sessionId": "session-uuid", // ... } ``` --- ### 5.2 Mobile 2FA **Flow** 1. `/start` → Sends SMS code 2. `/complete` → Validates and finalizes session --- #### `POST /verification-services/mobile-2factor-verification/start` | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ----------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `client` | String | No | Context | | `reason` | String | No | Reason | **Response** ```json { "status": "OK", "sessionId": "user session id UUID", "userId": "user-uuid", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", } ``` --- #### `POST /verification-services/mobile-2factor-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------ | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `secretCode` | String | Yes | Code via SMS | **Response** ```json { // user session data "sessionId": "session-uuid", // ... } ``` --- ### 5.3 2FA Behavioral Notes * One active code per session * Cooldown: `resendTimeWindow` (e.g., 60s) * Expiration: `expireTimeWindow` (e.g., 5m) --- ## 6. Password Reset ### 6.1 By Email **Flow** 1. `/start` → Sends verification code via email 2. `/complete` → Validates and resets password --- #### `POST /verification-services/password-reset-by-email/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------- | | `email` | String | Yes | User email | **Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` #### `POST /verification-services/password-reset-by-email/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------- | | `email` | String | Yes | User email | | `secretCode` | String | Yes | Code received | | `password` | String | Yes | New password | **Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` --- ### 6.2 By Mobile **Flow** 1. `/start` → Sends SMS code 2. `/complete` → Validates and resets password --- #### `POST /verification-services/password-reset-by-mobile/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------- | | `mobile` | String | Yes | Mobile number | **Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` #### `POST /verification-services/password-reset-by-mobile/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ---------------- | | `email` | String | Yes | Associated email | | `secretCode` | String | Yes | Code via SMS | | `password` | String | Yes | New password | **Response** ```json { "status": "OK", "isVerified": true, "mobile": "+1 444 ....", // in testMode "userId": "user-uuid", } ``` --- ### 6.3 Behavioral Notes * Cooldown: 60s resend * Expiration: 24h * One session per user * Works without an active login session --- ## 7. Verification Method Types ### 7.1 `byCode` User manually enters the 6-digit code in frontend. ### 7.2 `byLink` Frontend handles a one-click verification via email/SMS link containing code parameters. ## 8) `GET /currentuser` — Current Session **Purpose** Return the currently authenticated user’s session. **Route Type** `sessionInfo` **Authentication** Requires a valid access token (header or cookie). ### Request *No parameters.* ### Example ```js axios.get("/currentuser", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) Returns the session object (identity, tenancy, token metadata): ```json { "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", "roleId": "user", "tenantId": "abc123", "accessToken": "jwt-token-string", "...": "..." } ``` ### Errors * **401 Unauthorized** — No active session/token ```json { "status": "ERR", "message": "No login found" } ``` **Notes** * Commonly called by web/mobile clients after login to hydrate session state. * Includes key identity/tenant fields and a token reference (if applicable). * Ensure a valid token is supplied to receive a 200 response. --- ## 9) `GET /permissions` — List Effective Permissions **Purpose** Return all effective permission grants for the current user. **Route Type** `permissionFetch` **Authentication** Requires a valid access token. ### Request *No parameters.* ### Example ```js axios.get("/permissions", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) Array of permission grants (aligned with `givenPermissions`): ```json [ { "id": "perm1", "permissionName": "adminPanel.access", "roleId": "admin", "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" }, { "id": "perm2", "permissionName": "orders.manage", "roleId": null, "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" } ] ``` **Field meanings (per item):** * `permissionName`: Granted permission key. * `roleId`: Present if granted via role. * `subjectUserId`: Present if granted directly to the user. * `subjectUserGroupId`: Present if granted via group. * `objectId`: Present if scoped to a specific object (OBAC). * `canDo`: `true` if enabled, `false` if restricted. ### Errors * **401 Unauthorized** — No active session ```json { "status": "ERR", "message": "No login found" } ``` * **500 Internal Server Error** — Unexpected failure **Notes** * Available on all Mindbricks-generated services (not only Auth). * **Auth service:** Reads live `givenPermissions` from DB. * **Other services:** Typically respond from a cached/projected view (e.g., ElasticSearch) for faster checks. > **Tip:** Cache permission results client-side/server-side and refresh after login or permission updates. --- ## 10) `GET /permissions/:permissionName` — Check Permission Scope **Purpose** Check whether the current user has a specific permission and return any scoped object exceptions/inclusions. **Route Type** `permissionScopeCheck` **Authentication** Requires a valid access token. ### Path Parameters | Name | Type | Required | Source | | ---------------- | ------ | -------- | ------------------------------- | | `permissionName` | String | Yes | `request.params.permissionName` | ### Example ```js axios.get("/permissions/orders.manage", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) ```json { "canDo": true, "exceptions": [ "a1f2e3d4-xxxx-yyyy-zzzz-object1", "b2c3d4e5-xxxx-yyyy-zzzz-object2" ] } ``` **Interpretation** * If `canDo: true`: permission is generally granted **except** the listed `exceptions` (restrictions). * If `canDo: false`: permission is generally **not** granted, **only** allowed for the listed `exceptions` (selective overrides). * `exceptions` contains object IDs (UUID strings) from the relevant domain model. ### Errors * **401 Unauthorized** — No active session/token. ## Services And Data Object ## Auth Service Authentication service for the project ### Auth Service Data Objects **User** A data object that stores the user information and handles login settings. ### Auth Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` ### `Get User` API This api is used by admin roles or the users themselves to get the user profile information. **Rest Route** The `getUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `getUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users/:userId** ```js axios({ method: 'GET', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update User` API This route is used by admins to update user profiles. **Rest Route** The `updateUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `updateUser` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/users/:userId** ```js axios({ method: 'PATCH', url: `/v1/users/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Profile` API This route is used by users to update their profiles. **Rest Route** The `updateProfile` API REST controller can be triggered via the following route: `/v1/profile/:userId` **Rest Request Parameters** The `updateProfile` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/profile/:userId** ```js axios({ method: 'PATCH', url: `/v1/profile/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create User` API This api is used by admin roles to create a new user manually from admin panels **Rest Route** The `createUser` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `createUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | email | String | true | request.body?.email | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **email** : A string value to represent the user's email. **password** : A string value to represent the user's password. It will be stored as hashed. **fullname** : A string value to represent the fullname of the user **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/users** ```js axios({ method: 'POST', url: '/v1/users', data: { avatar:"String", email:"String", password:"String", fullname:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete User` API This api is used by admins to delete user profiles. **Rest Route** The `deleteUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `deleteUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/users/:userId** ```js axios({ method: 'DELETE', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Archive Profile` API This api is used by users to archive their profiles. **Rest Route** The `archiveProfile` API REST controller can be triggered via the following route: `/v1/archiveprofile/:userId` **Rest Request Parameters** The `archiveProfile` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/archiveprofile/:userId** ```js axios({ method: 'DELETE', url: `/v1/archiveprofile/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Users` API The list of users is filtered by the tenantId. **Rest Route** The `listUsers` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `listUsers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users** ```js axios({ method: 'GET', url: '/v1/users', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Search Users` API The list of users is filtered by the tenantId. **Rest Route** The `searchUsers` API REST controller can be triggered via the following route: `/v1/searchusers` **Rest Request Parameters** The `searchUsers` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | keyword | String | true | request.query?.keyword | **keyword** : **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchusers** ```js axios({ method: 'GET', url: '/v1/searchusers', data: { }, params: { keyword:'"String"', } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Userrole` API This route is used by admin roles to update the user role.The default role is user when a user is registered. A user's role can be updated by superAdmin or admin **Rest Route** The `updateUserRole` API REST controller can be triggered via the following route: `/v1/userrole/:userId` **Rest Request Parameters** The `updateUserRole` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | roleId | String | true | request.body?.roleId | **userId** : This id paremeter is used to select the required data object that will be updated **roleId** : The new roleId of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userrole/:userId** ```js axios({ method: 'PATCH', url: `/v1/userrole/${userId}`, data: { roleId:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpassword` API This route is used to update the password of users in the profile page by users themselves **Rest Route** The `updateUserPassword` API REST controller can be triggered via the following route: `/v1/userpassword/:userId` **Rest Request Parameters** The `updateUserPassword` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | oldPassword | String | true | request.body?.oldPassword | | newPassword | String | true | request.body?.newPassword | **userId** : This id paremeter is used to select the required data object that will be updated **oldPassword** : The old password of the user that will be overridden bu the new one. Send for double check. **newPassword** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpassword/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpassword/${userId}`, data: { oldPassword:"String", newPassword:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpasswordbyadmin` API This route is used to change any user password by admins only. Superadmin can chnage all passwords, admins can change only nonadmin passwords **Rest Route** The `updateUserPasswordByAdmin` API REST controller can be triggered via the following route: `/v1/userpasswordbyadmin/:userId` **Rest Request Parameters** The `updateUserPasswordByAdmin` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | password | String | true | request.body?.password | **userId** : This id paremeter is used to select the required data object that will be updated **password** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpasswordbyadmin/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpasswordbyadmin/${userId}`, data: { password:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Briefuser` API This route is used by public to get simple user profile information. **Rest Route** The `getBriefUser` API REST controller can be triggered via the following route: `/v1/briefuser/:userId` **Rest Request Parameters** The `getBriefUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/briefuser/:userId** ```js axios({ method: 'GET', url: `/v1/briefuser/${userId}`, data: { }, params: { } }); ``` **REST Response** This route's response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "fullname": "String", "avatar": "String", "isActive": true } } ``` ### `Register User` API This api is used by public users to register themselves **Rest Route** The `registerUser` API REST controller can be triggered via the following route: `/v1/registeruser` **Rest Request Parameters** The `registerUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **password** : The password defined by the the user that is being registered. **fullname** : The fullname defined by the the user that is being registered. **email** : The email defined by the the user that is being registered. **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## AuctionOffer Service Handles auction bids and fixed-price offers for product listings, enforces real-time auction state, handles strict offer workflows including counter-offers, and triggers domain events for bid/offer notifications. No payment or frontend aggregation logic included. ### AuctionOffer Service Data Objects **AuctionOfferOffer** Represents an offer (best offer/counter-offer) made on a fixed-price product. Tracks buyer, seller, amounts, currency, state transitions, counter-offers, and expiry. **AuctionOfferBid** Represents an individual bid placed on an auction-type product. Linked to product and user, tracks bid amount, currency, status (ACTIVE, WON, LOST, CANCELLED), and time placed. ### AuctionOffer Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auctionoffer-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auctionoffer-api` * **Production:** `https://ebaycclone.mindbricks.co/auctionoffer-api` ### `Update Auctionofferoffer` API Updates offer: accepts/declines/counters by seller, withdraws by buyer before response. Enforces status transition rules, sets respondedAt. Triggers event. **Rest Route** The `updateAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `updateAuctionOfferOffer` api has got 8 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | message | String | false | request.body?.message | | status | Enum | false | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | **auctionOfferOfferId** : This id paremeter is used to select the required data object that will be updated **counterOfferId** : References another offer (counter-offer chain). **counterMessage** : Message accompanying seller's counter-offer (optional). **counterAmount** : Counter-offer amount (when offer is COUNTERED). **message** : Message/special notes from buyer (optional). **status** : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). **expiresAt** : When this offer expires (optional). **respondedAt** : When the seller (or buyer, for counter-offer) responded/updated the offer status. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Auctionofferbid` API Creates a new bid for an auction product. Validates auction status, not seller, product type, bid window, and ensures min. increment. Updates product.currentBid and product.highestBidderId atomically. Triggers notification event. **Rest Route** The `createAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids` **Rest Request Parameters** The `createAuctionOfferBid` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | bidAmount | Double | true | request.body?.bidAmount | | currency | String | true | request.body?.currency | | status | Enum | true | request.body?.status | | productId | ID | true | request.body?.productId | **bidAmount** : Bid amount placed by the user. **currency** : ISO currency for the bid (e.g., USD, EUR). **status** : Bid status: ACTIVE, WON, LOST, CANCELLED. **productId** : Product being bid on (must be AUCTION type). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/auctionofferbids** ```js axios({ method: 'POST', url: '/v1/auctionofferbids', data: { bidAmount:"Double", currency:"String", status:"Enum", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Auctionofferbid` API Gets a single bid (only visible to owner/admin or for auction history). **Rest Route** The `getAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `getAuctionOfferBid` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | **auctionOfferBidId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'GET', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Auctionofferoffer` API Gets a single offer (shown to buyer/seller or admin). **Rest Route** The `getAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `getAuctionOfferOffer` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | **auctionOfferOfferId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'GET', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Auctionofferoffers` API Lists offers by product, user, status, or counterOffer chain. **Rest Route** The `listAuctionOfferOffers` API REST controller can be triggered via the following route: `/v1/auctionofferoffers` **Rest Request Parameters** The `listAuctionOfferOffers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers** ```js axios({ method: 'GET', url: '/v1/auctionofferoffers', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferOffers": [ { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Auctionofferbid` API Updates a bid’s status (allow only status update, e.g. CANCELLED, WIN/LOSE on admin settlement). Only owner/admin, and only if auction not ended or not settled. Triggers notification event. **Rest Route** The `updateAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `updateAuctionOfferBid` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | | status | Enum | false | request.body?.status | **auctionOfferBidId** : This id paremeter is used to select the required data object that will be updated **status** : Bid status: ACTIVE, WON, LOST, CANCELLED. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { status:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Auctionofferoffer` API Creates a new offer for a fixed-price product, validating acceptOffers, type, eligibility, and product/seller/buyer active. Defaults to PENDING state. Triggers notification event. **Rest Route** The `createAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers` **Rest Request Parameters** The `createAuctionOfferOffer` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | productId | ID | true | request.body?.productId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | offerAmount | Double | true | request.body?.offerAmount | | message | String | false | request.body?.message | | status | Enum | true | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | **currency** : ISO currency (e.g., USD, EUR) for the offer. **productId** : Product the offer applies to (must be fixed-price, acceptOffers true). **counterOfferId** : References another offer (counter-offer chain). **counterMessage** : Message accompanying seller's counter-offer (optional). **counterAmount** : Counter-offer amount (when offer is COUNTERED). **offerAmount** : Primary offer amount from buyer. **message** : Message/special notes from buyer (optional). **status** : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). **expiresAt** : When this offer expires (optional). **respondedAt** : When the seller (or buyer, for counter-offer) responded/updated the offer status. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/auctionofferoffers** ```js axios({ method: 'POST', url: '/v1/auctionofferoffers', data: { currency:"String", productId:"ID", counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", offerAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Auctionofferbids` API Lists bids by product, user, or auction, supports history/analytics. **Rest Route** The `listAuctionOfferBids` API REST controller can be triggered via the following route: `/v1/auctionofferbids` **Rest Request Parameters** The `listAuctionOfferBids` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids** ```js axios({ method: 'GET', url: '/v1/auctionofferbids', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBids", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferBids": [ { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Auctionofferbid` API Soft-deletes a bid (for admin or self before auction ends). **Rest Route** The `deleteAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `deleteAuctionOfferBid` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | **auctionOfferBidId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Auctionofferoffer` API Soft-deletes an offer (allowed only in non-accepted/expired state). **Rest Route** The `deleteAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `deleteAuctionOfferOffer` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | **auctionOfferOfferId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## CategoryManagement Service Handles product categories and subcategories for marketplace browsing and classification, supporting public discovery plus admin-only management. ### CategoryManagement Service Data Objects **Category** Represents a product category in the marketplace (e.g., Electronics, Clothing, Toys), used for browsing, filtering, and discovery. Admins manage categories. **Subcategory** Represents a subcategory within a parent category (e.g., 'Smartphones' under 'Electronics'). Used for more granular product discovery and navigation. 'group' categorizes special display logic. ### CategoryManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/categorymanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/categorymanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/categorymanagement-api` ### `Delete Category` API Soft-delete a category (admin-only). **Rest Route** The `deleteCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `deleteCategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | **categoryId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/categories/:categoryId** ```js axios({ method: 'DELETE', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Subcategory` API Get a subcategory by ID. Public - only active subcategories returned except for admin. **Rest Route** The `getSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `getSubcategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | **subcategoryId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/subcategories/:subcategoryId** ```js axios({ method: 'GET', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Category` API Get a single category by ID. Public - only active categories returned (for non-admins). **Rest Route** The `getCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `getCategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | **categoryId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/categories/:categoryId** ```js axios({ method: 'GET', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Subcategory` API Update subcategory (admin-only), including group enum change. **Rest Route** The `updateSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `updateSubcategory` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | name | String | false | request.body?.name | | group | Enum | false | request.body?.group | **subcategoryId** : This id paremeter is used to select the required data object that will be updated **categoryId** : Reference to the parent category (category.id). **name** : Display name of the subcategory. **group** : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/subcategories/:subcategoryId** ```js axios({ method: 'PATCH', url: `/v1/subcategories/${subcategoryId}`, data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Subcategories` API List all subcategories for browsing/filtering, with support for group enum and parent category queries. Only active subcategories shown to public/non-admin users. **Rest Route** The `listSubcategories` API REST controller can be triggered via the following route: `/v1/subcategories` **Rest Request Parameters** The `listSubcategories` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/subcategories** ```js axios({ method: 'GET', url: '/v1/subcategories', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "subcategories": [ { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Subcategory` API Soft-delete a subcategory (admin-only). **Rest Route** The `deleteSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `deleteSubcategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | **subcategoryId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/subcategories/:subcategoryId** ```js axios({ method: 'DELETE', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Categories` API List all categories for browsing and filtering. Only active categories shown to public/non-admin users. **Rest Route** The `listCategories` API REST controller can be triggered via the following route: `/v1/categories` **Rest Request Parameters** The `listCategories` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/categories** ```js axios({ method: 'GET', url: '/v1/categories', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "categories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "categories": [ { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Category` API Update category details (admin-only). **Rest Route** The `updateCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `updateCategory` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | false | request.body?.title | **categoryId** : This id paremeter is used to select the required data object that will be updated **imageUrl** : URL for category image/avatar (optional, used for homepage visuals). **subtitle** : Optional short description for UI/tooltips. **title** : Display name of the category. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/categories/:categoryId** ```js axios({ method: 'PATCH', url: `/v1/categories/${categoryId}`, data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Subcategory` API Create a new subcategory under a given category (admin-only), with enum group constraint. **Rest Route** The `createSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories` **Rest Request Parameters** The `createSubcategory` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.body?.categoryId | | name | String | true | request.body?.name | | group | Enum | true | request.body?.group | **categoryId** : Reference to the parent category (category.id). **name** : Display name of the subcategory. **group** : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/subcategories** ```js axios({ method: 'POST', url: '/v1/subcategories', data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Category` API Create a new category (admin-only) for product classification. **Rest Route** The `createCategory` API REST controller can be triggered via the following route: `/v1/categories` **Rest Request Parameters** The `createCategory` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | true | request.body?.title | **imageUrl** : URL for category image/avatar (optional, used for homepage visuals). **subtitle** : Optional short description for UI/tooltips. **title** : Display name of the category. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/categories** ```js axios({ method: 'POST', url: '/v1/categories', data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## Messaging Service In-app messaging service for direct user-to-user text messages (buyers/sellers). Stores, retrieves, and manages user conversations. Launch version: text-only. ### Messaging Service Data Objects **MessagingMessage** A direct, text-only in-app message between two users (buyer/seller); stores sender, recipient, content, read status, and timestamp. ### Messaging Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/messaging-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/messaging-api` * **Production:** `https://ebaycclone.mindbricks.co/messaging-api` ### `List Messagingmessages` API List all messages in the conversation between the logged-in user and another party, ordered by sentAt descending. Can filter unread with isRead. Returns only messages visible to user (isActive). **Rest Route** The `listMessagingMessages` API REST controller can be triggered via the following route: `/v1/messagingmessages` **Rest Request Parameters** The `listMessagingMessages` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages** ```js axios({ method: 'GET', url: '/v1/messagingmessages', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessages", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "messagingMessages": [ { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Messagingmessage` API Send a new text message from the logged-in user to a recipient. Sender is set from session. Launch version supports only text content. **Rest Route** The `createMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages` **Rest Request Parameters** The `createMessagingMessage` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | toUserId | ID | true | request.body?.toUserId | | content | String | true | request.body?.content | | isRead | Boolean | true | request.body?.isRead | **toUserId** : Recipient (user) of this message. **content** : Text content of the message. No files or attachments for launch. **isRead** : If true, recipient has marked this message as read. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/messagingmessages** ```js axios({ method: 'POST', url: '/v1/messagingmessages', data: { toUserId:"ID", content:"String", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Messagingmessage` API Update a message (mark as read/unread). Only the recipient or admin can change isRead. No content edits. Sender, content, sentAt are immutable. **Rest Route** The `updateMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `updateMessagingMessage` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | | isRead | Boolean | false | request.body?.isRead | **messagingMessageId** : This id paremeter is used to select the required data object that will be updated **isRead** : If true, recipient has marked this message as read. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'PATCH', url: `/v1/messagingmessages/${messagingMessageId}`, data: { isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Messagingmessage` API Get a message by ID. Only accessible to the sender, the recipient, or an admin. Used for message detail view or reading a single message in a thread. **Rest Route** The `getMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `getMessagingMessage` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | **messagingMessageId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'GET', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Messagingmessage` API Delete a message (soft-delete). Only sender, recipient, or admin may delete a message. Deletion only hides it for the user; not a full erase unless both delete. **Rest Route** The `deleteMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `deleteMessagingMessage` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | **messagingMessageId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'DELETE', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## NotificationManagement Service Handles storage, management, and event-driven delivery of in-app and email notifications for user-impacting system events (bids, offers, orders, feedback, messaging, etc.). Supports marking notifications as read/unread, structured filtering by event type/channel, and always returns in-app notifications ordered by recency. ### NotificationManagement Service Data Objects **Notification** Stores and manages in-app and email notifications tied to user-facing events like bids, offers, orders, messaging, shipment, and feedback. Includes event type (notificationType) for filter/search, arbitrary event payload, and delivery channel. Soft-delete enforced. In-app notifications always sorted by createdAt DESC on retrieval. ### NotificationManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/notificationmanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/notificationmanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/notificationmanagement-api` ### `Create Notification` API Creates a notification entry in response to a system/business event. Only allowed for system/event processes and admins (not standard user/action). Typically event-driven, receives userId, notificationType, payload, and channel. **Rest Route** The `createNotification` API REST controller can be triggered via the following route: `/v1/notifications` **Rest Request Parameters** The `createNotification` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationType | Enum | true | request.body?.notificationType | | userId | ID | true | request.body?.userId | | channel | Enum | true | request.body?.channel | | payload | Object | true | request.body?.payload | | isRead | Boolean | true | request.body?.isRead | **notificationType** : Type of event triggering notification (e.g., BID_UPDATED, ORDER_SHIPPED, MESSAGE_RECEIVED, etc.). Used for display/icon and query filter. **userId** : User receiving the notification (recipient). **channel** : Channel by which notification is delivered: IN_APP or EMAIL. **payload** : Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. **isRead** : Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/notifications** ```js axios({ method: 'POST', url: '/v1/notifications', data: { notificationType:"Enum", userId:"ID", channel:"Enum", payload:"Object", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Notification` API Updates a notification (mark as read/unread, payload patch for e.g. admin fix). Only receiver (userId) or admins may update. isRead is primary update scenario; others very limited. **Rest Route** The `updateNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `updateNotification` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | | payload | Object | false | request.body?.payload | | isRead | Boolean | false | request.body?.isRead | **notificationId** : This id paremeter is used to select the required data object that will be updated **payload** : Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. **isRead** : Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/notifications/:notificationId** ```js axios({ method: 'PATCH', url: `/v1/notifications/${notificationId}`, data: { payload:"Object", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Notifications` API Returns filtered list of notifications for a user, with optional filters: notificationType, isRead, channel. Always sorted by createdAt (descending) for in-app notifications. Only retrieval allowed for owner/admin. **Rest Route** The `listNotifications` API REST controller can be triggered via the following route: `/v1/notifications` **Rest Request Parameters** The `listNotifications` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/notifications** ```js axios({ method: 'GET', url: '/v1/notifications', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notifications", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "notifications": [ { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Notification` API Soft-delete a notification record. Only receiver or admin may delete. **Rest Route** The `deleteNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `deleteNotification` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | **notificationId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/notifications/:notificationId** ```js axios({ method: 'DELETE', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Notification` API Retrieves a notification for the receiver or admin. Used to populate content on detail/expanded view. **Rest Route** The `getNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `getNotification` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | **notificationId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/notifications/:notificationId** ```js axios({ method: 'GET', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## SearchIndexing Service Maintains the denormalized search index (materialized view) for global, public search across products, sellers, categories, and subcategories. Handles indexing in response to entity events and exposes optimized query endpoints for BFF/aggregator. ### SearchIndexing Service Data Objects **SearchIndex** Materialized/denormalized search index record for a marketplace entity (product, seller, category, subcategory). Used exclusively for high-speed querying in BFF global/public search. ### SearchIndexing Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/searchindexing-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/searchindexing-api` * **Production:** `https://ebaycclone.mindbricks.co/searchindexing-api` ### `List Searchindexes` API List/search search index entries by type or referenceId (used by BFF/global search). Always excludes inactive (soft-deleted) records. Supports filtering and full-text search filters by documentType/referenceId for admin/maintenance use. **Rest Route** The `listSearchIndexes` API REST controller can be triggered via the following route: `/v1/searchindexes` **Rest Request Parameters** The `listSearchIndexes` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchindexes** ```js axios({ method: 'GET', url: '/v1/searchindexes', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndices", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "searchIndices": [ { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Searchindex` API Update an existing searchIndex record (by (documentType, referenceId) or id). Used in response to events (entity edit, data change); internal/automation/admin only. **Rest Route** The `updateSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `updateSearchIndex` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | | documentType | Enum | false | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | false | request.body?.indexedAt | **searchIndexId** : This id paremeter is used to select the required data object that will be updated **documentType** : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY **document** : Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. **referenceId** : ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. **indexedAt** : Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/searchindexs/:searchIndexId** ```js axios({ method: 'PATCH', url: `/v1/searchindexs/${searchIndexId}`, data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Searchindex` API Soft-delete a searchIndex record (by id or by (documentType, referenceId)). Typical use: in response to entity soft-delete; internal/automation/admin only. **Rest Route** The `deleteSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `deleteSearchIndex` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | **searchIndexId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/searchindexs/:searchIndexId** ```js axios({ method: 'DELETE', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Searchindex` API Create a new searchIndex record (internal, used by event triggers and admin tools only). Typically called when a new product/seller/category/subcategory is created. **Rest Route** The `createSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs` **Rest Request Parameters** The `createSearchIndex` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | documentType | Enum | true | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | true | request.body?.indexedAt | **documentType** : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY **document** : Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. **referenceId** : ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. **indexedAt** : Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/searchindexs** ```js axios({ method: 'POST', url: '/v1/searchindexs', data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Searchindex` API Get a single denormalized index record (by id, or documentType+referenceId). Used by BFF for full entity search. Always excludes inactive records unless forced (admin only path). **Rest Route** The `getSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `getSearchIndex` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | **searchIndexId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchindexs/:searchIndexId** ```js axios({ method: 'GET', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## AdminModeration Service Administrative backend service for moderation and manual override actions. Responsible for logging all admin interventions (user/product/feedback/media/category/order/notification/searchindex moderation), triggering corrections via interservice calls, and providing comprehensive audit trails for compliance. ### AdminModeration Service Data Objects **ModerationAction** Audit record for all admin moderation/override actions affecting core business entities. Links to admin, timestamp, entity type/ID, action performed, and reason. ### AdminModeration Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/adminmoderation-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/adminmoderation-api` * **Production:** `https://ebaycclone.mindbricks.co/adminmoderation-api` ### `Get Moderationaction` API Get a single moderation action log by ID. Used to review admin audit trails; accessible only to platform admins. **Rest Route** The `getModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `getModerationAction` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | **moderationActionId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/moderationactions/:moderationActionId** ```js axios({ method: 'GET', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Moderationaction` API Soft-deletes a moderation action log record (dangerous; allowed only to superadmins or strict manual correction), primarily for audit correction or internal error cleanup. Usually, moderation logs are immutable. **Rest Route** The `deleteModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `deleteModerationAction` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | **moderationActionId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/moderationactions/:moderationActionId** ```js axios({ method: 'DELETE', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Moderationaction` API Logs an admin moderation or override action in the system for audit and traceability. Requires admin login, takes context from session, and creates an audit entry for any admin operation over any entity type. **Rest Route** The `createModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions` **Rest Request Parameters** The `createModerationAction` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | entityId | ID | true | request.body?.entityId | | entityType | Enum | true | request.body?.entityType | | reason | String | true | request.body?.reason | | actionType | Enum | true | request.body?.actionType | **entityId** : ID of target entity affected by moderation (user/product/etc). **entityType** : Type of entity affected (USER, PRODUCT, FEEDBACK, MEDIA, CATEGORY, NOTIFICATION, ORDER, SEARCHINDEX). **reason** : Explanation or justification for the moderation action performed. **actionType** : Type of moderation action (e.g., SOFT_DELETE, RESTORE, UPDATE_ROLE, MANUAL_CORRECTION, MEDIA_FLAG, INDEX_REBUILD, PAYMENT_FIX, FEEDBACK_OVERRIDE, ADMIN_NOTE). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/moderationactions** ```js axios({ method: 'POST', url: '/v1/moderationactions', data: { entityId:"ID", entityType:"Enum", reason:"String", actionType:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Moderationactions` API List moderation actions for admin dashboard/audit search. Supports filtering by admin, entityType, entityId, actionType, and date. Always sorted by most recent action. **Rest Route** The `listModerationActions` API REST controller can be triggered via the following route: `/v1/moderationactions` **Rest Request Parameters** The `listModerationActions` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/moderationactions** ```js axios({ method: 'GET', url: '/v1/moderationactions', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationActions", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "moderationActions": [ { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Moderationaction` API Allows update of explanation/note on a moderation action for correction (typically by admin or superadmin only). No entity/type/admin may be changed after creation; only 'reason' is editable for audit consistency. **Rest Route** The `updateModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `updateModerationAction` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | | reason | String | false | request.body?.reason | **moderationActionId** : This id paremeter is used to select the required data object that will be updated **reason** : Explanation or justification for the moderation action performed. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/moderationactions/:moderationActionId** ```js axios({ method: 'PATCH', url: `/v1/moderationactions/${moderationActionId}`, data: { reason:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## WatchlistCart Service Handles user watchlists (with custom folders) and shopping cart preparation for checkout, strictly enforcing only fixed-price products in carts, supporting item moves/bulk operations, and robust default/folder logic.. ### WatchlistCart Service Data Objects **WatchlistItem** Item in a user’s watchlist, optionally in a named folder; references product and user. **CartItem** Single product pending checkout in a user’s cart. Only fixed-price products permitted; quantity supported for multi-unit purchases (if allowed). **WatchlistList** A named folder/list in a user’s watchlist. Default list exists for all users. Custom lists may be created and deleted. ### WatchlistCart Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/watchlistcart-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/watchlistcart-api` * **Production:** `https://ebaycclone.mindbricks.co/watchlistcart-api` ### `List Watchlistlist` API List all lists in user’s watchlists. Supports listing by listId for folders. **Rest Route** The `listWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists` **Rest Request Parameters** The `listWatchlistList` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/watchlistlists** ```js axios({ method: 'GET', url: '/v1/watchlistlists', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Cartitems` API List all cart items for a user (pending checkout). **Rest Route** The `listCartItems` API REST controller can be triggered via the following route: `/v1/cartitems` **Rest Request Parameters** The `listCartItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/cartitems** ```js axios({ method: 'GET', url: '/v1/cartitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "price": "Double", "title": "String", "type": "Enum", "type_idx": "Integer", "mediaAssetIds": "ID" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Cartitem` API Remove an item from the user’s cart. **Rest Route** The `deleteCartItem` API REST controller can be triggered via the following route: `/v1/cartitems/:cartItemId` **Rest Request Parameters** The `deleteCartItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | **cartItemId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/cartitems/:cartItemId** ```js axios({ method: 'DELETE', url: `/v1/cartitems/${cartItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Watchlistitem` API Add product to user’s watchlist (default or target list/folder). One (user, product, list) per item enforced. Block duplicates. **Rest Route** The `createWatchlistItem` API REST controller can be triggered via the following route: `/v1/watchlistitems` **Rest Request Parameters** The `createWatchlistItem` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | productId | ID | true | request.body?.productId | | listId | ID | false | request.body?.listId | **addedAt** : Timestamp watchlist item created. **productId** : Referenced product in the watchlist. **listId** : Owning watchlistList; null if in default watchlist. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/watchlistitems** ```js axios({ method: 'POST', url: '/v1/watchlistitems', data: { addedAt:"Date", productId:"ID", listId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Watchlistitems` API List all products in user’s watchlists. Supports listing by listId for folders. **Rest Route** The `listWatchlistItems` API REST controller can be triggered via the following route: `/v1/watchlistitems` **Rest Request Parameters** The `listWatchlistItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/watchlistitems** ```js axios({ method: 'GET', url: '/v1/watchlistitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Cartitemquantity` API Change the quantity for a cart item. User must own the item. **Rest Route** The `updateCartItemQuantity` API REST controller can be triggered via the following route: `/v1/cartitemquantity/:cartItemId` **Rest Request Parameters** The `updateCartItemQuantity` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | | quantity | Integer | false | request.body?.quantity | **cartItemId** : This id paremeter is used to select the required data object that will be updated **quantity** : How many units (if product allows). **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/cartitemquantity/:cartItemId** ```js axios({ method: 'PATCH', url: `/v1/cartitemquantity/${cartItemId}`, data: { quantity:"Integer", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Watchlistlist` API Create a new custom watchlist folder. Name must be unique per user; ‘Default’ is reserved for system. **Rest Route** The `createWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists` **Rest Request Parameters** The `createWatchlistList` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | name | String | true | request.body?.name | **name** : Custom folder or list name. 'Default' is reserved (non-deletable for each user). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/watchlistlists** ```js axios({ method: 'POST', url: '/v1/watchlistlists', data: { name:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Watchlistlist` API Delete a custom watchlist (folder). Items are reassigned to user’s default list. Cannot delete default list. **Rest Route** The `deleteWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists/:watchlistListId` **Rest Request Parameters** The `deleteWatchlistList` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistListId | ID | true | request.params?.watchlistListId | **watchlistListId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistlists/:watchlistListId** ```js axios({ method: 'DELETE', url: `/v1/watchlistlists/${watchlistListId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Watchlistitem` API Remove a product from a user’s watchlist. **Rest Route** The `deleteWatchlistItem` API REST controller can be triggered via the following route: `/v1/watchlistitems/:watchlistItemId` **Rest Request Parameters** The `deleteWatchlistItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistItemId | ID | true | request.params?.watchlistItemId | **watchlistItemId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistitems/:watchlistItemId** ```js axios({ method: 'DELETE', url: `/v1/watchlistitems/${watchlistItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Cartitem` API Add an item to the user’s cart. Only fixed-price products allowed. Duplicates not permitted. **Rest Route** The `createCartItem` API REST controller can be triggered via the following route: `/v1/cartitems` **Rest Request Parameters** The `createCartItem` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | **addedAt** : Timestamp added to cart. **quantity** : How many units (if product allows). **productId** : Product being checked out. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/cartitems** ```js axios({ method: 'POST', url: '/v1/cartitems', data: { addedAt:"Date", quantity:"Integer", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Do Userwatchlist` API userwatchlist **Rest Route** The `userwatchlist` API REST controller can be triggered via the following route: `/v1/userwatchlist` **Rest Request Parameters** The `userwatchlist` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userwatchlist** ```js axios({ method: 'GET', url: '/v1/userwatchlist', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Usercartitems` API list all cart items adde by user **Rest Route** The `listUserCartItems` API REST controller can be triggered via the following route: `/v1/usercartitems` **Rest Request Parameters** The `listUserCartItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/usercartitems** ```js axios({ method: 'GET', url: '/v1/usercartitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "shipping": "Double" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Do Userwatchlistlists` API list all watch lists created by user **Rest Route** The `userwatchlistlists` API REST controller can be triggered via the following route: `/v1/userwatchlistlists` **Rest Request Parameters** The `userwatchlistlists` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userwatchlistlists** ```js axios({ method: 'GET', url: '/v1/userwatchlistlists', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ## ProductListing Service Handles product listings (both auction and fixed-price), image/media storage with validations, enforces immutable type, soft-delete, and public product discovery. ### ProductListing Service Data Objects **ProductListingMedia** Stores and manages images/media associated with products, including secure URL, MIME type, and size validation. Each asset can be used by multiple products. **ProductListingProduct** Represents a single product listing (fixed-price or auction) in the marketplace, with seller, category, type, price information, shipping details, media references, and dynamic auction fields. ### ProductListing Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/productlisting-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/productlisting-api` * **Production:** `https://ebaycclone.mindbricks.co/productlisting-api` ### `List Productlistingmedia` API List all media assets (admin or for media management/bulk preview). **Rest Route** The `listProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias` **Rest Request Parameters** The `listProductListingMedia` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias** ```js axios({ method: 'GET', url: '/v1/productlistingmedias', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedias", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingMedias": [ { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Productlistingproduct` API Get a single product listing. Checks isActive and public status. Includes media, category, subcategory, and seller info via joins. **Rest Route** The `getProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `getProductListingProduct` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | **productListingProductId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'GET', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Productlistingownproducts` API listing the loggedin user's products **Rest Route** The `listProductListingOwnProducts` API REST controller can be triggered via the following route: `/v1/productlistingownproducts` **Rest Request Parameters** The `listProductListingOwnProducts` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingownproducts** ```js axios({ method: 'GET', url: '/v1/productlistingownproducts', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Productlistingmedia` API Get a single media asset by ID (for admin or to display in product UI). **Rest Route** The `getProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` **Rest Request Parameters** The `getProductListingMedia` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | **productListingMediaId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'GET', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Productlistingproducts` API List public product listings. Only isActive=true records are returned. Includes category, subcategory, seller, media joins. Supports filtering. **Rest Route** The `listProductListingProducts` API REST controller can be triggered via the following route: `/v1/productlistingproducts` **Rest Request Parameters** The `listProductListingProducts` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts** ```js axios({ method: 'GET', url: '/v1/productlistingproducts', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Productlistingproduct` API Soft-delete a product listing. Only owner or admin can delete. **Rest Route** The `deleteProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `deleteProductListingProduct` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | **productListingProductId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'DELETE', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Productlistingproduct` API Update a product listing. Product type cannot be changed (immutable). **Rest Route** The `updateProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `updateProductListingProduct` api has got 21 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | | currency | String | false | request.body?.currency | | description | Text | false | request.body?.description | | condition | Enum | false | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | false | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | false | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | false | request.body?.shippingMethod | | shipping | Double | false | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | false | request.body?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | **productListingProductId** : This id paremeter is used to select the required data object that will be updated **currency** : ISO currency code (e.g. USD, EUR) **description** : Product detailed description **condition** : Condition of product: BRAND_NEW, NEW, or USED **startBid** : The opening bid value (for auction type products) **endPrice** : Optional immediate sale/upper end price for auction (if AUCTION type) **price** : Product price (required if fixed price type) **title** : Product title **startPrice** : Minimum starting price for auction (required if AUCTION type) **endBid** : The upper (max) bid value for auction products (if any) **estimatedDelivery** : Estimated delivery date for this product **shippingCurrency** : Currency code for shipping cost **mediaAssetIds** : References to associated product/media assets **shippingMethod** : Shipping option for product: STANDARD, EXPRESS, or FREE **shipping** : Shipping cost for this product **startBidDate** : Date/time when auction bidding begins **subcategoryId** : Reference to subcategory **categoryId** : Reference to parent category **endBidDate** : Date/time when auction bidding ends **currentBid** : Current highest bid for auction-type product (updated atomically on bid placement) **highestBidderId** : User ID of current highest bidder (auction-only, updated by auction microservice) **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'PATCH', url: `/v1/productlistingproducts/${productListingProductId}`, data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Productlistingproduct` API Create a new product listing (fixed or auction), conditioned on product type. Type is immutable after creation. **Rest Route** The `createProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts` **Rest Request Parameters** The `createProductListingProduct` api has got 21 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | description | Text | true | request.body?.description | | condition | Enum | true | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | true | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | type | Enum | true | request.body?.type | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | true | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | true | request.body?.shippingMethod | | shipping | Double | true | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | true | request.body?.subcategoryId | | categoryId | ID | true | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | **currency** : ISO currency code (e.g. USD, EUR) **description** : Product detailed description **condition** : Condition of product: BRAND_NEW, NEW, or USED **startBid** : The opening bid value (for auction type products) **endPrice** : Optional immediate sale/upper end price for auction (if AUCTION type) **price** : Product price (required if fixed price type) **title** : Product title **startPrice** : Minimum starting price for auction (required if AUCTION type) **type** : Product listing type, either FIXED or AUCTION (immutable after creation) **endBid** : The upper (max) bid value for auction products (if any) **estimatedDelivery** : Estimated delivery date for this product **shippingCurrency** : Currency code for shipping cost **mediaAssetIds** : References to associated product/media assets **shippingMethod** : Shipping option for product: STANDARD, EXPRESS, or FREE **shipping** : Shipping cost for this product **startBidDate** : Date/time when auction bidding begins **subcategoryId** : Reference to subcategory **categoryId** : Reference to parent category **endBidDate** : Date/time when auction bidding ends **currentBid** : Current highest bid for auction-type product (updated atomically on bid placement) **highestBidderId** : User ID of current highest bidder (auction-only, updated by auction microservice) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/productlistingproducts** ```js axios({ method: 'POST', url: '/v1/productlistingproducts', data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", type:"Enum", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Productlistingmedia` API Soft-delete a media asset (typically by admin or media owner for flagged/invalid content). **Rest Route** The `deleteProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` **Rest Request Parameters** The `deleteProductListingMedia` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | **productListingMediaId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'DELETE', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Productlistingmedia` API Create a new media asset record after validation. Used mainly by edge controller after upload. **Rest Route** The `createProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias` **Rest Request Parameters** The `createProductListingMedia` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | mimeType | String | true | request.body?.mimeType | | productId | ID | false | request.body?.productId | | url | String | true | request.body?.url | | size | Integer | true | request.body?.size | **mimeType** : MIME type of the uploaded media (e.g., image/jpeg) **productId** : ID of product associated with this media asset **url** : Secure, validated URL for the media asset (S3 or equivalent) **size** : Media size in bytes (for validation and quota) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/productlistingmedias** ```js axios({ method: 'POST', url: '/v1/productlistingmedias', data: { mimeType:"String", productId:"ID", url:"String", size:"Integer", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## OrderManagement Service Handles all marketplace orders, manual checkout flows for fixed-price/offer/auction settlements, Stripe payment processing and webhook reconciliation, explicit status updates (shipping, delivery, cancellation), and feedback eligibility via orderItems. ### OrderManagement Service Data Objects **OrderManagementOrder** Marketplace order record. Stores buyer, shipping, status, items, Stripe payment data, and manual shipment/delivery events. Only accessible to admins or the buyer/seller of order items. **OrderManagementOrderItem** Order line item representing purchase of a single product from a specific seller as part of an order. Enables feedback, delivery, and per-seller analytics. Immutable after order creation. **Sys_orderManagementOrderPayment** A payment storage object to store the payment life cyle of orders based on orderManagementOrder object. It is autocreated based on the source object's checkout config **Sys_paymentCustomer** A payment storage object to store the customer values of the payment platform **Sys_paymentMethod** A payment storage object to store the payment methods of the platform customers ### OrderManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/ordermanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/ordermanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/ordermanagement-api` ### `List Ordermanagementorders` API List orders, filtered for buyer and/or seller, or by admin. Includes select orderItems. **Rest Route** The `listOrderManagementOrders` API REST controller can be triggered via the following route: `/v1/ordermanagementorders` **Rest Request Parameters** The `listOrderManagementOrders` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ordermanagementorders', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Ordermanagementorderitem` API Get a specific order item (for feedback/business logic). **Rest Route** The `getOrderManagementOrderItem` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems/:orderManagementOrderItemId` **Rest Request Parameters** The `getOrderManagementOrderItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderItemId | ID | true | request.params?.orderManagementOrderItemId | **orderManagementOrderItemId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems/:orderManagementOrderItemId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderitems/${orderManagementOrderItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Ordermanagementorder` API Soft-delete/cancel order by admin or eligible actor prior to shipment. Sets status to CANCELLED and cancels active payment intent if pending. Irreversible and blocks feedback. **Rest Route** The `deleteOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` **Rest Request Parameters** The `deleteOrderManagementOrder` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorder` API Get single order by ID. Only accessible to admin, buyer, or relevant sellers of items within this order. Includes all orderItems. **Rest Route** The `getOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` **Rest Request Parameters** The `getOrderManagementOrder` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | **orderManagementOrderId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Ordermanagementorderstatus` API Update order status (manual shipment, delivery, cancellation/refund). Restricted: only seller of all items can mark as shipped, only buyer can confirm delivery, only admin can set refund/cancelled. Timestamps updated as per business rule. **Rest Route** The `updateOrderManagementOrderStatus` API REST controller can be triggered via the following route: `/v1/ordermanagementorderstatus/:orderManagementOrderId` **Rest Request Parameters** The `updateOrderManagementOrderStatus` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **status** : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderstatus/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderstatus/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Complete Orderstripewebhook` API Webhook endpoint called by Stripe to reconcile payment state and update order status based on paymentIntentId and event data. No authentication required (Stripe IPs only). **Rest Route** The `completeOrderStripeWebhook` API REST controller can be triggered via the following route: `/v1/completeorderstripewebhook/:orderManagementOrderId` **Rest Request Parameters** The `completeOrderStripeWebhook` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **status** : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/completeorderstripewebhook/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/completeorderstripewebhook/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderbyproductid` API get orders by productId **Rest Route** The `getOrderManagementOrderByProductId` API REST controller can be triggered via the following route: `/v1/ordermanagementorderbyproductid/:items` **Rest Request Parameters** The `getOrderManagementOrderByProductId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | items | String | true | request.params?.items | **orderManagementOrderId** : This id paremeter is used to query the required data object. **items** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderbyproductid/:items** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderbyproductid/${items}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Ordermanagementorder` API Creates an order and initiates Stripe payment. Validates that all products in the order are fixed-price, populates orderItems, saves Stripe customer/paymentMethod/paymentIntentId for reconciliation. Only accessible to buyers for own checkouts and only allows fixed-price product checkout (no auction). **Rest Route** The `createOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders` **Rest Request Parameters** The `createOrderManagementOrder` api has got 14 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderNumber | String | true | request.body?.orderNumber | | items | ID | false | request.body?.items | | paymentMethodId | String | true | request.body?.paymentMethodId | | stripeCustomerId | String | true | request.body?.stripeCustomerId | | paymentIntentId | String | false | request.body?.paymentIntentId | | shippingAddress | Object | true | request.body?.shippingAddress | | summary | Object | true | request.body?.summary | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderNumber** : Unique, human-friendly order number (displayed to users); enforced unique. **items** : Array of orderManagementOrderItem ids representing items in this order. **paymentMethodId** : Stripe paymentMethodId used for payment. Not stored if cash or other payment (future). **stripeCustomerId** : Stripe customerId of buyer; enables saved/paymentMethodId flows. **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **shippingAddress** : Shipping address for the order (copy of buyer address at purchase time). **summary** : Object with total, subtotal, currency, shipping, discount breakdown as snapshot of order at time of purchase. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorders** ```js axios({ method: 'POST', url: '/v1/ordermanagementorders', data: { orderNumber:"String", items:"ID", paymentMethodId:"String", stripeCustomerId:"String", paymentIntentId:"String", shippingAddress:"Object", summary:"Object", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderitems` API List order items for a given order or for buyer/seller analytics. Used for feedback management. **Rest Route** The `listOrderManagementOrderItems` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems` **Rest Request Parameters** The `listOrderManagementOrderItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Ownordermanagementorders` API list the loggedin user orders **Rest Route** The `listOwnOrderManagementOrders` API REST controller can be triggered via the following route: `/v1/ownordermanagementorders` **Rest Request Parameters** The `listOwnOrderManagementOrders` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ownordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ownordermanagementorders', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Lis Ordermanagementownorderitem` API list the loggedin user's order items **Rest Route** The `lisOrderManagementOwnOrderItem` API REST controller can be triggered via the following route: `/v1/lisordermanagementownorderitem` **Rest Request Parameters** The `lisOrderManagementOwnOrderItem` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/lisordermanagementownorderitem** ```js axios({ method: 'GET', url: '/v1/lisordermanagementownorderitem', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Ordermanagementorderitem` API create order item **Rest Route** The `createOrderManagementOrderItem` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems` **Rest Request Parameters** The `createOrderManagementOrderItem` api has got 8 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | shipping | Double | true | request.body?.shipping | | orderId | ID | true | request.body?.orderId | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | | price | Double | true | request.body?.price | | sellerId | ID | true | request.body?.sellerId | | title | String | true | request.body?.title | | currency | String | true | request.body?.currency | **shipping** : Shipping cost for this product (may be 0 for free shipping). **orderId** : Parent order this item belongs to; enables join and lifecycle tracking. **quantity** : Number of units purchased for this product. **productId** : ID of product purchased in this line item. **price** : Unit price for this product at purchase time. **sellerId** : UserId of seller (owner of product at purchase time). **title** : Product title at purchase time (copied for convenience/audit). **currency** : Currency code for price/shipping (ISO 4217). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderitems** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderitems', data: { shipping:"Double", orderId:"ID", quantity:"Integer", productId:"ID", price:"Double", sellerId:"ID", title:"String", currency:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpayment2` API This route is used to get the payment information by ID. **Rest Route** The `getOrderManagementOrderPayment2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `getOrderManagementOrderPayment2` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderpayments2` API This route is used to list all payments. **Rest Route** The `listOrderManagementOrderPayments2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayments2` **Rest Request Parameters** The `listOrderManagementOrderPayments2` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Ordermanagementorderpayment` API This route is used to create a new payment. **Rest Route** The `createOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment` **Rest Request Parameters** The `createOrderManagementOrderPayment` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderId | ID | true | request.body?.orderId | | paymentId | String | true | request.body?.paymentId | | paymentStatus | String | true | request.body?.paymentStatus | | statusLiteral | String | true | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | **orderId** : an ID value to represent the orderId which is the ID parameter of the source orderManagementOrder object **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderpayment', data: { orderId:"ID", paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Ordermanagementorderpayment` API This route is used to update an existing payment. **Rest Route** The `updateOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `updateOrderManagementOrderPayment` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | false | request.body?.paymentId | | paymentStatus | String | false | request.body?.paymentStatus | | statusLiteral | String | false | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | **sys_orderManagementOrderPaymentId** : This id paremeter is used to select the required data object that will be updated **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Ordermanagementorderpayment` API This route is used to delete a payment. **Rest Route** The `deleteOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `deleteOrderManagementOrderPayment` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderpayments2` API This route is used to list all payments. **Rest Route** The `listOrderManagementOrderPayments2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayments2` **Rest Request Parameters** The `listOrderManagementOrderPayments2` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Ordermanagementorderpaymentbyorderid` API This route is used to get the payment information by order id. **Rest Route** The `getOrderManagementOrderPaymentByOrderId` API REST controller can be triggered via the following route: `/v1/orderManagementOrderpaymentbyorderid/:orderId` **Rest Request Parameters** The `getOrderManagementOrderPaymentByOrderId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | orderId | String | true | request.params?.orderId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **orderId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbyorderid/:orderId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbyorderid/${orderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpaymentbypaymentid` API This route is used to get the payment information by payment id. **Rest Route** The `getOrderManagementOrderPaymentByPaymentId` API REST controller can be triggered via the following route: `/v1/orderManagementOrderpaymentbypaymentid/:paymentId` **Rest Request Parameters** The `getOrderManagementOrderPaymentByPaymentId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | true | request.params?.paymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **paymentId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbypaymentid/:paymentId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbypaymentid/${paymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpayment2` API This route is used to get the payment information by ID. **Rest Route** The `getOrderManagementOrderPayment2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `getOrderManagementOrderPayment2` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Start Ordermanagementorderpayment` API Start payment for orderManagementOrder **Rest Route** The `startOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/startordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `startOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to start a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/startordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/startordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Refresh Ordermanagementorderpayment` API Refresh payment info for orderManagementOrder from Stripe **Rest Route** The `refreshOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/refreshordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `refreshOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to refresh a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/refreshordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/refreshordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Callback Ordermanagementorderpayment` API Refresh payment values by gateway webhook call for orderManagementOrder **Rest Route** The `callbackOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/callbackordermanagementorderpayment` **Rest Request Parameters** The `callbackOrderManagementOrderPayment` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.body?.orderManagementOrderId | **orderManagementOrderId** : The order id parameter that will be read from webhook callback params **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/callbackordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/callbackordermanagementorderpayment', data: { orderManagementOrderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Get Paymentcustomerbyuserid` API This route is used to get the payment customer information by user id. **Rest Route** The `getPaymentCustomerByUserId` API REST controller can be triggered via the following route: `/v1/paymentcustomers/:userId` **Rest Request Parameters** The `getPaymentCustomerByUserId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_paymentCustomerId | ID | true | request.params?.sys_paymentCustomerId | | userId | String | true | request.params?.userId | **sys_paymentCustomerId** : This id paremeter is used to query the required data object. **userId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomers/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_paymentCustomer": { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Paymentcustomers` API This route is used to list all payment customers. **Rest Route** The `listPaymentCustomers` API REST controller can be triggered via the following route: `/v1/paymentcustomers` **Rest Request Parameters** The `listPaymentCustomers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers** ```js axios({ method: 'GET', url: '/v1/paymentcustomers', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentCustomers": [ { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Paymentcustomermethods` API This route is used to list all payment customer methods. **Rest Route** The `listPaymentCustomerMethods` API REST controller can be triggered via the following route: `/v1/paymentcustomermethods/:userId` **Rest Request Parameters** The `listPaymentCustomerMethods` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | String | true | request.params?.userId | **userId** : This parameter will be used to select the data objects that want to be listed **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomermethods/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomermethods/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentMethods", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentMethods": [ { "id": "ID", "paymentMethodId": "String", "userId": "ID", "customerId": "String", "cardHolderName": "String", "cardHolderZip": "String", "platform": "String", "cardInfo": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ## Feedback Service Handles feedback for order items: one feedback per buyer/orderItem, attached to sellerId for analytical feedback/rating aggregation and reputation tracking. Enables querying feedbacks received/given for sellers and buyers. test ### Feedback Service Data Objects **Feedback** One feedback per (buyer, orderItem). Stores rating (1-5), comment, ties to seller for analytics. Created only after delivery confirmed on order item. ### Feedback Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/feedback-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/feedback-api` * **Production:** `https://ebaycclone.mindbricks.co/feedback-api` ### `List Feedbacks` API List feedback with filtering by buyerId (given), sellerId (received), productId, or orderItemId. Used for showing seller profile, buyer profile, or order analytics. **Rest Route** The `listFeedbacks` API REST controller can be triggered via the following route: `/v1/feedbacks` **Rest Request Parameters** The `listFeedbacks` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/feedbacks** ```js axios({ method: 'GET', url: '/v1/feedbacks', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedbacks", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "feedbacks": [ { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Feedback` API Get a single feedback by id. Accessible to public (for seller profile, product, or audit views). **Rest Route** The `getFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `getFeedback` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | **feedbackId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/feedbacks/:feedbackId** ```js axios({ method: 'GET', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Feedback` API Update feedback (comment/rating) for existing feedback record (buyer only). Admin can update as override. **Rest Route** The `updateFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `updateFeedback` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | | rating | Integer | false | request.body?.rating | | comment | String | false | request.body?.comment | **feedbackId** : This id paremeter is used to select the required data object that will be updated **rating** : Rating (1-5 stars) submitted by buyer. Required. **comment** : Optional textual feedback comment, max ~500 chars. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/feedbacks/:feedbackId** ```js axios({ method: 'PATCH', url: `/v1/feedbacks/${feedbackId}`, data: { rating:"Integer", comment:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Feedback` API Delete (soft-delete) feedback (by buyer or admin). Only feedback owner or admin. **Rest Route** The `deleteFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `deleteFeedback` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | **feedbackId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/feedbacks/:feedbackId** ```js axios({ method: 'DELETE', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Feedback` API Buyer creates feedback for a delivered order item. Only allowed once per (buyer, orderItemId). Allowed only once order item is delivered. **Rest Route** The `createFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks` **Rest Request Parameters** The `createFeedback` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | rating | Integer | true | request.body?.rating | | orderId | ID | true | request.body?.orderId | | orderItemId | ID | true | request.body?.orderItemId | | sellerId | ID | true | request.body?.sellerId | | comment | String | false | request.body?.comment | | productId | ID | true | request.body?.productId | **rating** : Rating (1-5 stars) submitted by buyer. Required. **orderId** : Order containing this purchased item. Used for aggregation and validation. **orderItemId** : Purchased item (line item) in order. Feedback is per (buyer, orderItem). **sellerId** : Seller of product for analytics/aggregation. Not author; used for querying feedback about sellers. **comment** : Optional textual feedback comment, max ~500 chars. **productId** : The product listing being reviewed (snapshot at order time). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/feedbacks** ```js axios({ method: 'POST', url: '/v1/feedbacks', data: { rating:"Integer", orderId:"ID", orderItemId:"ID", sellerId:"ID", comment:"String", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # REST API GUIDE ## ebaycclone-auth-service Authentication service for the project ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to: Email: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. ## Documentation Scope Welcome to the official documentation for the Auth Service's REST API. This document is designed to provide a comprehensive guide to interfacing with our Auth Service exclusively through RESTful API endpoints. **Intended Audience** This documentation is intended for developers and integrators who are looking to interact with the Auth Service via HTTP requests for purposes such as creating, updating, deleting and querying Auth objects. **Overview** Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases. Beyond REST It's important to note that the Auth Service also supports alternative methods of interaction, such as gRPC and messaging via a Message Broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation. ## Authentication And Authorization To ensure secure access to the Auth service's protected endpoints, a project-wide access token is required. This token serves as the primary method for authenticating requests to our service. However, it's important to note that access control varies across different routes: **Protected API**: Certain API (routes) require specific authorization levels. Access to these routes is contingent upon the possession of a valid access token that meets the route-specific authorization criteria. Unauthorized requests to these routes will be rejected. **Public API **: The service also includes public API (routes) that are accessible without authentication. These public endpoints are designed for open access and do not require an access token. ### Token Locations When including your access token in a request, ensure it is placed in one of the following specified locations. The service will sequentially search these locations for the token, utilizing the first one it encounters. | Location | Token Name / Param Name | | ---------------------- | ---------------------------- | | Query | access_token | | Authorization Header | Bearer | | Header | ebaycclone-access-token| | Cookie | ebaycclone-access-token| Please ensure the token is correctly placed in one of these locations, using the appropriate label as indicated. The service prioritizes these locations in the order listed, processing the first token it successfully identifies. ## Api Definitions This section outlines the API endpoints available within the Auth service. Each endpoint can receive parameters through various methods, meticulously described in the following definitions. It's important to understand the flexibility in how parameters can be included in requests to effectively interact with the Auth service. This service is configured to listen for HTTP requests on port `3011`, serving both the main API interface and default administrative endpoints. The following routes are available by default: * **API Test Interface (API Face):** `/` * **Swagger Documentation:** `/swagger` * **Postman Collection Download:** `/getPostmanCollection` * **Health Checks:** `/health` and `/admin/health` * **Current Session Info:** `/currentuser` * **Favicon:** `/favicon.ico` This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` **Parameter Inclusion Methods:** Parameters can be incorporated into API requests in several ways, each with its designated location. Understanding these methods is crucial for correctly constructing your requests: **Query Parameters:** Included directly in the URL's query string. **Path Parameters:** Embedded within the URL's path. **Body Parameters:** Sent within the JSON body of the request. **Session Parameters:** Automatically read from the session object. This method is used for parameters that are intrinsic to the user's session, such as userId. When using an API that involves session parameters, you can omit these from your request. The service will automatically bind them to the API layer, provided that a session is associated with your request. **Note on Session Parameters:** Session parameters represent a unique method of parameter inclusion, relying on the context of the user's session. A common example of a session parameter is userId, which the service automatically associates with your request when a session exists. This feature ensures seamless integration of user-specific data without manual input for each request. By adhering to the specified parameter inclusion methods, you can effectively utilize the Auth service's API endpoints. For detailed information on each endpoint, including required parameters and their accepted locations, refer to the individual API definitions below. ### Common Parameters The `Auth` service's business API support several common parameters designed to modify and enhance the behavior of API requests. These parameters are not individually listed in the API route definitions to avoid repetition. Instead, refer to this section to understand how to leverage these common behaviors across different routes. Note that all common parameters should be included in the query part of the URL. ### Supported Common Parameters: - **getJoins (BOOLEAN)**: Controls whether to retrieve associated objects along with the main object. By default, `getJoins` is assumed to be `true`. Set it to `false` if you prefer to receive only the main fields of an object, excluding its associations. - **excludeCQRS (BOOLEAN)**: Applicable only when `getJoins` is `true`. By default, `excludeCQRS` is set to `false`. Enabling this parameter (`true`) omits non-local associations, which are typically more resource-intensive as they require querying external services like ElasticSearch for additional information. Use this to optimize response times and resource usage. - **requestId (String)**: Identifies a request to enable tracking through the service's log chain. A random hex string of 32 characters is assigned by default. If you wish to use a custom `requestId`, simply include it in your query parameters. - **caching (BOOLEAN)**: Determines the use of caching for query API. By default, caching is enabled (`true`). To ensure the freshest data directly from the database, set this parameter to `false`, bypassing the cache. - **cacheTTL (Integer)**: Specifies the Time-To-Live (TTL) for query caching, in seconds. This is particularly useful for adjusting the default caching duration (5 minutes) for `get list` queries. Setting a custom `cacheTTL` allows you to fine-tune the cache lifespan to meet your needs. - **pageNumber (Integer)**: For paginated `get list` API's, this parameter selects which page of results to retrieve. The default is `1`, indicating the first page. To disable pagination and retrieve all results, set `pageNumber` to `0`. - **pageRowCount (Integer)**: In conjunction with paginated API's, this parameter defines the number of records per page. The default value is `25`. Adjusting `pageRowCount` allows you to control the volume of data returned in a single request. By utilizing these common parameters, you can tailor the behavior of API requests to suit your specific requirements, ensuring optimal performance and usability of the `Auth` service. ### Error Response If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity: - **400 Bad Request**: The request was improperly formatted or contained invalid parameters, preventing the server from processing it. - **401 Unauthorized**: The request lacked valid authentication credentials or the credentials provided do not grant access to the requested resource. - **404 Not Found**: The requested resource was not found on the server. - **500 Internal Server Error**: The server encountered an unexpected condition that prevented it from fulfilling the request. Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ### Object Structure of a Successfull Response When the `Auth` service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client. **Key Characteristics of the Response Envelope:** - **Data Presentation**: Depending on the nature of the request, the service returns either a single data object or an array of objects encapsulated within the JSON envelope. - **Creation and Update API**: These API routes return the unmodified (pure) form of the data object(s), without any associations to other data objects. - **Delete API**: Even though the data is removed from the database, the last known state of the data object(s) is returned in its pure form. - **Get Requests**: A single data object is returned in JSON format. - **Get List Requests**: An array of data objects is provided, reflecting a collection of resources. - **Data Structure and Joins**: The complexity of the data structure in the response can vary based on the API's architectural design and the join options specified in the request. The architecture might inherently limit join operations, or they might be dynamically controlled through query parameters. - **Pure Data Forms**: In some cases, the response mirrors the exact structure found in the primary data table, without extensions. - **Extended Data Forms**: Alternatively, responses might include data extended through joins with tables within the same service or aggregated from external sources, such as ElasticSearch indices related to other services. - **Join Varieties**: The extensions might involve one-to-one joins, resulting in single object associations, or one-to-many joins, leading to an array of objects. In certain instances, the data might even feature nested inclusions from other data objects. **Design Considerations**: The structure of a API's response data is meticulously crafted during the service's architectural planning. This design ensures that responses adequately reflect the intended data relationships and service logic, providing clients with rich and meaningful information. **Brief Data**: Certain API's return a condensed version of the object data, intentionally selecting only specific fields deemed useful for that request. In such instances, the API documentation will detail the properties included in the response, guiding developers on what to expect. ### API Response Structure The API utilizes a standardized JSON envelope to encapsulate responses. This envelope is designed to consistently deliver both the requested data and essential metadata, ensuring that clients can efficiently interpret and utilize the response. **HTTP Status Codes:** - **200 OK**: This status code is returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request has been processed successfully. - **201 Created**: This status code is specific to CREATE operations, signifying that the requested resource has been successfully created. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling the successful execution of the request. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3 "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` - **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation performed. **Handling Errors:** For details on handling error scenarios and understanding the structure of error responses, please refer to the "Error Response" section provided earlier in this documentation. It outlines how error conditions are communicated, including the use of HTTP status codes and standardized JSON structures for error messages. ## Resources Auth service provides the following resources which are stored in its own database as a data object. Note that a resource for an api access is a data object for the service. ### User resource *Resource Definition* : A data object that stores the user information and handles login settings. *User Resource Properties* | Name | Type | Required | Default | Definition | | ---- | ---- | -------- | ------- | ---------- | | **email** | String | | | * A string value to represent the user's email.* | | **password** | String | | | * A string value to represent the user's password. It will be stored as hashed.* | | **fullname** | String | | | *A string value to represent the fullname of the user* | | **avatar** | String | | | *The avatar url of the user. A random avatar will be generated if not provided* | | **roleId** | String | | | *A string value to represent the roleId of the user.* | | **emailVerified** | Boolean | | | *A boolean value to represent the email verification status of the user.* | | **phone** | String | | | *user's phone number* | | **address** | Object | | | *user's adress* | ## Business Api ### Get User API *API Definition* : This api is used by admin roles or the users themselves to get the user profile information. *API Crud Type* : get *Default access route* : *GET* `/v1/users/:userId` #### Parameters The getUser api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | To access the api you can use the **REST** controller with the path **GET /v1/users/:userId** ```js axios({ method: 'GET', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`user`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"user","method":"GET","action":"get","appVersion":"Version","rowCount":1,"user":{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Get User](businessApi/getUser). ### Update User API *API Definition* : This route is used by admins to update user profiles. *API Crud Type* : update *Default access route* : *PATCH* `/v1/users/:userId` #### Parameters The updateUser api has got 5 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | To access the api you can use the **REST** controller with the path **PATCH /v1/users/:userId** ```js axios({ method: 'PATCH', url: `/v1/users/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`user`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"user","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"user":{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Update User](businessApi/updateUser). ### Update Profile API *API Definition* : This route is used by users to update their profiles. *API Crud Type* : update *Default access route* : *PATCH* `/v1/profile/:userId` #### Parameters The updateProfile api has got 5 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | To access the api you can use the **REST** controller with the path **PATCH /v1/profile/:userId** ```js axios({ method: 'PATCH', url: `/v1/profile/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`user`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"user","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"user":{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Update Profile](businessApi/updateProfile). ### Create User API *API Definition* : This api is used by admin roles to create a new user manually from admin panels *API Crud Type* : create *Default access route* : *POST* `/v1/users` #### Parameters The createUser api has got 6 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | email | String | true | request.body?.email | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | To access the api you can use the **REST** controller with the path **POST /v1/users** ```js axios({ method: 'POST', url: '/v1/users', data: { avatar:"String", email:"String", password:"String", fullname:"String", phone:"String", address:"Object", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`user`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"user","method":"POST","action":"create","appVersion":"Version","rowCount":1,"user":{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Create User](businessApi/createUser). ### Delete User API *API Definition* : This api is used by admins to delete user profiles. *API Crud Type* : delete *Default access route* : *DELETE* `/v1/users/:userId` #### Parameters The deleteUser api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | To access the api you can use the **REST** controller with the path **DELETE /v1/users/:userId** ```js axios({ method: 'DELETE', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`user`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"user","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"user":{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Delete User](businessApi/deleteUser). ### Archive Profile API *API Definition* : This api is used by users to archive their profiles. *API Crud Type* : delete *Default access route* : *DELETE* `/v1/archiveprofile/:userId` #### Parameters The archiveProfile api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | To access the api you can use the **REST** controller with the path **DELETE /v1/archiveprofile/:userId** ```js axios({ method: 'DELETE', url: `/v1/archiveprofile/${userId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`user`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"user","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"user":{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Archive Profile](businessApi/archiveProfile). ### List Users API *API Definition* : The list of users is filtered by the tenantId. *API Crud Type* : list *Default access route* : *GET* `/v1/users` The listUsers api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/users** ```js axios({ method: 'GET', url: '/v1/users', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`users`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"users","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","users":[{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For List Users](businessApi/listUsers). ### Search Users API *API Definition* : The list of users is filtered by the tenantId. *API Crud Type* : list *Default access route* : *GET* `/v1/searchusers` #### Parameters The searchUsers api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | keyword | String | true | request.query?.keyword | To access the api you can use the **REST** controller with the path **GET /v1/searchusers** ```js axios({ method: 'GET', url: '/v1/searchusers', data: { }, params: { keyword:'"String"', } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`users`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"users","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","users":[{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Search Users](businessApi/searchUsers). ### Update Userrole API *API Definition* : This route is used by admin roles to update the user role.The default role is user when a user is registered. A user's role can be updated by superAdmin or admin *API Crud Type* : update *Default access route* : *PATCH* `/v1/userrole/:userId` #### Parameters The updateUserRole api has got 2 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | roleId | String | true | request.body?.roleId | To access the api you can use the **REST** controller with the path **PATCH /v1/userrole/:userId** ```js axios({ method: 'PATCH', url: `/v1/userrole/${userId}`, data: { roleId:"String", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`user`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"user","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"user":{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Update Userrole](businessApi/updateUserRole). ### Update Userpassword API *API Definition* : This route is used to update the password of users in the profile page by users themselves *API Crud Type* : update *Default access route* : *PATCH* `/v1/userpassword/:userId` #### Parameters The updateUserPassword api has got 3 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | oldPassword | String | true | request.body?.oldPassword | | newPassword | String | true | request.body?.newPassword | To access the api you can use the **REST** controller with the path **PATCH /v1/userpassword/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpassword/${userId}`, data: { oldPassword:"String", newPassword:"String", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`user`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"user","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"user":{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Update Userpassword](businessApi/updateUserPassword). ### Update Userpasswordbyadmin API *API Definition* : This route is used to change any user password by admins only. Superadmin can chnage all passwords, admins can change only nonadmin passwords *API Crud Type* : update *Default access route* : *PATCH* `/v1/userpasswordbyadmin/:userId` #### Parameters The updateUserPasswordByAdmin api has got 2 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | password | String | true | request.body?.password | To access the api you can use the **REST** controller with the path **PATCH /v1/userpasswordbyadmin/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpasswordbyadmin/${userId}`, data: { password:"String", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`user`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"user","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"user":{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Update Userpasswordbyadmin](businessApi/updateUserPasswordByAdmin). ### Get Briefuser API *API Definition* : This route is used by public to get simple user profile information. *API Crud Type* : get *Default access route* : *GET* `/v1/briefuser/:userId` #### Parameters The getBriefUser api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | To access the api you can use the **REST** controller with the path **GET /v1/briefuser/:userId** ```js axios({ method: 'GET', url: `/v1/briefuser/${userId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`user`** object in the respones. However, some properties may be omitted based on the object's internal logic. This route's response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"user","method":"GET","action":"get","appVersion":"Version","rowCount":1,"user":{"fullname":"String","avatar":"String","isActive":true}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Get Briefuser](businessApi/getBriefUser). ### Register User API *API Definition* : This api is used by public users to register themselves *API Crud Type* : create *Default access route* : *POST* `/v1/registeruser` #### Parameters The registerUser api has got 6 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`user`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"user","method":"POST","action":"create","appVersion":"Version","rowCount":1,"user":{"id":"ID","email":"String","password":"String","fullname":"String","avatar":"String","roleId":"String","emailVerified":"Boolean","phone":"String","address":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Register User](businessApi/registerUser). ### Authentication Specific Routes ### Route: login *Route Definition*: Handles the login process by verifying user credentials and generating an authenticated session. *Route Type*: login *Access Routes*: - `GET /login`: Returns the HTML login page (not a frontend module, typically used in browser-based contexts for test purpose to make sending POST /login easier). - `POST /login`: Accepts credentials, verifies the user, creates a session, and returns a JWT access token. #### Parameters | Parameter | Type | Required | Population | |-------------|----------|----------|-----------------------------| | username | String | Yes | `request.body.username` | | password | String | Yes | `request.body.password` | #### Notes - This route accepts login credentials and creates an authenticated session if credentials are valid. - On success, the response will: - Set a cookie named `projectname-access-token[-tenantCodename]` with the JWT token. - Include the token in the response headers under the same name. - Return the full `session` object in the JSON body. - Note that `username` parameter should have the email of the user as value. You can also send an `email` parameter instead of `username` parameter. If both sent only `username` parameter will be read. ```js // Sample POST /login call axios.post("/login", { username: "user@example.com", password: "securePassword" }); ``` **Success Response** Returns the authenticated session object with a status code `200 OK`. A secure HTTP-only cookie and an access token header are included in the response. ```json { "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", ... } ``` **Error Responses** * **401 Unauthorized:** Invalid username or password. * **403 Forbidden:** Login attempt rejected due to pending email/mobile verification or 2FA requirements. * **400 Bad Request:** Missing credentials in the request. ### Route: logout *Route Definition*: Logs the user out by terminating the current session and clearing the access token. *Route Type*: logout *Access Route*: `POST /logout` #### Parameters This route does not require any parameters in the body or query. #### Behavior - Invalidates the current session on the server (if stored). - Clears the access token cookie (`projectname-access-token[-tenantCodename]`) from the client. - Responds with a 200 status and a simple confirmation object. ```js // Sample POST /logout call axios.post("/logout", {}, { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Notes** * This route is public, meaning it can be called without a session or token. * If the session is active, the server will clear associated session state and cookies. * The logout behavior may vary slightly depending on whether you're using cookie-based or header-based token management. **Error Responses** 00200 OK:** Always returned, regardless of whether a session existed. Logout is treated as idempotent. ### Route: publickey *Route Definition*: Returns the public RSA key used to verify JWT access tokens issued by the auth service. *Route Type*: publicKeyFetch *Access Route*: `GET /publickey` #### Parameters | Parameter | Type | Required | Population | |-----------|--------|----------|--------------------| | keyId | String | No | `request.query.keyId` | - `keyId` is optional. If provided, retrieves the public key corresponding to the specific `keyId`. If omitted, retrieves the current active public key (`global.currentKeyId`). #### Behavior - Reads the requested RSA public key file from the server filesystem. - If the key exists, returns it along with its `keyId`. - If the key does not exist, returns a 404 error. ```js // Sample GET /publickey call axios.get("/publickey", { params: { keyId: "currentKeyIdOptional" } }); ``` **Success Response** Returns the active public key and its associated keyId. ```json { "keyId": "a1b2c3d4", "keyData": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhki...\n-----END PUBLIC KEY-----" } ```` **Error Responses** **404 Not Found:** Public key file could not be found on the server. ### Token Key Management Mindbricks uses RSA key pairs to sign and verify JWT access tokens securely. While the auth service signs each token with a private key, other services within the system — or external clients — need the corresponding **public key** to verify the authenticity and integrity of received tokens. The `/publickey` endpoint allows services and clients to dynamically fetch the currently active public key, ensuring that token verification remains secure even if key rotation is performed. > **Note**: > The `/publickey` route is not intended for direct frontend (browser) consumption. > Instead, it is primarily used by trusted backend services, APIs, or middleware systems that need to independently verify access tokens issued by the auth service — without making verification-dependent API calls to the auth service itself. Accessing the public key is crucial for validating user sessions efficiently and maintaining a decentralized trust model across your platform. ### Route: relogin *Route Definition*: Performs a silent login by verifying the current access token, refreshing the session, and returning a new access token along with updated user information. *Route Type*: sessionRefresh *Access Route*: `GET /relogin` #### Parameters This route does **not** require any request parameters. #### Behavior - Validates the access token associated with the request. - If the token is valid: - Re-authenticates the user using the session's user ID. - Fetches the most up-to-date user information from the database. - Generates a new session object with a **new session ID** and **new access token**. - If the token is invalid or missing, returns a 401 Unauthorized error. ```js // Example call to refresh session axios.get("/relogin", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** Returns a new session object, refreshed from database data. ```json { "sessionId": "new-session-uuid", "userId": "user-uuid", "email": "user@example.com", "roleId": "admin", "accessToken": "new-jwt-token", ... } ``` **Error Responses** * **401 Unauthorized**: Token is missing, invalid, or session cannot be re-established. ```json { "status": "ERR", "message": "Cannot relogin" } ``` **Notes** - The `/relogin` route is commonly used for **silent login flows**, especially after page reloads or token-based auto-login mechanisms. - It triggers internal logic (`req.userAuthUpdate = true`) to signal that the session should be re-initialized and repopulated. - It is not a simple session lookup — it performs a fresh authentication pass using the session's user context. - The refreshed session ensures any updates to user profile, roles, or permissions are immediately reflected. > **Tip:** > This route is ideal when you want to **rebuild a user's session** in the frontend without requiring them to manually log in again. ## Verification Services — Email Verification Email verification is a two-step flow that ensures a user's email address is verified and trusted by the system. All verification services, including email verification, are located under the `/verification-services` base path. ### When is Email Verification Triggered? - After user registration, if `emailVerificationRequiredForLogin` is active. - During a separate user action to verify or update email addresses. - When login fails with `EmailVerificationNeeded` and frontend initiates verification. ### Email Verification Flow 1. **Frontend calls `/verification-services/email-verification/start`** with the user's email address. - Mindbricks checks if the email is already verified. - A secret code is generated and stored in the cache linked to the user. - The code is sent to the user's email or returned in the response (only in development environments for easier testing). 2. **User receives the code and enters it into the frontend application.** 3. **Frontend calls `/verification-services/email-verification/complete`** with the `email` and the received `secretCode`. - Mindbricks checks that the code is valid, not expired, and matches. - If valid, the user’s `emailVerified` flag is set to `true`, and a success response is returned. --- ## API Endpoints ### POST `/verification-services/email-verification/start` **Purpose** Starts the email verification process by generating and sending a secret verification code. #### Request Body | Parameter | Type | Required | Description | |-----------|--------|----------|-----------------------------| | email | String | Yes | The email address to verify | ```json { "email": "user@example.com" } ``` #### Success Response Secret code details (in development environment). Confirms that the verification step has been started. ```json { "userId": "user-uuid", "email": "user@example.com", "secretCode": "123456", "expireTime": 86400, "date": "2024-04-29T10:00:00.000Z" } ``` > ⚠️ In production, the secret code is only sent via email, not exposed in the API response. #### Error Responses - `400 Bad Request`: Email already verified. - `403 Forbidden`: Sending a code too frequently (anti-spam). --- ### POST `/verification-services/email-verification/complete` **Purpose** Completes the email verification by validating the secret code. #### Request Body | Parameter | Type | Required | Description | |-------------|--------|----------|-------------------------------------| | email | String | Yes | The user email being verified | | secretCode | String | Yes | The secret code received via email | ```json { "email": "user@example.com", "secretCode": "123456" } ``` #### Success Response Returns confirmation that the email has been verified. ```json { "userId": "user-uuid", "email": "user@example.com", "isVerified": true } ``` #### Error Responses - `403 Forbidden`: - Secret code mismatch - Secret code expired - No ongoing verification found --- ## Important Behavioral Notes ### Resend Throttling You can only request a new verification code after a cooldown period (`resendTimeWindow`, e.g., 60 seconds). ### Expiration Handling Verification codes expire after a configured period (`expireTimeWindow`, e.g., 1 day). ### One Code Per Session Only one active verification session per user is allowed at a time. > 💡 Mindbricks automatically manages spam prevention, session caching, expiration, and event broadcasting (start/complete events) for all verification steps. ## Verification Services — Mobile Verification Mobile verification is a two-step flow that ensures a user's mobile number is verified and trusted by the system. All verification services, including mobile verification, are located under the `/verification-services` base path. ### When is Mobile Verification Triggered? - After user registration, if `mobileVerificationRequiredForLogin` is active. - During a separate user action to verify or update mobile numbers. - When login fails with `MobileVerificationNeeded` and frontend initiates verification. ### Mobile Verification Flow 1. **Frontend calls `/verification-services/mobile-verification/start`** with the user's email address (used to locate the user). - Mindbricks checks if the mobile number is already verified. - A secret code is generated and stored in the cache linked to the user. - The code is sent to the user's mobile via SMS or returned in the response (only in development environments for easier testing). 2. **User receives the code and enters it into the frontend application.** 3. **Frontend calls `/verification-services/mobile-verification/complete`** with the `email` and the received `secretCode`. - Mindbricks checks that the code is valid, not expired, and matches. - If valid, the user’s `mobileVerified` flag is set to `true`, and a success response is returned. --- ## API Endpoints ### POST `/verification-services/mobile-verification/start` **Purpose**: Starts the mobile verification process by generating and sending a secret verification code. #### Request Body | Parameter | Type | Required | Description | |-----------|--------|----------|-------------------------------------| | email | String | Yes | The email address associated with the mobile number to verify | ```json { "email": "user@example.com" } ``` **Success Response** Secret code details (in development environment). Confirms that the verification step has been started. ```json { "userId": "user-uuid", "mobile": "+15551234567", "secretCode": "123456", "expireTime": 86400, "date": "2024-04-29T10:00:00.000Z" } ``` ⚠️ In production, the secret code is only sent via SMS, not exposed in the API response. **Error Responses** - 400 Bad Request: Mobile already verified. - 403 Forbidden: Sending a code too frequently (anti-spam). --- ### POST `/verification-services/mobile-verification/complete` **Purpose**: Completes the mobile verification by validating the secret code. #### Request Body | Parameter | Type | Required | Description | |-------------|--------|----------|------------------------------------| | email | String | Yes | The user's email being verified | | secretCode | String | Yes | The secret code received via SMS | ```json { "email": "user@example.com", "secretCode": "123456" } ``` **Success Response** Returns confirmation that the mobile number has been verified. ```json { "userId": "user-uuid", "mobile": "+15551234567", "isVerified": true } ``` **Error Responses** 403 Forbidden: - Secret code mismatch - Secret code expired - No ongoing verification found --- ## Important Behavioral Notes **Resend Throttling**: You can only request a new verification code after a cooldown period (`resendTimeWindow`, e.g., 60 seconds). **Expiration Handling**: Verification codes expire after a configured period (`expireTimeWindow`, e.g., 1 day). **One Code Per Session**: Only one active verification session per user is allowed at a time. 💡 Mindbricks automatically manages spam prevention, session caching, expiration, and event broadcasting (start/complete events) for all verification steps. ## Verification Services — Email 2FA Verification Email 2FA (Two-Factor Authentication) provides an additional layer of security by requiring users to confirm their identity using a secret code sent to their email address. This process is used in login flows or sensitive actions that need extra verification. All verification services, including 2FA, are located under the `/verification-services` base path. ### When is Email 2FA Triggered? - During login flows where `sessionNeedsEmail2FA` is `true` - When the backend enforces two-factor authentication for a sensitive operation ### Email 2FA Flow 1. **Frontend calls `/verification-services/email-2factor-verification/start`** with the user's id, session id, client info, and reason. - Mindbricks identifies the user and checks if a cooldown period applies. - A new secret code is generated and stored, linked to the current session ID. - The code is sent via email or returned in development environments. 2. **User receives the code and enters it into the frontend application.** 3. **Frontend calls `/verification-services/email-2factor-verification/complete`** with the `userId`, `sessionId`, and the `secretCode`. - Mindbricks verifies the code, validates the session, and updates the session to remove the 2FA requirement. --- ## API Endpoints ### POST `/verification-services/email-2factor-verification/start` **Purpose**: Starts the email-based 2FA process by generating and sending a verification code. #### Request Body | Parameter | Type | Required | Description | |-----------|--------|----------|-----------------------------------------------| | userId | String | Yes | The user’s ID | | sessionId | String | Yes | The current session ID | | client | String | No | Optional client tag or context | | reason | String | No | Optional reason for triggering 2FA | ```json { "userId": "user-uuid", "sessionId": "session-uuid", "client": "login-page", "reason": "Login requires email 2FA" } ``` #### Success Response ```json { "sessionId": "session-uuid", "userId": "user-uuid", "email": "user@example.com", "secretCode": "123456", "expireTime": 300, "date": "2024-04-29T10:00:00.000Z" } ``` ⚠️ In production, the `secretCode` is only sent via email, not exposed in the API response. #### Error Responses - **403 Forbidden**: Sending a code too frequently (anti-spam) - **401 Unauthorized**: User session not found --- ### POST `/verification-services/email-2factor-verification/complete` **Purpose**: Completes the email 2FA process by validating the secret code and session. #### Request Body | Parameter | Type | Required | Description | |-------------|--------|----------|--------------------------------------------------| | userId | String | Yes | The user’s ID | | sessionId | String | Yes | The session ID the code is tied to | | secretCode | String | Yes | The secret code received via email | ```json { "userId": "user-uuid", "sessionId": "session-uuid", "secretCode": "123456" } ``` #### Success Response Returns an updated session with 2FA disabled: ```json { "sessionId": "session-uuid", "userId": "user-uuid", "sessionNeedsEmail2FA": false, ... } ``` #### Error Responses - **403 Forbidden**: - Secret code mismatch - Secret code expired - Verification step not found --- ### Important Behavioral Notes - **One Code Per Session**: Only one active code can be issued per session. - **Resend Throttling**: Code requests are throttled based on `resendTimeWindow` (e.g., 60 seconds). - **Expiration**: Codes expire after `expireTimeWindow` (e.g., 5 minutes). - 💡 Mindbricks manages session cache, spam control, expiration tracking, and event notifications for all 2FA steps. ## Verification Services — Mobile 2FA Verification Mobile 2FA (Two-Factor Authentication) is a security mechanism that adds an extra layer of authentication using a user's verified mobile number. All verification services, including mobile 2FA, are accessible under the `/verification-services` base path. ### When is Mobile 2FA Triggered? - During login or critical actions requiring step-up authentication. - When the session has a flag `sessionNeedsMobile2FA = true`. - When login or session verification fails with `MobileVerificationNeeded`, indicating 2FA is required. ### Mobile 2FA Verification Flow 1. **Frontend calls `/verification-services/mobile-2factor-verification/start`** with the user's id, session id, client info, and reason. - Mindbricks finds the user by id. - Verifies that the user has a verified mobile number. - A secret code is generated and cached against the session. - The code is sent to the user's verified mobile number or returned in the response (only in development environments). 2. **User receives the code and enters it in the frontend app.** 3. **Frontend calls `/verification-services/mobile-2factor-verification/complete`** with the `userId`, `sessionId`, and `secretCode`. - Mindbricks validates the code for expiration and correctness. - If valid, the session flag `sessionNeedsMobile2FA` is cleared. - A refreshed session object is returned. --- ## API Endpoints ### POST `/verification-services/mobile-2factor-verification/start` **Purpose**: Initiates mobile-based 2FA by generating and sending a secret code. #### Request Body | Parameter | Type | Required | Description | |-----------|--------|----------|-----------------------------------------------| | userId | String | Yes | The user’s ID | | sessionId | String | Yes | The current session ID | | client | String | No | Optional client tag or context | | reason | String | No | Optional reason for triggering 2FA | ```json { "userId": "user-uuid", "sessionId": "session-uuid", "client": "login-page", "reason": "Login requires mobile 2FA" } ``` **Success Response** Returns the generated code (only in development), expiration info, and metadata. ```json { "userId": "user-uuid", "sessionId": "session-uuid", "mobile": "+15551234567", "secretCode": "654321", "expireTime": 300, "date": "2024-04-29T11:00:00.000Z" } ``` ⚠️ In production environments, the secret code is not included in the response and is instead delivered via SMS. **Error Responses** - 403 Forbidden: Mobile number not verified. - 403 Forbidden: Code resend attempted before cooldown period (`resendTimeWindow`). - 401 Unauthorized: Email not recognized or session invalid. --- ### POST `/verification-services/mobile-2factor-verification/complete` **Purpose**: Completes mobile 2FA verification by validating the secret code and updating the session. #### Request Body | Parameter | Type | Required | Description | |-------------|--------|----------|-------------------------------------| | userId | String | Yes | ID of the user | | sessionId | String | Yes | ID of the session | | secretCode | String | Yes | The 6-digit code received via SMS | ```json { "userId": "user-uuid", "sessionId": "session-uuid", "secretCode": "654321" } ``` **Success Response** Returns the updated session with `sessionNeedsMobile2FA: false`. ```json { "sessionId": "session-uuid", "userId": "user-uuid", "sessionNeedsMobile2FA": false, "accessToken": "jwt-token", "expiresIn": 86400 } ``` **Error Responses** - 403 Forbidden: Code mismatch or expired. - 403 Forbidden: No ongoing verification found. - 401 Unauthorized: Session does not exist or is invalid. --- ### Behavioral Notes - **Rate Limiting**: A user can only request a new mobile 2FA code after the cooldown period (`resendTimeWindow`, e.g., 60 seconds). - **Expiration**: Mobile 2FA codes expire after the configured time (`expireTimeWindow`, e.g., 5 minutes). - **Session Integrity**: Verification status is tied to the session; incorrect sessionId will invalidate the attempt. 💡 Mindbricks handles session integrity, rate limiting, and secure code delivery to ensure a robust mobile 2FA process. ## Verification Services — Password Reset by Email Password Reset by Email enables a user to securely reset their password using a secret code sent to their registered email address. All verification services, including password reset by email, are located under the `/verification-services` base path. ### When is Password Reset by Email Triggered? - When a user requests to reset their password by providing their email address. - This service is typically exposed on a “Forgot Password?” flow in the frontend. ### Password Reset Flow 1. **Frontend calls `/verification-services/password-reset-by-email/start`** with the user's email. - Mindbricks checks if the user exists and if the email is registered. - A secret code is generated and stored in the cache linked to the user. - The code is sent to the user's email, or returned in the response (in development environments only for testing). 2. **User receives the code and enters it into the frontend along with the new password.** 3. **Frontend calls `/verification-services/password-reset-by-email/complete`** with the `email`, the `secretCode`, and the new `password`. - Mindbricks checks that the code is valid, not expired, and matches. - If valid, the user’s password is reset, their `emailVerified` flag is set to `true`, and a success response is returned. --- ## API Endpoints ### POST `/verification-services/password-reset-by-email/start` **Purpose**: Starts the password reset process by generating and sending a secret verification code. #### Request Body | Parameter | Type | Required | Description | |-----------|--------|----------|-------------------------------------| | email | String | Yes | The email address of the user | ```json { "email": "user@example.com" } ``` **Success Response** Returns secret code details (only in development environment) and confirmation that the verification step has been started. ```json { "userId": "user-uuid", "email": "user@example.com", "secretCode": "123456", "expireTime": 86400, "date": "2024-04-29T10:00:00.000Z" } ``` ⚠️ In production, the secret code is only sent via email and not exposed in the API response. **Error Responses** - `401 NotAuthenticated`: Email address not found or not associated with a user. - `403 Forbidden`: Sending a code too frequently (spam prevention). --- ### POST `/verification-services/password-reset-by-email/complete` **Purpose**: Completes the password reset process by validating the secret code and updating the user's password. #### Request Body | Parameter | Type | Required | Description | |-------------|--------|----------|----------------------------------------------| | email | String | Yes | The email address of the user | | secretCode | String | Yes | The code received via email | | password | String | Yes | The new password the user wants to set | ```json { "email": "user@example.com", "secretCode": "123456", "password": "newSecurePassword123" } ``` **Success Response** ```json { "userId": "user-uuid", "email": "user@example.com", "isVerified": true } ``` **Error Responses** - `403 Forbidden`: - Secret code mismatch - Secret code expired - No ongoing verification found --- ## Important Behavioral Notes ### Resend Throttling: A new verification code can only be requested after a cooldown period (configured via `resendTimeWindow`, e.g., 60 seconds). ### Expiration Handling: Verification codes automatically expire after a predefined period (`expireTimeWindow`, e.g., 1 day). ### Session & Event Handling: Mindbricks manages: - Spam prevention - Code caching per user - Expiration logic - Verification start/complete events ## Verification Services — Password Reset by Mobile Password reset by mobile provides users with a secure mechanism to reset their password using a verification code sent via SMS to their registered mobile number. All verification services, including password reset by mobile, are located under the `/verification-services` base path. ### When is Password Reset by Mobile Triggered? - When a user forgets their password and selects the mobile reset option. - When a user explicitly initiates password recovery via mobile on the login or help screen. ### Password Reset by Mobile Flow 1. **Frontend calls `/verification-services/password-reset-by-mobile/start`** with the user's mobile number or associated identifier. - Mindbricks checks if a user with the given mobile exists. - A secret code is generated and stored in the cache for that user. - The code is sent to the user's mobile (or returned in development environments for testing). 2. **User receives the code via SMS and enters it into the frontend app.** 3. **Frontend calls `/verification-services/password-reset-by-mobile/complete`** with the user's `email`, the `secretCode`, and the new `password`. - Mindbricks validates the secret code and its expiration. - If valid, it updates the user's password and returns a success response. --- ## API Endpoints ### POST `/verification-services/password-reset-by-mobile/start` **Purpose**: Initiates the mobile-based password reset by sending a verification code to the user's mobile. #### Request Body | Parameter | Type | Required | Description | |-----------|--------|----------|------------------------------| | mobile | String | Yes | The mobile number to verify | ```json { "mobile": "+905551234567" } ``` ### Success Response Returns the verification context (code returned only in development): ```json { "userId": "user-uuid", "mobile": "+905551234567", "secretCode": "123456", "expireTime": 86400, "date": "2024-04-29T10:00:00.000Z" } ``` ⚠️ In production, the `secretCode` is not included in the response and is only sent via SMS. ### Error Responses - **400 Bad Request**: Mobile already verified - **403 Forbidden**: Rate-limited (code already sent recently) - **404 Not Found**: User with provided mobile not found --- ### POST `/verification-services/password-reset-by-mobile/complete` **Purpose**: Finalizes the password reset process by validating the received verification code and updating the user’s password. #### Request Body | Parameter | Type | Required | Description | |-------------|--------|----------|-------------------------------------------------| | email | String | Yes | The email address of the user | | secretCode | String | Yes | The code received via SMS | | password | String | Yes | The new password to assign | ```json { "email": "user@example.com", "secretCode": "123456", "password": "NewSecurePassword123!" } ``` ### Success Response ```json { "userId": "user-uuid", "mobile": "+905551234567", "isVerified": true } ``` --- ### Important Behavioral Notes - **Throttling**: Codes can only be resent after a delay defined by `resendTimeWindow` (e.g., 60 seconds). - **Expiration**: Codes expire after the `expireTimeWindow` (e.g., 1 day). - **One Active Session**: Only one active password reset session is allowed per user at a time. - **Session-less**: This flow does not require an active session — it works for unauthenticated users. 💡 Mindbricks handles spam protection, session caching, and event-based logging (for both start and complete operations) as part of the verification service base class. ## Verification Method Types ### 🧾 For byCode Verifications This verification type requires the user to manually enter a 6-digit code. **Frontend Action**: Display a secure input page where the user can enter the code they received via email or SMS. After collecting the code and any required metadata (such as `userId` or `sessionId`), make a `POST` request to the corresponding `/complete` endpoint. --- ### 🔗 For byLink Verifications This verification type uses a clickable link embedded in an email (or SMS message). **Frontend Action**: The link points to a `GET` page in your frontend that parses `userId` and `code` from the query string and sends them to the backend via a `POST` request to the corresponding `/complete` endpoint. This enables one-click verification without requiring the user to type in a code. ### Common Routes ### Route: currentuser *Route Definition*: Retrieves the currently authenticated user's session information. *Route Type*: sessionInfo *Access Route*: `GET /currentuser` #### Parameters This route does **not** require any request parameters. #### Behavior - Returns the authenticated session object associated with the current access token. - If no valid session exists, responds with a 401 Unauthorized. ```js // Sample GET /currentuser call axios.get("/currentuser", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** Returns the session object, including user-related data and token information. ``` { "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", "roleId": "user", "tenantId": "abc123", "accessToken": "jwt-token-string", ... } ``` **Error Response** **401 Unauthorized:** No active session found. ``` { "status": "ERR", "message": "No login found" } ``` **Notes** * This route is typically used by frontend or mobile applications to fetch the current session state after login. * The returned session includes key user identity fields, tenant information (if applicable), and the access token for further authenticated requests. * Always ensure a valid access token is provided in the request to retrieve the session. ### Route: permissions `*Route Definition*`: Retrieves all effective permission records assigned to the currently authenticated user. `*Route Type*`: permissionFetch *Access Route*: `GET /permissions` #### Parameters This route does **not** require any request parameters. #### Behavior - Fetches all active permission records (`givenPermissions` entries) associated with the current user session. - Returns a full array of permission objects. - Requires a valid session (`access token`) to be available. ```js // Sample GET /permissions call axios.get("/permissions", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** Returns an array of permission objects. ```json [ { "id": "perm1", "permissionName": "adminPanel.access", "roleId": "admin", "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" }, { "id": "perm2", "permissionName": "orders.manage", "roleId": null, "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" } ] ``` Each object reflects a single permission grant, aligned with the givenPermissions model: - `**permissionName**`: The permission the user has. - `**roleId**`: If the permission was granted through a role. -` **subjectUserId**`: If directly granted to the user. - `**subjectUserGroupId**`: If granted through a group. - `**objectId**`: If tied to a specific object (OBAC). - `**canDo**`: True or false flag to represent if permission is active or restricted. **Error Responses** * **401 Unauthorized**: No active session found. ```json { "status": "ERR", "message": "No login found" } ``` * **500 Internal Server Error**: Unexpected error fetching permissions. **Notes** * The /permissions route is available across all backend services generated by Mindbricks, not just the auth service. * Auth service: Fetches permissions freshly from the live database (givenPermissions table). * Other services: Typically use a cached or projected view of permissions stored in a common ElasticSearch store, optimized for faster authorization checks. > **Tip**: > Applications can cache permission results client-side or server-side, but should occasionally refresh by calling this endpoint, especially after login or permission-changing operations. ### Route: permissions/:permissionName *Route Definition*: Checks whether the current user has access to a specific permission, and provides a list of scoped object exceptions or inclusions. *Route Type*: permissionScopeCheck *Access Route*: `GET /permissions/:permissionName` #### Parameters | Parameter | Type | Required | Population | |------------------|--------|----------|------------------------| | permissionName | String | Yes | `request.params.permissionName` | #### Behavior - Evaluates whether the current user **has access** to the given `permissionName`. - Returns a structured object indicating: - Whether the permission is generally granted (`canDo`) - Which object IDs are explicitly included or excluded from access (`exceptions`) - Requires a valid session (`access token`). ```js // Sample GET /permissions/orders.manage axios.get("/permissions/orders.manage", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** ```json { "canDo": true, "exceptions": [ "a1f2e3d4-xxxx-yyyy-zzzz-object1", "b2c3d4e5-xxxx-yyyy-zzzz-object2" ] } ``` * If `canDo` is `true`, the user generally has the permission, but not for the objects listed in `exceptions` (i.e., restrictions). * If `canDo` is `false`, the user does not have the permission by default — but only for the objects in `exceptions`, they do have permission (i.e., selective overrides). * The exceptions array contains valid **UUID strings**, each corresponding to an object ID (typically from the data model targeted by the permission). ## Copyright All sources, documents and other digital materials are copyright of . ## About Us For more information please visit our website: . . . # Service Design Specification **Athentication documentation** -Version:**`1.0.7`** ## Scope This document provides a structured architectural overview of the `authentication` module of the project.The `authentication` module of the project is used to generate authentication and authorization specific code for all services but a more specific purpose of the module is also to store all required configuration to generate an automatic user service for the project which is named 'ebaycclone-auth-service'. So in this document you will find - The detailed configuration of the authetication module. - The effect of the authetication configuration on the auth (user) service and the detailed structures of the auto-generated user service. - The effect of the authetication configuration on the resource services and the detailed authentication and authorization structures of a resource server. This document has been automatically generated based on the authetication module definition within Mindbricks, ensuring that the information reflects the source of truth used during code generation and deployment. The document is intended to serve multiple audiences: * **Service architects** can use it to validate design decisions and ensure alignment with broader architectural goals. * **Developers and maintainers** will find it useful for understanding the structure and behavior of the service, facilitating easier debugging, feature extension, and integration with other systems. * **Stakeholders and reviewers** can use it to gain a clear understanding of the service's capabilities and domain logic. > **Note for Frontend Developers**: While this document is valuable for understanding business logic and data interactions, please refer to the [Service API Documentation](#) for endpoint-level specifications and integration details. > **Note for Backend Developers**: Since the code for this service is automatically generated by Mindbricks, you typically won't need to implement or modify it manually. However, this document is especially valuable when you're building other services—whether within Mindbricks or externally—that need to interact with or depend on this service. It provides a clear reference to the service's data contracts, business rules, and API structure, helping ensure compatibility and correct integration. * **API Test Interface (API Face):** `/` * **Swagger Documentation:** `/swagger` * **Postman Collection Download:** `/getPostmanCollection` * **Health Checks:** `/health` and `/admin/health` * **Current Session Info:** `/currentuser` * **Favicon:** `/favicon.ico` This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` ## Authentication Essentials Mindbricks provides a comprehensive authentication module that serves as the foundation for user management and security across all services. This module is designed to be flexible, allowing for the generation of authentication and authorization code tailored to project's specific needs. Mindbricks supports multiple authentication strategies, for the first validation of the user, the auth service supports the following authentication strategies: - **Password-based authentication**: Users can log in using a username and password. - **Social login**: Users can authenticate using third-party providers like Google, Facebook, or GitHub. - **Single Sign-On (SSO)**: Users can log in using an SSO provider, allowing for seamless access across multiple applications. - **API Key**: Services can authenticate using API keys for secure communication. Once the user is validated through one of the above strategies, the user is granted a JWT token that can be used to access the protected resources of the service. JWT tokens are generated by the auth service and can be used to access protected resources of the service. The JWT token is open and contains the user's identity and any additional claims required for authorization. The token is signed using a private RSA key, ensuring its integrity and authenticity. Once the JWT token is generated, it can be used to access protected resources of the service. The JWT token is structured as follows: ```json { "keyId": "716a8738ec3d499f84d58bda6ee772ce", "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "sub": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", loginDate: "2023-10-01T12:00:00Z" } ``` Key id for a token represents the private-public key pair used to sign the token. To validate the signature of the token, the public key is used. Any service which will use the JWT token can request a publick ket from the auth service using the following endpoint: ```http GET /publickey?keyId=[keyIdInToken] ``` Mindbricks generated services manages the key rotation automatically, so the public key is always up to date and valid for the JWT tokens generated by the auth service. If you add any manual service to the project which should validate the JWT token, you can use the public key endpoint to get the public key and validate the JWT token signature. The JWT token life cycle is configured in the authentication module of the project. This project uses the following configuration for the JWT token: The token is valid for days after it is issued. And the private key used to sign the token is rotated every days. Note that when a new key is generated to sign the JWT tokens, the old key is still valid for the period of days. So it is recommended to cache the old public keys for the period of days to validate the JWT tokens issued with the old keys. ## The Login Definition The login definition is a crucial part of the authentication module, as it defines how user and tenant model is defined. In this section it is specified how users, user groups, and tenants are defined in the project's data model. These definitions allow Mindbricks to dynamically extract identity and authorization data from project-specific data objects. ### User Settings **Super Admin User Email**: `admin@admin.com`** The login email of the super admin user. This user has full permissions across the project and is not tenant-scoped. If not defined, the project owner's email is used. This email must be unique and valid to support email-based features like verification and password reset. Super admin user is created automatically when the project is initialized with a roleId of `superAdmin` and a userId of `f7103b85-fcda-4dec-92c6-c336f71fd3a2`. **Super Admin User Password**: Super admin user password is defined in this module as well, but masked in this document. To edit it you can use the **User Settings** section of **Login Definition** chapter of the Mindbricks **Authentication Module**. **Username Type**: The type of the username which is stored in the database and written to the session object for information purposes.: -`asFullName`: The username is stored in one property, `fullname`, and represents the full name of the user, which is a combination of first name and last name. -`asNamePair`: The username is stored in two properties, `name` and `surname`, which are combined to form the full name of the user. This project uses the `asFullName` type, so the user name is stored in one property, `fullname`, and represents the full name of the user, which is a combination of first name and last name. **User Groups**: The project does not support user groups, so the auth service will not create any user group related data objects. **Public User Registration**: The project allows public user registration, meaning that users can register themselves without the need for an admin to create an account for them. This is useful for projects that require user self-registration, such as social networks, forums, or any application where users need to create their own accounts. The user registration process is handled by the auth service, which will create a new user data object in the database. The user registration process will create a new user with the `userId` and `roleId` set to `user`, and the user will be able to log in using the username and password they provided during registration. The reigstered user's roleId will be updated later to any other roleId by the super admin or admin users. If any social login is enabled for the project, the user can also sign up using the social login providers. Note that when users register themselves using socila logi, first all the data that can be provided by the social login provider will written to Redis cache with a key called socialCode, and this code will be returned to the api consumer, which can be used to complete the registration process. **Email Verification Required For Login**: The project requires email verification for user login, meaning that users must verify their email address before they can log in. This is useful for projects that require email verification to ensure that users have provided a valid email address, such as social networks, forums, or any application where email verification is required. The email verification process is handled by the auth service, which will send a verification email to the user's email address after they register or change their email address. You can check the email verification details in the REST API documentation of the auth service. **Email 2FA Is Not Required For Login**: The project does not require email-based two-factor authentication (2FA) for user login, meaning that users can log in using only their username and password without providing a second factor of authentication. This is useful for projects that do not require an additional layer of security for user login, such as enterprise applications, internal tools, or any application where email-based 2FA is not required. While the email 2FA is not required, the auth service will still support email 2FA if it is configured in the verification services. You can prefer email 2FA at any time before any action or make it optional which means that users can provide a second factor of authentication if they want to, but it is not required for login. You can check the email 2FA details in the REST API documentation of the auth service. **User Mobile Is Not Active**: The authetication module is not configured to support mobile numbers for users. **User Auto Avatar Script**: Mindbricks stores an avatar property inthe user data model automatically. This project supports also automatic avatar generation for users with the following script configuretion. The auth service will generate an avatar for each user when it is not specified in the registration process. The script is defined in the authentication module and can be edited in the **User Settings** section of **Login Definition** chapter of the Mindbricks **Authentication Module**. The script is executed when a new user is created, and it generates an avatar based on user properties. ```js `https://gravatar.com/avatar/${LIB.common.md5(this.email ?? 'nullValue')}?s=200&d=identicon` ``` ### Tenant Settings This project is not configured to support multi-tenancy, meaning that users and other data are not scoped to a specific tenant. This allows for a single-tenant data management, where all users and other data are shared across the project. ## Verification Services The project supports various verification services that enhance security and user experience. These services are designed to verify user identity through different channels, such as email and mobile, and can be configured to suit the project's needs. Please check the auth service API documentation for more details on how to use these services through the REST API. A verification service is configured with the following settings: -`verificationType`: The type of verification handling, which can be one of the following: -- `byCode`: The verification is handled by entering a code in the frontend. -- `byLink`: The verification is handled by clicking a link in the frontend, which will automatically verify the user through the auth service. -`resendTimeWindow`: The time window in seconds during which the user can request a new verification code or link. -`expireTimeWindow`: The time window in seconds after which the verification code or link will expire and become invalid. ### Password Reset By Email The project supports password reset by email, allowing users to reset their passwords securely through a verification code sent to their registered email address. This service is useful for projects that require users to reset their passwords securely, such as social networks, forums, or any application where password reset is required. The password reset by email process is handled by the auth service, which will send a verification code to the user's email address after they request a password reset. ```json { verificationType: "byCode", resendTimeWindow: 60, expireTimeWindow: 86400 } ``` ### Password Reset By Mobile The project supports password reset by mobile, allowing users to reset their passwords securely through a verification code sent to their registered mobile number. This service is useful for projects that require users to reset their passwords securely, such as social networks, forums, or any application where password reset is required. The password reset by mobile process is handled by the auth service, which will send a verification code to the user's mobile number after they request a password reset. ```json { verificationType: "byCode", resendTimeWindow: 60, expireTimeWindow: 300 } ``` ### Email Verification The project supports email verification, allowing users to verify their email addresses securely through a verification code sent to their registered email address. This service is useful for projects that require users to verify their email addresses securely, such as social networks, forums, or any application where email verification is required. The email verification process is handled by the auth service, which will send a verification code to the user's email address after they register or change their email address. ```json { verificationType: "byCode", resendTimeWindow: 60, expireTimeWindow: 86400 } ``` ### Mobile Verification The project supports mobile verification, allowing users to verify their mobile numbers securely through a verification code sent to their registered mobile number. This service is useful for projects that require users to verify their mobile numbers securely, such as social networks, forums, or any application where mobile verification is required. The mobile verification process is handled by the auth service, which will send a verification code to the user's mobile number after they register or change their mobile number. ```json { verificationType: "byCode", resendTimeWindow: 60, expireTimeWindow: 300 } ``` ### Email 2FA The project supports email-based two-factor authentication (2FA), allowing users to enhance their login security by providing a second factor of authentication, such as a verification code sent to their registered email address. This service is useful for projects that require an additional layer of security for user login, such as social networks, forums, or any application where email-based 2FA is required. The email 2FA process is handled by the auth service, which will send a verification code to the user's email address after they log in. The user must provide the verification code to complete the login process. ```json { verificationType: "byCode", resendTimeWindow: 60, expireTimeWindow: 86400 } ``` ### Mobile 2FA The project supports mobile-based two-factor authentication (2FA), allowing users to enhance their login security by providing a second factor of authentication, such as a verification code sent to their registered mobile number. This service is useful for projects that require an additional layer of security for user login, such as social networks, forums, or any application where mobile-based 2FA is required. The mobile 2FA process is handled by the auth service, which will send a verification code to the user's mobile number after they log in. The user must provide the verification code to complete the login process. ```json { verificationType: "byCode", resendTimeWindow: 60, expireTimeWindow: 300 } ``` ## Access Control (Not Configured) The project does not support any access control mechanisms, meaning that users can access all resources without any restrictions. If you want to add access control mechanisms, you can do so in the **Access Control** chapter of Mindbricks **Authentication Module**. ## Social Logins (Not Configured) The project does not support any social logins, meaning that users cannot log in using their social media accounts. If you want to add social logins, you can do so in the **Social Logins** chapter of Mindbricks **Authentication Module**. ## User Properties `phone` `address` The project supports above user properties, allowing for the storage of additional user information beyond the default properties. User properties are defined in the **User Properties** chapter of authentication module and can be edited in the **User Properties** section. These properties can be used to store additional information about users, such as preferences, settings, or any other custom data that is relevant to the project. User properties are stored in the user data object, and they can be accessed and modified through the auth service API. To see a detailed configuretion of the user properties, please check the **User Data Object** docmentation below. ## Auth Service Data Objects The service uses a **PostgreSQL** database for data storage, with the database name set to `ebaycclone-auth-service`. Data deletion is managed using a **soft delete** strategy. Instead of removing records from the database, they are flagged as inactive by setting the `isActive` field to `false`. | Object Name | Description | Public Access | |-------------|-------------|---------------| | `user` | A data object that stores the user information and handles login settings. | accessPrivate | ## user Data Object ### Object Overview **Description:** A data object that stores the user information and handles login settings. This object represents a core data structure within the service and acts as the blueprint for database interaction, API generation, and business logic enforcement. It is defined using the `ObjectSettings` pattern, which governs its behavior, access control, caching strategy, and integration points with other systems such as Stripe and Redis. ### Core Configuration - **Soft Delete:** Enabled — Determines whether records are marked inactive (`isActive = false`) instead of being physically deleted. - **Public Access:** accessPrivate — If enabled, anonymous users may access this object’s data depending on API-level rules. ### Redis Entity Caching This data object is configured for Redis entity caching, which improves data retrieval performance by storing frequently accessed data in Redis. Each time a new instance is created, updated or deleted, the cache is updated accordingly. Any get requests by id will first check the cache before querying the database. If you want to use the cache by other select criteria, you can configure any data property as a Redis cluster. ### Properties Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `email` | String | Yes | A string value to represent the user's email. | | `password` | String | Yes | A string value to represent the user's password. It will be stored as hashed. | | `fullname` | String | Yes | A string value to represent the fullname of the user | | `avatar` | String | No | The avatar url of the user. A random avatar will be generated if not provided | | `roleId` | String | Yes | A string value to represent the roleId of the user. | | `emailVerified` | Boolean | Yes | A boolean value to represent the email verification status of the user. | | `phone` | String | No | user's phone number | | `address` | Object | No | user's adress | * Required properties are mandatory for creating objects and must be provided in the request body if no default value is set. ### Default Values Default values are automatically assigned to properties when a new object is created, if no value is provided in the request body. Since default values are applied on db level, they should be literal values, not expressions.If you want to use expressions, you can use transposed parameters in any business API to set default values dynamically. - **email**: 'default' - **password**: 'default' - **fullname**: 'default' - **roleId**: user ### Always Create with Default Values Some of the default values are set to be always used when creating a new object, even if the property value is provided in the request body. It ensures that the property is always initialized with a default value when the object is created. - **roleId**: Will be created with value `user` - **emailVerified**: Will be created with value `false` ### Constant Properties `email` Constant properties are defined to be immutable after creation, meaning they cannot be updated or changed once set. They are typically used for properties that should remain constant throughout the object's lifecycle. A property is set to be constant if the `Allow Update` option is set to `false`. ### Auto Update Properties `fullname` `avatar` `phone` `address` An update crud API created with the option `Auto Params` enabled will automatically update these properties with the provided values in the request body. If you want to update any property in your own business logic not by user input, you can set the `Allow Auto Update` option to false. These properties will be added to the update API's body parameters and can be updated by the user if any value is provided in the request body. ### Hashed Properties `password` Hashed properties are stored in the database as a hash value, providing an additional layer of security for sensitive data. ### Elastic Search Indexing `email` `fullname` `roleId` `emailVerified` `phone` `address` Properties that are indexed in Elastic Search will be searchable via the Elastic Search API. While all properties are stored in the elastic search index of the data object, only those marked for Elastic Search indexing will be available for search queries. ### Database Indexing `email` Properties that are indexed in the database will be optimized for query performance, allowing for faster data retrieval. Make a property indexed in the database if you want to use it frequently in query filters or sorting. ### Unique Properties `email` Unique properties are enforced to have distinct values across all instances of the data object, preventing duplicate entries. Note that a unique property is automatically indexed in the database so you will not need to set the `Indexed in DB` option. ### Cache Select Properties `email` Cache select properties are used to collect data from Redis entity cache with a different key than the data object id. This allows you to cache data that is not directly related to the data object id, but a frequently used filter. ### Secondary Key Properties `email` Secondary key properties are used to create an additional indexed identifiers for the data object, allowing for alternative access patterns. Different than normal indexed properties, secondary keys will act as primary keys and Mindbricks will provide automatic secondary key db utility functions to access the data object by the secondary key. ### Filter Properties `email` `password` `fullname` `avatar` `roleId` `emailVerified` `phone` `address` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's that have "Auto Params" enabled. - **email**: String has a filter named `email` - **password**: String has a filter named `password` - **fullname**: String has a filter named `fullname` - **avatar**: String has a filter named `avatar` - **roleId**: String has a filter named `roleId` - **emailVerified**: Boolean has a filter named `emailVerified` - **phone**: String has a filter named `phone` - **address**: Object has a filter named `adress` # EVENT API GUIDE ## BFF SERVICE The BFF service is a microservice that acts as a bridge between the client and backend services. It provides a unified API for the client to interact with multiple backend services, simplifying the communication process and improving performance. ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to. For inquiries, feedback, or further information regarding the architecture, please direct your communication to: **Email**: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. ## Documentation Scope Welcome to the official documentation for the BFF Service Event Listeners. This guide details the Kafka-based event listeners responsible for reacting to ElasticSearch index events. It describes listener responsibilities, the topics they subscribe to, and expected payloads. **Intended Audience** This documentation is intended for developers, architects, and system administrators involved in the design, implementation, and maintenance of the BFF Service. It assumes familiarity with microservices architecture, the Kafka messaging system, and ElasticSearch. **Overview** Each ElasticSearch index operation (create, update, delete) emits a corresponding event to Kafka. These events are consumed by listeners responsible for executing aggregate functions to ensure index- and system-level consistency. ## Kafka Event Listeners # REST API GUIDE ## BFF SERVICE BFF service is a microservice that acts as a bridge between the client and the backend services. It provides a unified API for the client to interact with multiple backend services, simplifying the communication process and improving performance. ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to. For inquiries, feedback, or further information regarding the architecture, please direct your communication to: Email: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. ## Documentation Scope Welcome to the official documentation for the BFF Service's REST API. This document is designed to provide a comprehensive guide to interfacing with our BFF Service exclusively through RESTful API endpoints. **Intended Audience** This documentation is intended for developers and integrators who are looking to interact with the BFF Service via HTTP requests for purposes such as listing, filtering, and searching data. **Overview** Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases. **Beyond REST** It's important to note that the BFF Service also supports alternative methods of interaction, such as gRPC and messaging via a Message Broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation. --- ## Resources ### Elastic Index Resource _Resource Definition_: A virtual resource representing dynamic search data from a specified index. --- ## Route: List Records _Route Definition_: Returns a paginated list from the elastic index. _Route Type_: list _Default access route_: _POST_ `/:indexName/list` ### Parameters | Parameter | Type | Required | Population | |-------------|--------|----------|-----------------| | indexName | String | Yes | path.param | | page | Number | No | query.page | | limit | Number | No | query.limit | | sortBy | String | No | query.sortBy | | sortOrder | String | No | query.sortOrder | | q | String | No | query.q | | filters | Object | Yes | body | ```js axios({ method: "POST", url: `/${indexName}/list`, data: { filters: "Object" }, params: { page: "Number", limit: "Number", sortBy: "String", sortOrder: "String", q: "String" } }); ```

The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a "status": "OK" property.

--- _Default access route_: _GET_ `/:indexName/list` ### Parameters | Parameter | Type | Required | Population | |-------------|--------|----------|-----------------| | indexName | String | Yes | path.param | | page | Number | No | query.page | | limit | Number | No | query.limit | | sortBy | String | No | query.sortBy | | sortOrder | String | No | query.sortOrder | | q | String | No | query.q | ```js axios({ method: "GET", url: `/${indexName}/list`, data:{}, params: { page: "Number", limit: "Number", sortBy: "String", sortOrder: "String", q: "String" } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a "status": "OK" property. ## Route: Count Records _Route Definition_: Counts matching documents in the elastic index. _Route Type_: count _Default access route_: _POST_ `/:indexName/count` ### Parameters | Parameter | Type | Required | Population | |-------------|--------|----------|-------------| | indexName | String | Yes | path.param | | q | String | No | query.q | | filters | Object | Yes | body | ```js axios({ method: "POST", url: `/${indexName}/count`, data: { filters: "Object" }, params: { q: "String" } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a "status": "OK" property. --- _Default access route_: _GET_ `/:indexName/count` ### Parameters | Parameter | Type | Required | Population | |-------------|--------|----------|-------------| | indexName | String | Yes | path.param | | q | String | No | query.q | ```js axios({ method: "GET", url: `/${indexName}/count`, data:{}, params: { q: "String" } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a "status": "OK" property. ## Route: Get Index Schema _Route Definition_: Returns the schema for the elastic index. _Route Type_: get _Default access route_: _GET_ `/:indexName/schema` ### Parameters | Parameter | Type | Required | Population | |-------------|--------|----------|-------------| | indexName | String | Yes | path.param | ```js axios({ method: "GET", url: `/${indexName}/schema`, data:{}, params: {} }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a "status": "OK" property. ## Route: Filters ### GET /:indexName/filters _Route Type_: get ### Parameters | Parameter | Type | Required | Population | |-------------|--------|----------|-------------| | indexName | String | Yes | path.param | | page | Number | No | query.page | | limit | Number | No | query.limit | ```js axios({ method: "GET", url: `/${indexName}/filters`, data:{}, params: { page: "Number", limit: "Number" } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a "status": "OK" property. ### POST /:indexName/filters _Route Type_: create ### Parameters | Parameter | Type | Required | Population | |-------------|--------|----------|-------------| | indexName | String | Yes | path.param | | filters | Object | Yes | body | ```js axios({ method: "POST", url: `/${indexName}/filters`, data: { filterName: "String", conditions: "Object" }, params: {} }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a "status": "OK" property. ### DELETE /:indexName/filters/:filterId _Route Type_: delete ### Parameters | Parameter | Type | Required | Population | |-------------|--------|----------|-------------| | indexName | String | Yes | path.param | | filterId | String | Yes | path.param | ```js axios({ method: "DELETE", url: `/${indexName}/filters/${filterId}`, data:{}, params: {} }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a "status": "OK" property. ## Route: Get One Record _Route Type_: get _Default access route_: _GET_ `/:indexName/:id` ### Parameters | Parameter | Type | Required | Population | |-------------|--------|----------|-------------| | indexName | String | Yes | path.param | | id | ID | Yes | path.param | ```js axios({ method: "GET", url: `/${indexName}/${id}`, data:{}, params: {} }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a "status": "OK" property. --- # Service Design Specification **BFF Service Documentation** **Version:** `1.0` --- ## Scope This document provides a comprehensive architectural overview of the **BFF Service**, a Backend-for-Frontend layer designed to unify access to backend ElasticSearch indices and event-driven aggregation logic. The service offers a full REST API suite and listens to Kafka topics to synchronize enriched views. This document is intended for: * **Architects** ensuring integration patterns and event consistency. * **Developers** building on top of or consuming the BFF service. * **DevOps Engineers** responsible for deployment and environment setup. > For endpoint-level specifications, refer to the REST API Guide. > For listener-level behavior, refer to the Event API Guide. --- ## Service Settings * **Port**: Configurable via `HTTP_PORT`, default: `3000` * **ElasticSearch**: Primary storage and query engine * **Kafka Broker**: `KAFKA_BROKER` for aggregation sync * **Mindbricks Injected Interface**: Configured with `api-face` * **Dynamic REST Routes**: Powered via codegen with `/` structure --- ## API Routes Overview The BFF service exposes a dynamic REST API interface that provides full access to ElasticSearch indices. These include list, count, filter, and schema-based interactions for both stored and virtual views. For full documentation of REST routes, including supported methods and examples, refer to the **REST API Guide**. --- ## Kafka Event Listeners The BFF service listens to ElasticSearch-related Kafka topics to maintain enriched and denormalized indices. These listeners trigger view aggregation functions upon receiving `create`, `update`, or `delete` events for primary and related entities. For detailed behavior, payloads, and listener-to-function mappings, refer to the **Event Guide**. --- ## Aggregation Strategy Each view is either: * **Stored View**: materialized into a separate ElasticSearch index * **Virtual View**: dynamically aggregated on request For each stored view: * `viewNameAggregateData(id)` handles source rehydration * Aggregates are executed via `aggregateNameAggregateDataFromIndex()` * Lookups via `lookupNameLookupDataFromIndex()` * Stats via `statNameStatDataFromIndex()` Final document is saved to: `_` --- ## Middleware ### Error Handling * `ApiError` extends native error * `errorConverter` ensures consistent error format * `errorHandler` outputs error JSON with stack trace in development ### Request Validation * `validate()` uses Joi + custom schema per route * Filters and pagination are schema-validated * Filter operators supported: `eq`, `noteq`, `range`, `wildcard`, `match`, etc. ### Async Wrapper * `catchAsync(fn)` auto-handles exceptions in async route handlers --- ## Elasticsearch Utilities * **Index Management**: create, check, delete * **Document Operations**: get, create, update, delete * **Query Builders**: * `queryBuilder()` for filters * `searchBuilder()` for full-text queries * `aggBuilder()` for terms aggregations * **Multi-index search support** with `multiSearchBuilder()` * **Dynamic Schema Extraction** via `fieldBuilder()` --- ## Cron Repair Logic Runs periodically to ensure data integrity: * `runAllRepair()` triggers each `viewNameRepair()` * For each view: * Reads base index with `match_all` * Re-runs aggregation pipeline * Indexes final result into enriched view index --- ## Environment Variables | Variable | Description | | -------------------- | ---------------------------------- | | `HTTP_PORT` | Service port | | `KAFKA_BROKER` | Kafka broker host | | `ELASTIC_URL` | Elasticsearch base URL | | `CORS_ORIGIN` | Allowed frontend origin (optional) | | `NODE_ENV` | Environment (dev, prod) | | `SERVICE_URL` | Used for injected API face config | | `SERVICE_SHORT_NAME` | Used in injected auth URL | --- ## App Lifecycle 1. Loads env: `.env`, `.prod.env`, etc. 2. Bootstraps Express app with: * CORS setup * JSON + cookie parsers * Dynamic routes * Swagger and API Face 3. Starts: * Kafka listeners * Cron repair jobs * Full enrichment pipelines 4. Handles SIGINT to close server cleanly --- ## Testing Strategy ### Unit Tests * Aggregation methods per view * Joi schemas * Custom middleware (errors, async, pick) ### Integration Tests * REST APIs (mock Elastic) * Kafka event triggers → view enrichment ### Load Tests (Optional) * GET `/index/list` with filters * Event storm on Kafka topics * Cron job load verification --- # EVENT GUIDE ## ebaycclone-categorymanagement-service Handles product categories and subcategories for marketplace browsing and classification, supporting public discovery plus admin-only management. ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to: Email: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. # Documentation Scope Welcome to the official documentation for the `CategoryManagement` Service Event descriptions. This guide is dedicated to detailing how to subscribe to and listen for state changes within the `CategoryManagement` Service, offering an exclusive focus on event subscription mechanisms. **Intended Audience** This documentation is aimed at developers and integrators looking to monitor `CategoryManagement` Service state changes. It is especially relevant for those wishing to implement or enhance business logic based on interactions with `CategoryManagement` objects. **Overview** This section provides detailed instructions on monitoring service events, covering payload structures and demonstrating typical use cases through examples. # Authentication and Authorization Access to the `CategoryManagement` service's events is facilitated through the project's Kafka server, which is not accessible to the public. Subscription to a Kafka topic requires being on the same network and possessing valid Kafka user credentials. This document presupposes that readers have existing access to the Kafka server. Additionally, the service offers a public subscription option via REST for real-time data management in frontend applications, secured through REST API authentication and authorization mechanisms. To subscribe to service events via the REST API, please consult the Realtime REST API Guide. # Database Events Database events are triggered at the database layer, automatically and atomically, in response to any modifications at the data level. These events serve to notify subscribers about the creation, update, or deletion of objects within the database, distinct from any overarching business logic. Listening to database events is particularly beneficial for those focused on tracking changes at the database level. A typical use case for subscribing to database events is to replicate the data store of one service within another service's scope, ensuring data consistency and syncronization across services. For example, while a business operation such as "approve membership" might generate a high-level business event like `membership-approved`, the underlying database changes could involve multiple state updates to different entities. These might be published as separate events, such as `dbevent-member-updated` and `dbevent-user-updated`, reflecting the granular changes at the database level. Such detailed eventing provides a robust foundation for building responsive, data-driven applications, enabling fine-grained observability and reaction to the dynamics of the data landscape. It also facilitates the architectural pattern of event sourcing, where state changes are captured as a sequence of events, allowing for high-fidelity data replication and history replay for analytical or auditing purposes. ## DbEvent category-created **Event topic**: `ebaycclone-categorymanagement-service-dbevent-category-created` This event is triggered upon the creation of a `category` data object in the database. The event payload encompasses the newly created data, encapsulated within the root of the paylod. **Event payload**: ```json {"id":"ID","imageUrl":"String","subtitle":"String","title":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent category-updated **Event topic**: `ebaycclone-categorymanagement-service-dbevent-category-updated` Activation of this event follows the update of a `category` data object. The payload contains the updated information under the `category` attribute, along with the original data prior to update, labeled as `old_category` and also you can find the old and new versions of updated-only portion of the data.. **Event payload**: ```json { old_category:{"id":"ID","imageUrl":"String","subtitle":"String","title":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, category:{"id":"ID","imageUrl":"String","subtitle":"String","title":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, oldDataValues, newDataValues } ``` ## DbEvent category-deleted **Event topic**: `ebaycclone-categorymanagement-service-dbevent-category-deleted` This event announces the deletion of a `category` data object, covering both hard deletions (permanent removal) and soft deletions (where the `isActive` attribute is set to false). Regardless of the deletion type, the event payload will present the data as it was immediately before deletion, highlighting an `isActive` status of false for soft deletions. **Event payload**: ```json {"id":"ID","imageUrl":"String","subtitle":"String","title":"String","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent subcategory-created **Event topic**: `ebaycclone-categorymanagement-service-dbevent-subcategory-created` This event is triggered upon the creation of a `subcategory` data object in the database. The event payload encompasses the newly created data, encapsulated within the root of the paylod. **Event payload**: ```json {"id":"ID","categoryId":"ID","name":"String","group":"Enum","group_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent subcategory-updated **Event topic**: `ebaycclone-categorymanagement-service-dbevent-subcategory-updated` Activation of this event follows the update of a `subcategory` data object. The payload contains the updated information under the `subcategory` attribute, along with the original data prior to update, labeled as `old_subcategory` and also you can find the old and new versions of updated-only portion of the data.. **Event payload**: ```json { old_subcategory:{"id":"ID","categoryId":"ID","name":"String","group":"Enum","group_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, subcategory:{"id":"ID","categoryId":"ID","name":"String","group":"Enum","group_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, oldDataValues, newDataValues } ``` ## DbEvent subcategory-deleted **Event topic**: `ebaycclone-categorymanagement-service-dbevent-subcategory-deleted` This event announces the deletion of a `subcategory` data object, covering both hard deletions (permanent removal) and soft deletions (where the `isActive` attribute is set to false). Regardless of the deletion type, the event payload will present the data as it was immediately before deletion, highlighting an `isActive` status of false for soft deletions. **Event payload**: ```json {"id":"ID","categoryId":"ID","name":"String","group":"Enum","group_idx":"Integer","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` # ElasticSearch Index Events Within the `CategoryManagement` service, most data objects are mirrored in ElasticSearch indices, ensuring these indices remain syncronized with their database counterparts through creation, updates, and deletions. These indices serve dual purposes: they act as a data source for external services and furnish aggregated data tailored to enhance frontend user experiences. Consequently, an ElasticSearch index might encapsulate data in its original form or aggregate additional information from other data objects. These aggregations can include both one-to-one and one-to-many relationships not only with database objects within the same service but also across different services. This capability allows developers to access comprehensive, aggregated data efficiently. By subscribing to ElasticSearch index events, developers are notified when an index is updated and can directly obtain the aggregated entity within the event payload, bypassing the need for separate ElasticSearch queries. It's noteworthy that some services may augment another service's index by appending to the entity’s `extends` object. In such scenarios, an `*-extended` event will contain only the newly added data. Should you require the complete dataset, you would need to retrieve the full ElasticSearch index entity using the provided ID. This approach to indexing and event handling facilitates a modular, interconnected architecture where services can seamlessly integrate and react to changes, enriching the overall data ecosystem and enabling more dynamic, responsive applications. ## Index Event category-created **Event topic**: `elastic-index-ebaycclone_category-created` **Event payload**: ```json {"id":"ID","imageUrl":"String","subtitle":"String","title":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event category-updated **Event topic**: `elastic-index-ebaycclone_category-created` **Event payload**: ```json {"id":"ID","imageUrl":"String","subtitle":"String","title":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event category-deleted **Event topic**: `elastic-index-ebaycclone_category-deleted` **Event payload**: ```json {"id":"ID","imageUrl":"String","subtitle":"String","title":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event category-extended **Event topic**: `elastic-index-ebaycclone_category-extended` **Event payload**: ```js { id: id, extends: { [extendName]: "Object", [extendName + "_count"]: "Number", }, } ``` # Route Events Route events are emitted following the successful execution of a route. While most routes perform CRUD (Create, Read, Update, Delete) operations on data objects, resulting in route events that closely resemble database events, there are distinctions worth noting. A single route execution might trigger multiple CRUD actions and ElasticSearch indexing operations. However, for those primarily concerned with the overarching business logic and its outcomes, listening to the consolidated route event, published once at the conclusion of the route's execution, is more pertinent. Moreover, routes often deliver aggregated data beyond the primary database object, catering to specific client needs. For instance, creating a data object via a route might not only return the entity's data but also route-specific metrics, such as the executing user's permissions related to the entity. Alternatively, a route might automatically generate default child entities following the creation of a parent object. Consequently, the route event encapsulates a unified dataset encompassing both the parent and its children, in contrast to individual events triggered for each entity created. Therefore, subscribing to route events can offer a richer, more contextually relevant set of information aligned with business logic. The payload of a route event mirrors the REST response JSON of the route, providing a direct and comprehensive reflection of the data and metadata communicated to the client. This ensures that subscribers to route events receive a payload that encapsulates both the primary data involved and any additional information deemed significant at the business level, facilitating a deeper understanding and integration of the service's functional outcomes. ## Route Event category-deleted **Event topic** : `ebaycclone-categorymanagement-service-category-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `category` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`category`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"category","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"category":{"id":"ID","imageUrl":"String","subtitle":"String","title":"String","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event subcategory-retrived **Event topic** : `ebaycclone-categorymanagement-service-subcategory-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `subcategory` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`subcategory`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"subcategory","method":"GET","action":"get","appVersion":"Version","rowCount":1,"subcategory":{"id":"ID","categoryId":"ID","name":"String","group":"Enum","group_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event category-retrived **Event topic** : `ebaycclone-categorymanagement-service-category-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `category` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`category`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"category","method":"GET","action":"get","appVersion":"Version","rowCount":1,"category":{"id":"ID","imageUrl":"String","subtitle":"String","title":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event subcategory-updated **Event topic** : `ebaycclone-categorymanagement-service-subcategory-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `subcategory` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`subcategory`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"subcategory","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"subcategory":{"id":"ID","categoryId":"ID","name":"String","group":"Enum","group_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event subcategories-listed **Event topic** : `ebaycclone-categorymanagement-service-subcategories-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `subcategories` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`subcategories`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"subcategories","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","subcategories":[{"id":"ID","categoryId":"ID","name":"String","group":"Enum","group_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event subcategory-deleted **Event topic** : `ebaycclone-categorymanagement-service-subcategory-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `subcategory` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`subcategory`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"subcategory","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"subcategory":{"id":"ID","categoryId":"ID","name":"String","group":"Enum","group_idx":"Integer","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event categories-listed **Event topic** : `ebaycclone-categorymanagement-service-categories-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `categories` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`categories`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"categories","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","categories":[{"id":"ID","imageUrl":"String","subtitle":"String","title":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event category-updated **Event topic** : `ebaycclone-categorymanagement-service-category-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `category` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`category`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"category","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"category":{"id":"ID","imageUrl":"String","subtitle":"String","title":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event subcategory-created **Event topic** : `ebaycclone-categorymanagement-service-subcategory-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `subcategory` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`subcategory`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"subcategory","method":"POST","action":"create","appVersion":"Version","rowCount":1,"subcategory":{"id":"ID","categoryId":"ID","name":"String","group":"Enum","group_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event category-created **Event topic** : `ebaycclone-categorymanagement-service-category-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `category` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`category`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"category","method":"POST","action":"create","appVersion":"Version","rowCount":1,"category":{"id":"ID","imageUrl":"String","subtitle":"String","title":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Index Event subcategory-created **Event topic**: `elastic-index-ebaycclone_subcategory-created` **Event payload**: ```json {"id":"ID","categoryId":"ID","name":"String","group":"Enum","group_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event subcategory-updated **Event topic**: `elastic-index-ebaycclone_subcategory-created` **Event payload**: ```json {"id":"ID","categoryId":"ID","name":"String","group":"Enum","group_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event subcategory-deleted **Event topic**: `elastic-index-ebaycclone_subcategory-deleted` **Event payload**: ```json {"id":"ID","categoryId":"ID","name":"String","group":"Enum","group_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event subcategory-extended **Event topic**: `elastic-index-ebaycclone_subcategory-extended` **Event payload**: ```js { id: id, extends: { [extendName]: "Object", [extendName + "_count"]: "Number", }, } ``` # Route Events Route events are emitted following the successful execution of a route. While most routes perform CRUD (Create, Read, Update, Delete) operations on data objects, resulting in route events that closely resemble database events, there are distinctions worth noting. A single route execution might trigger multiple CRUD actions and ElasticSearch indexing operations. However, for those primarily concerned with the overarching business logic and its outcomes, listening to the consolidated route event, published once at the conclusion of the route's execution, is more pertinent. Moreover, routes often deliver aggregated data beyond the primary database object, catering to specific client needs. For instance, creating a data object via a route might not only return the entity's data but also route-specific metrics, such as the executing user's permissions related to the entity. Alternatively, a route might automatically generate default child entities following the creation of a parent object. Consequently, the route event encapsulates a unified dataset encompassing both the parent and its children, in contrast to individual events triggered for each entity created. Therefore, subscribing to route events can offer a richer, more contextually relevant set of information aligned with business logic. The payload of a route event mirrors the REST response JSON of the route, providing a direct and comprehensive reflection of the data and metadata communicated to the client. This ensures that subscribers to route events receive a payload that encapsulates both the primary data involved and any additional information deemed significant at the business level, facilitating a deeper understanding and integration of the service's functional outcomes. ## Route Event category-deleted **Event topic** : `ebaycclone-categorymanagement-service-category-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `category` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`category`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"category","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"category":{"id":"ID","imageUrl":"String","subtitle":"String","title":"String","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event subcategory-retrived **Event topic** : `ebaycclone-categorymanagement-service-subcategory-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `subcategory` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`subcategory`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"subcategory","method":"GET","action":"get","appVersion":"Version","rowCount":1,"subcategory":{"id":"ID","categoryId":"ID","name":"String","group":"Enum","group_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event category-retrived **Event topic** : `ebaycclone-categorymanagement-service-category-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `category` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`category`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"category","method":"GET","action":"get","appVersion":"Version","rowCount":1,"category":{"id":"ID","imageUrl":"String","subtitle":"String","title":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event subcategory-updated **Event topic** : `ebaycclone-categorymanagement-service-subcategory-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `subcategory` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`subcategory`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"subcategory","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"subcategory":{"id":"ID","categoryId":"ID","name":"String","group":"Enum","group_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event subcategories-listed **Event topic** : `ebaycclone-categorymanagement-service-subcategories-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `subcategories` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`subcategories`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"subcategories","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","subcategories":[{"id":"ID","categoryId":"ID","name":"String","group":"Enum","group_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event subcategory-deleted **Event topic** : `ebaycclone-categorymanagement-service-subcategory-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `subcategory` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`subcategory`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"subcategory","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"subcategory":{"id":"ID","categoryId":"ID","name":"String","group":"Enum","group_idx":"Integer","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event categories-listed **Event topic** : `ebaycclone-categorymanagement-service-categories-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `categories` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`categories`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"categories","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","categories":[{"id":"ID","imageUrl":"String","subtitle":"String","title":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event category-updated **Event topic** : `ebaycclone-categorymanagement-service-category-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `category` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`category`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"category","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"category":{"id":"ID","imageUrl":"String","subtitle":"String","title":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event subcategory-created **Event topic** : `ebaycclone-categorymanagement-service-subcategory-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `subcategory` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`subcategory`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"subcategory","method":"POST","action":"create","appVersion":"Version","rowCount":1,"subcategory":{"id":"ID","categoryId":"ID","name":"String","group":"Enum","group_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event category-created **Event topic** : `ebaycclone-categorymanagement-service-category-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `category` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`category`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"category","method":"POST","action":"create","appVersion":"Version","rowCount":1,"category":{"id":"ID","imageUrl":"String","subtitle":"String","title":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` # Copyright All sources, documents and other digital materials are copyright of . # About Us For more information please visit our website: . . . # **EBAYCCLONE** FRONTEND GUIDE FOR AI CODING AGENTS This document is a rest api guide for the ebaycclone project. The document is designed for AI agents who will generate frontend code that will consume the project backend. The project has got 1 auth service, 1 notification service, 1 bff service and business services. Each service is a separate microservice application and listens the HTTP request from different service urls. The services may be in preview server, staging server or real production server. So each service have got 3 acess urls. Frontend application should support all deployemnt servers in the development phase, and user should be able to select the target api server in the login page. ## Project Introduction ebaycClone is a comprehensive backend for an online marketplace supporting auctions and fixed-price sales of physical goods, with role-based access, public user registration, Stripe payments, notifications, and robust ownership enforcement. ## API Structure ### Object Structure of a Successfull Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client. **HTTP Status Codes:** - **200 OK**: This status code is returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request has been processed successfully. - **201 Created**: This status code is specific to CREATE operations, signifying that the requested resource has been successfully created. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling the successful execution of the request. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` - **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation performed. ### Additional Data Each api may have include addtional data other than the main data object according to the business logic of the API. They will be given in each API's response signature. ### Error Response If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity: - **400 Bad Request**: The request was improperly formatted or contained invalid parameters, preventing the server from processing it. - **401 Unauthorized**: The request lacked valid authentication token , login required - **403 Forbidden Error** Curent token provided do not grant access to the requested resource. - **404 Not Found**: The requested resource was not found on the server. - **500 Internal Server Error**: The server encountered an unexpected condition that prevented it from fulfilling the request. Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Accessing the backend Each service of the backend has got its own url according to the deployment environement. User may want to test the frontend in one of the 3 deployments of the application, preview, staging and production. Please ensure that register and login pages do have a deployemnt server selection option, so as the frontned coding agent you can arrange the base url path of all services. The base url of the application in each environment is as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com` * **Staging:** `https://ebaycclone-stage.mindbricks.co` * **Production:** `https://ebaycclone.mindbricks.co` For the auth service the base url is as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` For each other service, the service base url will be given in service sections. Any login requied request to the backend should have a valid token, when a user makes a successfull login, the ressponse JSON includes a JWT access token in the `accessToken`fields. In normal conditions, this token is also set to the cookie and then consumed automatically, but since AI coding agents preview options may fail to use cookies, please ensure that in each request include the access token in the bearer auth header. ## Registration Management First of all please ensure that register and login pages do have a deployemnt server selection option, so as the frontned coding agent you can arrange the base url path of all services. Start with a landing page and arranging register, verification and login flow. So at the first step, you need a general knowledge of the application to make a good landing page and the authetication flow. ### How To Register Using `registeruser` route of auth api, send the required fields to the backend in your registration page. The registerUser api in in `auth` service, is described with request and response structure below. Note that since `registerUser` api is a business api, it has a version control, so please call it with the given version like `/v1/registeruser` ### `Register User` API This api is used by public users to register themselves **Rest Route** The `registerUser` API REST controller can be triggered via the following route: `/v1/registeruser` **Rest Request Parameters** The `registerUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **password** : The password defined by the the user that is being registered. **fullname** : The fullname defined by the the user that is being registered. **email** : The email defined by the the user that is being registered. **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` After a successful registration, frontend code should handle the verification needs. The registration response will have a `user` object in the root envelope, this object will have user information with an `id` parameter. ### Email Verification In the registration response, you should check the property `emailVerificationNeeded` in the reponse root, and if this property is true you should start the email verification flow. After login process, if you get an HTTP error status, and if there is an `errCode` property in the response with `EmailVerificationNeeded` value, you should start the email verification flow. 1. Call the email verification `start` route of the backend (described below) with the user email, backend will send a secret code to the given email adresss. **Backend can send the email message if the architect defined a real mail service or smtp server, so during the development time backend will send the secret code also to the frontend. You can get this secret code from the response within the `secretCode` property**. 2. The secret code in the sent email message will be a 6 digits code , and you should arrange an input page so that the user can paste this code to the frontend application. Please navigate to this input page after you start the verification process. **If the secretCode is sent to the frontend for test purposes, then you should show it as info in the input page, so that user can copy and paste it**. 3. There is a `codeIndex` property in the start response, please show it's value on the input page, so that user can match the index in the message with the one on the screen. 4. When the user submits the code, please complete the email verification using the `complete` route of the backend (described below) with the user email and the secret code. 5. After you get a successful response from email verification, you can navigate to the login page. Here is the `start`and `complete` routes of email verification. These are system routes , so they dont have a version control. #### `POST /verification-services/email-verification/start` **Purpose:** Starts the email verification by generating and sending a secret code. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `email` | String | Yes | User’s email address to verify | **Example Request** ```json { "email": "user@example.com" } ``` **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ In production, `secretCode` is **not** returned — only sent via email. **Error Responses** * `400 Bad Request`: Already verified * `403 Forbidden`: Too many attempts (rate limit) --- #### `POST /verification-services/email-verification/complete` **Purpose:** Completes the verification using the received code. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `email` | String | Yes | User’s email | | `secretCode` | String | Yes | Verification code | **Success Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` **Error Responses** * `403 Forbidden`: Code expired or mismatched * `404 Not Found`: No verification in progress --- ## Login Management After a successfull login and completing required verifications, user can now login. Please make a fancy minimal login page where user can enter his email and password. ## Bucket Management This application has a bucket service and is used to store user or other objects related files. Bucket service is login agnostic, so when accessing for write or private read, you should insert a bucket token (given by services) to your request authorization header as bearer token. **User Bucket** This bucket is used to store public user files for each user. When a user logs in, or in /currentuser response there is `userBucketToken` to be used when sending user related public files to the bucket service. To upload `POST {baseUrl}/bucket/upload` Request body is form data which includes the bucketId and the file as binary in `files` property. ```js { bucketId: "{userId}-public-user-bucket", files: {binary} } ``` Response status is 200 on succesfull result, eg body: ```json { "success": true, "data": [ { "fileId": "9da03f6d-0409-41ad-bb06-225a244ae408", "originalName": "test (10).png", "mimeType": "image/png", "size": 604063, "status": "uploaded", "bucketName": "f7103b85-fcda-4dec-92c6-c336f71fd3a2-public-user-bucket", "isPublic": true, "downloadUrl": "https://babilcom.mindbricks.co/bucket/download/9da03f6d-0409-41ad-bb06-225a244ae408" } ] } ``` To download a file from the bucket, you should know its fileId, so if youupload an avatar or something else, be sure that the download url or the fileId is stored in backend. Bucket is mostly used, in object creations where alos demands an addtional file like a product image or user avatar. So after you upload your image to the bucket, insert the returned download url to the related property in the related object creation. **Application Bucket** This Ebaycclone application alos has common public bucket which everybody has a read access, but only users who have `superAdmin`, `admin` or `saasAdmin` roles can write (upload) to the bucket. The common public project bucket id is `"ebaycclone-public-common-bucket"` and in certain areas like product image uploads, since the user will already have the admin bucket token, he will be able to upload realted object images. Please make your UI arrangements as able to upload files to the bucket using these bucket tokens. **Object Buckets** Some objects may return also a bucket token, to upload or access related files with object. For example, when you get a project's data in a project management application, if there is a public or private bucket token, this is provided mostly for uploading project related files or downloading them with the token. These buckets will be used according to the descriptions given along with the object definitions. ## Role Management This Ebaycclone may have different role names defined fro different business logic. But unless another case is asked by the user, respect to the admin roles which may be `superAdmin`, `admin` or `saasAdmin` in the currentuser or login response given with the `roleId`property. ```json { // ... "roleId":"superAdmin", // ... } ``` If the application needs an admin panel, or any admin related page, please use these roleId's to decide if the user can access those pages or not. ## 1. Authentication Routes ### 1.1 `POST /login` — User Login **Purpose:** Verifies user credentials and creates an authenticated session with a JWT access token. **Access Routes:** * `GET /login`: Returns a minimal HTML login page (for browser-based testing). * `POST /login`: Authenticates user credentials and returns an access token and session. #### Request Parameters | Parameter | Type | Required | Source | | ---------- | ------ | -------- | ----------------------- | | `username` | String | Yes | `request.body.username` | | `password` | String | Yes | `request.body.password` | #### Behavior * Authenticates credentials and returns a session object. * Sets cookie: `projectname-access-token[-tenantCodename]` * Adds the same token in response headers. * Accepts either `username` or `email` fields (if both exist, `username` is prioritized). #### Example ```js axios.post("/login", { username: "user@example.com", password: "securePassword" }); ``` #### Success Response ```json { "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", //... } ``` #### Error Responses * `401 Unauthorized`: Invalid credentials * `403 Forbidden`: Email/mobile verification or 2FA pending * `400 Bad Request`: Missing parameters --- ### 1.2 `POST /logout` — User Logout **Purpose:** Terminates the current session and clears associated authentication tokens. #### Behavior * Invalidates session (if exists). * Clears cookie `projectname-access-token[-tenantCodename]`. * Returns a confirmation response (always `200 OK`). #### Example ```js axios.post("/logout", {}, { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` #### Notes * Can be called without a session (idempotent behavior). * Works for both cookie-based and token-based sessions. #### Success Response ```json { "status": "OK", "message": "User logged out successfully" } ``` --- ## 2. Verification Services Overview All verification routes are grouped under the `/verification-services` base path. They follow a **two-step verification pattern**: `start` → `complete`. --- ## 3. Email Verification ### 3.1 Trigger Scenarios * After registration (`emailVerificationRequiredForLogin` = true) * When updating email address * When login fails due to unverified email ### 3.2 Flow Summary 1. `/start` → Generate & send code via email. 2. `/complete` → Verify code and mark email as verified. ** PLEASE NOTE ** Email verification is a frontend triiggered process. After user registers, the frontend should start the email verification process and navigate to its code input page. --- ### 3.3 `POST /verification-services/email-verification/start` **Purpose:** Starts the email verification by generating and sending a secret code. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `email` | String | Yes | User’s email address to verify | **Example Request** ```json { "email": "user@example.com" } ``` **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ In production, `secretCode` is **not** returned — only sent via email. **Error Responses** * `400 Bad Request`: Already verified * `403 Forbidden`: Too many attempts (rate limit) --- ### 3.4 `POST /verification-services/email-verification/complete` **Purpose:** Completes the verification using the received code. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `email` | String | Yes | User’s email | | `secretCode` | String | Yes | Verification code | **Success Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` **Error Responses** * `403 Forbidden`: Code expired or mismatched * `404 Not Found`: No verification in progress --- ### 3.5 Behavioral Notes * **Resend Cooldown:** `resendTimeWindow` (e.g. 60s) * **Expiration:** Codes expire after `expireTimeWindow` (e.g. 1 day) * **Single Active Session:** One verification per user --- ## 4. Mobile Verification ### 4.1 Trigger Scenarios * After registration (`mobileVerificationRequiredForLogin` = true) * When updating phone number * On login requiring mobile verification ### 4.2 Flow 1. `/start` → Sends verification code via SMS 2. `/complete` → Validates code and confirms number --- ### 4.3 `POST /verification-services/mobile-verification/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------ | | `email` | String | Yes | User’s email to locate mobile record | **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 180, "verificationType": "byCode", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ `secretCode` returned only in development. **Errors** * `400 Bad Request`: Already verified * `403 Forbidden`: Rate-limited --- ### 4.4 `POST /verification-services/mobile-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------------- | | `email` | String | Yes | Associated email | | `secretCode` | String | Yes | Code received via SMS | **Success Response** ```json { "status": "OK", "isVerified": true, "mobile": "+1 333 ...", // in testMode "userId": "user-uuid", } ``` --- ### 4.5 Behavioral Notes * **Cooldown:** One code per minute * **Expiration:** Codes valid for 1 day * **One Session Per User** --- ## 5. Two-Factor Authentication (2FA) ### 5.1 Email 2FA **Flow** 1. `/start` → Generates and sends email code 2. `/complete` → Verifies code and updates session --- #### `POST /verification-services/email-2factor-verification/start` | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ---------------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Current session | | `client` | String | No | Optional context | | `reason` | String | No | Reason for 2FA | **Response** ```json { "status": "OK", "sessionId": "user session id UUID", "userId": "user-uuid", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", } ``` --- #### `POST /verification-services/email-2factor-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `secretCode` | String | Yes | Code from email | **Response** ```json { // user session data "sessionId": "session-uuid", // ... } ``` --- ### 5.2 Mobile 2FA **Flow** 1. `/start` → Sends SMS code 2. `/complete` → Validates and finalizes session --- #### `POST /verification-services/mobile-2factor-verification/start` | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ----------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `client` | String | No | Context | | `reason` | String | No | Reason | **Response** ```json { "status": "OK", "sessionId": "user session id UUID", "userId": "user-uuid", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", } ``` --- #### `POST /verification-services/mobile-2factor-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------ | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `secretCode` | String | Yes | Code via SMS | **Response** ```json { // user session data "sessionId": "session-uuid", // ... } ``` --- ### 5.3 2FA Behavioral Notes * One active code per session * Cooldown: `resendTimeWindow` (e.g., 60s) * Expiration: `expireTimeWindow` (e.g., 5m) --- ## 6. Password Reset ### 6.1 By Email **Flow** 1. `/start` → Sends verification code via email 2. `/complete` → Validates and resets password --- #### `POST /verification-services/password-reset-by-email/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------- | | `email` | String | Yes | User email | **Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` #### `POST /verification-services/password-reset-by-email/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------- | | `email` | String | Yes | User email | | `secretCode` | String | Yes | Code received | | `password` | String | Yes | New password | **Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` --- ### 6.2 By Mobile **Flow** 1. `/start` → Sends SMS code 2. `/complete` → Validates and resets password --- #### `POST /verification-services/password-reset-by-mobile/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------- | | `mobile` | String | Yes | Mobile number | **Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` #### `POST /verification-services/password-reset-by-mobile/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ---------------- | | `email` | String | Yes | Associated email | | `secretCode` | String | Yes | Code via SMS | | `password` | String | Yes | New password | **Response** ```json { "status": "OK", "isVerified": true, "mobile": "+1 444 ....", // in testMode "userId": "user-uuid", } ``` --- ### 6.3 Behavioral Notes * Cooldown: 60s resend * Expiration: 24h * One session per user * Works without an active login session --- ## 7. Verification Method Types ### 7.1 `byCode` User manually enters the 6-digit code in frontend. ### 7.2 `byLink` Frontend handles a one-click verification via email/SMS link containing code parameters. ## 8) `GET /currentuser` — Current Session **Purpose** Return the currently authenticated user’s session. **Route Type** `sessionInfo` **Authentication** Requires a valid access token (header or cookie). ### Request *No parameters.* ### Example ```js axios.get("/currentuser", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) Returns the session object (identity, tenancy, token metadata): ```json { "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", "roleId": "user", "tenantId": "abc123", "accessToken": "jwt-token-string", "...": "..." } ``` ### Errors * **401 Unauthorized** — No active session/token ```json { "status": "ERR", "message": "No login found" } ``` **Notes** * Commonly called by web/mobile clients after login to hydrate session state. * Includes key identity/tenant fields and a token reference (if applicable). * Ensure a valid token is supplied to receive a 200 response. --- ## 9) `GET /permissions` — List Effective Permissions **Purpose** Return all effective permission grants for the current user. **Route Type** `permissionFetch` **Authentication** Requires a valid access token. ### Request *No parameters.* ### Example ```js axios.get("/permissions", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) Array of permission grants (aligned with `givenPermissions`): ```json [ { "id": "perm1", "permissionName": "adminPanel.access", "roleId": "admin", "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" }, { "id": "perm2", "permissionName": "orders.manage", "roleId": null, "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" } ] ``` **Field meanings (per item):** * `permissionName`: Granted permission key. * `roleId`: Present if granted via role. * `subjectUserId`: Present if granted directly to the user. * `subjectUserGroupId`: Present if granted via group. * `objectId`: Present if scoped to a specific object (OBAC). * `canDo`: `true` if enabled, `false` if restricted. ### Errors * **401 Unauthorized** — No active session ```json { "status": "ERR", "message": "No login found" } ``` * **500 Internal Server Error** — Unexpected failure **Notes** * Available on all Mindbricks-generated services (not only Auth). * **Auth service:** Reads live `givenPermissions` from DB. * **Other services:** Typically respond from a cached/projected view (e.g., ElasticSearch) for faster checks. > **Tip:** Cache permission results client-side/server-side and refresh after login or permission updates. --- ## 10) `GET /permissions/:permissionName` — Check Permission Scope **Purpose** Check whether the current user has a specific permission and return any scoped object exceptions/inclusions. **Route Type** `permissionScopeCheck` **Authentication** Requires a valid access token. ### Path Parameters | Name | Type | Required | Source | | ---------------- | ------ | -------- | ------------------------------- | | `permissionName` | String | Yes | `request.params.permissionName` | ### Example ```js axios.get("/permissions/orders.manage", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) ```json { "canDo": true, "exceptions": [ "a1f2e3d4-xxxx-yyyy-zzzz-object1", "b2c3d4e5-xxxx-yyyy-zzzz-object2" ] } ``` **Interpretation** * If `canDo: true`: permission is generally granted **except** the listed `exceptions` (restrictions). * If `canDo: false`: permission is generally **not** granted, **only** allowed for the listed `exceptions` (selective overrides). * `exceptions` contains object IDs (UUID strings) from the relevant domain model. ### Errors * **401 Unauthorized** — No active session/token. ## Services And Data Object ## Auth Service Authentication service for the project ### Auth Service Data Objects **User** A data object that stores the user information and handles login settings. ### Auth Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` ### `Get User` API This api is used by admin roles or the users themselves to get the user profile information. **Rest Route** The `getUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `getUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users/:userId** ```js axios({ method: 'GET', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update User` API This route is used by admins to update user profiles. **Rest Route** The `updateUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `updateUser` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/users/:userId** ```js axios({ method: 'PATCH', url: `/v1/users/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Profile` API This route is used by users to update their profiles. **Rest Route** The `updateProfile` API REST controller can be triggered via the following route: `/v1/profile/:userId` **Rest Request Parameters** The `updateProfile` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/profile/:userId** ```js axios({ method: 'PATCH', url: `/v1/profile/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create User` API This api is used by admin roles to create a new user manually from admin panels **Rest Route** The `createUser` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `createUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | email | String | true | request.body?.email | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **email** : A string value to represent the user's email. **password** : A string value to represent the user's password. It will be stored as hashed. **fullname** : A string value to represent the fullname of the user **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/users** ```js axios({ method: 'POST', url: '/v1/users', data: { avatar:"String", email:"String", password:"String", fullname:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete User` API This api is used by admins to delete user profiles. **Rest Route** The `deleteUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `deleteUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/users/:userId** ```js axios({ method: 'DELETE', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Archive Profile` API This api is used by users to archive their profiles. **Rest Route** The `archiveProfile` API REST controller can be triggered via the following route: `/v1/archiveprofile/:userId` **Rest Request Parameters** The `archiveProfile` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/archiveprofile/:userId** ```js axios({ method: 'DELETE', url: `/v1/archiveprofile/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Users` API The list of users is filtered by the tenantId. **Rest Route** The `listUsers` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `listUsers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users** ```js axios({ method: 'GET', url: '/v1/users', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Search Users` API The list of users is filtered by the tenantId. **Rest Route** The `searchUsers` API REST controller can be triggered via the following route: `/v1/searchusers` **Rest Request Parameters** The `searchUsers` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | keyword | String | true | request.query?.keyword | **keyword** : **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchusers** ```js axios({ method: 'GET', url: '/v1/searchusers', data: { }, params: { keyword:'"String"', } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Userrole` API This route is used by admin roles to update the user role.The default role is user when a user is registered. A user's role can be updated by superAdmin or admin **Rest Route** The `updateUserRole` API REST controller can be triggered via the following route: `/v1/userrole/:userId` **Rest Request Parameters** The `updateUserRole` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | roleId | String | true | request.body?.roleId | **userId** : This id paremeter is used to select the required data object that will be updated **roleId** : The new roleId of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userrole/:userId** ```js axios({ method: 'PATCH', url: `/v1/userrole/${userId}`, data: { roleId:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpassword` API This route is used to update the password of users in the profile page by users themselves **Rest Route** The `updateUserPassword` API REST controller can be triggered via the following route: `/v1/userpassword/:userId` **Rest Request Parameters** The `updateUserPassword` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | oldPassword | String | true | request.body?.oldPassword | | newPassword | String | true | request.body?.newPassword | **userId** : This id paremeter is used to select the required data object that will be updated **oldPassword** : The old password of the user that will be overridden bu the new one. Send for double check. **newPassword** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpassword/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpassword/${userId}`, data: { oldPassword:"String", newPassword:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpasswordbyadmin` API This route is used to change any user password by admins only. Superadmin can chnage all passwords, admins can change only nonadmin passwords **Rest Route** The `updateUserPasswordByAdmin` API REST controller can be triggered via the following route: `/v1/userpasswordbyadmin/:userId` **Rest Request Parameters** The `updateUserPasswordByAdmin` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | password | String | true | request.body?.password | **userId** : This id paremeter is used to select the required data object that will be updated **password** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpasswordbyadmin/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpasswordbyadmin/${userId}`, data: { password:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Briefuser` API This route is used by public to get simple user profile information. **Rest Route** The `getBriefUser` API REST controller can be triggered via the following route: `/v1/briefuser/:userId` **Rest Request Parameters** The `getBriefUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/briefuser/:userId** ```js axios({ method: 'GET', url: `/v1/briefuser/${userId}`, data: { }, params: { } }); ``` **REST Response** This route's response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "fullname": "String", "avatar": "String", "isActive": true } } ``` ### `Register User` API This api is used by public users to register themselves **Rest Route** The `registerUser` API REST controller can be triggered via the following route: `/v1/registeruser` **Rest Request Parameters** The `registerUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **password** : The password defined by the the user that is being registered. **fullname** : The fullname defined by the the user that is being registered. **email** : The email defined by the the user that is being registered. **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## AuctionOffer Service Handles auction bids and fixed-price offers for product listings, enforces real-time auction state, handles strict offer workflows including counter-offers, and triggers domain events for bid/offer notifications. No payment or frontend aggregation logic included. ### AuctionOffer Service Data Objects **AuctionOfferOffer** Represents an offer (best offer/counter-offer) made on a fixed-price product. Tracks buyer, seller, amounts, currency, state transitions, counter-offers, and expiry. **AuctionOfferBid** Represents an individual bid placed on an auction-type product. Linked to product and user, tracks bid amount, currency, status (ACTIVE, WON, LOST, CANCELLED), and time placed. ### AuctionOffer Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auctionoffer-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auctionoffer-api` * **Production:** `https://ebaycclone.mindbricks.co/auctionoffer-api` ### `Update Auctionofferoffer` API Updates offer: accepts/declines/counters by seller, withdraws by buyer before response. Enforces status transition rules, sets respondedAt. Triggers event. **Rest Route** The `updateAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `updateAuctionOfferOffer` api has got 8 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | message | String | false | request.body?.message | | status | Enum | false | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | **auctionOfferOfferId** : This id paremeter is used to select the required data object that will be updated **counterOfferId** : References another offer (counter-offer chain). **counterMessage** : Message accompanying seller's counter-offer (optional). **counterAmount** : Counter-offer amount (when offer is COUNTERED). **message** : Message/special notes from buyer (optional). **status** : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). **expiresAt** : When this offer expires (optional). **respondedAt** : When the seller (or buyer, for counter-offer) responded/updated the offer status. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Auctionofferbid` API Creates a new bid for an auction product. Validates auction status, not seller, product type, bid window, and ensures min. increment. Updates product.currentBid and product.highestBidderId atomically. Triggers notification event. **Rest Route** The `createAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids` **Rest Request Parameters** The `createAuctionOfferBid` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | bidAmount | Double | true | request.body?.bidAmount | | currency | String | true | request.body?.currency | | status | Enum | true | request.body?.status | | productId | ID | true | request.body?.productId | **bidAmount** : Bid amount placed by the user. **currency** : ISO currency for the bid (e.g., USD, EUR). **status** : Bid status: ACTIVE, WON, LOST, CANCELLED. **productId** : Product being bid on (must be AUCTION type). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/auctionofferbids** ```js axios({ method: 'POST', url: '/v1/auctionofferbids', data: { bidAmount:"Double", currency:"String", status:"Enum", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Auctionofferbid` API Gets a single bid (only visible to owner/admin or for auction history). **Rest Route** The `getAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `getAuctionOfferBid` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | **auctionOfferBidId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'GET', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Auctionofferoffer` API Gets a single offer (shown to buyer/seller or admin). **Rest Route** The `getAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `getAuctionOfferOffer` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | **auctionOfferOfferId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'GET', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Auctionofferoffers` API Lists offers by product, user, status, or counterOffer chain. **Rest Route** The `listAuctionOfferOffers` API REST controller can be triggered via the following route: `/v1/auctionofferoffers` **Rest Request Parameters** The `listAuctionOfferOffers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers** ```js axios({ method: 'GET', url: '/v1/auctionofferoffers', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferOffers": [ { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Auctionofferbid` API Updates a bid’s status (allow only status update, e.g. CANCELLED, WIN/LOSE on admin settlement). Only owner/admin, and only if auction not ended or not settled. Triggers notification event. **Rest Route** The `updateAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `updateAuctionOfferBid` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | | status | Enum | false | request.body?.status | **auctionOfferBidId** : This id paremeter is used to select the required data object that will be updated **status** : Bid status: ACTIVE, WON, LOST, CANCELLED. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { status:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Auctionofferoffer` API Creates a new offer for a fixed-price product, validating acceptOffers, type, eligibility, and product/seller/buyer active. Defaults to PENDING state. Triggers notification event. **Rest Route** The `createAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers` **Rest Request Parameters** The `createAuctionOfferOffer` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | productId | ID | true | request.body?.productId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | offerAmount | Double | true | request.body?.offerAmount | | message | String | false | request.body?.message | | status | Enum | true | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | **currency** : ISO currency (e.g., USD, EUR) for the offer. **productId** : Product the offer applies to (must be fixed-price, acceptOffers true). **counterOfferId** : References another offer (counter-offer chain). **counterMessage** : Message accompanying seller's counter-offer (optional). **counterAmount** : Counter-offer amount (when offer is COUNTERED). **offerAmount** : Primary offer amount from buyer. **message** : Message/special notes from buyer (optional). **status** : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). **expiresAt** : When this offer expires (optional). **respondedAt** : When the seller (or buyer, for counter-offer) responded/updated the offer status. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/auctionofferoffers** ```js axios({ method: 'POST', url: '/v1/auctionofferoffers', data: { currency:"String", productId:"ID", counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", offerAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Auctionofferbids` API Lists bids by product, user, or auction, supports history/analytics. **Rest Route** The `listAuctionOfferBids` API REST controller can be triggered via the following route: `/v1/auctionofferbids` **Rest Request Parameters** The `listAuctionOfferBids` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids** ```js axios({ method: 'GET', url: '/v1/auctionofferbids', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBids", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferBids": [ { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Auctionofferbid` API Soft-deletes a bid (for admin or self before auction ends). **Rest Route** The `deleteAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `deleteAuctionOfferBid` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | **auctionOfferBidId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Auctionofferoffer` API Soft-deletes an offer (allowed only in non-accepted/expired state). **Rest Route** The `deleteAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `deleteAuctionOfferOffer` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | **auctionOfferOfferId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## CategoryManagement Service Handles product categories and subcategories for marketplace browsing and classification, supporting public discovery plus admin-only management. ### CategoryManagement Service Data Objects **Category** Represents a product category in the marketplace (e.g., Electronics, Clothing, Toys), used for browsing, filtering, and discovery. Admins manage categories. **Subcategory** Represents a subcategory within a parent category (e.g., 'Smartphones' under 'Electronics'). Used for more granular product discovery and navigation. 'group' categorizes special display logic. ### CategoryManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/categorymanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/categorymanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/categorymanagement-api` ### `Delete Category` API Soft-delete a category (admin-only). **Rest Route** The `deleteCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `deleteCategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | **categoryId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/categories/:categoryId** ```js axios({ method: 'DELETE', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Subcategory` API Get a subcategory by ID. Public - only active subcategories returned except for admin. **Rest Route** The `getSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `getSubcategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | **subcategoryId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/subcategories/:subcategoryId** ```js axios({ method: 'GET', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Category` API Get a single category by ID. Public - only active categories returned (for non-admins). **Rest Route** The `getCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `getCategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | **categoryId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/categories/:categoryId** ```js axios({ method: 'GET', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Subcategory` API Update subcategory (admin-only), including group enum change. **Rest Route** The `updateSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `updateSubcategory` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | name | String | false | request.body?.name | | group | Enum | false | request.body?.group | **subcategoryId** : This id paremeter is used to select the required data object that will be updated **categoryId** : Reference to the parent category (category.id). **name** : Display name of the subcategory. **group** : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/subcategories/:subcategoryId** ```js axios({ method: 'PATCH', url: `/v1/subcategories/${subcategoryId}`, data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Subcategories` API List all subcategories for browsing/filtering, with support for group enum and parent category queries. Only active subcategories shown to public/non-admin users. **Rest Route** The `listSubcategories` API REST controller can be triggered via the following route: `/v1/subcategories` **Rest Request Parameters** The `listSubcategories` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/subcategories** ```js axios({ method: 'GET', url: '/v1/subcategories', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "subcategories": [ { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Subcategory` API Soft-delete a subcategory (admin-only). **Rest Route** The `deleteSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `deleteSubcategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | **subcategoryId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/subcategories/:subcategoryId** ```js axios({ method: 'DELETE', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Categories` API List all categories for browsing and filtering. Only active categories shown to public/non-admin users. **Rest Route** The `listCategories` API REST controller can be triggered via the following route: `/v1/categories` **Rest Request Parameters** The `listCategories` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/categories** ```js axios({ method: 'GET', url: '/v1/categories', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "categories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "categories": [ { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Category` API Update category details (admin-only). **Rest Route** The `updateCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `updateCategory` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | false | request.body?.title | **categoryId** : This id paremeter is used to select the required data object that will be updated **imageUrl** : URL for category image/avatar (optional, used for homepage visuals). **subtitle** : Optional short description for UI/tooltips. **title** : Display name of the category. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/categories/:categoryId** ```js axios({ method: 'PATCH', url: `/v1/categories/${categoryId}`, data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Subcategory` API Create a new subcategory under a given category (admin-only), with enum group constraint. **Rest Route** The `createSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories` **Rest Request Parameters** The `createSubcategory` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.body?.categoryId | | name | String | true | request.body?.name | | group | Enum | true | request.body?.group | **categoryId** : Reference to the parent category (category.id). **name** : Display name of the subcategory. **group** : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/subcategories** ```js axios({ method: 'POST', url: '/v1/subcategories', data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Category` API Create a new category (admin-only) for product classification. **Rest Route** The `createCategory` API REST controller can be triggered via the following route: `/v1/categories` **Rest Request Parameters** The `createCategory` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | true | request.body?.title | **imageUrl** : URL for category image/avatar (optional, used for homepage visuals). **subtitle** : Optional short description for UI/tooltips. **title** : Display name of the category. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/categories** ```js axios({ method: 'POST', url: '/v1/categories', data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## Messaging Service In-app messaging service for direct user-to-user text messages (buyers/sellers). Stores, retrieves, and manages user conversations. Launch version: text-only. ### Messaging Service Data Objects **MessagingMessage** A direct, text-only in-app message between two users (buyer/seller); stores sender, recipient, content, read status, and timestamp. ### Messaging Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/messaging-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/messaging-api` * **Production:** `https://ebaycclone.mindbricks.co/messaging-api` ### `List Messagingmessages` API List all messages in the conversation between the logged-in user and another party, ordered by sentAt descending. Can filter unread with isRead. Returns only messages visible to user (isActive). **Rest Route** The `listMessagingMessages` API REST controller can be triggered via the following route: `/v1/messagingmessages` **Rest Request Parameters** The `listMessagingMessages` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages** ```js axios({ method: 'GET', url: '/v1/messagingmessages', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessages", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "messagingMessages": [ { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Messagingmessage` API Send a new text message from the logged-in user to a recipient. Sender is set from session. Launch version supports only text content. **Rest Route** The `createMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages` **Rest Request Parameters** The `createMessagingMessage` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | toUserId | ID | true | request.body?.toUserId | | content | String | true | request.body?.content | | isRead | Boolean | true | request.body?.isRead | **toUserId** : Recipient (user) of this message. **content** : Text content of the message. No files or attachments for launch. **isRead** : If true, recipient has marked this message as read. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/messagingmessages** ```js axios({ method: 'POST', url: '/v1/messagingmessages', data: { toUserId:"ID", content:"String", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Messagingmessage` API Update a message (mark as read/unread). Only the recipient or admin can change isRead. No content edits. Sender, content, sentAt are immutable. **Rest Route** The `updateMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `updateMessagingMessage` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | | isRead | Boolean | false | request.body?.isRead | **messagingMessageId** : This id paremeter is used to select the required data object that will be updated **isRead** : If true, recipient has marked this message as read. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'PATCH', url: `/v1/messagingmessages/${messagingMessageId}`, data: { isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Messagingmessage` API Get a message by ID. Only accessible to the sender, the recipient, or an admin. Used for message detail view or reading a single message in a thread. **Rest Route** The `getMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `getMessagingMessage` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | **messagingMessageId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'GET', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Messagingmessage` API Delete a message (soft-delete). Only sender, recipient, or admin may delete a message. Deletion only hides it for the user; not a full erase unless both delete. **Rest Route** The `deleteMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `deleteMessagingMessage` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | **messagingMessageId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'DELETE', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## NotificationManagement Service Handles storage, management, and event-driven delivery of in-app and email notifications for user-impacting system events (bids, offers, orders, feedback, messaging, etc.). Supports marking notifications as read/unread, structured filtering by event type/channel, and always returns in-app notifications ordered by recency. ### NotificationManagement Service Data Objects **Notification** Stores and manages in-app and email notifications tied to user-facing events like bids, offers, orders, messaging, shipment, and feedback. Includes event type (notificationType) for filter/search, arbitrary event payload, and delivery channel. Soft-delete enforced. In-app notifications always sorted by createdAt DESC on retrieval. ### NotificationManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/notificationmanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/notificationmanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/notificationmanagement-api` ### `Create Notification` API Creates a notification entry in response to a system/business event. Only allowed for system/event processes and admins (not standard user/action). Typically event-driven, receives userId, notificationType, payload, and channel. **Rest Route** The `createNotification` API REST controller can be triggered via the following route: `/v1/notifications` **Rest Request Parameters** The `createNotification` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationType | Enum | true | request.body?.notificationType | | userId | ID | true | request.body?.userId | | channel | Enum | true | request.body?.channel | | payload | Object | true | request.body?.payload | | isRead | Boolean | true | request.body?.isRead | **notificationType** : Type of event triggering notification (e.g., BID_UPDATED, ORDER_SHIPPED, MESSAGE_RECEIVED, etc.). Used for display/icon and query filter. **userId** : User receiving the notification (recipient). **channel** : Channel by which notification is delivered: IN_APP or EMAIL. **payload** : Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. **isRead** : Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/notifications** ```js axios({ method: 'POST', url: '/v1/notifications', data: { notificationType:"Enum", userId:"ID", channel:"Enum", payload:"Object", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Notification` API Updates a notification (mark as read/unread, payload patch for e.g. admin fix). Only receiver (userId) or admins may update. isRead is primary update scenario; others very limited. **Rest Route** The `updateNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `updateNotification` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | | payload | Object | false | request.body?.payload | | isRead | Boolean | false | request.body?.isRead | **notificationId** : This id paremeter is used to select the required data object that will be updated **payload** : Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. **isRead** : Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/notifications/:notificationId** ```js axios({ method: 'PATCH', url: `/v1/notifications/${notificationId}`, data: { payload:"Object", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Notifications` API Returns filtered list of notifications for a user, with optional filters: notificationType, isRead, channel. Always sorted by createdAt (descending) for in-app notifications. Only retrieval allowed for owner/admin. **Rest Route** The `listNotifications` API REST controller can be triggered via the following route: `/v1/notifications` **Rest Request Parameters** The `listNotifications` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/notifications** ```js axios({ method: 'GET', url: '/v1/notifications', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notifications", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "notifications": [ { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Notification` API Soft-delete a notification record. Only receiver or admin may delete. **Rest Route** The `deleteNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `deleteNotification` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | **notificationId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/notifications/:notificationId** ```js axios({ method: 'DELETE', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Notification` API Retrieves a notification for the receiver or admin. Used to populate content on detail/expanded view. **Rest Route** The `getNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `getNotification` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | **notificationId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/notifications/:notificationId** ```js axios({ method: 'GET', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## SearchIndexing Service Maintains the denormalized search index (materialized view) for global, public search across products, sellers, categories, and subcategories. Handles indexing in response to entity events and exposes optimized query endpoints for BFF/aggregator. ### SearchIndexing Service Data Objects **SearchIndex** Materialized/denormalized search index record for a marketplace entity (product, seller, category, subcategory). Used exclusively for high-speed querying in BFF global/public search. ### SearchIndexing Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/searchindexing-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/searchindexing-api` * **Production:** `https://ebaycclone.mindbricks.co/searchindexing-api` ### `List Searchindexes` API List/search search index entries by type or referenceId (used by BFF/global search). Always excludes inactive (soft-deleted) records. Supports filtering and full-text search filters by documentType/referenceId for admin/maintenance use. **Rest Route** The `listSearchIndexes` API REST controller can be triggered via the following route: `/v1/searchindexes` **Rest Request Parameters** The `listSearchIndexes` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchindexes** ```js axios({ method: 'GET', url: '/v1/searchindexes', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndices", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "searchIndices": [ { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Searchindex` API Update an existing searchIndex record (by (documentType, referenceId) or id). Used in response to events (entity edit, data change); internal/automation/admin only. **Rest Route** The `updateSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `updateSearchIndex` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | | documentType | Enum | false | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | false | request.body?.indexedAt | **searchIndexId** : This id paremeter is used to select the required data object that will be updated **documentType** : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY **document** : Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. **referenceId** : ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. **indexedAt** : Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/searchindexs/:searchIndexId** ```js axios({ method: 'PATCH', url: `/v1/searchindexs/${searchIndexId}`, data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Searchindex` API Soft-delete a searchIndex record (by id or by (documentType, referenceId)). Typical use: in response to entity soft-delete; internal/automation/admin only. **Rest Route** The `deleteSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `deleteSearchIndex` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | **searchIndexId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/searchindexs/:searchIndexId** ```js axios({ method: 'DELETE', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Searchindex` API Create a new searchIndex record (internal, used by event triggers and admin tools only). Typically called when a new product/seller/category/subcategory is created. **Rest Route** The `createSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs` **Rest Request Parameters** The `createSearchIndex` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | documentType | Enum | true | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | true | request.body?.indexedAt | **documentType** : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY **document** : Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. **referenceId** : ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. **indexedAt** : Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/searchindexs** ```js axios({ method: 'POST', url: '/v1/searchindexs', data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Searchindex` API Get a single denormalized index record (by id, or documentType+referenceId). Used by BFF for full entity search. Always excludes inactive records unless forced (admin only path). **Rest Route** The `getSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `getSearchIndex` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | **searchIndexId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchindexs/:searchIndexId** ```js axios({ method: 'GET', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## AdminModeration Service Administrative backend service for moderation and manual override actions. Responsible for logging all admin interventions (user/product/feedback/media/category/order/notification/searchindex moderation), triggering corrections via interservice calls, and providing comprehensive audit trails for compliance. ### AdminModeration Service Data Objects **ModerationAction** Audit record for all admin moderation/override actions affecting core business entities. Links to admin, timestamp, entity type/ID, action performed, and reason. ### AdminModeration Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/adminmoderation-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/adminmoderation-api` * **Production:** `https://ebaycclone.mindbricks.co/adminmoderation-api` ### `Get Moderationaction` API Get a single moderation action log by ID. Used to review admin audit trails; accessible only to platform admins. **Rest Route** The `getModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `getModerationAction` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | **moderationActionId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/moderationactions/:moderationActionId** ```js axios({ method: 'GET', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Moderationaction` API Soft-deletes a moderation action log record (dangerous; allowed only to superadmins or strict manual correction), primarily for audit correction or internal error cleanup. Usually, moderation logs are immutable. **Rest Route** The `deleteModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `deleteModerationAction` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | **moderationActionId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/moderationactions/:moderationActionId** ```js axios({ method: 'DELETE', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Moderationaction` API Logs an admin moderation or override action in the system for audit and traceability. Requires admin login, takes context from session, and creates an audit entry for any admin operation over any entity type. **Rest Route** The `createModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions` **Rest Request Parameters** The `createModerationAction` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | entityId | ID | true | request.body?.entityId | | entityType | Enum | true | request.body?.entityType | | reason | String | true | request.body?.reason | | actionType | Enum | true | request.body?.actionType | **entityId** : ID of target entity affected by moderation (user/product/etc). **entityType** : Type of entity affected (USER, PRODUCT, FEEDBACK, MEDIA, CATEGORY, NOTIFICATION, ORDER, SEARCHINDEX). **reason** : Explanation or justification for the moderation action performed. **actionType** : Type of moderation action (e.g., SOFT_DELETE, RESTORE, UPDATE_ROLE, MANUAL_CORRECTION, MEDIA_FLAG, INDEX_REBUILD, PAYMENT_FIX, FEEDBACK_OVERRIDE, ADMIN_NOTE). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/moderationactions** ```js axios({ method: 'POST', url: '/v1/moderationactions', data: { entityId:"ID", entityType:"Enum", reason:"String", actionType:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Moderationactions` API List moderation actions for admin dashboard/audit search. Supports filtering by admin, entityType, entityId, actionType, and date. Always sorted by most recent action. **Rest Route** The `listModerationActions` API REST controller can be triggered via the following route: `/v1/moderationactions` **Rest Request Parameters** The `listModerationActions` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/moderationactions** ```js axios({ method: 'GET', url: '/v1/moderationactions', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationActions", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "moderationActions": [ { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Moderationaction` API Allows update of explanation/note on a moderation action for correction (typically by admin or superadmin only). No entity/type/admin may be changed after creation; only 'reason' is editable for audit consistency. **Rest Route** The `updateModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `updateModerationAction` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | | reason | String | false | request.body?.reason | **moderationActionId** : This id paremeter is used to select the required data object that will be updated **reason** : Explanation or justification for the moderation action performed. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/moderationactions/:moderationActionId** ```js axios({ method: 'PATCH', url: `/v1/moderationactions/${moderationActionId}`, data: { reason:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## WatchlistCart Service Handles user watchlists (with custom folders) and shopping cart preparation for checkout, strictly enforcing only fixed-price products in carts, supporting item moves/bulk operations, and robust default/folder logic.. ### WatchlistCart Service Data Objects **WatchlistItem** Item in a user’s watchlist, optionally in a named folder; references product and user. **CartItem** Single product pending checkout in a user’s cart. Only fixed-price products permitted; quantity supported for multi-unit purchases (if allowed). **WatchlistList** A named folder/list in a user’s watchlist. Default list exists for all users. Custom lists may be created and deleted. ### WatchlistCart Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/watchlistcart-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/watchlistcart-api` * **Production:** `https://ebaycclone.mindbricks.co/watchlistcart-api` ### `List Watchlistlist` API List all lists in user’s watchlists. Supports listing by listId for folders. **Rest Route** The `listWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists` **Rest Request Parameters** The `listWatchlistList` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/watchlistlists** ```js axios({ method: 'GET', url: '/v1/watchlistlists', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Cartitems` API List all cart items for a user (pending checkout). **Rest Route** The `listCartItems` API REST controller can be triggered via the following route: `/v1/cartitems` **Rest Request Parameters** The `listCartItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/cartitems** ```js axios({ method: 'GET', url: '/v1/cartitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "price": "Double", "title": "String", "type": "Enum", "type_idx": "Integer", "mediaAssetIds": "ID" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Cartitem` API Remove an item from the user’s cart. **Rest Route** The `deleteCartItem` API REST controller can be triggered via the following route: `/v1/cartitems/:cartItemId` **Rest Request Parameters** The `deleteCartItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | **cartItemId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/cartitems/:cartItemId** ```js axios({ method: 'DELETE', url: `/v1/cartitems/${cartItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Watchlistitem` API Add product to user’s watchlist (default or target list/folder). One (user, product, list) per item enforced. Block duplicates. **Rest Route** The `createWatchlistItem` API REST controller can be triggered via the following route: `/v1/watchlistitems` **Rest Request Parameters** The `createWatchlistItem` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | productId | ID | true | request.body?.productId | | listId | ID | false | request.body?.listId | **addedAt** : Timestamp watchlist item created. **productId** : Referenced product in the watchlist. **listId** : Owning watchlistList; null if in default watchlist. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/watchlistitems** ```js axios({ method: 'POST', url: '/v1/watchlistitems', data: { addedAt:"Date", productId:"ID", listId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Watchlistitems` API List all products in user’s watchlists. Supports listing by listId for folders. **Rest Route** The `listWatchlistItems` API REST controller can be triggered via the following route: `/v1/watchlistitems` **Rest Request Parameters** The `listWatchlistItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/watchlistitems** ```js axios({ method: 'GET', url: '/v1/watchlistitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Cartitemquantity` API Change the quantity for a cart item. User must own the item. **Rest Route** The `updateCartItemQuantity` API REST controller can be triggered via the following route: `/v1/cartitemquantity/:cartItemId` **Rest Request Parameters** The `updateCartItemQuantity` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | | quantity | Integer | false | request.body?.quantity | **cartItemId** : This id paremeter is used to select the required data object that will be updated **quantity** : How many units (if product allows). **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/cartitemquantity/:cartItemId** ```js axios({ method: 'PATCH', url: `/v1/cartitemquantity/${cartItemId}`, data: { quantity:"Integer", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Watchlistlist` API Create a new custom watchlist folder. Name must be unique per user; ‘Default’ is reserved for system. **Rest Route** The `createWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists` **Rest Request Parameters** The `createWatchlistList` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | name | String | true | request.body?.name | **name** : Custom folder or list name. 'Default' is reserved (non-deletable for each user). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/watchlistlists** ```js axios({ method: 'POST', url: '/v1/watchlistlists', data: { name:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Watchlistlist` API Delete a custom watchlist (folder). Items are reassigned to user’s default list. Cannot delete default list. **Rest Route** The `deleteWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists/:watchlistListId` **Rest Request Parameters** The `deleteWatchlistList` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistListId | ID | true | request.params?.watchlistListId | **watchlistListId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistlists/:watchlistListId** ```js axios({ method: 'DELETE', url: `/v1/watchlistlists/${watchlistListId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Watchlistitem` API Remove a product from a user’s watchlist. **Rest Route** The `deleteWatchlistItem` API REST controller can be triggered via the following route: `/v1/watchlistitems/:watchlistItemId` **Rest Request Parameters** The `deleteWatchlistItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistItemId | ID | true | request.params?.watchlistItemId | **watchlistItemId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistitems/:watchlistItemId** ```js axios({ method: 'DELETE', url: `/v1/watchlistitems/${watchlistItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Cartitem` API Add an item to the user’s cart. Only fixed-price products allowed. Duplicates not permitted. **Rest Route** The `createCartItem` API REST controller can be triggered via the following route: `/v1/cartitems` **Rest Request Parameters** The `createCartItem` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | **addedAt** : Timestamp added to cart. **quantity** : How many units (if product allows). **productId** : Product being checked out. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/cartitems** ```js axios({ method: 'POST', url: '/v1/cartitems', data: { addedAt:"Date", quantity:"Integer", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Do Userwatchlist` API userwatchlist **Rest Route** The `userwatchlist` API REST controller can be triggered via the following route: `/v1/userwatchlist` **Rest Request Parameters** The `userwatchlist` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userwatchlist** ```js axios({ method: 'GET', url: '/v1/userwatchlist', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Usercartitems` API list all cart items adde by user **Rest Route** The `listUserCartItems` API REST controller can be triggered via the following route: `/v1/usercartitems` **Rest Request Parameters** The `listUserCartItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/usercartitems** ```js axios({ method: 'GET', url: '/v1/usercartitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "shipping": "Double" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Do Userwatchlistlists` API list all watch lists created by user **Rest Route** The `userwatchlistlists` API REST controller can be triggered via the following route: `/v1/userwatchlistlists` **Rest Request Parameters** The `userwatchlistlists` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userwatchlistlists** ```js axios({ method: 'GET', url: '/v1/userwatchlistlists', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ## ProductListing Service Handles product listings (both auction and fixed-price), image/media storage with validations, enforces immutable type, soft-delete, and public product discovery. ### ProductListing Service Data Objects **ProductListingMedia** Stores and manages images/media associated with products, including secure URL, MIME type, and size validation. Each asset can be used by multiple products. **ProductListingProduct** Represents a single product listing (fixed-price or auction) in the marketplace, with seller, category, type, price information, shipping details, media references, and dynamic auction fields. ### ProductListing Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/productlisting-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/productlisting-api` * **Production:** `https://ebaycclone.mindbricks.co/productlisting-api` ### `List Productlistingmedia` API List all media assets (admin or for media management/bulk preview). **Rest Route** The `listProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias` **Rest Request Parameters** The `listProductListingMedia` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias** ```js axios({ method: 'GET', url: '/v1/productlistingmedias', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedias", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingMedias": [ { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Productlistingproduct` API Get a single product listing. Checks isActive and public status. Includes media, category, subcategory, and seller info via joins. **Rest Route** The `getProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `getProductListingProduct` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | **productListingProductId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'GET', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Productlistingownproducts` API listing the loggedin user's products **Rest Route** The `listProductListingOwnProducts` API REST controller can be triggered via the following route: `/v1/productlistingownproducts` **Rest Request Parameters** The `listProductListingOwnProducts` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingownproducts** ```js axios({ method: 'GET', url: '/v1/productlistingownproducts', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Productlistingmedia` API Get a single media asset by ID (for admin or to display in product UI). **Rest Route** The `getProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` **Rest Request Parameters** The `getProductListingMedia` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | **productListingMediaId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'GET', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Productlistingproducts` API List public product listings. Only isActive=true records are returned. Includes category, subcategory, seller, media joins. Supports filtering. **Rest Route** The `listProductListingProducts` API REST controller can be triggered via the following route: `/v1/productlistingproducts` **Rest Request Parameters** The `listProductListingProducts` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts** ```js axios({ method: 'GET', url: '/v1/productlistingproducts', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Productlistingproduct` API Soft-delete a product listing. Only owner or admin can delete. **Rest Route** The `deleteProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `deleteProductListingProduct` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | **productListingProductId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'DELETE', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Productlistingproduct` API Update a product listing. Product type cannot be changed (immutable). **Rest Route** The `updateProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `updateProductListingProduct` api has got 21 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | | currency | String | false | request.body?.currency | | description | Text | false | request.body?.description | | condition | Enum | false | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | false | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | false | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | false | request.body?.shippingMethod | | shipping | Double | false | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | false | request.body?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | **productListingProductId** : This id paremeter is used to select the required data object that will be updated **currency** : ISO currency code (e.g. USD, EUR) **description** : Product detailed description **condition** : Condition of product: BRAND_NEW, NEW, or USED **startBid** : The opening bid value (for auction type products) **endPrice** : Optional immediate sale/upper end price for auction (if AUCTION type) **price** : Product price (required if fixed price type) **title** : Product title **startPrice** : Minimum starting price for auction (required if AUCTION type) **endBid** : The upper (max) bid value for auction products (if any) **estimatedDelivery** : Estimated delivery date for this product **shippingCurrency** : Currency code for shipping cost **mediaAssetIds** : References to associated product/media assets **shippingMethod** : Shipping option for product: STANDARD, EXPRESS, or FREE **shipping** : Shipping cost for this product **startBidDate** : Date/time when auction bidding begins **subcategoryId** : Reference to subcategory **categoryId** : Reference to parent category **endBidDate** : Date/time when auction bidding ends **currentBid** : Current highest bid for auction-type product (updated atomically on bid placement) **highestBidderId** : User ID of current highest bidder (auction-only, updated by auction microservice) **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'PATCH', url: `/v1/productlistingproducts/${productListingProductId}`, data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Productlistingproduct` API Create a new product listing (fixed or auction), conditioned on product type. Type is immutable after creation. **Rest Route** The `createProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts` **Rest Request Parameters** The `createProductListingProduct` api has got 21 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | description | Text | true | request.body?.description | | condition | Enum | true | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | true | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | type | Enum | true | request.body?.type | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | true | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | true | request.body?.shippingMethod | | shipping | Double | true | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | true | request.body?.subcategoryId | | categoryId | ID | true | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | **currency** : ISO currency code (e.g. USD, EUR) **description** : Product detailed description **condition** : Condition of product: BRAND_NEW, NEW, or USED **startBid** : The opening bid value (for auction type products) **endPrice** : Optional immediate sale/upper end price for auction (if AUCTION type) **price** : Product price (required if fixed price type) **title** : Product title **startPrice** : Minimum starting price for auction (required if AUCTION type) **type** : Product listing type, either FIXED or AUCTION (immutable after creation) **endBid** : The upper (max) bid value for auction products (if any) **estimatedDelivery** : Estimated delivery date for this product **shippingCurrency** : Currency code for shipping cost **mediaAssetIds** : References to associated product/media assets **shippingMethod** : Shipping option for product: STANDARD, EXPRESS, or FREE **shipping** : Shipping cost for this product **startBidDate** : Date/time when auction bidding begins **subcategoryId** : Reference to subcategory **categoryId** : Reference to parent category **endBidDate** : Date/time when auction bidding ends **currentBid** : Current highest bid for auction-type product (updated atomically on bid placement) **highestBidderId** : User ID of current highest bidder (auction-only, updated by auction microservice) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/productlistingproducts** ```js axios({ method: 'POST', url: '/v1/productlistingproducts', data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", type:"Enum", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Productlistingmedia` API Soft-delete a media asset (typically by admin or media owner for flagged/invalid content). **Rest Route** The `deleteProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` **Rest Request Parameters** The `deleteProductListingMedia` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | **productListingMediaId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'DELETE', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Productlistingmedia` API Create a new media asset record after validation. Used mainly by edge controller after upload. **Rest Route** The `createProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias` **Rest Request Parameters** The `createProductListingMedia` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | mimeType | String | true | request.body?.mimeType | | productId | ID | false | request.body?.productId | | url | String | true | request.body?.url | | size | Integer | true | request.body?.size | **mimeType** : MIME type of the uploaded media (e.g., image/jpeg) **productId** : ID of product associated with this media asset **url** : Secure, validated URL for the media asset (S3 or equivalent) **size** : Media size in bytes (for validation and quota) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/productlistingmedias** ```js axios({ method: 'POST', url: '/v1/productlistingmedias', data: { mimeType:"String", productId:"ID", url:"String", size:"Integer", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## OrderManagement Service Handles all marketplace orders, manual checkout flows for fixed-price/offer/auction settlements, Stripe payment processing and webhook reconciliation, explicit status updates (shipping, delivery, cancellation), and feedback eligibility via orderItems. ### OrderManagement Service Data Objects **OrderManagementOrder** Marketplace order record. Stores buyer, shipping, status, items, Stripe payment data, and manual shipment/delivery events. Only accessible to admins or the buyer/seller of order items. **OrderManagementOrderItem** Order line item representing purchase of a single product from a specific seller as part of an order. Enables feedback, delivery, and per-seller analytics. Immutable after order creation. **Sys_orderManagementOrderPayment** A payment storage object to store the payment life cyle of orders based on orderManagementOrder object. It is autocreated based on the source object's checkout config **Sys_paymentCustomer** A payment storage object to store the customer values of the payment platform **Sys_paymentMethod** A payment storage object to store the payment methods of the platform customers ### OrderManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/ordermanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/ordermanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/ordermanagement-api` ### `List Ordermanagementorders` API List orders, filtered for buyer and/or seller, or by admin. Includes select orderItems. **Rest Route** The `listOrderManagementOrders` API REST controller can be triggered via the following route: `/v1/ordermanagementorders` **Rest Request Parameters** The `listOrderManagementOrders` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ordermanagementorders', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Ordermanagementorderitem` API Get a specific order item (for feedback/business logic). **Rest Route** The `getOrderManagementOrderItem` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems/:orderManagementOrderItemId` **Rest Request Parameters** The `getOrderManagementOrderItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderItemId | ID | true | request.params?.orderManagementOrderItemId | **orderManagementOrderItemId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems/:orderManagementOrderItemId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderitems/${orderManagementOrderItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Ordermanagementorder` API Soft-delete/cancel order by admin or eligible actor prior to shipment. Sets status to CANCELLED and cancels active payment intent if pending. Irreversible and blocks feedback. **Rest Route** The `deleteOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` **Rest Request Parameters** The `deleteOrderManagementOrder` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorder` API Get single order by ID. Only accessible to admin, buyer, or relevant sellers of items within this order. Includes all orderItems. **Rest Route** The `getOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` **Rest Request Parameters** The `getOrderManagementOrder` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | **orderManagementOrderId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Ordermanagementorderstatus` API Update order status (manual shipment, delivery, cancellation/refund). Restricted: only seller of all items can mark as shipped, only buyer can confirm delivery, only admin can set refund/cancelled. Timestamps updated as per business rule. **Rest Route** The `updateOrderManagementOrderStatus` API REST controller can be triggered via the following route: `/v1/ordermanagementorderstatus/:orderManagementOrderId` **Rest Request Parameters** The `updateOrderManagementOrderStatus` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **status** : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderstatus/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderstatus/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Complete Orderstripewebhook` API Webhook endpoint called by Stripe to reconcile payment state and update order status based on paymentIntentId and event data. No authentication required (Stripe IPs only). **Rest Route** The `completeOrderStripeWebhook` API REST controller can be triggered via the following route: `/v1/completeorderstripewebhook/:orderManagementOrderId` **Rest Request Parameters** The `completeOrderStripeWebhook` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **status** : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/completeorderstripewebhook/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/completeorderstripewebhook/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderbyproductid` API get orders by productId **Rest Route** The `getOrderManagementOrderByProductId` API REST controller can be triggered via the following route: `/v1/ordermanagementorderbyproductid/:items` **Rest Request Parameters** The `getOrderManagementOrderByProductId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | items | String | true | request.params?.items | **orderManagementOrderId** : This id paremeter is used to query the required data object. **items** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderbyproductid/:items** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderbyproductid/${items}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Ordermanagementorder` API Creates an order and initiates Stripe payment. Validates that all products in the order are fixed-price, populates orderItems, saves Stripe customer/paymentMethod/paymentIntentId for reconciliation. Only accessible to buyers for own checkouts and only allows fixed-price product checkout (no auction). **Rest Route** The `createOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders` **Rest Request Parameters** The `createOrderManagementOrder` api has got 14 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderNumber | String | true | request.body?.orderNumber | | items | ID | false | request.body?.items | | paymentMethodId | String | true | request.body?.paymentMethodId | | stripeCustomerId | String | true | request.body?.stripeCustomerId | | paymentIntentId | String | false | request.body?.paymentIntentId | | shippingAddress | Object | true | request.body?.shippingAddress | | summary | Object | true | request.body?.summary | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderNumber** : Unique, human-friendly order number (displayed to users); enforced unique. **items** : Array of orderManagementOrderItem ids representing items in this order. **paymentMethodId** : Stripe paymentMethodId used for payment. Not stored if cash or other payment (future). **stripeCustomerId** : Stripe customerId of buyer; enables saved/paymentMethodId flows. **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **shippingAddress** : Shipping address for the order (copy of buyer address at purchase time). **summary** : Object with total, subtotal, currency, shipping, discount breakdown as snapshot of order at time of purchase. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorders** ```js axios({ method: 'POST', url: '/v1/ordermanagementorders', data: { orderNumber:"String", items:"ID", paymentMethodId:"String", stripeCustomerId:"String", paymentIntentId:"String", shippingAddress:"Object", summary:"Object", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderitems` API List order items for a given order or for buyer/seller analytics. Used for feedback management. **Rest Route** The `listOrderManagementOrderItems` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems` **Rest Request Parameters** The `listOrderManagementOrderItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Ownordermanagementorders` API list the loggedin user orders **Rest Route** The `listOwnOrderManagementOrders` API REST controller can be triggered via the following route: `/v1/ownordermanagementorders` **Rest Request Parameters** The `listOwnOrderManagementOrders` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ownordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ownordermanagementorders', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Lis Ordermanagementownorderitem` API list the loggedin user's order items **Rest Route** The `lisOrderManagementOwnOrderItem` API REST controller can be triggered via the following route: `/v1/lisordermanagementownorderitem` **Rest Request Parameters** The `lisOrderManagementOwnOrderItem` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/lisordermanagementownorderitem** ```js axios({ method: 'GET', url: '/v1/lisordermanagementownorderitem', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Ordermanagementorderitem` API create order item **Rest Route** The `createOrderManagementOrderItem` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems` **Rest Request Parameters** The `createOrderManagementOrderItem` api has got 8 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | shipping | Double | true | request.body?.shipping | | orderId | ID | true | request.body?.orderId | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | | price | Double | true | request.body?.price | | sellerId | ID | true | request.body?.sellerId | | title | String | true | request.body?.title | | currency | String | true | request.body?.currency | **shipping** : Shipping cost for this product (may be 0 for free shipping). **orderId** : Parent order this item belongs to; enables join and lifecycle tracking. **quantity** : Number of units purchased for this product. **productId** : ID of product purchased in this line item. **price** : Unit price for this product at purchase time. **sellerId** : UserId of seller (owner of product at purchase time). **title** : Product title at purchase time (copied for convenience/audit). **currency** : Currency code for price/shipping (ISO 4217). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderitems** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderitems', data: { shipping:"Double", orderId:"ID", quantity:"Integer", productId:"ID", price:"Double", sellerId:"ID", title:"String", currency:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpayment2` API This route is used to get the payment information by ID. **Rest Route** The `getOrderManagementOrderPayment2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `getOrderManagementOrderPayment2` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderpayments2` API This route is used to list all payments. **Rest Route** The `listOrderManagementOrderPayments2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayments2` **Rest Request Parameters** The `listOrderManagementOrderPayments2` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Ordermanagementorderpayment` API This route is used to create a new payment. **Rest Route** The `createOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment` **Rest Request Parameters** The `createOrderManagementOrderPayment` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderId | ID | true | request.body?.orderId | | paymentId | String | true | request.body?.paymentId | | paymentStatus | String | true | request.body?.paymentStatus | | statusLiteral | String | true | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | **orderId** : an ID value to represent the orderId which is the ID parameter of the source orderManagementOrder object **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderpayment', data: { orderId:"ID", paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Ordermanagementorderpayment` API This route is used to update an existing payment. **Rest Route** The `updateOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `updateOrderManagementOrderPayment` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | false | request.body?.paymentId | | paymentStatus | String | false | request.body?.paymentStatus | | statusLiteral | String | false | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | **sys_orderManagementOrderPaymentId** : This id paremeter is used to select the required data object that will be updated **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Ordermanagementorderpayment` API This route is used to delete a payment. **Rest Route** The `deleteOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `deleteOrderManagementOrderPayment` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderpayments2` API This route is used to list all payments. **Rest Route** The `listOrderManagementOrderPayments2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayments2` **Rest Request Parameters** The `listOrderManagementOrderPayments2` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Ordermanagementorderpaymentbyorderid` API This route is used to get the payment information by order id. **Rest Route** The `getOrderManagementOrderPaymentByOrderId` API REST controller can be triggered via the following route: `/v1/orderManagementOrderpaymentbyorderid/:orderId` **Rest Request Parameters** The `getOrderManagementOrderPaymentByOrderId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | orderId | String | true | request.params?.orderId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **orderId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbyorderid/:orderId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbyorderid/${orderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpaymentbypaymentid` API This route is used to get the payment information by payment id. **Rest Route** The `getOrderManagementOrderPaymentByPaymentId` API REST controller can be triggered via the following route: `/v1/orderManagementOrderpaymentbypaymentid/:paymentId` **Rest Request Parameters** The `getOrderManagementOrderPaymentByPaymentId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | true | request.params?.paymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **paymentId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbypaymentid/:paymentId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbypaymentid/${paymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpayment2` API This route is used to get the payment information by ID. **Rest Route** The `getOrderManagementOrderPayment2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `getOrderManagementOrderPayment2` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Start Ordermanagementorderpayment` API Start payment for orderManagementOrder **Rest Route** The `startOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/startordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `startOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to start a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/startordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/startordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Refresh Ordermanagementorderpayment` API Refresh payment info for orderManagementOrder from Stripe **Rest Route** The `refreshOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/refreshordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `refreshOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to refresh a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/refreshordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/refreshordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Callback Ordermanagementorderpayment` API Refresh payment values by gateway webhook call for orderManagementOrder **Rest Route** The `callbackOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/callbackordermanagementorderpayment` **Rest Request Parameters** The `callbackOrderManagementOrderPayment` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.body?.orderManagementOrderId | **orderManagementOrderId** : The order id parameter that will be read from webhook callback params **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/callbackordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/callbackordermanagementorderpayment', data: { orderManagementOrderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Get Paymentcustomerbyuserid` API This route is used to get the payment customer information by user id. **Rest Route** The `getPaymentCustomerByUserId` API REST controller can be triggered via the following route: `/v1/paymentcustomers/:userId` **Rest Request Parameters** The `getPaymentCustomerByUserId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_paymentCustomerId | ID | true | request.params?.sys_paymentCustomerId | | userId | String | true | request.params?.userId | **sys_paymentCustomerId** : This id paremeter is used to query the required data object. **userId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomers/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_paymentCustomer": { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Paymentcustomers` API This route is used to list all payment customers. **Rest Route** The `listPaymentCustomers` API REST controller can be triggered via the following route: `/v1/paymentcustomers` **Rest Request Parameters** The `listPaymentCustomers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers** ```js axios({ method: 'GET', url: '/v1/paymentcustomers', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentCustomers": [ { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Paymentcustomermethods` API This route is used to list all payment customer methods. **Rest Route** The `listPaymentCustomerMethods` API REST controller can be triggered via the following route: `/v1/paymentcustomermethods/:userId` **Rest Request Parameters** The `listPaymentCustomerMethods` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | String | true | request.params?.userId | **userId** : This parameter will be used to select the data objects that want to be listed **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomermethods/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomermethods/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentMethods", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentMethods": [ { "id": "ID", "paymentMethodId": "String", "userId": "ID", "customerId": "String", "cardHolderName": "String", "cardHolderZip": "String", "platform": "String", "cardInfo": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ## Feedback Service Handles feedback for order items: one feedback per buyer/orderItem, attached to sellerId for analytical feedback/rating aggregation and reputation tracking. Enables querying feedbacks received/given for sellers and buyers. test ### Feedback Service Data Objects **Feedback** One feedback per (buyer, orderItem). Stores rating (1-5), comment, ties to seller for analytics. Created only after delivery confirmed on order item. ### Feedback Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/feedback-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/feedback-api` * **Production:** `https://ebaycclone.mindbricks.co/feedback-api` ### `List Feedbacks` API List feedback with filtering by buyerId (given), sellerId (received), productId, or orderItemId. Used for showing seller profile, buyer profile, or order analytics. **Rest Route** The `listFeedbacks` API REST controller can be triggered via the following route: `/v1/feedbacks` **Rest Request Parameters** The `listFeedbacks` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/feedbacks** ```js axios({ method: 'GET', url: '/v1/feedbacks', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedbacks", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "feedbacks": [ { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Feedback` API Get a single feedback by id. Accessible to public (for seller profile, product, or audit views). **Rest Route** The `getFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `getFeedback` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | **feedbackId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/feedbacks/:feedbackId** ```js axios({ method: 'GET', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Feedback` API Update feedback (comment/rating) for existing feedback record (buyer only). Admin can update as override. **Rest Route** The `updateFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `updateFeedback` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | | rating | Integer | false | request.body?.rating | | comment | String | false | request.body?.comment | **feedbackId** : This id paremeter is used to select the required data object that will be updated **rating** : Rating (1-5 stars) submitted by buyer. Required. **comment** : Optional textual feedback comment, max ~500 chars. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/feedbacks/:feedbackId** ```js axios({ method: 'PATCH', url: `/v1/feedbacks/${feedbackId}`, data: { rating:"Integer", comment:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Feedback` API Delete (soft-delete) feedback (by buyer or admin). Only feedback owner or admin. **Rest Route** The `deleteFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `deleteFeedback` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | **feedbackId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/feedbacks/:feedbackId** ```js axios({ method: 'DELETE', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Feedback` API Buyer creates feedback for a delivered order item. Only allowed once per (buyer, orderItemId). Allowed only once order item is delivered. **Rest Route** The `createFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks` **Rest Request Parameters** The `createFeedback` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | rating | Integer | true | request.body?.rating | | orderId | ID | true | request.body?.orderId | | orderItemId | ID | true | request.body?.orderItemId | | sellerId | ID | true | request.body?.sellerId | | comment | String | false | request.body?.comment | | productId | ID | true | request.body?.productId | **rating** : Rating (1-5 stars) submitted by buyer. Required. **orderId** : Order containing this purchased item. Used for aggregation and validation. **orderItemId** : Purchased item (line item) in order. Feedback is per (buyer, orderItem). **sellerId** : Seller of product for analytics/aggregation. Not author; used for querying feedback about sellers. **comment** : Optional textual feedback comment, max ~500 chars. **productId** : The product listing being reviewed (snapshot at order time). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/feedbacks** ```js axios({ method: 'POST', url: '/v1/feedbacks', data: { rating:"Integer", orderId:"ID", orderItemId:"ID", sellerId:"ID", comment:"String", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # REST API GUIDE ## ebaycclone-categorymanagement-service Handles product categories and subcategories for marketplace browsing and classification, supporting public discovery plus admin-only management. ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to: Email: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. ## Documentation Scope Welcome to the official documentation for the CategoryManagement Service's REST API. This document is designed to provide a comprehensive guide to interfacing with our CategoryManagement Service exclusively through RESTful API endpoints. **Intended Audience** This documentation is intended for developers and integrators who are looking to interact with the CategoryManagement Service via HTTP requests for purposes such as creating, updating, deleting and querying CategoryManagement objects. **Overview** Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases. Beyond REST It's important to note that the CategoryManagement Service also supports alternative methods of interaction, such as gRPC and messaging via a Message Broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation. ## Authentication And Authorization To ensure secure access to the CategoryManagement service's protected endpoints, a project-wide access token is required. This token serves as the primary method for authenticating requests to our service. However, it's important to note that access control varies across different routes: **Protected API**: Certain API (routes) require specific authorization levels. Access to these routes is contingent upon the possession of a valid access token that meets the route-specific authorization criteria. Unauthorized requests to these routes will be rejected. **Public API **: The service also includes public API (routes) that are accessible without authentication. These public endpoints are designed for open access and do not require an access token. ### Token Locations When including your access token in a request, ensure it is placed in one of the following specified locations. The service will sequentially search these locations for the token, utilizing the first one it encounters. | Location | Token Name / Param Name | | ---------------------- | ---------------------------- | | Query | access_token | | Authorization Header | Bearer | | Header | ebaycclone-access-token| | Cookie | ebaycclone-access-token| Please ensure the token is correctly placed in one of these locations, using the appropriate label as indicated. The service prioritizes these locations in the order listed, processing the first token it successfully identifies. ## Api Definitions This section outlines the API endpoints available within the CategoryManagement service. Each endpoint can receive parameters through various methods, meticulously described in the following definitions. It's important to understand the flexibility in how parameters can be included in requests to effectively interact with the CategoryManagement service. This service is configured to listen for HTTP requests on port `3002`, serving both the main API interface and default administrative endpoints. The following routes are available by default: * **API Test Interface (API Face):** `/` * **Swagger Documentation:** `/swagger` * **Postman Collection Download:** `/getPostmanCollection` * **Health Checks:** `/health` and `/admin/health` * **Current Session Info:** `/currentuser` * **Favicon:** `/favicon.ico` This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/categorymanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/categorymanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/categorymanagement-api` **Parameter Inclusion Methods:** Parameters can be incorporated into API requests in several ways, each with its designated location. Understanding these methods is crucial for correctly constructing your requests: **Query Parameters:** Included directly in the URL's query string. **Path Parameters:** Embedded within the URL's path. **Body Parameters:** Sent within the JSON body of the request. **Session Parameters:** Automatically read from the session object. This method is used for parameters that are intrinsic to the user's session, such as userId. When using an API that involves session parameters, you can omit these from your request. The service will automatically bind them to the API layer, provided that a session is associated with your request. **Note on Session Parameters:** Session parameters represent a unique method of parameter inclusion, relying on the context of the user's session. A common example of a session parameter is userId, which the service automatically associates with your request when a session exists. This feature ensures seamless integration of user-specific data without manual input for each request. By adhering to the specified parameter inclusion methods, you can effectively utilize the CategoryManagement service's API endpoints. For detailed information on each endpoint, including required parameters and their accepted locations, refer to the individual API definitions below. ### Common Parameters The `CategoryManagement` service's business API support several common parameters designed to modify and enhance the behavior of API requests. These parameters are not individually listed in the API route definitions to avoid repetition. Instead, refer to this section to understand how to leverage these common behaviors across different routes. Note that all common parameters should be included in the query part of the URL. ### Supported Common Parameters: - **getJoins (BOOLEAN)**: Controls whether to retrieve associated objects along with the main object. By default, `getJoins` is assumed to be `true`. Set it to `false` if you prefer to receive only the main fields of an object, excluding its associations. - **excludeCQRS (BOOLEAN)**: Applicable only when `getJoins` is `true`. By default, `excludeCQRS` is set to `false`. Enabling this parameter (`true`) omits non-local associations, which are typically more resource-intensive as they require querying external services like ElasticSearch for additional information. Use this to optimize response times and resource usage. - **requestId (String)**: Identifies a request to enable tracking through the service's log chain. A random hex string of 32 characters is assigned by default. If you wish to use a custom `requestId`, simply include it in your query parameters. - **caching (BOOLEAN)**: Determines the use of caching for query API. By default, caching is enabled (`true`). To ensure the freshest data directly from the database, set this parameter to `false`, bypassing the cache. - **cacheTTL (Integer)**: Specifies the Time-To-Live (TTL) for query caching, in seconds. This is particularly useful for adjusting the default caching duration (5 minutes) for `get list` queries. Setting a custom `cacheTTL` allows you to fine-tune the cache lifespan to meet your needs. - **pageNumber (Integer)**: For paginated `get list` API's, this parameter selects which page of results to retrieve. The default is `1`, indicating the first page. To disable pagination and retrieve all results, set `pageNumber` to `0`. - **pageRowCount (Integer)**: In conjunction with paginated API's, this parameter defines the number of records per page. The default value is `25`. Adjusting `pageRowCount` allows you to control the volume of data returned in a single request. By utilizing these common parameters, you can tailor the behavior of API requests to suit your specific requirements, ensuring optimal performance and usability of the `CategoryManagement` service. ### Error Response If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity: - **400 Bad Request**: The request was improperly formatted or contained invalid parameters, preventing the server from processing it. - **401 Unauthorized**: The request lacked valid authentication credentials or the credentials provided do not grant access to the requested resource. - **404 Not Found**: The requested resource was not found on the server. - **500 Internal Server Error**: The server encountered an unexpected condition that prevented it from fulfilling the request. Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ### Object Structure of a Successfull Response When the `CategoryManagement` service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client. **Key Characteristics of the Response Envelope:** - **Data Presentation**: Depending on the nature of the request, the service returns either a single data object or an array of objects encapsulated within the JSON envelope. - **Creation and Update API**: These API routes return the unmodified (pure) form of the data object(s), without any associations to other data objects. - **Delete API**: Even though the data is removed from the database, the last known state of the data object(s) is returned in its pure form. - **Get Requests**: A single data object is returned in JSON format. - **Get List Requests**: An array of data objects is provided, reflecting a collection of resources. - **Data Structure and Joins**: The complexity of the data structure in the response can vary based on the API's architectural design and the join options specified in the request. The architecture might inherently limit join operations, or they might be dynamically controlled through query parameters. - **Pure Data Forms**: In some cases, the response mirrors the exact structure found in the primary data table, without extensions. - **Extended Data Forms**: Alternatively, responses might include data extended through joins with tables within the same service or aggregated from external sources, such as ElasticSearch indices related to other services. - **Join Varieties**: The extensions might involve one-to-one joins, resulting in single object associations, or one-to-many joins, leading to an array of objects. In certain instances, the data might even feature nested inclusions from other data objects. **Design Considerations**: The structure of a API's response data is meticulously crafted during the service's architectural planning. This design ensures that responses adequately reflect the intended data relationships and service logic, providing clients with rich and meaningful information. **Brief Data**: Certain API's return a condensed version of the object data, intentionally selecting only specific fields deemed useful for that request. In such instances, the API documentation will detail the properties included in the response, guiding developers on what to expect. ### API Response Structure The API utilizes a standardized JSON envelope to encapsulate responses. This envelope is designed to consistently deliver both the requested data and essential metadata, ensuring that clients can efficiently interpret and utilize the response. **HTTP Status Codes:** - **200 OK**: This status code is returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request has been processed successfully. - **201 Created**: This status code is specific to CREATE operations, signifying that the requested resource has been successfully created. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling the successful execution of the request. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3 "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` - **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation performed. **Handling Errors:** For details on handling error scenarios and understanding the structure of error responses, please refer to the "Error Response" section provided earlier in this documentation. It outlines how error conditions are communicated, including the use of HTTP status codes and standardized JSON structures for error messages. ## Resources CategoryManagement service provides the following resources which are stored in its own database as a data object. Note that a resource for an api access is a data object for the service. ### Category resource *Resource Definition* : Represents a product category in the marketplace (e.g., Electronics, Clothing, Toys), used for browsing, filtering, and discovery. Admins manage categories. *Category Resource Properties* | Name | Type | Required | Default | Definition | | ---- | ---- | -------- | ------- | ---------- | | **imageUrl** | String | | | *URL for category image/avatar (optional, used for homepage visuals).* | | **subtitle** | String | | | *Optional short description for UI/tooltips.* | | **title** | String | | | *Display name of the category.* | ### Subcategory resource *Resource Definition* : Represents a subcategory within a parent category (e.g., 'Smartphones' under 'Electronics'). Used for more granular product discovery and navigation. 'group' categorizes special display logic. *Subcategory Resource Properties* | Name | Type | Required | Default | Definition | | ---- | ---- | -------- | ------- | ---------- | | **categoryId** | ID | | | *Reference to the parent category (category.id).* | | **name** | String | | | *Display name of the subcategory.* | | **group** | Enum | | | *Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE.* | #### Enum Properties Enum properties are represented as strings in the database. The values are mapped to their corresponding names in the application layer. ##### group Enum Property *Property Definition* : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE.*Enum Options* | Name | Value | Index | | ---- | ----- | ----- | | **MOST_POPULAR** | `"MOST_POPULAR""` | 0 | | **MORE** | `"MORE""` | 1 | ## Business Api ### Delete Category API *API Definition* : Soft-delete a category (admin-only). *API Crud Type* : delete *Default access route* : *DELETE* `/v1/categories/:categoryId` #### Parameters The deleteCategory api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | To access the api you can use the **REST** controller with the path **DELETE /v1/categories/:categoryId** ```js axios({ method: 'DELETE', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`category`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"category","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"category":{"id":"ID","imageUrl":"String","subtitle":"String","title":"String","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Delete Category](businessApi/deleteCategory). ### Get Subcategory API *API Definition* : Get a subcategory by ID. Public - only active subcategories returned except for admin. *API Crud Type* : get *Default access route* : *GET* `/v1/subcategories/:subcategoryId` #### Parameters The getSubcategory api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | To access the api you can use the **REST** controller with the path **GET /v1/subcategories/:subcategoryId** ```js axios({ method: 'GET', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`subcategory`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"subcategory","method":"GET","action":"get","appVersion":"Version","rowCount":1,"subcategory":{"id":"ID","categoryId":"ID","name":"String","group":"Enum","group_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Get Subcategory](businessApi/getSubcategory). ### Get Category API *API Definition* : Get a single category by ID. Public - only active categories returned (for non-admins). *API Crud Type* : get *Default access route* : *GET* `/v1/categories/:categoryId` #### Parameters The getCategory api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | To access the api you can use the **REST** controller with the path **GET /v1/categories/:categoryId** ```js axios({ method: 'GET', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`category`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"category","method":"GET","action":"get","appVersion":"Version","rowCount":1,"category":{"id":"ID","imageUrl":"String","subtitle":"String","title":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Get Category](businessApi/getCategory). ### Update Subcategory API *API Definition* : Update subcategory (admin-only), including group enum change. *API Crud Type* : update *Default access route* : *PATCH* `/v1/subcategories/:subcategoryId` #### Parameters The updateSubcategory api has got 4 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | name | String | false | request.body?.name | | group | Enum | false | request.body?.group | To access the api you can use the **REST** controller with the path **PATCH /v1/subcategories/:subcategoryId** ```js axios({ method: 'PATCH', url: `/v1/subcategories/${subcategoryId}`, data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`subcategory`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"subcategory","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"subcategory":{"id":"ID","categoryId":"ID","name":"String","group":"Enum","group_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Update Subcategory](businessApi/updateSubcategory). ### List Subcategories API *API Definition* : List all subcategories for browsing/filtering, with support for group enum and parent category queries. Only active subcategories shown to public/non-admin users. *API Crud Type* : list *Default access route* : *GET* `/v1/subcategories` The listSubcategories api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/subcategories** ```js axios({ method: 'GET', url: '/v1/subcategories', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`subcategories`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"subcategories","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","subcategories":[{"id":"ID","categoryId":"ID","name":"String","group":"Enum","group_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For List Subcategories](businessApi/listSubcategories). ### Delete Subcategory API *API Definition* : Soft-delete a subcategory (admin-only). *API Crud Type* : delete *Default access route* : *DELETE* `/v1/subcategories/:subcategoryId` #### Parameters The deleteSubcategory api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | To access the api you can use the **REST** controller with the path **DELETE /v1/subcategories/:subcategoryId** ```js axios({ method: 'DELETE', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`subcategory`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"subcategory","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"subcategory":{"id":"ID","categoryId":"ID","name":"String","group":"Enum","group_idx":"Integer","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Delete Subcategory](businessApi/deleteSubcategory). ### List Categories API *API Definition* : List all categories for browsing and filtering. Only active categories shown to public/non-admin users. *API Crud Type* : list *Default access route* : *GET* `/v1/categories` The listCategories api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/categories** ```js axios({ method: 'GET', url: '/v1/categories', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`categories`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"categories","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","categories":[{"id":"ID","imageUrl":"String","subtitle":"String","title":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For List Categories](businessApi/listCategories). ### Update Category API *API Definition* : Update category details (admin-only). *API Crud Type* : update *Default access route* : *PATCH* `/v1/categories/:categoryId` #### Parameters The updateCategory api has got 4 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | false | request.body?.title | To access the api you can use the **REST** controller with the path **PATCH /v1/categories/:categoryId** ```js axios({ method: 'PATCH', url: `/v1/categories/${categoryId}`, data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`category`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"category","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"category":{"id":"ID","imageUrl":"String","subtitle":"String","title":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Update Category](businessApi/updateCategory). ### Create Subcategory API *API Definition* : Create a new subcategory under a given category (admin-only), with enum group constraint. *API Crud Type* : create *Default access route* : *POST* `/v1/subcategories` #### Parameters The createSubcategory api has got 3 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.body?.categoryId | | name | String | true | request.body?.name | | group | Enum | true | request.body?.group | To access the api you can use the **REST** controller with the path **POST /v1/subcategories** ```js axios({ method: 'POST', url: '/v1/subcategories', data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`subcategory`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"subcategory","method":"POST","action":"create","appVersion":"Version","rowCount":1,"subcategory":{"id":"ID","categoryId":"ID","name":"String","group":"Enum","group_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Create Subcategory](businessApi/createSubcategory). ### Create Category API *API Definition* : Create a new category (admin-only) for product classification. *API Crud Type* : create *Default access route* : *POST* `/v1/categories` #### Parameters The createCategory api has got 3 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | true | request.body?.title | To access the api you can use the **REST** controller with the path **POST /v1/categories** ```js axios({ method: 'POST', url: '/v1/categories', data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`category`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"category","method":"POST","action":"create","appVersion":"Version","rowCount":1,"category":{"id":"ID","imageUrl":"String","subtitle":"String","title":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Create Category](businessApi/createCategory). ### Authentication Specific Routes ### Common Routes ### Route: currentuser *Route Definition*: Retrieves the currently authenticated user's session information. *Route Type*: sessionInfo *Access Route*: `GET /currentuser` #### Parameters This route does **not** require any request parameters. #### Behavior - Returns the authenticated session object associated with the current access token. - If no valid session exists, responds with a 401 Unauthorized. ```js // Sample GET /currentuser call axios.get("/currentuser", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** Returns the session object, including user-related data and token information. ``` { "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", "roleId": "user", "tenantId": "abc123", "accessToken": "jwt-token-string", ... } ``` **Error Response** **401 Unauthorized:** No active session found. ``` { "status": "ERR", "message": "No login found" } ``` **Notes** * This route is typically used by frontend or mobile applications to fetch the current session state after login. * The returned session includes key user identity fields, tenant information (if applicable), and the access token for further authenticated requests. * Always ensure a valid access token is provided in the request to retrieve the session. ### Route: permissions `*Route Definition*`: Retrieves all effective permission records assigned to the currently authenticated user. `*Route Type*`: permissionFetch *Access Route*: `GET /permissions` #### Parameters This route does **not** require any request parameters. #### Behavior - Fetches all active permission records (`givenPermissions` entries) associated with the current user session. - Returns a full array of permission objects. - Requires a valid session (`access token`) to be available. ```js // Sample GET /permissions call axios.get("/permissions", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** Returns an array of permission objects. ```json [ { "id": "perm1", "permissionName": "adminPanel.access", "roleId": "admin", "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" }, { "id": "perm2", "permissionName": "orders.manage", "roleId": null, "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" } ] ``` Each object reflects a single permission grant, aligned with the givenPermissions model: - `**permissionName**`: The permission the user has. - `**roleId**`: If the permission was granted through a role. -` **subjectUserId**`: If directly granted to the user. - `**subjectUserGroupId**`: If granted through a group. - `**objectId**`: If tied to a specific object (OBAC). - `**canDo**`: True or false flag to represent if permission is active or restricted. **Error Responses** * **401 Unauthorized**: No active session found. ```json { "status": "ERR", "message": "No login found" } ``` * **500 Internal Server Error**: Unexpected error fetching permissions. **Notes** * The /permissions route is available across all backend services generated by Mindbricks, not just the auth service. * Auth service: Fetches permissions freshly from the live database (givenPermissions table). * Other services: Typically use a cached or projected view of permissions stored in a common ElasticSearch store, optimized for faster authorization checks. > **Tip**: > Applications can cache permission results client-side or server-side, but should occasionally refresh by calling this endpoint, especially after login or permission-changing operations. ### Route: permissions/:permissionName *Route Definition*: Checks whether the current user has access to a specific permission, and provides a list of scoped object exceptions or inclusions. *Route Type*: permissionScopeCheck *Access Route*: `GET /permissions/:permissionName` #### Parameters | Parameter | Type | Required | Population | |------------------|--------|----------|------------------------| | permissionName | String | Yes | `request.params.permissionName` | #### Behavior - Evaluates whether the current user **has access** to the given `permissionName`. - Returns a structured object indicating: - Whether the permission is generally granted (`canDo`) - Which object IDs are explicitly included or excluded from access (`exceptions`) - Requires a valid session (`access token`). ```js // Sample GET /permissions/orders.manage axios.get("/permissions/orders.manage", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** ```json { "canDo": true, "exceptions": [ "a1f2e3d4-xxxx-yyyy-zzzz-object1", "b2c3d4e5-xxxx-yyyy-zzzz-object2" ] } ``` * If `canDo` is `true`, the user generally has the permission, but not for the objects listed in `exceptions` (i.e., restrictions). * If `canDo` is `false`, the user does not have the permission by default — but only for the objects in `exceptions`, they do have permission (i.e., selective overrides). * The exceptions array contains valid **UUID strings**, each corresponding to an object ID (typically from the data model targeted by the permission). ## Copyright All sources, documents and other digital materials are copyright of . ## About Us For more information please visit our website: . . . # Service Design Specification **ebaycclone-categorymanagement-service** documentation -Version:**`1.0.0`** ## Scope This document provides a structured architectural overview of the `categoryManagement` microservice, detailing its configuration, data model, authorization logic, business rules, and API design. It has been automatically generated based on the service definition within Mindbricks, ensuring that the information reflects the source of truth used during code generation and deployment. The document is intended to serve multiple audiences: * **Service architects** can use it to validate design decisions and ensure alignment with broader architectural goals. * **Developers and maintainers** will find it useful for understanding the structure and behavior of the service, facilitating easier debugging, feature extension, and integration with other systems. * **Stakeholders and reviewers** can use it to gain a clear understanding of the service's capabilities and domain logic. > **Note for Frontend Developers**: While this document is valuable for understanding business logic and data interactions, please refer to the [Service API Documentation](#) for endpoint-level specifications and integration details. > **Note for Backend Developers**: Since the code for this service is automatically generated by Mindbricks, you typically won't need to implement or modify it manually. However, this document is especially valuable when you're building other services—whether within Mindbricks or externally—that need to interact with or depend on this service. It provides a clear reference to the service's data contracts, business rules, and API structure, helping ensure compatibility and correct integration. ## `CategoryManagement` Service Settings [**Edit**](categorymanagement/serviceSettings) Handles product categories and subcategories for marketplace browsing and classification, supporting public discovery plus admin-only management. ### Service Overview This service is configured to listen for HTTP requests on port `3002`, serving both the main API interface and default administrative endpoints. The following routes are available by default: * **API Test Interface (API Face):** `/` * **Swagger Documentation:** `/swagger` * **Postman Collection Download:** `/getPostmanCollection` * **Health Checks:** `/health` and `/admin/health` * **Current Session Info:** `/currentuser` * **Favicon:** `/favicon.ico` The service uses a **PostgreSQL** database for data storage, with the database name set to `ebaycclone-categorymanagement-service`. This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/categorymanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/categorymanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/categorymanagement-api` ### Authentication & Security - **Login Required**: No This service does not require user authentication for access. It is designed to be publicly accessible, allowing anonymous users to interact with its endpoints. However, certain CRUD routes may still require login based on their specific configurations. ### Service Data Objects The service uses a **PostgreSQL** database for data storage, with the database name set to `ebaycclone-categorymanagement-service`. Data deletion is managed using a **soft delete** strategy. Instead of removing records from the database, they are flagged as inactive by setting the `isActive` field to `false`. | Object Name | Description | Public Access | |-------------|-------------|---------------| | `category` | Represents a product category in the marketplace (e.g., Electronics, Clothing, Toys), used for browsing, filtering, and discovery. Admins manage categories. | accessPublic | | `subcategory` | Represents a subcategory within a parent category (e.g., 'Smartphones' under 'Electronics'). Used for more granular product discovery and navigation. 'group' categorizes special display logic. | accessPublic | ## category Data Object ### Object Overview **Description:** Represents a product category in the marketplace (e.g., Electronics, Clothing, Toys), used for browsing, filtering, and discovery. Admins manage categories. This object represents a core data structure within the service and acts as the blueprint for database interaction, API generation, and business logic enforcement. It is defined using the `ObjectSettings` pattern, which governs its behavior, access control, caching strategy, and integration points with other systems such as Stripe and Redis. ### Core Configuration - **Soft Delete:** Enabled — Determines whether records are marked inactive (`isActive = false`) instead of being physically deleted. - **Public Access:** accessPublic — If enabled, anonymous users may access this object’s data depending on API-level rules. ### Properties Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `imageUrl` | String | No | URL for category image/avatar (optional, used for homepage visuals). | | `subtitle` | String | No | Optional short description for UI/tooltips. | | `title` | String | Yes | Display name of the category. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value is set. ### Default Values Default values are automatically assigned to properties when a new object is created, if no value is provided in the request body. Since default values are applied on db level, they should be literal values, not expressions.If you want to use expressions, you can use transposed parameters in any business API to set default values dynamically. - **title**: 'default' ### Auto Update Properties `imageUrl` `subtitle` `title` An update crud API created with the option `Auto Params` enabled will automatically update these properties with the provided values in the request body. If you want to update any property in your own business logic not by user input, you can set the `Allow Auto Update` option to false. These properties will be added to the update API's body parameters and can be updated by the user if any value is provided in the request body. ### Elastic Search Indexing `title` Properties that are indexed in Elastic Search will be searchable via the Elastic Search API. While all properties are stored in the elastic search index of the data object, only those marked for Elastic Search indexing will be available for search queries. ### Filter Properties `title` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's that have "Auto Params" enabled. - **title**: String has a filter named `title` ## subcategory Data Object ### Object Overview **Description:** Represents a subcategory within a parent category (e.g., 'Smartphones' under 'Electronics'). Used for more granular product discovery and navigation. 'group' categorizes special display logic. This object represents a core data structure within the service and acts as the blueprint for database interaction, API generation, and business logic enforcement. It is defined using the `ObjectSettings` pattern, which governs its behavior, access control, caching strategy, and integration points with other systems such as Stripe and Redis. ### Core Configuration - **Soft Delete:** Enabled — Determines whether records are marked inactive (`isActive = false`) instead of being physically deleted. - **Public Access:** accessPublic — If enabled, anonymous users may access this object’s data depending on API-level rules. ### Properties Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `categoryId` | ID | Yes | Reference to the parent category (category.id). | | `name` | String | Yes | Display name of the subcategory. | | `group` | Enum | Yes | Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value is set. ### Default Values Default values are automatically assigned to properties when a new object is created, if no value is provided in the request body. Since default values are applied on db level, they should be literal values, not expressions.If you want to use expressions, you can use transposed parameters in any business API to set default values dynamically. - **categoryId**: '00000000-0000-0000-0000-000000000000' - **name**: 'default' - **group**: MORE ### Auto Update Properties `categoryId` `name` `group` An update crud API created with the option `Auto Params` enabled will automatically update these properties with the provided values in the request body. If you want to update any property in your own business logic not by user input, you can set the `Allow Auto Update` option to false. These properties will be added to the update API's body parameters and can be updated by the user if any value is provided in the request body. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an addtional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the index property to sort by the enum value or when your enum options represent a sequence of values. - **group**: [MOST_POPULAR, MORE] ### Elastic Search Indexing `categoryId` `name` `group` Properties that are indexed in Elastic Search will be searchable via the Elastic Search API. While all properties are stored in the elastic search index of the data object, only those marked for Elastic Search indexing will be available for search queries. ### Database Indexing `categoryId` Properties that are indexed in the database will be optimized for query performance, allowing for faster data retrieval. Make a property indexed in the database if you want to use it frequently in query filters or sorting. ### Relation Properties `categoryId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. You can define relations in the data object properties, which will be used to create foreign key constraints in the database. For complex joins operations, Mindbricks supportsa BFF pattern, where you can view dynamic and static views based on Elastic Search Indexes. Use db level relations for simple one-to-one or one-to-many relationships, and use BFF views for complex joins that require multiple data objects to be joined together. - **categoryId**: ID Relation to `category`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes ### Filter Properties `categoryId` `name` `group` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's that have "Auto Params" enabled. - **categoryId**: ID has a filter named `categoryId` - **name**: String has a filter named `name` - **group**: Enum has a filter named `group` ## Business Logic categoryManagement has got 10 Business APIs to manage its internal and crud logic. For the details of each business API refer to its chapter. * [Delete Category](/businessLogic/deletecategory) * [Get Subcategory](/businessLogic/getsubcategory) * [Get Category](/businessLogic/getcategory) * [Update Subcategory](/businessLogic/updatesubcategory) * [List Subcategories](/businessLogic/listsubcategories) * [Delete Subcategory](/businessLogic/deletesubcategory) * [List Categories](/businessLogic/listcategories) * [Update Category](/businessLogic/updatecategory) * [Create Subcategory](/businessLogic/createsubcategory) * [Create Category](/businessLogic/createcategory) ## Edge Controllers No edge controllers defined for this service. --- ## Service Library ### Functions No general functions defined. ### Hook Functions No hook functions defined. ### Edge Functions No edge functions defined. ### Templates No templates defined. ### Assets No assets defined. ### Public Assets No public assets defined. --- ### Event Emission --- ## Integration Patterns ## Deployment Considerations ### Environment Configuration - **HTTP Port**: `3002` - **Database Type**: MongoDB - **Global Soft Delete**: Enabled ## Implementation Guidelines ### Development Workflow 1. **Data Model Implementation**: Generate database schema from data object definitions 2. **CRUD Route Generation**: Implement auto-generated routes with custom logic 3. **Custom Logic Integration**: Implement hook functions and edge functions 4. **Authentication Integration**: Configure with project-level authentication 5. **Testing**: Unit and integration testing for all components ### Code Generation Expectations - **Database Schema**: Auto-generated from data objects and relationships - **API Routes**: REST endpoints with customizable behavior - **Validation Logic**: Input validation from property definitions - **Access Control**: Authentication and authorization middleware ### Custom Code Integration Points - **Hook Functions**: Lifecycle-specific custom logic - **Edge Functions**: Full request/response control - **Library Functions**: Reusable business logic - **Templates**: Dynamic content rendering ### Testing Strategy #### Unit Testing - Test all custom library functions - Test validation logic and business rules - Test hook function implementations #### Integration Testing - Test API endpoints with authentication scenarios - Test database operations and transactions - Test external integrations - Test event emission and Kafka integration #### Performance Testing - Load test high-traffic endpoints - Test caching effectiveness - Monitor database query performance - Test scalability under load --- ## Appendices ### Data Type Reference | Type | Description | Storage | |------|-------------|---------| | ID | Unique identifier | UUID (SQL) / ObjectID (NoSQL) | | String | Short text (≤255 chars) | VARCHAR | | Text | Long-form text | TEXT | | Integer | 32-bit whole numbers | INT | | Boolean | True/false values | BOOLEAN | | Double | 64-bit floating point | DOUBLE | | Float | 32-bit floating point | FLOAT | | Short | 16-bit integers | SMALLINT | | Object | JSON object | JSONB (PostgreSQL) / Object (MongoDB) | | Date | ISO 8601 timestamp | TIMESTAMP | | Enum | Fixed numeric values | SMALLINT with lookup | ### Enum Value Mappings #### Request Locations - `0`: Bearer token in Authorization header - `1`: Cookie value - `2`: Custom HTTP header - `3`: Query parameter - `4`: Request body property - `5`: URL path parameter - `6`: Session data - `7`: Root request object #### HTTP Methods - `0`: GET - `1`: POST - `2`: PUT - `3`: PATCH - `4`: DELETE ### Edge Function Signature ```javascript async function edgeFunction(request) { // Custom request processing // Return response object or throw error return { data: {}, status: 200, message: "Success" }; } ``` --- *This document was generated from the service architecture definition and should be kept in sync with implementation changes.* -------------------------------------------------------- title: Example description: Test slug: example date: 01.04.2025 -------------------------------------------------------- # Example ## deneme # EVENT GUIDE ## ebaycclone-feedback-service Handles feedback for order items: one feedback per buyer/orderItem, attached to sellerId for analytical feedback/rating aggregation and reputation tracking. Enables querying feedbacks received/given for sellers and buyers. test ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to: Email: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. # Documentation Scope Welcome to the official documentation for the `Feedback` Service Event descriptions. This guide is dedicated to detailing how to subscribe to and listen for state changes within the `Feedback` Service, offering an exclusive focus on event subscription mechanisms. **Intended Audience** This documentation is aimed at developers and integrators looking to monitor `Feedback` Service state changes. It is especially relevant for those wishing to implement or enhance business logic based on interactions with `Feedback` objects. **Overview** This section provides detailed instructions on monitoring service events, covering payload structures and demonstrating typical use cases through examples. # Authentication and Authorization Access to the `Feedback` service's events is facilitated through the project's Kafka server, which is not accessible to the public. Subscription to a Kafka topic requires being on the same network and possessing valid Kafka user credentials. This document presupposes that readers have existing access to the Kafka server. Additionally, the service offers a public subscription option via REST for real-time data management in frontend applications, secured through REST API authentication and authorization mechanisms. To subscribe to service events via the REST API, please consult the Realtime REST API Guide. # Database Events Database events are triggered at the database layer, automatically and atomically, in response to any modifications at the data level. These events serve to notify subscribers about the creation, update, or deletion of objects within the database, distinct from any overarching business logic. Listening to database events is particularly beneficial for those focused on tracking changes at the database level. A typical use case for subscribing to database events is to replicate the data store of one service within another service's scope, ensuring data consistency and syncronization across services. For example, while a business operation such as "approve membership" might generate a high-level business event like `membership-approved`, the underlying database changes could involve multiple state updates to different entities. These might be published as separate events, such as `dbevent-member-updated` and `dbevent-user-updated`, reflecting the granular changes at the database level. Such detailed eventing provides a robust foundation for building responsive, data-driven applications, enabling fine-grained observability and reaction to the dynamics of the data landscape. It also facilitates the architectural pattern of event sourcing, where state changes are captured as a sequence of events, allowing for high-fidelity data replication and history replay for analytical or auditing purposes. ## DbEvent feedback-created **Event topic**: `ebaycclone-feedback-service-dbevent-feedback-created` This event is triggered upon the creation of a `feedback` data object in the database. The event payload encompasses the newly created data, encapsulated within the root of the paylod. **Event payload**: ```json {"id":"ID","rating":"Integer","orderId":"ID","buyerId":"ID","orderItemId":"ID","sellerId":"ID","comment":"String","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent feedback-updated **Event topic**: `ebaycclone-feedback-service-dbevent-feedback-updated` Activation of this event follows the update of a `feedback` data object. The payload contains the updated information under the `feedback` attribute, along with the original data prior to update, labeled as `old_feedback` and also you can find the old and new versions of updated-only portion of the data.. **Event payload**: ```json { old_feedback:{"id":"ID","rating":"Integer","orderId":"ID","buyerId":"ID","orderItemId":"ID","sellerId":"ID","comment":"String","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, feedback:{"id":"ID","rating":"Integer","orderId":"ID","buyerId":"ID","orderItemId":"ID","sellerId":"ID","comment":"String","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, oldDataValues, newDataValues } ``` ## DbEvent feedback-deleted **Event topic**: `ebaycclone-feedback-service-dbevent-feedback-deleted` This event announces the deletion of a `feedback` data object, covering both hard deletions (permanent removal) and soft deletions (where the `isActive` attribute is set to false). Regardless of the deletion type, the event payload will present the data as it was immediately before deletion, highlighting an `isActive` status of false for soft deletions. **Event payload**: ```json {"id":"ID","rating":"Integer","orderId":"ID","buyerId":"ID","orderItemId":"ID","sellerId":"ID","comment":"String","productId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` # ElasticSearch Index Events Within the `Feedback` service, most data objects are mirrored in ElasticSearch indices, ensuring these indices remain syncronized with their database counterparts through creation, updates, and deletions. These indices serve dual purposes: they act as a data source for external services and furnish aggregated data tailored to enhance frontend user experiences. Consequently, an ElasticSearch index might encapsulate data in its original form or aggregate additional information from other data objects. These aggregations can include both one-to-one and one-to-many relationships not only with database objects within the same service but also across different services. This capability allows developers to access comprehensive, aggregated data efficiently. By subscribing to ElasticSearch index events, developers are notified when an index is updated and can directly obtain the aggregated entity within the event payload, bypassing the need for separate ElasticSearch queries. It's noteworthy that some services may augment another service's index by appending to the entity’s `extends` object. In such scenarios, an `*-extended` event will contain only the newly added data. Should you require the complete dataset, you would need to retrieve the full ElasticSearch index entity using the provided ID. This approach to indexing and event handling facilitates a modular, interconnected architecture where services can seamlessly integrate and react to changes, enriching the overall data ecosystem and enabling more dynamic, responsive applications. ## Index Event feedback-created **Event topic**: `elastic-index-ebaycclone_feedback-created` **Event payload**: ```json {"id":"ID","rating":"Integer","orderId":"ID","buyerId":"ID","orderItemId":"ID","sellerId":"ID","comment":"String","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event feedback-updated **Event topic**: `elastic-index-ebaycclone_feedback-created` **Event payload**: ```json {"id":"ID","rating":"Integer","orderId":"ID","buyerId":"ID","orderItemId":"ID","sellerId":"ID","comment":"String","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event feedback-deleted **Event topic**: `elastic-index-ebaycclone_feedback-deleted` **Event payload**: ```json {"id":"ID","rating":"Integer","orderId":"ID","buyerId":"ID","orderItemId":"ID","sellerId":"ID","comment":"String","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event feedback-extended **Event topic**: `elastic-index-ebaycclone_feedback-extended` **Event payload**: ```js { id: id, extends: { [extendName]: "Object", [extendName + "_count"]: "Number", }, } ``` # Route Events Route events are emitted following the successful execution of a route. While most routes perform CRUD (Create, Read, Update, Delete) operations on data objects, resulting in route events that closely resemble database events, there are distinctions worth noting. A single route execution might trigger multiple CRUD actions and ElasticSearch indexing operations. However, for those primarily concerned with the overarching business logic and its outcomes, listening to the consolidated route event, published once at the conclusion of the route's execution, is more pertinent. Moreover, routes often deliver aggregated data beyond the primary database object, catering to specific client needs. For instance, creating a data object via a route might not only return the entity's data but also route-specific metrics, such as the executing user's permissions related to the entity. Alternatively, a route might automatically generate default child entities following the creation of a parent object. Consequently, the route event encapsulates a unified dataset encompassing both the parent and its children, in contrast to individual events triggered for each entity created. Therefore, subscribing to route events can offer a richer, more contextually relevant set of information aligned with business logic. The payload of a route event mirrors the REST response JSON of the route, providing a direct and comprehensive reflection of the data and metadata communicated to the client. This ensures that subscribers to route events receive a payload that encapsulates both the primary data involved and any additional information deemed significant at the business level, facilitating a deeper understanding and integration of the service's functional outcomes. ## Route Event feedbacks-listed **Event topic** : `ebaycclone-feedback-service-feedbacks-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `feedbacks` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`feedbacks`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"feedbacks","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","feedbacks":[{"id":"ID","rating":"Integer","orderId":"ID","buyerId":"ID","orderItemId":"ID","sellerId":"ID","comment":"String","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event feedback-retrived **Event topic** : `ebaycclone-feedback-service-feedback-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `feedback` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`feedback`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"feedback","method":"GET","action":"get","appVersion":"Version","rowCount":1,"feedback":{"id":"ID","rating":"Integer","orderId":"ID","buyerId":"ID","orderItemId":"ID","sellerId":"ID","comment":"String","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event feedback-updated **Event topic** : `ebaycclone-feedback-service-feedback-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `feedback` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`feedback`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"feedback","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"feedback":{"id":"ID","rating":"Integer","orderId":"ID","buyerId":"ID","orderItemId":"ID","sellerId":"ID","comment":"String","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event feedback-deleted **Event topic** : `ebaycclone-feedback-service-feedback-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `feedback` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`feedback`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"feedback","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"feedback":{"id":"ID","rating":"Integer","orderId":"ID","buyerId":"ID","orderItemId":"ID","sellerId":"ID","comment":"String","productId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event feedback-created **Event topic** : `ebaycclone-feedback-service-feedback-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `feedback` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`feedback`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"feedback","method":"POST","action":"create","appVersion":"Version","rowCount":1,"feedback":{"id":"ID","rating":"Integer","orderId":"ID","buyerId":"ID","orderItemId":"ID","sellerId":"ID","comment":"String","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` # Copyright All sources, documents and other digital materials are copyright of . # About Us For more information please visit our website: . . . # **EBAYCCLONE** FRONTEND GUIDE FOR AI CODING AGENTS This document is a rest api guide for the ebaycclone project. The document is designed for AI agents who will generate frontend code that will consume the project backend. The project has got 1 auth service, 1 notification service, 1 bff service and business services. Each service is a separate microservice application and listens the HTTP request from different service urls. The services may be in preview server, staging server or real production server. So each service have got 3 acess urls. Frontend application should support all deployemnt servers in the development phase, and user should be able to select the target api server in the login page. ## Project Introduction ebaycClone is a comprehensive backend for an online marketplace supporting auctions and fixed-price sales of physical goods, with role-based access, public user registration, Stripe payments, notifications, and robust ownership enforcement. ## API Structure ### Object Structure of a Successfull Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client. **HTTP Status Codes:** - **200 OK**: This status code is returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request has been processed successfully. - **201 Created**: This status code is specific to CREATE operations, signifying that the requested resource has been successfully created. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling the successful execution of the request. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` - **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation performed. ### Additional Data Each api may have include addtional data other than the main data object according to the business logic of the API. They will be given in each API's response signature. ### Error Response If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity: - **400 Bad Request**: The request was improperly formatted or contained invalid parameters, preventing the server from processing it. - **401 Unauthorized**: The request lacked valid authentication token , login required - **403 Forbidden Error** Curent token provided do not grant access to the requested resource. - **404 Not Found**: The requested resource was not found on the server. - **500 Internal Server Error**: The server encountered an unexpected condition that prevented it from fulfilling the request. Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Accessing the backend Each service of the backend has got its own url according to the deployment environement. User may want to test the frontend in one of the 3 deployments of the application, preview, staging and production. Please ensure that register and login pages do have a deployemnt server selection option, so as the frontned coding agent you can arrange the base url path of all services. The base url of the application in each environment is as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com` * **Staging:** `https://ebaycclone-stage.mindbricks.co` * **Production:** `https://ebaycclone.mindbricks.co` For the auth service the base url is as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` For each other service, the service base url will be given in service sections. Any login requied request to the backend should have a valid token, when a user makes a successfull login, the ressponse JSON includes a JWT access token in the `accessToken`fields. In normal conditions, this token is also set to the cookie and then consumed automatically, but since AI coding agents preview options may fail to use cookies, please ensure that in each request include the access token in the bearer auth header. ## Registration Management First of all please ensure that register and login pages do have a deployemnt server selection option, so as the frontned coding agent you can arrange the base url path of all services. Start with a landing page and arranging register, verification and login flow. So at the first step, you need a general knowledge of the application to make a good landing page and the authetication flow. ### How To Register Using `registeruser` route of auth api, send the required fields to the backend in your registration page. The registerUser api in in `auth` service, is described with request and response structure below. Note that since `registerUser` api is a business api, it has a version control, so please call it with the given version like `/v1/registeruser` ### `Register User` API This api is used by public users to register themselves **Rest Route** The `registerUser` API REST controller can be triggered via the following route: `/v1/registeruser` **Rest Request Parameters** The `registerUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **password** : The password defined by the the user that is being registered. **fullname** : The fullname defined by the the user that is being registered. **email** : The email defined by the the user that is being registered. **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` After a successful registration, frontend code should handle the verification needs. The registration response will have a `user` object in the root envelope, this object will have user information with an `id` parameter. ### Email Verification In the registration response, you should check the property `emailVerificationNeeded` in the reponse root, and if this property is true you should start the email verification flow. After login process, if you get an HTTP error status, and if there is an `errCode` property in the response with `EmailVerificationNeeded` value, you should start the email verification flow. 1. Call the email verification `start` route of the backend (described below) with the user email, backend will send a secret code to the given email adresss. **Backend can send the email message if the architect defined a real mail service or smtp server, so during the development time backend will send the secret code also to the frontend. You can get this secret code from the response within the `secretCode` property**. 2. The secret code in the sent email message will be a 6 digits code , and you should arrange an input page so that the user can paste this code to the frontend application. Please navigate to this input page after you start the verification process. **If the secretCode is sent to the frontend for test purposes, then you should show it as info in the input page, so that user can copy and paste it**. 3. There is a `codeIndex` property in the start response, please show it's value on the input page, so that user can match the index in the message with the one on the screen. 4. When the user submits the code, please complete the email verification using the `complete` route of the backend (described below) with the user email and the secret code. 5. After you get a successful response from email verification, you can navigate to the login page. Here is the `start`and `complete` routes of email verification. These are system routes , so they dont have a version control. #### `POST /verification-services/email-verification/start` **Purpose:** Starts the email verification by generating and sending a secret code. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `email` | String | Yes | User’s email address to verify | **Example Request** ```json { "email": "user@example.com" } ``` **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ In production, `secretCode` is **not** returned — only sent via email. **Error Responses** * `400 Bad Request`: Already verified * `403 Forbidden`: Too many attempts (rate limit) --- #### `POST /verification-services/email-verification/complete` **Purpose:** Completes the verification using the received code. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `email` | String | Yes | User’s email | | `secretCode` | String | Yes | Verification code | **Success Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` **Error Responses** * `403 Forbidden`: Code expired or mismatched * `404 Not Found`: No verification in progress --- ## Login Management After a successfull login and completing required verifications, user can now login. Please make a fancy minimal login page where user can enter his email and password. ## Bucket Management This application has a bucket service and is used to store user or other objects related files. Bucket service is login agnostic, so when accessing for write or private read, you should insert a bucket token (given by services) to your request authorization header as bearer token. **User Bucket** This bucket is used to store public user files for each user. When a user logs in, or in /currentuser response there is `userBucketToken` to be used when sending user related public files to the bucket service. To upload `POST {baseUrl}/bucket/upload` Request body is form data which includes the bucketId and the file as binary in `files` property. ```js { bucketId: "{userId}-public-user-bucket", files: {binary} } ``` Response status is 200 on succesfull result, eg body: ```json { "success": true, "data": [ { "fileId": "9da03f6d-0409-41ad-bb06-225a244ae408", "originalName": "test (10).png", "mimeType": "image/png", "size": 604063, "status": "uploaded", "bucketName": "f7103b85-fcda-4dec-92c6-c336f71fd3a2-public-user-bucket", "isPublic": true, "downloadUrl": "https://babilcom.mindbricks.co/bucket/download/9da03f6d-0409-41ad-bb06-225a244ae408" } ] } ``` To download a file from the bucket, you should know its fileId, so if youupload an avatar or something else, be sure that the download url or the fileId is stored in backend. Bucket is mostly used, in object creations where alos demands an addtional file like a product image or user avatar. So after you upload your image to the bucket, insert the returned download url to the related property in the related object creation. **Application Bucket** This Ebaycclone application alos has common public bucket which everybody has a read access, but only users who have `superAdmin`, `admin` or `saasAdmin` roles can write (upload) to the bucket. The common public project bucket id is `"ebaycclone-public-common-bucket"` and in certain areas like product image uploads, since the user will already have the admin bucket token, he will be able to upload realted object images. Please make your UI arrangements as able to upload files to the bucket using these bucket tokens. **Object Buckets** Some objects may return also a bucket token, to upload or access related files with object. For example, when you get a project's data in a project management application, if there is a public or private bucket token, this is provided mostly for uploading project related files or downloading them with the token. These buckets will be used according to the descriptions given along with the object definitions. ## Role Management This Ebaycclone may have different role names defined fro different business logic. But unless another case is asked by the user, respect to the admin roles which may be `superAdmin`, `admin` or `saasAdmin` in the currentuser or login response given with the `roleId`property. ```json { // ... "roleId":"superAdmin", // ... } ``` If the application needs an admin panel, or any admin related page, please use these roleId's to decide if the user can access those pages or not. ## 1. Authentication Routes ### 1.1 `POST /login` — User Login **Purpose:** Verifies user credentials and creates an authenticated session with a JWT access token. **Access Routes:** * `GET /login`: Returns a minimal HTML login page (for browser-based testing). * `POST /login`: Authenticates user credentials and returns an access token and session. #### Request Parameters | Parameter | Type | Required | Source | | ---------- | ------ | -------- | ----------------------- | | `username` | String | Yes | `request.body.username` | | `password` | String | Yes | `request.body.password` | #### Behavior * Authenticates credentials and returns a session object. * Sets cookie: `projectname-access-token[-tenantCodename]` * Adds the same token in response headers. * Accepts either `username` or `email` fields (if both exist, `username` is prioritized). #### Example ```js axios.post("/login", { username: "user@example.com", password: "securePassword" }); ``` #### Success Response ```json { "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", //... } ``` #### Error Responses * `401 Unauthorized`: Invalid credentials * `403 Forbidden`: Email/mobile verification or 2FA pending * `400 Bad Request`: Missing parameters --- ### 1.2 `POST /logout` — User Logout **Purpose:** Terminates the current session and clears associated authentication tokens. #### Behavior * Invalidates session (if exists). * Clears cookie `projectname-access-token[-tenantCodename]`. * Returns a confirmation response (always `200 OK`). #### Example ```js axios.post("/logout", {}, { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` #### Notes * Can be called without a session (idempotent behavior). * Works for both cookie-based and token-based sessions. #### Success Response ```json { "status": "OK", "message": "User logged out successfully" } ``` --- ## 2. Verification Services Overview All verification routes are grouped under the `/verification-services` base path. They follow a **two-step verification pattern**: `start` → `complete`. --- ## 3. Email Verification ### 3.1 Trigger Scenarios * After registration (`emailVerificationRequiredForLogin` = true) * When updating email address * When login fails due to unverified email ### 3.2 Flow Summary 1. `/start` → Generate & send code via email. 2. `/complete` → Verify code and mark email as verified. ** PLEASE NOTE ** Email verification is a frontend triiggered process. After user registers, the frontend should start the email verification process and navigate to its code input page. --- ### 3.3 `POST /verification-services/email-verification/start` **Purpose:** Starts the email verification by generating and sending a secret code. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `email` | String | Yes | User’s email address to verify | **Example Request** ```json { "email": "user@example.com" } ``` **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ In production, `secretCode` is **not** returned — only sent via email. **Error Responses** * `400 Bad Request`: Already verified * `403 Forbidden`: Too many attempts (rate limit) --- ### 3.4 `POST /verification-services/email-verification/complete` **Purpose:** Completes the verification using the received code. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `email` | String | Yes | User’s email | | `secretCode` | String | Yes | Verification code | **Success Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` **Error Responses** * `403 Forbidden`: Code expired or mismatched * `404 Not Found`: No verification in progress --- ### 3.5 Behavioral Notes * **Resend Cooldown:** `resendTimeWindow` (e.g. 60s) * **Expiration:** Codes expire after `expireTimeWindow` (e.g. 1 day) * **Single Active Session:** One verification per user --- ## 4. Mobile Verification ### 4.1 Trigger Scenarios * After registration (`mobileVerificationRequiredForLogin` = true) * When updating phone number * On login requiring mobile verification ### 4.2 Flow 1. `/start` → Sends verification code via SMS 2. `/complete` → Validates code and confirms number --- ### 4.3 `POST /verification-services/mobile-verification/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------ | | `email` | String | Yes | User’s email to locate mobile record | **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 180, "verificationType": "byCode", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ `secretCode` returned only in development. **Errors** * `400 Bad Request`: Already verified * `403 Forbidden`: Rate-limited --- ### 4.4 `POST /verification-services/mobile-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------------- | | `email` | String | Yes | Associated email | | `secretCode` | String | Yes | Code received via SMS | **Success Response** ```json { "status": "OK", "isVerified": true, "mobile": "+1 333 ...", // in testMode "userId": "user-uuid", } ``` --- ### 4.5 Behavioral Notes * **Cooldown:** One code per minute * **Expiration:** Codes valid for 1 day * **One Session Per User** --- ## 5. Two-Factor Authentication (2FA) ### 5.1 Email 2FA **Flow** 1. `/start` → Generates and sends email code 2. `/complete` → Verifies code and updates session --- #### `POST /verification-services/email-2factor-verification/start` | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ---------------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Current session | | `client` | String | No | Optional context | | `reason` | String | No | Reason for 2FA | **Response** ```json { "status": "OK", "sessionId": "user session id UUID", "userId": "user-uuid", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", } ``` --- #### `POST /verification-services/email-2factor-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `secretCode` | String | Yes | Code from email | **Response** ```json { // user session data "sessionId": "session-uuid", // ... } ``` --- ### 5.2 Mobile 2FA **Flow** 1. `/start` → Sends SMS code 2. `/complete` → Validates and finalizes session --- #### `POST /verification-services/mobile-2factor-verification/start` | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ----------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `client` | String | No | Context | | `reason` | String | No | Reason | **Response** ```json { "status": "OK", "sessionId": "user session id UUID", "userId": "user-uuid", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", } ``` --- #### `POST /verification-services/mobile-2factor-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------ | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `secretCode` | String | Yes | Code via SMS | **Response** ```json { // user session data "sessionId": "session-uuid", // ... } ``` --- ### 5.3 2FA Behavioral Notes * One active code per session * Cooldown: `resendTimeWindow` (e.g., 60s) * Expiration: `expireTimeWindow` (e.g., 5m) --- ## 6. Password Reset ### 6.1 By Email **Flow** 1. `/start` → Sends verification code via email 2. `/complete` → Validates and resets password --- #### `POST /verification-services/password-reset-by-email/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------- | | `email` | String | Yes | User email | **Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` #### `POST /verification-services/password-reset-by-email/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------- | | `email` | String | Yes | User email | | `secretCode` | String | Yes | Code received | | `password` | String | Yes | New password | **Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` --- ### 6.2 By Mobile **Flow** 1. `/start` → Sends SMS code 2. `/complete` → Validates and resets password --- #### `POST /verification-services/password-reset-by-mobile/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------- | | `mobile` | String | Yes | Mobile number | **Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` #### `POST /verification-services/password-reset-by-mobile/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ---------------- | | `email` | String | Yes | Associated email | | `secretCode` | String | Yes | Code via SMS | | `password` | String | Yes | New password | **Response** ```json { "status": "OK", "isVerified": true, "mobile": "+1 444 ....", // in testMode "userId": "user-uuid", } ``` --- ### 6.3 Behavioral Notes * Cooldown: 60s resend * Expiration: 24h * One session per user * Works without an active login session --- ## 7. Verification Method Types ### 7.1 `byCode` User manually enters the 6-digit code in frontend. ### 7.2 `byLink` Frontend handles a one-click verification via email/SMS link containing code parameters. ## 8) `GET /currentuser` — Current Session **Purpose** Return the currently authenticated user’s session. **Route Type** `sessionInfo` **Authentication** Requires a valid access token (header or cookie). ### Request *No parameters.* ### Example ```js axios.get("/currentuser", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) Returns the session object (identity, tenancy, token metadata): ```json { "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", "roleId": "user", "tenantId": "abc123", "accessToken": "jwt-token-string", "...": "..." } ``` ### Errors * **401 Unauthorized** — No active session/token ```json { "status": "ERR", "message": "No login found" } ``` **Notes** * Commonly called by web/mobile clients after login to hydrate session state. * Includes key identity/tenant fields and a token reference (if applicable). * Ensure a valid token is supplied to receive a 200 response. --- ## 9) `GET /permissions` — List Effective Permissions **Purpose** Return all effective permission grants for the current user. **Route Type** `permissionFetch` **Authentication** Requires a valid access token. ### Request *No parameters.* ### Example ```js axios.get("/permissions", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) Array of permission grants (aligned with `givenPermissions`): ```json [ { "id": "perm1", "permissionName": "adminPanel.access", "roleId": "admin", "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" }, { "id": "perm2", "permissionName": "orders.manage", "roleId": null, "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" } ] ``` **Field meanings (per item):** * `permissionName`: Granted permission key. * `roleId`: Present if granted via role. * `subjectUserId`: Present if granted directly to the user. * `subjectUserGroupId`: Present if granted via group. * `objectId`: Present if scoped to a specific object (OBAC). * `canDo`: `true` if enabled, `false` if restricted. ### Errors * **401 Unauthorized** — No active session ```json { "status": "ERR", "message": "No login found" } ``` * **500 Internal Server Error** — Unexpected failure **Notes** * Available on all Mindbricks-generated services (not only Auth). * **Auth service:** Reads live `givenPermissions` from DB. * **Other services:** Typically respond from a cached/projected view (e.g., ElasticSearch) for faster checks. > **Tip:** Cache permission results client-side/server-side and refresh after login or permission updates. --- ## 10) `GET /permissions/:permissionName` — Check Permission Scope **Purpose** Check whether the current user has a specific permission and return any scoped object exceptions/inclusions. **Route Type** `permissionScopeCheck` **Authentication** Requires a valid access token. ### Path Parameters | Name | Type | Required | Source | | ---------------- | ------ | -------- | ------------------------------- | | `permissionName` | String | Yes | `request.params.permissionName` | ### Example ```js axios.get("/permissions/orders.manage", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) ```json { "canDo": true, "exceptions": [ "a1f2e3d4-xxxx-yyyy-zzzz-object1", "b2c3d4e5-xxxx-yyyy-zzzz-object2" ] } ``` **Interpretation** * If `canDo: true`: permission is generally granted **except** the listed `exceptions` (restrictions). * If `canDo: false`: permission is generally **not** granted, **only** allowed for the listed `exceptions` (selective overrides). * `exceptions` contains object IDs (UUID strings) from the relevant domain model. ### Errors * **401 Unauthorized** — No active session/token. ## Services And Data Object ## Auth Service Authentication service for the project ### Auth Service Data Objects **User** A data object that stores the user information and handles login settings. ### Auth Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` ### `Get User` API This api is used by admin roles or the users themselves to get the user profile information. **Rest Route** The `getUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `getUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users/:userId** ```js axios({ method: 'GET', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update User` API This route is used by admins to update user profiles. **Rest Route** The `updateUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `updateUser` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/users/:userId** ```js axios({ method: 'PATCH', url: `/v1/users/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Profile` API This route is used by users to update their profiles. **Rest Route** The `updateProfile` API REST controller can be triggered via the following route: `/v1/profile/:userId` **Rest Request Parameters** The `updateProfile` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/profile/:userId** ```js axios({ method: 'PATCH', url: `/v1/profile/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create User` API This api is used by admin roles to create a new user manually from admin panels **Rest Route** The `createUser` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `createUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | email | String | true | request.body?.email | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **email** : A string value to represent the user's email. **password** : A string value to represent the user's password. It will be stored as hashed. **fullname** : A string value to represent the fullname of the user **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/users** ```js axios({ method: 'POST', url: '/v1/users', data: { avatar:"String", email:"String", password:"String", fullname:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete User` API This api is used by admins to delete user profiles. **Rest Route** The `deleteUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `deleteUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/users/:userId** ```js axios({ method: 'DELETE', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Archive Profile` API This api is used by users to archive their profiles. **Rest Route** The `archiveProfile` API REST controller can be triggered via the following route: `/v1/archiveprofile/:userId` **Rest Request Parameters** The `archiveProfile` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/archiveprofile/:userId** ```js axios({ method: 'DELETE', url: `/v1/archiveprofile/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Users` API The list of users is filtered by the tenantId. **Rest Route** The `listUsers` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `listUsers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users** ```js axios({ method: 'GET', url: '/v1/users', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Search Users` API The list of users is filtered by the tenantId. **Rest Route** The `searchUsers` API REST controller can be triggered via the following route: `/v1/searchusers` **Rest Request Parameters** The `searchUsers` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | keyword | String | true | request.query?.keyword | **keyword** : **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchusers** ```js axios({ method: 'GET', url: '/v1/searchusers', data: { }, params: { keyword:'"String"', } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Userrole` API This route is used by admin roles to update the user role.The default role is user when a user is registered. A user's role can be updated by superAdmin or admin **Rest Route** The `updateUserRole` API REST controller can be triggered via the following route: `/v1/userrole/:userId` **Rest Request Parameters** The `updateUserRole` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | roleId | String | true | request.body?.roleId | **userId** : This id paremeter is used to select the required data object that will be updated **roleId** : The new roleId of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userrole/:userId** ```js axios({ method: 'PATCH', url: `/v1/userrole/${userId}`, data: { roleId:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpassword` API This route is used to update the password of users in the profile page by users themselves **Rest Route** The `updateUserPassword` API REST controller can be triggered via the following route: `/v1/userpassword/:userId` **Rest Request Parameters** The `updateUserPassword` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | oldPassword | String | true | request.body?.oldPassword | | newPassword | String | true | request.body?.newPassword | **userId** : This id paremeter is used to select the required data object that will be updated **oldPassword** : The old password of the user that will be overridden bu the new one. Send for double check. **newPassword** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpassword/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpassword/${userId}`, data: { oldPassword:"String", newPassword:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpasswordbyadmin` API This route is used to change any user password by admins only. Superadmin can chnage all passwords, admins can change only nonadmin passwords **Rest Route** The `updateUserPasswordByAdmin` API REST controller can be triggered via the following route: `/v1/userpasswordbyadmin/:userId` **Rest Request Parameters** The `updateUserPasswordByAdmin` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | password | String | true | request.body?.password | **userId** : This id paremeter is used to select the required data object that will be updated **password** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpasswordbyadmin/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpasswordbyadmin/${userId}`, data: { password:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Briefuser` API This route is used by public to get simple user profile information. **Rest Route** The `getBriefUser` API REST controller can be triggered via the following route: `/v1/briefuser/:userId` **Rest Request Parameters** The `getBriefUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/briefuser/:userId** ```js axios({ method: 'GET', url: `/v1/briefuser/${userId}`, data: { }, params: { } }); ``` **REST Response** This route's response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "fullname": "String", "avatar": "String", "isActive": true } } ``` ### `Register User` API This api is used by public users to register themselves **Rest Route** The `registerUser` API REST controller can be triggered via the following route: `/v1/registeruser` **Rest Request Parameters** The `registerUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **password** : The password defined by the the user that is being registered. **fullname** : The fullname defined by the the user that is being registered. **email** : The email defined by the the user that is being registered. **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## AuctionOffer Service Handles auction bids and fixed-price offers for product listings, enforces real-time auction state, handles strict offer workflows including counter-offers, and triggers domain events for bid/offer notifications. No payment or frontend aggregation logic included. ### AuctionOffer Service Data Objects **AuctionOfferOffer** Represents an offer (best offer/counter-offer) made on a fixed-price product. Tracks buyer, seller, amounts, currency, state transitions, counter-offers, and expiry. **AuctionOfferBid** Represents an individual bid placed on an auction-type product. Linked to product and user, tracks bid amount, currency, status (ACTIVE, WON, LOST, CANCELLED), and time placed. ### AuctionOffer Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auctionoffer-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auctionoffer-api` * **Production:** `https://ebaycclone.mindbricks.co/auctionoffer-api` ### `Update Auctionofferoffer` API Updates offer: accepts/declines/counters by seller, withdraws by buyer before response. Enforces status transition rules, sets respondedAt. Triggers event. **Rest Route** The `updateAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `updateAuctionOfferOffer` api has got 8 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | message | String | false | request.body?.message | | status | Enum | false | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | **auctionOfferOfferId** : This id paremeter is used to select the required data object that will be updated **counterOfferId** : References another offer (counter-offer chain). **counterMessage** : Message accompanying seller's counter-offer (optional). **counterAmount** : Counter-offer amount (when offer is COUNTERED). **message** : Message/special notes from buyer (optional). **status** : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). **expiresAt** : When this offer expires (optional). **respondedAt** : When the seller (or buyer, for counter-offer) responded/updated the offer status. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Auctionofferbid` API Creates a new bid for an auction product. Validates auction status, not seller, product type, bid window, and ensures min. increment. Updates product.currentBid and product.highestBidderId atomically. Triggers notification event. **Rest Route** The `createAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids` **Rest Request Parameters** The `createAuctionOfferBid` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | bidAmount | Double | true | request.body?.bidAmount | | currency | String | true | request.body?.currency | | status | Enum | true | request.body?.status | | productId | ID | true | request.body?.productId | **bidAmount** : Bid amount placed by the user. **currency** : ISO currency for the bid (e.g., USD, EUR). **status** : Bid status: ACTIVE, WON, LOST, CANCELLED. **productId** : Product being bid on (must be AUCTION type). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/auctionofferbids** ```js axios({ method: 'POST', url: '/v1/auctionofferbids', data: { bidAmount:"Double", currency:"String", status:"Enum", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Auctionofferbid` API Gets a single bid (only visible to owner/admin or for auction history). **Rest Route** The `getAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `getAuctionOfferBid` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | **auctionOfferBidId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'GET', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Auctionofferoffer` API Gets a single offer (shown to buyer/seller or admin). **Rest Route** The `getAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `getAuctionOfferOffer` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | **auctionOfferOfferId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'GET', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Auctionofferoffers` API Lists offers by product, user, status, or counterOffer chain. **Rest Route** The `listAuctionOfferOffers` API REST controller can be triggered via the following route: `/v1/auctionofferoffers` **Rest Request Parameters** The `listAuctionOfferOffers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers** ```js axios({ method: 'GET', url: '/v1/auctionofferoffers', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferOffers": [ { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Auctionofferbid` API Updates a bid’s status (allow only status update, e.g. CANCELLED, WIN/LOSE on admin settlement). Only owner/admin, and only if auction not ended or not settled. Triggers notification event. **Rest Route** The `updateAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `updateAuctionOfferBid` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | | status | Enum | false | request.body?.status | **auctionOfferBidId** : This id paremeter is used to select the required data object that will be updated **status** : Bid status: ACTIVE, WON, LOST, CANCELLED. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { status:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Auctionofferoffer` API Creates a new offer for a fixed-price product, validating acceptOffers, type, eligibility, and product/seller/buyer active. Defaults to PENDING state. Triggers notification event. **Rest Route** The `createAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers` **Rest Request Parameters** The `createAuctionOfferOffer` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | productId | ID | true | request.body?.productId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | offerAmount | Double | true | request.body?.offerAmount | | message | String | false | request.body?.message | | status | Enum | true | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | **currency** : ISO currency (e.g., USD, EUR) for the offer. **productId** : Product the offer applies to (must be fixed-price, acceptOffers true). **counterOfferId** : References another offer (counter-offer chain). **counterMessage** : Message accompanying seller's counter-offer (optional). **counterAmount** : Counter-offer amount (when offer is COUNTERED). **offerAmount** : Primary offer amount from buyer. **message** : Message/special notes from buyer (optional). **status** : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). **expiresAt** : When this offer expires (optional). **respondedAt** : When the seller (or buyer, for counter-offer) responded/updated the offer status. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/auctionofferoffers** ```js axios({ method: 'POST', url: '/v1/auctionofferoffers', data: { currency:"String", productId:"ID", counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", offerAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Auctionofferbids` API Lists bids by product, user, or auction, supports history/analytics. **Rest Route** The `listAuctionOfferBids` API REST controller can be triggered via the following route: `/v1/auctionofferbids` **Rest Request Parameters** The `listAuctionOfferBids` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids** ```js axios({ method: 'GET', url: '/v1/auctionofferbids', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBids", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferBids": [ { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Auctionofferbid` API Soft-deletes a bid (for admin or self before auction ends). **Rest Route** The `deleteAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `deleteAuctionOfferBid` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | **auctionOfferBidId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Auctionofferoffer` API Soft-deletes an offer (allowed only in non-accepted/expired state). **Rest Route** The `deleteAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `deleteAuctionOfferOffer` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | **auctionOfferOfferId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## CategoryManagement Service Handles product categories and subcategories for marketplace browsing and classification, supporting public discovery plus admin-only management. ### CategoryManagement Service Data Objects **Category** Represents a product category in the marketplace (e.g., Electronics, Clothing, Toys), used for browsing, filtering, and discovery. Admins manage categories. **Subcategory** Represents a subcategory within a parent category (e.g., 'Smartphones' under 'Electronics'). Used for more granular product discovery and navigation. 'group' categorizes special display logic. ### CategoryManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/categorymanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/categorymanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/categorymanagement-api` ### `Delete Category` API Soft-delete a category (admin-only). **Rest Route** The `deleteCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `deleteCategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | **categoryId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/categories/:categoryId** ```js axios({ method: 'DELETE', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Subcategory` API Get a subcategory by ID. Public - only active subcategories returned except for admin. **Rest Route** The `getSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `getSubcategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | **subcategoryId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/subcategories/:subcategoryId** ```js axios({ method: 'GET', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Category` API Get a single category by ID. Public - only active categories returned (for non-admins). **Rest Route** The `getCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `getCategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | **categoryId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/categories/:categoryId** ```js axios({ method: 'GET', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Subcategory` API Update subcategory (admin-only), including group enum change. **Rest Route** The `updateSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `updateSubcategory` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | name | String | false | request.body?.name | | group | Enum | false | request.body?.group | **subcategoryId** : This id paremeter is used to select the required data object that will be updated **categoryId** : Reference to the parent category (category.id). **name** : Display name of the subcategory. **group** : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/subcategories/:subcategoryId** ```js axios({ method: 'PATCH', url: `/v1/subcategories/${subcategoryId}`, data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Subcategories` API List all subcategories for browsing/filtering, with support for group enum and parent category queries. Only active subcategories shown to public/non-admin users. **Rest Route** The `listSubcategories` API REST controller can be triggered via the following route: `/v1/subcategories` **Rest Request Parameters** The `listSubcategories` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/subcategories** ```js axios({ method: 'GET', url: '/v1/subcategories', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "subcategories": [ { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Subcategory` API Soft-delete a subcategory (admin-only). **Rest Route** The `deleteSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `deleteSubcategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | **subcategoryId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/subcategories/:subcategoryId** ```js axios({ method: 'DELETE', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Categories` API List all categories for browsing and filtering. Only active categories shown to public/non-admin users. **Rest Route** The `listCategories` API REST controller can be triggered via the following route: `/v1/categories` **Rest Request Parameters** The `listCategories` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/categories** ```js axios({ method: 'GET', url: '/v1/categories', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "categories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "categories": [ { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Category` API Update category details (admin-only). **Rest Route** The `updateCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `updateCategory` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | false | request.body?.title | **categoryId** : This id paremeter is used to select the required data object that will be updated **imageUrl** : URL for category image/avatar (optional, used for homepage visuals). **subtitle** : Optional short description for UI/tooltips. **title** : Display name of the category. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/categories/:categoryId** ```js axios({ method: 'PATCH', url: `/v1/categories/${categoryId}`, data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Subcategory` API Create a new subcategory under a given category (admin-only), with enum group constraint. **Rest Route** The `createSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories` **Rest Request Parameters** The `createSubcategory` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.body?.categoryId | | name | String | true | request.body?.name | | group | Enum | true | request.body?.group | **categoryId** : Reference to the parent category (category.id). **name** : Display name of the subcategory. **group** : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/subcategories** ```js axios({ method: 'POST', url: '/v1/subcategories', data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Category` API Create a new category (admin-only) for product classification. **Rest Route** The `createCategory` API REST controller can be triggered via the following route: `/v1/categories` **Rest Request Parameters** The `createCategory` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | true | request.body?.title | **imageUrl** : URL for category image/avatar (optional, used for homepage visuals). **subtitle** : Optional short description for UI/tooltips. **title** : Display name of the category. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/categories** ```js axios({ method: 'POST', url: '/v1/categories', data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## Messaging Service In-app messaging service for direct user-to-user text messages (buyers/sellers). Stores, retrieves, and manages user conversations. Launch version: text-only. ### Messaging Service Data Objects **MessagingMessage** A direct, text-only in-app message between two users (buyer/seller); stores sender, recipient, content, read status, and timestamp. ### Messaging Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/messaging-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/messaging-api` * **Production:** `https://ebaycclone.mindbricks.co/messaging-api` ### `List Messagingmessages` API List all messages in the conversation between the logged-in user and another party, ordered by sentAt descending. Can filter unread with isRead. Returns only messages visible to user (isActive). **Rest Route** The `listMessagingMessages` API REST controller can be triggered via the following route: `/v1/messagingmessages` **Rest Request Parameters** The `listMessagingMessages` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages** ```js axios({ method: 'GET', url: '/v1/messagingmessages', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessages", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "messagingMessages": [ { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Messagingmessage` API Send a new text message from the logged-in user to a recipient. Sender is set from session. Launch version supports only text content. **Rest Route** The `createMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages` **Rest Request Parameters** The `createMessagingMessage` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | toUserId | ID | true | request.body?.toUserId | | content | String | true | request.body?.content | | isRead | Boolean | true | request.body?.isRead | **toUserId** : Recipient (user) of this message. **content** : Text content of the message. No files or attachments for launch. **isRead** : If true, recipient has marked this message as read. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/messagingmessages** ```js axios({ method: 'POST', url: '/v1/messagingmessages', data: { toUserId:"ID", content:"String", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Messagingmessage` API Update a message (mark as read/unread). Only the recipient or admin can change isRead. No content edits. Sender, content, sentAt are immutable. **Rest Route** The `updateMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `updateMessagingMessage` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | | isRead | Boolean | false | request.body?.isRead | **messagingMessageId** : This id paremeter is used to select the required data object that will be updated **isRead** : If true, recipient has marked this message as read. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'PATCH', url: `/v1/messagingmessages/${messagingMessageId}`, data: { isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Messagingmessage` API Get a message by ID. Only accessible to the sender, the recipient, or an admin. Used for message detail view or reading a single message in a thread. **Rest Route** The `getMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `getMessagingMessage` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | **messagingMessageId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'GET', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Messagingmessage` API Delete a message (soft-delete). Only sender, recipient, or admin may delete a message. Deletion only hides it for the user; not a full erase unless both delete. **Rest Route** The `deleteMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `deleteMessagingMessage` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | **messagingMessageId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'DELETE', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## NotificationManagement Service Handles storage, management, and event-driven delivery of in-app and email notifications for user-impacting system events (bids, offers, orders, feedback, messaging, etc.). Supports marking notifications as read/unread, structured filtering by event type/channel, and always returns in-app notifications ordered by recency. ### NotificationManagement Service Data Objects **Notification** Stores and manages in-app and email notifications tied to user-facing events like bids, offers, orders, messaging, shipment, and feedback. Includes event type (notificationType) for filter/search, arbitrary event payload, and delivery channel. Soft-delete enforced. In-app notifications always sorted by createdAt DESC on retrieval. ### NotificationManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/notificationmanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/notificationmanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/notificationmanagement-api` ### `Create Notification` API Creates a notification entry in response to a system/business event. Only allowed for system/event processes and admins (not standard user/action). Typically event-driven, receives userId, notificationType, payload, and channel. **Rest Route** The `createNotification` API REST controller can be triggered via the following route: `/v1/notifications` **Rest Request Parameters** The `createNotification` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationType | Enum | true | request.body?.notificationType | | userId | ID | true | request.body?.userId | | channel | Enum | true | request.body?.channel | | payload | Object | true | request.body?.payload | | isRead | Boolean | true | request.body?.isRead | **notificationType** : Type of event triggering notification (e.g., BID_UPDATED, ORDER_SHIPPED, MESSAGE_RECEIVED, etc.). Used for display/icon and query filter. **userId** : User receiving the notification (recipient). **channel** : Channel by which notification is delivered: IN_APP or EMAIL. **payload** : Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. **isRead** : Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/notifications** ```js axios({ method: 'POST', url: '/v1/notifications', data: { notificationType:"Enum", userId:"ID", channel:"Enum", payload:"Object", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Notification` API Updates a notification (mark as read/unread, payload patch for e.g. admin fix). Only receiver (userId) or admins may update. isRead is primary update scenario; others very limited. **Rest Route** The `updateNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `updateNotification` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | | payload | Object | false | request.body?.payload | | isRead | Boolean | false | request.body?.isRead | **notificationId** : This id paremeter is used to select the required data object that will be updated **payload** : Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. **isRead** : Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/notifications/:notificationId** ```js axios({ method: 'PATCH', url: `/v1/notifications/${notificationId}`, data: { payload:"Object", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Notifications` API Returns filtered list of notifications for a user, with optional filters: notificationType, isRead, channel. Always sorted by createdAt (descending) for in-app notifications. Only retrieval allowed for owner/admin. **Rest Route** The `listNotifications` API REST controller can be triggered via the following route: `/v1/notifications` **Rest Request Parameters** The `listNotifications` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/notifications** ```js axios({ method: 'GET', url: '/v1/notifications', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notifications", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "notifications": [ { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Notification` API Soft-delete a notification record. Only receiver or admin may delete. **Rest Route** The `deleteNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `deleteNotification` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | **notificationId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/notifications/:notificationId** ```js axios({ method: 'DELETE', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Notification` API Retrieves a notification for the receiver or admin. Used to populate content on detail/expanded view. **Rest Route** The `getNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `getNotification` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | **notificationId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/notifications/:notificationId** ```js axios({ method: 'GET', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## SearchIndexing Service Maintains the denormalized search index (materialized view) for global, public search across products, sellers, categories, and subcategories. Handles indexing in response to entity events and exposes optimized query endpoints for BFF/aggregator. ### SearchIndexing Service Data Objects **SearchIndex** Materialized/denormalized search index record for a marketplace entity (product, seller, category, subcategory). Used exclusively for high-speed querying in BFF global/public search. ### SearchIndexing Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/searchindexing-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/searchindexing-api` * **Production:** `https://ebaycclone.mindbricks.co/searchindexing-api` ### `List Searchindexes` API List/search search index entries by type or referenceId (used by BFF/global search). Always excludes inactive (soft-deleted) records. Supports filtering and full-text search filters by documentType/referenceId for admin/maintenance use. **Rest Route** The `listSearchIndexes` API REST controller can be triggered via the following route: `/v1/searchindexes` **Rest Request Parameters** The `listSearchIndexes` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchindexes** ```js axios({ method: 'GET', url: '/v1/searchindexes', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndices", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "searchIndices": [ { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Searchindex` API Update an existing searchIndex record (by (documentType, referenceId) or id). Used in response to events (entity edit, data change); internal/automation/admin only. **Rest Route** The `updateSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `updateSearchIndex` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | | documentType | Enum | false | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | false | request.body?.indexedAt | **searchIndexId** : This id paremeter is used to select the required data object that will be updated **documentType** : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY **document** : Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. **referenceId** : ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. **indexedAt** : Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/searchindexs/:searchIndexId** ```js axios({ method: 'PATCH', url: `/v1/searchindexs/${searchIndexId}`, data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Searchindex` API Soft-delete a searchIndex record (by id or by (documentType, referenceId)). Typical use: in response to entity soft-delete; internal/automation/admin only. **Rest Route** The `deleteSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `deleteSearchIndex` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | **searchIndexId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/searchindexs/:searchIndexId** ```js axios({ method: 'DELETE', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Searchindex` API Create a new searchIndex record (internal, used by event triggers and admin tools only). Typically called when a new product/seller/category/subcategory is created. **Rest Route** The `createSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs` **Rest Request Parameters** The `createSearchIndex` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | documentType | Enum | true | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | true | request.body?.indexedAt | **documentType** : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY **document** : Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. **referenceId** : ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. **indexedAt** : Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/searchindexs** ```js axios({ method: 'POST', url: '/v1/searchindexs', data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Searchindex` API Get a single denormalized index record (by id, or documentType+referenceId). Used by BFF for full entity search. Always excludes inactive records unless forced (admin only path). **Rest Route** The `getSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `getSearchIndex` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | **searchIndexId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchindexs/:searchIndexId** ```js axios({ method: 'GET', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## AdminModeration Service Administrative backend service for moderation and manual override actions. Responsible for logging all admin interventions (user/product/feedback/media/category/order/notification/searchindex moderation), triggering corrections via interservice calls, and providing comprehensive audit trails for compliance. ### AdminModeration Service Data Objects **ModerationAction** Audit record for all admin moderation/override actions affecting core business entities. Links to admin, timestamp, entity type/ID, action performed, and reason. ### AdminModeration Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/adminmoderation-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/adminmoderation-api` * **Production:** `https://ebaycclone.mindbricks.co/adminmoderation-api` ### `Get Moderationaction` API Get a single moderation action log by ID. Used to review admin audit trails; accessible only to platform admins. **Rest Route** The `getModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `getModerationAction` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | **moderationActionId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/moderationactions/:moderationActionId** ```js axios({ method: 'GET', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Moderationaction` API Soft-deletes a moderation action log record (dangerous; allowed only to superadmins or strict manual correction), primarily for audit correction or internal error cleanup. Usually, moderation logs are immutable. **Rest Route** The `deleteModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `deleteModerationAction` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | **moderationActionId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/moderationactions/:moderationActionId** ```js axios({ method: 'DELETE', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Moderationaction` API Logs an admin moderation or override action in the system for audit and traceability. Requires admin login, takes context from session, and creates an audit entry for any admin operation over any entity type. **Rest Route** The `createModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions` **Rest Request Parameters** The `createModerationAction` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | entityId | ID | true | request.body?.entityId | | entityType | Enum | true | request.body?.entityType | | reason | String | true | request.body?.reason | | actionType | Enum | true | request.body?.actionType | **entityId** : ID of target entity affected by moderation (user/product/etc). **entityType** : Type of entity affected (USER, PRODUCT, FEEDBACK, MEDIA, CATEGORY, NOTIFICATION, ORDER, SEARCHINDEX). **reason** : Explanation or justification for the moderation action performed. **actionType** : Type of moderation action (e.g., SOFT_DELETE, RESTORE, UPDATE_ROLE, MANUAL_CORRECTION, MEDIA_FLAG, INDEX_REBUILD, PAYMENT_FIX, FEEDBACK_OVERRIDE, ADMIN_NOTE). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/moderationactions** ```js axios({ method: 'POST', url: '/v1/moderationactions', data: { entityId:"ID", entityType:"Enum", reason:"String", actionType:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Moderationactions` API List moderation actions for admin dashboard/audit search. Supports filtering by admin, entityType, entityId, actionType, and date. Always sorted by most recent action. **Rest Route** The `listModerationActions` API REST controller can be triggered via the following route: `/v1/moderationactions` **Rest Request Parameters** The `listModerationActions` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/moderationactions** ```js axios({ method: 'GET', url: '/v1/moderationactions', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationActions", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "moderationActions": [ { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Moderationaction` API Allows update of explanation/note on a moderation action for correction (typically by admin or superadmin only). No entity/type/admin may be changed after creation; only 'reason' is editable for audit consistency. **Rest Route** The `updateModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `updateModerationAction` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | | reason | String | false | request.body?.reason | **moderationActionId** : This id paremeter is used to select the required data object that will be updated **reason** : Explanation or justification for the moderation action performed. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/moderationactions/:moderationActionId** ```js axios({ method: 'PATCH', url: `/v1/moderationactions/${moderationActionId}`, data: { reason:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## WatchlistCart Service Handles user watchlists (with custom folders) and shopping cart preparation for checkout, strictly enforcing only fixed-price products in carts, supporting item moves/bulk operations, and robust default/folder logic.. ### WatchlistCart Service Data Objects **WatchlistItem** Item in a user’s watchlist, optionally in a named folder; references product and user. **CartItem** Single product pending checkout in a user’s cart. Only fixed-price products permitted; quantity supported for multi-unit purchases (if allowed). **WatchlistList** A named folder/list in a user’s watchlist. Default list exists for all users. Custom lists may be created and deleted. ### WatchlistCart Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/watchlistcart-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/watchlistcart-api` * **Production:** `https://ebaycclone.mindbricks.co/watchlistcart-api` ### `List Watchlistlist` API List all lists in user’s watchlists. Supports listing by listId for folders. **Rest Route** The `listWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists` **Rest Request Parameters** The `listWatchlistList` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/watchlistlists** ```js axios({ method: 'GET', url: '/v1/watchlistlists', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Cartitems` API List all cart items for a user (pending checkout). **Rest Route** The `listCartItems` API REST controller can be triggered via the following route: `/v1/cartitems` **Rest Request Parameters** The `listCartItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/cartitems** ```js axios({ method: 'GET', url: '/v1/cartitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "price": "Double", "title": "String", "type": "Enum", "type_idx": "Integer", "mediaAssetIds": "ID" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Cartitem` API Remove an item from the user’s cart. **Rest Route** The `deleteCartItem` API REST controller can be triggered via the following route: `/v1/cartitems/:cartItemId` **Rest Request Parameters** The `deleteCartItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | **cartItemId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/cartitems/:cartItemId** ```js axios({ method: 'DELETE', url: `/v1/cartitems/${cartItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Watchlistitem` API Add product to user’s watchlist (default or target list/folder). One (user, product, list) per item enforced. Block duplicates. **Rest Route** The `createWatchlistItem` API REST controller can be triggered via the following route: `/v1/watchlistitems` **Rest Request Parameters** The `createWatchlistItem` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | productId | ID | true | request.body?.productId | | listId | ID | false | request.body?.listId | **addedAt** : Timestamp watchlist item created. **productId** : Referenced product in the watchlist. **listId** : Owning watchlistList; null if in default watchlist. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/watchlistitems** ```js axios({ method: 'POST', url: '/v1/watchlistitems', data: { addedAt:"Date", productId:"ID", listId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Watchlistitems` API List all products in user’s watchlists. Supports listing by listId for folders. **Rest Route** The `listWatchlistItems` API REST controller can be triggered via the following route: `/v1/watchlistitems` **Rest Request Parameters** The `listWatchlistItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/watchlistitems** ```js axios({ method: 'GET', url: '/v1/watchlistitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Cartitemquantity` API Change the quantity for a cart item. User must own the item. **Rest Route** The `updateCartItemQuantity` API REST controller can be triggered via the following route: `/v1/cartitemquantity/:cartItemId` **Rest Request Parameters** The `updateCartItemQuantity` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | | quantity | Integer | false | request.body?.quantity | **cartItemId** : This id paremeter is used to select the required data object that will be updated **quantity** : How many units (if product allows). **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/cartitemquantity/:cartItemId** ```js axios({ method: 'PATCH', url: `/v1/cartitemquantity/${cartItemId}`, data: { quantity:"Integer", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Watchlistlist` API Create a new custom watchlist folder. Name must be unique per user; ‘Default’ is reserved for system. **Rest Route** The `createWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists` **Rest Request Parameters** The `createWatchlistList` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | name | String | true | request.body?.name | **name** : Custom folder or list name. 'Default' is reserved (non-deletable for each user). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/watchlistlists** ```js axios({ method: 'POST', url: '/v1/watchlistlists', data: { name:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Watchlistlist` API Delete a custom watchlist (folder). Items are reassigned to user’s default list. Cannot delete default list. **Rest Route** The `deleteWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists/:watchlistListId` **Rest Request Parameters** The `deleteWatchlistList` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistListId | ID | true | request.params?.watchlistListId | **watchlistListId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistlists/:watchlistListId** ```js axios({ method: 'DELETE', url: `/v1/watchlistlists/${watchlistListId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Watchlistitem` API Remove a product from a user’s watchlist. **Rest Route** The `deleteWatchlistItem` API REST controller can be triggered via the following route: `/v1/watchlistitems/:watchlistItemId` **Rest Request Parameters** The `deleteWatchlistItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistItemId | ID | true | request.params?.watchlistItemId | **watchlistItemId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistitems/:watchlistItemId** ```js axios({ method: 'DELETE', url: `/v1/watchlistitems/${watchlistItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Cartitem` API Add an item to the user’s cart. Only fixed-price products allowed. Duplicates not permitted. **Rest Route** The `createCartItem` API REST controller can be triggered via the following route: `/v1/cartitems` **Rest Request Parameters** The `createCartItem` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | **addedAt** : Timestamp added to cart. **quantity** : How many units (if product allows). **productId** : Product being checked out. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/cartitems** ```js axios({ method: 'POST', url: '/v1/cartitems', data: { addedAt:"Date", quantity:"Integer", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Do Userwatchlist` API userwatchlist **Rest Route** The `userwatchlist` API REST controller can be triggered via the following route: `/v1/userwatchlist` **Rest Request Parameters** The `userwatchlist` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userwatchlist** ```js axios({ method: 'GET', url: '/v1/userwatchlist', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Usercartitems` API list all cart items adde by user **Rest Route** The `listUserCartItems` API REST controller can be triggered via the following route: `/v1/usercartitems` **Rest Request Parameters** The `listUserCartItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/usercartitems** ```js axios({ method: 'GET', url: '/v1/usercartitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "shipping": "Double" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Do Userwatchlistlists` API list all watch lists created by user **Rest Route** The `userwatchlistlists` API REST controller can be triggered via the following route: `/v1/userwatchlistlists` **Rest Request Parameters** The `userwatchlistlists` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userwatchlistlists** ```js axios({ method: 'GET', url: '/v1/userwatchlistlists', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ## ProductListing Service Handles product listings (both auction and fixed-price), image/media storage with validations, enforces immutable type, soft-delete, and public product discovery. ### ProductListing Service Data Objects **ProductListingMedia** Stores and manages images/media associated with products, including secure URL, MIME type, and size validation. Each asset can be used by multiple products. **ProductListingProduct** Represents a single product listing (fixed-price or auction) in the marketplace, with seller, category, type, price information, shipping details, media references, and dynamic auction fields. ### ProductListing Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/productlisting-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/productlisting-api` * **Production:** `https://ebaycclone.mindbricks.co/productlisting-api` ### `List Productlistingmedia` API List all media assets (admin or for media management/bulk preview). **Rest Route** The `listProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias` **Rest Request Parameters** The `listProductListingMedia` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias** ```js axios({ method: 'GET', url: '/v1/productlistingmedias', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedias", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingMedias": [ { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Productlistingproduct` API Get a single product listing. Checks isActive and public status. Includes media, category, subcategory, and seller info via joins. **Rest Route** The `getProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `getProductListingProduct` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | **productListingProductId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'GET', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Productlistingownproducts` API listing the loggedin user's products **Rest Route** The `listProductListingOwnProducts` API REST controller can be triggered via the following route: `/v1/productlistingownproducts` **Rest Request Parameters** The `listProductListingOwnProducts` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingownproducts** ```js axios({ method: 'GET', url: '/v1/productlistingownproducts', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Productlistingmedia` API Get a single media asset by ID (for admin or to display in product UI). **Rest Route** The `getProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` **Rest Request Parameters** The `getProductListingMedia` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | **productListingMediaId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'GET', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Productlistingproducts` API List public product listings. Only isActive=true records are returned. Includes category, subcategory, seller, media joins. Supports filtering. **Rest Route** The `listProductListingProducts` API REST controller can be triggered via the following route: `/v1/productlistingproducts` **Rest Request Parameters** The `listProductListingProducts` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts** ```js axios({ method: 'GET', url: '/v1/productlistingproducts', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Productlistingproduct` API Soft-delete a product listing. Only owner or admin can delete. **Rest Route** The `deleteProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `deleteProductListingProduct` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | **productListingProductId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'DELETE', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Productlistingproduct` API Update a product listing. Product type cannot be changed (immutable). **Rest Route** The `updateProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `updateProductListingProduct` api has got 21 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | | currency | String | false | request.body?.currency | | description | Text | false | request.body?.description | | condition | Enum | false | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | false | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | false | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | false | request.body?.shippingMethod | | shipping | Double | false | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | false | request.body?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | **productListingProductId** : This id paremeter is used to select the required data object that will be updated **currency** : ISO currency code (e.g. USD, EUR) **description** : Product detailed description **condition** : Condition of product: BRAND_NEW, NEW, or USED **startBid** : The opening bid value (for auction type products) **endPrice** : Optional immediate sale/upper end price for auction (if AUCTION type) **price** : Product price (required if fixed price type) **title** : Product title **startPrice** : Minimum starting price for auction (required if AUCTION type) **endBid** : The upper (max) bid value for auction products (if any) **estimatedDelivery** : Estimated delivery date for this product **shippingCurrency** : Currency code for shipping cost **mediaAssetIds** : References to associated product/media assets **shippingMethod** : Shipping option for product: STANDARD, EXPRESS, or FREE **shipping** : Shipping cost for this product **startBidDate** : Date/time when auction bidding begins **subcategoryId** : Reference to subcategory **categoryId** : Reference to parent category **endBidDate** : Date/time when auction bidding ends **currentBid** : Current highest bid for auction-type product (updated atomically on bid placement) **highestBidderId** : User ID of current highest bidder (auction-only, updated by auction microservice) **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'PATCH', url: `/v1/productlistingproducts/${productListingProductId}`, data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Productlistingproduct` API Create a new product listing (fixed or auction), conditioned on product type. Type is immutable after creation. **Rest Route** The `createProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts` **Rest Request Parameters** The `createProductListingProduct` api has got 21 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | description | Text | true | request.body?.description | | condition | Enum | true | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | true | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | type | Enum | true | request.body?.type | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | true | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | true | request.body?.shippingMethod | | shipping | Double | true | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | true | request.body?.subcategoryId | | categoryId | ID | true | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | **currency** : ISO currency code (e.g. USD, EUR) **description** : Product detailed description **condition** : Condition of product: BRAND_NEW, NEW, or USED **startBid** : The opening bid value (for auction type products) **endPrice** : Optional immediate sale/upper end price for auction (if AUCTION type) **price** : Product price (required if fixed price type) **title** : Product title **startPrice** : Minimum starting price for auction (required if AUCTION type) **type** : Product listing type, either FIXED or AUCTION (immutable after creation) **endBid** : The upper (max) bid value for auction products (if any) **estimatedDelivery** : Estimated delivery date for this product **shippingCurrency** : Currency code for shipping cost **mediaAssetIds** : References to associated product/media assets **shippingMethod** : Shipping option for product: STANDARD, EXPRESS, or FREE **shipping** : Shipping cost for this product **startBidDate** : Date/time when auction bidding begins **subcategoryId** : Reference to subcategory **categoryId** : Reference to parent category **endBidDate** : Date/time when auction bidding ends **currentBid** : Current highest bid for auction-type product (updated atomically on bid placement) **highestBidderId** : User ID of current highest bidder (auction-only, updated by auction microservice) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/productlistingproducts** ```js axios({ method: 'POST', url: '/v1/productlistingproducts', data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", type:"Enum", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Productlistingmedia` API Soft-delete a media asset (typically by admin or media owner for flagged/invalid content). **Rest Route** The `deleteProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` **Rest Request Parameters** The `deleteProductListingMedia` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | **productListingMediaId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'DELETE', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Productlistingmedia` API Create a new media asset record after validation. Used mainly by edge controller after upload. **Rest Route** The `createProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias` **Rest Request Parameters** The `createProductListingMedia` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | mimeType | String | true | request.body?.mimeType | | productId | ID | false | request.body?.productId | | url | String | true | request.body?.url | | size | Integer | true | request.body?.size | **mimeType** : MIME type of the uploaded media (e.g., image/jpeg) **productId** : ID of product associated with this media asset **url** : Secure, validated URL for the media asset (S3 or equivalent) **size** : Media size in bytes (for validation and quota) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/productlistingmedias** ```js axios({ method: 'POST', url: '/v1/productlistingmedias', data: { mimeType:"String", productId:"ID", url:"String", size:"Integer", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## OrderManagement Service Handles all marketplace orders, manual checkout flows for fixed-price/offer/auction settlements, Stripe payment processing and webhook reconciliation, explicit status updates (shipping, delivery, cancellation), and feedback eligibility via orderItems. ### OrderManagement Service Data Objects **OrderManagementOrder** Marketplace order record. Stores buyer, shipping, status, items, Stripe payment data, and manual shipment/delivery events. Only accessible to admins or the buyer/seller of order items. **OrderManagementOrderItem** Order line item representing purchase of a single product from a specific seller as part of an order. Enables feedback, delivery, and per-seller analytics. Immutable after order creation. **Sys_orderManagementOrderPayment** A payment storage object to store the payment life cyle of orders based on orderManagementOrder object. It is autocreated based on the source object's checkout config **Sys_paymentCustomer** A payment storage object to store the customer values of the payment platform **Sys_paymentMethod** A payment storage object to store the payment methods of the platform customers ### OrderManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/ordermanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/ordermanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/ordermanagement-api` ### `List Ordermanagementorders` API List orders, filtered for buyer and/or seller, or by admin. Includes select orderItems. **Rest Route** The `listOrderManagementOrders` API REST controller can be triggered via the following route: `/v1/ordermanagementorders` **Rest Request Parameters** The `listOrderManagementOrders` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ordermanagementorders', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Ordermanagementorderitem` API Get a specific order item (for feedback/business logic). **Rest Route** The `getOrderManagementOrderItem` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems/:orderManagementOrderItemId` **Rest Request Parameters** The `getOrderManagementOrderItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderItemId | ID | true | request.params?.orderManagementOrderItemId | **orderManagementOrderItemId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems/:orderManagementOrderItemId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderitems/${orderManagementOrderItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Ordermanagementorder` API Soft-delete/cancel order by admin or eligible actor prior to shipment. Sets status to CANCELLED and cancels active payment intent if pending. Irreversible and blocks feedback. **Rest Route** The `deleteOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` **Rest Request Parameters** The `deleteOrderManagementOrder` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorder` API Get single order by ID. Only accessible to admin, buyer, or relevant sellers of items within this order. Includes all orderItems. **Rest Route** The `getOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` **Rest Request Parameters** The `getOrderManagementOrder` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | **orderManagementOrderId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Ordermanagementorderstatus` API Update order status (manual shipment, delivery, cancellation/refund). Restricted: only seller of all items can mark as shipped, only buyer can confirm delivery, only admin can set refund/cancelled. Timestamps updated as per business rule. **Rest Route** The `updateOrderManagementOrderStatus` API REST controller can be triggered via the following route: `/v1/ordermanagementorderstatus/:orderManagementOrderId` **Rest Request Parameters** The `updateOrderManagementOrderStatus` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **status** : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderstatus/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderstatus/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Complete Orderstripewebhook` API Webhook endpoint called by Stripe to reconcile payment state and update order status based on paymentIntentId and event data. No authentication required (Stripe IPs only). **Rest Route** The `completeOrderStripeWebhook` API REST controller can be triggered via the following route: `/v1/completeorderstripewebhook/:orderManagementOrderId` **Rest Request Parameters** The `completeOrderStripeWebhook` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **status** : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/completeorderstripewebhook/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/completeorderstripewebhook/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderbyproductid` API get orders by productId **Rest Route** The `getOrderManagementOrderByProductId` API REST controller can be triggered via the following route: `/v1/ordermanagementorderbyproductid/:items` **Rest Request Parameters** The `getOrderManagementOrderByProductId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | items | String | true | request.params?.items | **orderManagementOrderId** : This id paremeter is used to query the required data object. **items** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderbyproductid/:items** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderbyproductid/${items}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Ordermanagementorder` API Creates an order and initiates Stripe payment. Validates that all products in the order are fixed-price, populates orderItems, saves Stripe customer/paymentMethod/paymentIntentId for reconciliation. Only accessible to buyers for own checkouts and only allows fixed-price product checkout (no auction). **Rest Route** The `createOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders` **Rest Request Parameters** The `createOrderManagementOrder` api has got 14 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderNumber | String | true | request.body?.orderNumber | | items | ID | false | request.body?.items | | paymentMethodId | String | true | request.body?.paymentMethodId | | stripeCustomerId | String | true | request.body?.stripeCustomerId | | paymentIntentId | String | false | request.body?.paymentIntentId | | shippingAddress | Object | true | request.body?.shippingAddress | | summary | Object | true | request.body?.summary | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderNumber** : Unique, human-friendly order number (displayed to users); enforced unique. **items** : Array of orderManagementOrderItem ids representing items in this order. **paymentMethodId** : Stripe paymentMethodId used for payment. Not stored if cash or other payment (future). **stripeCustomerId** : Stripe customerId of buyer; enables saved/paymentMethodId flows. **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **shippingAddress** : Shipping address for the order (copy of buyer address at purchase time). **summary** : Object with total, subtotal, currency, shipping, discount breakdown as snapshot of order at time of purchase. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorders** ```js axios({ method: 'POST', url: '/v1/ordermanagementorders', data: { orderNumber:"String", items:"ID", paymentMethodId:"String", stripeCustomerId:"String", paymentIntentId:"String", shippingAddress:"Object", summary:"Object", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderitems` API List order items for a given order or for buyer/seller analytics. Used for feedback management. **Rest Route** The `listOrderManagementOrderItems` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems` **Rest Request Parameters** The `listOrderManagementOrderItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Ownordermanagementorders` API list the loggedin user orders **Rest Route** The `listOwnOrderManagementOrders` API REST controller can be triggered via the following route: `/v1/ownordermanagementorders` **Rest Request Parameters** The `listOwnOrderManagementOrders` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ownordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ownordermanagementorders', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Lis Ordermanagementownorderitem` API list the loggedin user's order items **Rest Route** The `lisOrderManagementOwnOrderItem` API REST controller can be triggered via the following route: `/v1/lisordermanagementownorderitem` **Rest Request Parameters** The `lisOrderManagementOwnOrderItem` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/lisordermanagementownorderitem** ```js axios({ method: 'GET', url: '/v1/lisordermanagementownorderitem', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Ordermanagementorderitem` API create order item **Rest Route** The `createOrderManagementOrderItem` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems` **Rest Request Parameters** The `createOrderManagementOrderItem` api has got 8 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | shipping | Double | true | request.body?.shipping | | orderId | ID | true | request.body?.orderId | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | | price | Double | true | request.body?.price | | sellerId | ID | true | request.body?.sellerId | | title | String | true | request.body?.title | | currency | String | true | request.body?.currency | **shipping** : Shipping cost for this product (may be 0 for free shipping). **orderId** : Parent order this item belongs to; enables join and lifecycle tracking. **quantity** : Number of units purchased for this product. **productId** : ID of product purchased in this line item. **price** : Unit price for this product at purchase time. **sellerId** : UserId of seller (owner of product at purchase time). **title** : Product title at purchase time (copied for convenience/audit). **currency** : Currency code for price/shipping (ISO 4217). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderitems** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderitems', data: { shipping:"Double", orderId:"ID", quantity:"Integer", productId:"ID", price:"Double", sellerId:"ID", title:"String", currency:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpayment2` API This route is used to get the payment information by ID. **Rest Route** The `getOrderManagementOrderPayment2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `getOrderManagementOrderPayment2` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderpayments2` API This route is used to list all payments. **Rest Route** The `listOrderManagementOrderPayments2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayments2` **Rest Request Parameters** The `listOrderManagementOrderPayments2` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Ordermanagementorderpayment` API This route is used to create a new payment. **Rest Route** The `createOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment` **Rest Request Parameters** The `createOrderManagementOrderPayment` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderId | ID | true | request.body?.orderId | | paymentId | String | true | request.body?.paymentId | | paymentStatus | String | true | request.body?.paymentStatus | | statusLiteral | String | true | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | **orderId** : an ID value to represent the orderId which is the ID parameter of the source orderManagementOrder object **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderpayment', data: { orderId:"ID", paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Ordermanagementorderpayment` API This route is used to update an existing payment. **Rest Route** The `updateOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `updateOrderManagementOrderPayment` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | false | request.body?.paymentId | | paymentStatus | String | false | request.body?.paymentStatus | | statusLiteral | String | false | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | **sys_orderManagementOrderPaymentId** : This id paremeter is used to select the required data object that will be updated **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Ordermanagementorderpayment` API This route is used to delete a payment. **Rest Route** The `deleteOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `deleteOrderManagementOrderPayment` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderpayments2` API This route is used to list all payments. **Rest Route** The `listOrderManagementOrderPayments2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayments2` **Rest Request Parameters** The `listOrderManagementOrderPayments2` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Ordermanagementorderpaymentbyorderid` API This route is used to get the payment information by order id. **Rest Route** The `getOrderManagementOrderPaymentByOrderId` API REST controller can be triggered via the following route: `/v1/orderManagementOrderpaymentbyorderid/:orderId` **Rest Request Parameters** The `getOrderManagementOrderPaymentByOrderId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | orderId | String | true | request.params?.orderId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **orderId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbyorderid/:orderId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbyorderid/${orderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpaymentbypaymentid` API This route is used to get the payment information by payment id. **Rest Route** The `getOrderManagementOrderPaymentByPaymentId` API REST controller can be triggered via the following route: `/v1/orderManagementOrderpaymentbypaymentid/:paymentId` **Rest Request Parameters** The `getOrderManagementOrderPaymentByPaymentId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | true | request.params?.paymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **paymentId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbypaymentid/:paymentId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbypaymentid/${paymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpayment2` API This route is used to get the payment information by ID. **Rest Route** The `getOrderManagementOrderPayment2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `getOrderManagementOrderPayment2` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Start Ordermanagementorderpayment` API Start payment for orderManagementOrder **Rest Route** The `startOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/startordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `startOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to start a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/startordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/startordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Refresh Ordermanagementorderpayment` API Refresh payment info for orderManagementOrder from Stripe **Rest Route** The `refreshOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/refreshordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `refreshOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to refresh a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/refreshordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/refreshordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Callback Ordermanagementorderpayment` API Refresh payment values by gateway webhook call for orderManagementOrder **Rest Route** The `callbackOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/callbackordermanagementorderpayment` **Rest Request Parameters** The `callbackOrderManagementOrderPayment` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.body?.orderManagementOrderId | **orderManagementOrderId** : The order id parameter that will be read from webhook callback params **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/callbackordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/callbackordermanagementorderpayment', data: { orderManagementOrderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Get Paymentcustomerbyuserid` API This route is used to get the payment customer information by user id. **Rest Route** The `getPaymentCustomerByUserId` API REST controller can be triggered via the following route: `/v1/paymentcustomers/:userId` **Rest Request Parameters** The `getPaymentCustomerByUserId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_paymentCustomerId | ID | true | request.params?.sys_paymentCustomerId | | userId | String | true | request.params?.userId | **sys_paymentCustomerId** : This id paremeter is used to query the required data object. **userId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomers/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_paymentCustomer": { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Paymentcustomers` API This route is used to list all payment customers. **Rest Route** The `listPaymentCustomers` API REST controller can be triggered via the following route: `/v1/paymentcustomers` **Rest Request Parameters** The `listPaymentCustomers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers** ```js axios({ method: 'GET', url: '/v1/paymentcustomers', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentCustomers": [ { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Paymentcustomermethods` API This route is used to list all payment customer methods. **Rest Route** The `listPaymentCustomerMethods` API REST controller can be triggered via the following route: `/v1/paymentcustomermethods/:userId` **Rest Request Parameters** The `listPaymentCustomerMethods` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | String | true | request.params?.userId | **userId** : This parameter will be used to select the data objects that want to be listed **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomermethods/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomermethods/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentMethods", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentMethods": [ { "id": "ID", "paymentMethodId": "String", "userId": "ID", "customerId": "String", "cardHolderName": "String", "cardHolderZip": "String", "platform": "String", "cardInfo": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ## Feedback Service Handles feedback for order items: one feedback per buyer/orderItem, attached to sellerId for analytical feedback/rating aggregation and reputation tracking. Enables querying feedbacks received/given for sellers and buyers. test ### Feedback Service Data Objects **Feedback** One feedback per (buyer, orderItem). Stores rating (1-5), comment, ties to seller for analytics. Created only after delivery confirmed on order item. ### Feedback Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/feedback-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/feedback-api` * **Production:** `https://ebaycclone.mindbricks.co/feedback-api` ### `List Feedbacks` API List feedback with filtering by buyerId (given), sellerId (received), productId, or orderItemId. Used for showing seller profile, buyer profile, or order analytics. **Rest Route** The `listFeedbacks` API REST controller can be triggered via the following route: `/v1/feedbacks` **Rest Request Parameters** The `listFeedbacks` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/feedbacks** ```js axios({ method: 'GET', url: '/v1/feedbacks', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedbacks", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "feedbacks": [ { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Feedback` API Get a single feedback by id. Accessible to public (for seller profile, product, or audit views). **Rest Route** The `getFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `getFeedback` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | **feedbackId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/feedbacks/:feedbackId** ```js axios({ method: 'GET', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Feedback` API Update feedback (comment/rating) for existing feedback record (buyer only). Admin can update as override. **Rest Route** The `updateFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `updateFeedback` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | | rating | Integer | false | request.body?.rating | | comment | String | false | request.body?.comment | **feedbackId** : This id paremeter is used to select the required data object that will be updated **rating** : Rating (1-5 stars) submitted by buyer. Required. **comment** : Optional textual feedback comment, max ~500 chars. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/feedbacks/:feedbackId** ```js axios({ method: 'PATCH', url: `/v1/feedbacks/${feedbackId}`, data: { rating:"Integer", comment:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Feedback` API Delete (soft-delete) feedback (by buyer or admin). Only feedback owner or admin. **Rest Route** The `deleteFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `deleteFeedback` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | **feedbackId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/feedbacks/:feedbackId** ```js axios({ method: 'DELETE', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Feedback` API Buyer creates feedback for a delivered order item. Only allowed once per (buyer, orderItemId). Allowed only once order item is delivered. **Rest Route** The `createFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks` **Rest Request Parameters** The `createFeedback` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | rating | Integer | true | request.body?.rating | | orderId | ID | true | request.body?.orderId | | orderItemId | ID | true | request.body?.orderItemId | | sellerId | ID | true | request.body?.sellerId | | comment | String | false | request.body?.comment | | productId | ID | true | request.body?.productId | **rating** : Rating (1-5 stars) submitted by buyer. Required. **orderId** : Order containing this purchased item. Used for aggregation and validation. **orderItemId** : Purchased item (line item) in order. Feedback is per (buyer, orderItem). **sellerId** : Seller of product for analytics/aggregation. Not author; used for querying feedback about sellers. **comment** : Optional textual feedback comment, max ~500 chars. **productId** : The product listing being reviewed (snapshot at order time). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/feedbacks** ```js axios({ method: 'POST', url: '/v1/feedbacks', data: { rating:"Integer", orderId:"ID", orderItemId:"ID", sellerId:"ID", comment:"String", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # REST API GUIDE ## ebaycclone-feedback-service Handles feedback for order items: one feedback per buyer/orderItem, attached to sellerId for analytical feedback/rating aggregation and reputation tracking. Enables querying feedbacks received/given for sellers and buyers. test ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to: Email: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. ## Documentation Scope Welcome to the official documentation for the Feedback Service's REST API. This document is designed to provide a comprehensive guide to interfacing with our Feedback Service exclusively through RESTful API endpoints. **Intended Audience** This documentation is intended for developers and integrators who are looking to interact with the Feedback Service via HTTP requests for purposes such as creating, updating, deleting and querying Feedback objects. **Overview** Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases. Beyond REST It's important to note that the Feedback Service also supports alternative methods of interaction, such as gRPC and messaging via a Message Broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation. ## Authentication And Authorization To ensure secure access to the Feedback service's protected endpoints, a project-wide access token is required. This token serves as the primary method for authenticating requests to our service. However, it's important to note that access control varies across different routes: **Protected API**: Certain API (routes) require specific authorization levels. Access to these routes is contingent upon the possession of a valid access token that meets the route-specific authorization criteria. Unauthorized requests to these routes will be rejected. **Public API **: The service also includes public API (routes) that are accessible without authentication. These public endpoints are designed for open access and do not require an access token. ### Token Locations When including your access token in a request, ensure it is placed in one of the following specified locations. The service will sequentially search these locations for the token, utilizing the first one it encounters. | Location | Token Name / Param Name | | ---------------------- | ---------------------------- | | Query | access_token | | Authorization Header | Bearer | | Header | ebaycclone-access-token| | Cookie | ebaycclone-access-token| Please ensure the token is correctly placed in one of these locations, using the appropriate label as indicated. The service prioritizes these locations in the order listed, processing the first token it successfully identifies. ## Api Definitions This section outlines the API endpoints available within the Feedback service. Each endpoint can receive parameters through various methods, meticulously described in the following definitions. It's important to understand the flexibility in how parameters can be included in requests to effectively interact with the Feedback service. This service is configured to listen for HTTP requests on port `3008`, serving both the main API interface and default administrative endpoints. The following routes are available by default: * **API Test Interface (API Face):** `/` * **Swagger Documentation:** `/swagger` * **Postman Collection Download:** `/getPostmanCollection` * **Health Checks:** `/health` and `/admin/health` * **Current Session Info:** `/currentuser` * **Favicon:** `/favicon.ico` This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/feedback-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/feedback-api` * **Production:** `https://ebaycclone.mindbricks.co/feedback-api` **Parameter Inclusion Methods:** Parameters can be incorporated into API requests in several ways, each with its designated location. Understanding these methods is crucial for correctly constructing your requests: **Query Parameters:** Included directly in the URL's query string. **Path Parameters:** Embedded within the URL's path. **Body Parameters:** Sent within the JSON body of the request. **Session Parameters:** Automatically read from the session object. This method is used for parameters that are intrinsic to the user's session, such as userId. When using an API that involves session parameters, you can omit these from your request. The service will automatically bind them to the API layer, provided that a session is associated with your request. **Note on Session Parameters:** Session parameters represent a unique method of parameter inclusion, relying on the context of the user's session. A common example of a session parameter is userId, which the service automatically associates with your request when a session exists. This feature ensures seamless integration of user-specific data without manual input for each request. By adhering to the specified parameter inclusion methods, you can effectively utilize the Feedback service's API endpoints. For detailed information on each endpoint, including required parameters and their accepted locations, refer to the individual API definitions below. ### Common Parameters The `Feedback` service's business API support several common parameters designed to modify and enhance the behavior of API requests. These parameters are not individually listed in the API route definitions to avoid repetition. Instead, refer to this section to understand how to leverage these common behaviors across different routes. Note that all common parameters should be included in the query part of the URL. ### Supported Common Parameters: - **getJoins (BOOLEAN)**: Controls whether to retrieve associated objects along with the main object. By default, `getJoins` is assumed to be `true`. Set it to `false` if you prefer to receive only the main fields of an object, excluding its associations. - **excludeCQRS (BOOLEAN)**: Applicable only when `getJoins` is `true`. By default, `excludeCQRS` is set to `false`. Enabling this parameter (`true`) omits non-local associations, which are typically more resource-intensive as they require querying external services like ElasticSearch for additional information. Use this to optimize response times and resource usage. - **requestId (String)**: Identifies a request to enable tracking through the service's log chain. A random hex string of 32 characters is assigned by default. If you wish to use a custom `requestId`, simply include it in your query parameters. - **caching (BOOLEAN)**: Determines the use of caching for query API. By default, caching is enabled (`true`). To ensure the freshest data directly from the database, set this parameter to `false`, bypassing the cache. - **cacheTTL (Integer)**: Specifies the Time-To-Live (TTL) for query caching, in seconds. This is particularly useful for adjusting the default caching duration (5 minutes) for `get list` queries. Setting a custom `cacheTTL` allows you to fine-tune the cache lifespan to meet your needs. - **pageNumber (Integer)**: For paginated `get list` API's, this parameter selects which page of results to retrieve. The default is `1`, indicating the first page. To disable pagination and retrieve all results, set `pageNumber` to `0`. - **pageRowCount (Integer)**: In conjunction with paginated API's, this parameter defines the number of records per page. The default value is `25`. Adjusting `pageRowCount` allows you to control the volume of data returned in a single request. By utilizing these common parameters, you can tailor the behavior of API requests to suit your specific requirements, ensuring optimal performance and usability of the `Feedback` service. ### Error Response If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity: - **400 Bad Request**: The request was improperly formatted or contained invalid parameters, preventing the server from processing it. - **401 Unauthorized**: The request lacked valid authentication credentials or the credentials provided do not grant access to the requested resource. - **404 Not Found**: The requested resource was not found on the server. - **500 Internal Server Error**: The server encountered an unexpected condition that prevented it from fulfilling the request. Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ### Object Structure of a Successfull Response When the `Feedback` service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client. **Key Characteristics of the Response Envelope:** - **Data Presentation**: Depending on the nature of the request, the service returns either a single data object or an array of objects encapsulated within the JSON envelope. - **Creation and Update API**: These API routes return the unmodified (pure) form of the data object(s), without any associations to other data objects. - **Delete API**: Even though the data is removed from the database, the last known state of the data object(s) is returned in its pure form. - **Get Requests**: A single data object is returned in JSON format. - **Get List Requests**: An array of data objects is provided, reflecting a collection of resources. - **Data Structure and Joins**: The complexity of the data structure in the response can vary based on the API's architectural design and the join options specified in the request. The architecture might inherently limit join operations, or they might be dynamically controlled through query parameters. - **Pure Data Forms**: In some cases, the response mirrors the exact structure found in the primary data table, without extensions. - **Extended Data Forms**: Alternatively, responses might include data extended through joins with tables within the same service or aggregated from external sources, such as ElasticSearch indices related to other services. - **Join Varieties**: The extensions might involve one-to-one joins, resulting in single object associations, or one-to-many joins, leading to an array of objects. In certain instances, the data might even feature nested inclusions from other data objects. **Design Considerations**: The structure of a API's response data is meticulously crafted during the service's architectural planning. This design ensures that responses adequately reflect the intended data relationships and service logic, providing clients with rich and meaningful information. **Brief Data**: Certain API's return a condensed version of the object data, intentionally selecting only specific fields deemed useful for that request. In such instances, the API documentation will detail the properties included in the response, guiding developers on what to expect. ### API Response Structure The API utilizes a standardized JSON envelope to encapsulate responses. This envelope is designed to consistently deliver both the requested data and essential metadata, ensuring that clients can efficiently interpret and utilize the response. **HTTP Status Codes:** - **200 OK**: This status code is returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request has been processed successfully. - **201 Created**: This status code is specific to CREATE operations, signifying that the requested resource has been successfully created. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling the successful execution of the request. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3 "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` - **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation performed. **Handling Errors:** For details on handling error scenarios and understanding the structure of error responses, please refer to the "Error Response" section provided earlier in this documentation. It outlines how error conditions are communicated, including the use of HTTP status codes and standardized JSON structures for error messages. ## Resources Feedback service provides the following resources which are stored in its own database as a data object. Note that a resource for an api access is a data object for the service. ### Feedback resource *Resource Definition* : One feedback per (buyer, orderItem). Stores rating (1-5), comment, ties to seller for analytics. Created only after delivery confirmed on order item. *Feedback Resource Properties* | Name | Type | Required | Default | Definition | | ---- | ---- | -------- | ------- | ---------- | | **rating** | Integer | | | *Rating (1-5 stars) submitted by buyer. Required.* | | **orderId** | ID | | | *Order containing this purchased item. Used for aggregation and validation.* | | **buyerId** | ID | | | *User/buyer leaving feedback. Authenticated user, must match order item buyer.* | | **orderItemId** | ID | | | *Purchased item (line item) in order. Feedback is per (buyer, orderItem).* | | **sellerId** | ID | | | *Seller of product for analytics/aggregation. Not author; used for querying feedback about sellers.* | | **comment** | String | | | *Optional textual feedback comment, max ~500 chars.* | | **productId** | ID | | | *The product listing being reviewed (snapshot at order time).* | ## Business Api ### List Feedbacks API *API Definition* : List feedback with filtering by buyerId (given), sellerId (received), productId, or orderItemId. Used for showing seller profile, buyer profile, or order analytics. *API Crud Type* : list *Default access route* : *GET* `/v1/feedbacks` The listFeedbacks api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/feedbacks** ```js axios({ method: 'GET', url: '/v1/feedbacks', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`feedbacks`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"feedbacks","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","feedbacks":[{"id":"ID","rating":"Integer","orderId":"ID","buyerId":"ID","orderItemId":"ID","sellerId":"ID","comment":"String","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For List Feedbacks](businessApi/listFeedbacks). ### Get Feedback API *API Definition* : Get a single feedback by id. Accessible to public (for seller profile, product, or audit views). *API Crud Type* : get *Default access route* : *GET* `/v1/feedbacks/:feedbackId` #### Parameters The getFeedback api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | To access the api you can use the **REST** controller with the path **GET /v1/feedbacks/:feedbackId** ```js axios({ method: 'GET', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`feedback`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"feedback","method":"GET","action":"get","appVersion":"Version","rowCount":1,"feedback":{"id":"ID","rating":"Integer","orderId":"ID","buyerId":"ID","orderItemId":"ID","sellerId":"ID","comment":"String","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Get Feedback](businessApi/getFeedback). ### Update Feedback API *API Definition* : Update feedback (comment/rating) for existing feedback record (buyer only). Admin can update as override. *API Crud Type* : update *Default access route* : *PATCH* `/v1/feedbacks/:feedbackId` #### Parameters The updateFeedback api has got 3 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | | rating | Integer | false | request.body?.rating | | comment | String | false | request.body?.comment | To access the api you can use the **REST** controller with the path **PATCH /v1/feedbacks/:feedbackId** ```js axios({ method: 'PATCH', url: `/v1/feedbacks/${feedbackId}`, data: { rating:"Integer", comment:"String", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`feedback`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"feedback","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"feedback":{"id":"ID","rating":"Integer","orderId":"ID","buyerId":"ID","orderItemId":"ID","sellerId":"ID","comment":"String","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Update Feedback](businessApi/updateFeedback). ### Delete Feedback API *API Definition* : Delete (soft-delete) feedback (by buyer or admin). Only feedback owner or admin. *API Crud Type* : delete *Default access route* : *DELETE* `/v1/feedbacks/:feedbackId` #### Parameters The deleteFeedback api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | To access the api you can use the **REST** controller with the path **DELETE /v1/feedbacks/:feedbackId** ```js axios({ method: 'DELETE', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`feedback`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"feedback","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"feedback":{"id":"ID","rating":"Integer","orderId":"ID","buyerId":"ID","orderItemId":"ID","sellerId":"ID","comment":"String","productId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Delete Feedback](businessApi/deleteFeedback). ### Create Feedback API *API Definition* : Buyer creates feedback for a delivered order item. Only allowed once per (buyer, orderItemId). Allowed only once order item is delivered. *API Crud Type* : create *Default access route* : *POST* `/v1/feedbacks` #### Parameters The createFeedback api has got 6 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | rating | Integer | true | request.body?.rating | | orderId | ID | true | request.body?.orderId | | orderItemId | ID | true | request.body?.orderItemId | | sellerId | ID | true | request.body?.sellerId | | comment | String | false | request.body?.comment | | productId | ID | true | request.body?.productId | To access the api you can use the **REST** controller with the path **POST /v1/feedbacks** ```js axios({ method: 'POST', url: '/v1/feedbacks', data: { rating:"Integer", orderId:"ID", orderItemId:"ID", sellerId:"ID", comment:"String", productId:"ID", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`feedback`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"feedback","method":"POST","action":"create","appVersion":"Version","rowCount":1,"feedback":{"id":"ID","rating":"Integer","orderId":"ID","buyerId":"ID","orderItemId":"ID","sellerId":"ID","comment":"String","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Create Feedback](businessApi/createFeedback). ### Authentication Specific Routes ### Common Routes ### Route: currentuser *Route Definition*: Retrieves the currently authenticated user's session information. *Route Type*: sessionInfo *Access Route*: `GET /currentuser` #### Parameters This route does **not** require any request parameters. #### Behavior - Returns the authenticated session object associated with the current access token. - If no valid session exists, responds with a 401 Unauthorized. ```js // Sample GET /currentuser call axios.get("/currentuser", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** Returns the session object, including user-related data and token information. ``` { "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", "roleId": "user", "tenantId": "abc123", "accessToken": "jwt-token-string", ... } ``` **Error Response** **401 Unauthorized:** No active session found. ``` { "status": "ERR", "message": "No login found" } ``` **Notes** * This route is typically used by frontend or mobile applications to fetch the current session state after login. * The returned session includes key user identity fields, tenant information (if applicable), and the access token for further authenticated requests. * Always ensure a valid access token is provided in the request to retrieve the session. ### Route: permissions `*Route Definition*`: Retrieves all effective permission records assigned to the currently authenticated user. `*Route Type*`: permissionFetch *Access Route*: `GET /permissions` #### Parameters This route does **not** require any request parameters. #### Behavior - Fetches all active permission records (`givenPermissions` entries) associated with the current user session. - Returns a full array of permission objects. - Requires a valid session (`access token`) to be available. ```js // Sample GET /permissions call axios.get("/permissions", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** Returns an array of permission objects. ```json [ { "id": "perm1", "permissionName": "adminPanel.access", "roleId": "admin", "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" }, { "id": "perm2", "permissionName": "orders.manage", "roleId": null, "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" } ] ``` Each object reflects a single permission grant, aligned with the givenPermissions model: - `**permissionName**`: The permission the user has. - `**roleId**`: If the permission was granted through a role. -` **subjectUserId**`: If directly granted to the user. - `**subjectUserGroupId**`: If granted through a group. - `**objectId**`: If tied to a specific object (OBAC). - `**canDo**`: True or false flag to represent if permission is active or restricted. **Error Responses** * **401 Unauthorized**: No active session found. ```json { "status": "ERR", "message": "No login found" } ``` * **500 Internal Server Error**: Unexpected error fetching permissions. **Notes** * The /permissions route is available across all backend services generated by Mindbricks, not just the auth service. * Auth service: Fetches permissions freshly from the live database (givenPermissions table). * Other services: Typically use a cached or projected view of permissions stored in a common ElasticSearch store, optimized for faster authorization checks. > **Tip**: > Applications can cache permission results client-side or server-side, but should occasionally refresh by calling this endpoint, especially after login or permission-changing operations. ### Route: permissions/:permissionName *Route Definition*: Checks whether the current user has access to a specific permission, and provides a list of scoped object exceptions or inclusions. *Route Type*: permissionScopeCheck *Access Route*: `GET /permissions/:permissionName` #### Parameters | Parameter | Type | Required | Population | |------------------|--------|----------|------------------------| | permissionName | String | Yes | `request.params.permissionName` | #### Behavior - Evaluates whether the current user **has access** to the given `permissionName`. - Returns a structured object indicating: - Whether the permission is generally granted (`canDo`) - Which object IDs are explicitly included or excluded from access (`exceptions`) - Requires a valid session (`access token`). ```js // Sample GET /permissions/orders.manage axios.get("/permissions/orders.manage", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** ```json { "canDo": true, "exceptions": [ "a1f2e3d4-xxxx-yyyy-zzzz-object1", "b2c3d4e5-xxxx-yyyy-zzzz-object2" ] } ``` * If `canDo` is `true`, the user generally has the permission, but not for the objects listed in `exceptions` (i.e., restrictions). * If `canDo` is `false`, the user does not have the permission by default — but only for the objects in `exceptions`, they do have permission (i.e., selective overrides). * The exceptions array contains valid **UUID strings**, each corresponding to an object ID (typically from the data model targeted by the permission). ## Copyright All sources, documents and other digital materials are copyright of . ## About Us For more information please visit our website: . . . # Service Design Specification **ebaycclone-feedback-service** documentation -Version:**`1.0.1`** ## Scope This document provides a structured architectural overview of the `feedback` microservice, detailing its configuration, data model, authorization logic, business rules, and API design. It has been automatically generated based on the service definition within Mindbricks, ensuring that the information reflects the source of truth used during code generation and deployment. The document is intended to serve multiple audiences: * **Service architects** can use it to validate design decisions and ensure alignment with broader architectural goals. * **Developers and maintainers** will find it useful for understanding the structure and behavior of the service, facilitating easier debugging, feature extension, and integration with other systems. * **Stakeholders and reviewers** can use it to gain a clear understanding of the service's capabilities and domain logic. > **Note for Frontend Developers**: While this document is valuable for understanding business logic and data interactions, please refer to the [Service API Documentation](#) for endpoint-level specifications and integration details. > **Note for Backend Developers**: Since the code for this service is automatically generated by Mindbricks, you typically won't need to implement or modify it manually. However, this document is especially valuable when you're building other services—whether within Mindbricks or externally—that need to interact with or depend on this service. It provides a clear reference to the service's data contracts, business rules, and API structure, helping ensure compatibility and correct integration. ## `Feedback` Service Settings [**Edit**](feedback/serviceSettings) Handles feedback for order items: one feedback per buyer/orderItem, attached to sellerId for analytical feedback/rating aggregation and reputation tracking. Enables querying feedbacks received/given for sellers and buyers. test ### Service Overview This service is configured to listen for HTTP requests on port `3008`, serving both the main API interface and default administrative endpoints. The following routes are available by default: * **API Test Interface (API Face):** `/` * **Swagger Documentation:** `/swagger` * **Postman Collection Download:** `/getPostmanCollection` * **Health Checks:** `/health` and `/admin/health` * **Current Session Info:** `/currentuser` * **Favicon:** `/favicon.ico` The service uses a **PostgreSQL** database for data storage, with the database name set to `ebaycclone-feedback-service`. This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/feedback-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/feedback-api` * **Production:** `https://ebaycclone.mindbricks.co/feedback-api` ### Authentication & Security - **Login Required**: Yes This service requires user authentication for access. It supports both JWT and RSA-based authentication mechanisms, ensuring secure user sessions and data integrity. If a crud route also is configured to require login, it will check a valid JWT token in the request query/header/bearer/cookie. If the token is valid, it will extract the user information from the token and make the fetched session data available in the request context. ### Service Data Objects The service uses a **PostgreSQL** database for data storage, with the database name set to `ebaycclone-feedback-service`. Data deletion is managed using a **soft delete** strategy. Instead of removing records from the database, they are flagged as inactive by setting the `isActive` field to `false`. | Object Name | Description | Public Access | |-------------|-------------|---------------| | `feedback` | One feedback per (buyer, orderItem). Stores rating (1-5), comment, ties to seller for analytics. Created only after delivery confirmed on order item. | accessProtected | ## feedback Data Object ### Object Overview **Description:** One feedback per (buyer, orderItem). Stores rating (1-5), comment, ties to seller for analytics. Created only after delivery confirmed on order item. This object represents a core data structure within the service and acts as the blueprint for database interaction, API generation, and business logic enforcement. It is defined using the `ObjectSettings` pattern, which governs its behavior, access control, caching strategy, and integration points with other systems such as Stripe and Redis. ### Core Configuration - **Soft Delete:** Enabled — Determines whether records are marked inactive (`isActive = false`) instead of being physically deleted. - **Public Access:** accessProtected — If enabled, anonymous users may access this object’s data depending on API-level rules. ### Composite Indexes - **uniqBuyerOrderItem**: [buyerId, orderItemId] This composite index is defined to optimize query performance for complex queries involving multiple fields. The index also defines a conflict resolution strategy for duplicate key violations. When a new record would violate this composite index, the following action will be taken: **On Duplicate**: `throwError` An error will be thrown, preventing the insertion of conflicting data. ### Properties Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `rating` | Integer | Yes | Rating (1-5 stars) submitted by buyer. Required. | | `orderId` | ID | Yes | Order containing this purchased item. Used for aggregation and validation. | | `buyerId` | ID | Yes | User/buyer leaving feedback. Authenticated user, must match order item buyer. | | `orderItemId` | ID | Yes | Purchased item (line item) in order. Feedback is per (buyer, orderItem). | | `sellerId` | ID | Yes | Seller of product for analytics/aggregation. Not author; used for querying feedback about sellers. | | `comment` | String | No | Optional textual feedback comment, max ~500 chars. | | `productId` | ID | Yes | The product listing being reviewed (snapshot at order time). | * Required properties are mandatory for creating objects and must be provided in the request body if no default value is set. ### Default Values Default values are automatically assigned to properties when a new object is created, if no value is provided in the request body. Since default values are applied on db level, they should be literal values, not expressions.If you want to use expressions, you can use transposed parameters in any business API to set default values dynamically. - **rating**: 0 - **orderId**: '00000000-0000-0000-0000-000000000000' - **buyerId**: '00000000-0000-0000-0000-000000000000' - **orderItemId**: '00000000-0000-0000-0000-000000000000' - **sellerId**: '00000000-0000-0000-0000-000000000000' - **productId**: '00000000-0000-0000-0000-000000000000' ### Constant Properties `orderId` `buyerId` `orderItemId` `sellerId` `productId` Constant properties are defined to be immutable after creation, meaning they cannot be updated or changed once set. They are typically used for properties that should remain constant throughout the object's lifecycle. A property is set to be constant if the `Allow Update` option is set to `false`. ### Auto Update Properties `rating` `orderId` `buyerId` `orderItemId` `sellerId` `comment` `productId` An update crud API created with the option `Auto Params` enabled will automatically update these properties with the provided values in the request body. If you want to update any property in your own business logic not by user input, you can set the `Allow Auto Update` option to false. These properties will be added to the update API's body parameters and can be updated by the user if any value is provided in the request body. ### Elastic Search Indexing `rating` `orderId` `buyerId` `orderItemId` `sellerId` `comment` `productId` Properties that are indexed in Elastic Search will be searchable via the Elastic Search API. While all properties are stored in the elastic search index of the data object, only those marked for Elastic Search indexing will be available for search queries. ### Database Indexing `buyerId` `orderItemId` `sellerId` Properties that are indexed in the database will be optimized for query performance, allowing for faster data retrieval. Make a property indexed in the database if you want to use it frequently in query filters or sorting. ### Relation Properties `orderId` `buyerId` `orderItemId` `sellerId` `productId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. You can define relations in the data object properties, which will be used to create foreign key constraints in the database. For complex joins operations, Mindbricks supportsa BFF pattern, where you can view dynamic and static views based on Elastic Search Indexes. Use db level relations for simple one-to-one or one-to-many relationships, and use BFF views for complex joins that require multiple data objects to be joined together. - **orderId**: ID Relation to `orderManagementOrder`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes - **buyerId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes - **orderItemId**: ID Relation to `orderManagementOrderItem`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes - **sellerId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes - **productId**: ID Relation to `productListingProduct`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes ### Session Data Properties `buyerId` Session data properties are used to store data that is specific to the user session, allowing for personalized experiences and temporary data storage. If a property is configured as session data, it will be automatically mapped to the related field in the user session during CRUD operations. Note that session data properties can not be mutated by the user, but only by the system. - **buyerId**: ID property will be mapped to the session parameter `userId`. This property is also used to store the owner of the session data, allowing for ownership checks and access control. ### Filter Properties `rating` `orderId` `buyerId` `orderItemId` `sellerId` `productId` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's that have "Auto Params" enabled. - **rating**: Integer has a filter named `rating` - **orderId**: ID has a filter named `orderId` - **buyerId**: ID has a filter named `buyerId` - **orderItemId**: ID has a filter named `orderItemId` - **sellerId**: ID has a filter named `sellerId` - **productId**: ID has a filter named `productId` ## Business Logic feedback has got 5 Business APIs to manage its internal and crud logic. For the details of each business API refer to its chapter. * [List Feedbacks](/businessLogic/listfeedbacks) * [Get Feedback](/businessLogic/getfeedback) * [Update Feedback](/businessLogic/updatefeedback) * [Delete Feedback](/businessLogic/deletefeedback) * [Create Feedback](/businessLogic/createfeedback) ## Edge Controllers No edge controllers defined for this service. --- ## Service Library ### Functions No general functions defined. ### Hook Functions No hook functions defined. ### Edge Functions No edge functions defined. ### Templates No templates defined. ### Assets No assets defined. ### Public Assets No public assets defined. --- ### Event Emission --- ## Integration Patterns ## Deployment Considerations ### Environment Configuration - **HTTP Port**: `3008` - **Database Type**: MongoDB - **Global Soft Delete**: Enabled ## Implementation Guidelines ### Development Workflow 1. **Data Model Implementation**: Generate database schema from data object definitions 2. **CRUD Route Generation**: Implement auto-generated routes with custom logic 3. **Custom Logic Integration**: Implement hook functions and edge functions 4. **Authentication Integration**: Configure with project-level authentication 5. **Testing**: Unit and integration testing for all components ### Code Generation Expectations - **Database Schema**: Auto-generated from data objects and relationships - **API Routes**: REST endpoints with customizable behavior - **Validation Logic**: Input validation from property definitions - **Access Control**: Authentication and authorization middleware ### Custom Code Integration Points - **Hook Functions**: Lifecycle-specific custom logic - **Edge Functions**: Full request/response control - **Library Functions**: Reusable business logic - **Templates**: Dynamic content rendering ### Testing Strategy #### Unit Testing - Test all custom library functions - Test validation logic and business rules - Test hook function implementations #### Integration Testing - Test API endpoints with authentication scenarios - Test database operations and transactions - Test external integrations - Test event emission and Kafka integration #### Performance Testing - Load test high-traffic endpoints - Test caching effectiveness - Monitor database query performance - Test scalability under load --- ## Appendices ### Data Type Reference | Type | Description | Storage | |------|-------------|---------| | ID | Unique identifier | UUID (SQL) / ObjectID (NoSQL) | | String | Short text (≤255 chars) | VARCHAR | | Text | Long-form text | TEXT | | Integer | 32-bit whole numbers | INT | | Boolean | True/false values | BOOLEAN | | Double | 64-bit floating point | DOUBLE | | Float | 32-bit floating point | FLOAT | | Short | 16-bit integers | SMALLINT | | Object | JSON object | JSONB (PostgreSQL) / Object (MongoDB) | | Date | ISO 8601 timestamp | TIMESTAMP | | Enum | Fixed numeric values | SMALLINT with lookup | ### Enum Value Mappings #### Request Locations - `0`: Bearer token in Authorization header - `1`: Cookie value - `2`: Custom HTTP header - `3`: Query parameter - `4`: Request body property - `5`: URL path parameter - `6`: Session data - `7`: Root request object #### HTTP Methods - `0`: GET - `1`: POST - `2`: PUT - `3`: PATCH - `4`: DELETE ### Edge Function Signature ```javascript async function edgeFunction(request) { // Custom request processing // Return response object or throw error return { data: {}, status: 200, message: "Success" }; } ``` --- *This document was generated from the service architecture definition and should be kept in sync with implementation changes.* # **EBAYCCLONE** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 1 - Authentication Management** This document is the first part of a REST API guide for the ebaycclone project. It is designed for AI agents that will generate frontend code to consume the project’s backend. This first document includes general information about the project and its authentication management. Please read it carefully and implement all requirements described here. The project has 1 auth service, 1 notification service, 1 BFF service, and 10 business services, plus other helper services such as bucket and realtime. In this document you will be informed only about the auth service. The initial frontend will be generated to use this service. Each service is a separate microservice application and listens for HTTP requests at different service URLs. Services may be deployed to the preview server, staging server, or production server. Therefore, each service has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the home page. ## Project Introduction ebaycClone is a comprehensive backend for an online marketplace supporting auctions and fixed-price sales of physical goods, with role-based access, public user registration, Stripe payments, notifications, and robust ownership enforcement. ## API Structure ### Object Structure of a Successful Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client. **HTTP Status Codes:** * **200 OK**: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully. * **201 Created**: Returned for CREATE operations, indicating that the resource was created successfully. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling that the request executed successfully. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` * **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation. ### Additional Data Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature. ### Error Response If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity: * **400 Bad Request**: The request was improperly formatted or contained invalid parameters. * **401 Unauthorized**: The request lacked a valid authentication token; login is required. * **403 Forbidden**: The current token does not grant access to the requested resource. * **404 Not Found**: The requested resource was not found on the server. * **500 Internal Server Error**: The server encountered an unexpected condition. Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Accessing the backend Each backend service has its own URL for each deployment environment. Users may want to test the frontend in one of the three deployments—preview, staging, or production. Please ensure that the home page includes a deployment server selection option so that, as the frontend coding agent, you can set the base URL for all services. The base URL of the application in each environment is as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com` * **Staging:** `https://ebaycclone-stage.mindbricks.co` * **Production:** `https://ebaycclone.mindbricks.co` For the auth service, the base URLs are: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` For each other service, the service base URL will be given in the service sections. Any request that requires login must include a valid token in the Bearer authorization header. Please note that for each service in the project (which will be introduced in following pages) will use a different address so it is a good practice to define a separate client for each service in the frontend application lib source. Not only the different base urls, some services even may need different access rules when shaping the request. ## Home page First build a home page which shows some static content about the application, and has got login and registration (if is public) buttons. The home page shpuld be updated later according to the content that each service provides, as a frontend developer use best and common practices to reflect the service content to the home page. User may also give extra information for the home page content in addtion to this prompt. Note that this page should include a deployment (environment) selection option to set the base URL. Set the default to `production`. After user logs in, page header should show the current login state as in modern web pages, logged in user fullname, avatar, email and with a logout link, make a fancy current user component. The home page may have different views before and after login. ## Registration Management ### User Registration User registration is public in the application, ensure that the register and login pages include a deployment server selection option so that you can set the base URL for all services. Start with a home page and set up the registration , verification, and login flow. Using the `registeruser` route of the auth API, send the required fields from your registration page. Please create a simple and polished registration page that includes only the necessary fields of the registration API. The `registerUser` API in the `auth` service is described with the request and response structure below. Note that since the `registerUser` API is a business API, it is versioned; call it with the given version like `/v1/registeruser`. ### `Register User` API This api is used by public users to register themselves **Rest Route** The `registerUser` API REST controller can be triggered via the following route: `/v1/registeruser` **Rest Request Parameters** The `registerUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **password** : The password defined by the the user that is being registered. **fullname** : The fullname defined by the the user that is being registered. **email** : The email defined by the the user that is being registered. **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` After a successful registration, the frontend code should handle any verification requirements. Verification Management will be given in teh next prompt. The registration response will include a `user` object in the root envelope; this object contains user information with an `id` field. ## Login Management After successful registration and completing any required verifications, the user can log in. Please create a minimal, polished login page where the user can enter email and password. Note that this page should respect the deployment (environment) selection option made in the home page to set the base URL. If the user reaches this page directly skipping home page, the default `production`deployment will be used. The login API returns a created session. This session can be retrieved later with the access token using the `/currentuser` system route. Any request that requires login must include a valid token. When a user logs in successfully, the response JSON includes a JWT access token in the `accessToken` field. Under normal conditions, this token is also set as a cookie and consumed automatically. However, since AI coding agents’ preview options may fail to use cookies, ensure that each request includes the access token in the Bearer authorization header. If the login fails due to verification requirements, the response JSON includes an `errCode`. If it is `EmailVerificationNeeded`, start the email verification flow; if it is `MobileVerificationNeeded`, start the mobile verification flow. After a successful login, you can access session (user) information at any time with the `/currentuser` API. On inner pages, show brief profile information (avatar, name, etc.) using the session information from this API. Note that the `currentuser` API returns a session object, so there is no `id` property; instead, the values for the user and session are exposed as `userId` and `sessionId`. The response combines user and session information. The login, logout, and currentuser APIs are as follows. They are system routes and are not versioned. ### `POST /login` — User Login **Purpose:** Verifies user credentials and creates an authenticated session with a JWT access token. **Access Routes:** #### Request Parameters | Parameter | Type | Required | Source | | ---------- | ------ | -------- | ----------------------- | | `username` | String | Yes | `request.body.username` | | `password` | String | Yes | `request.body.password` | #### Behavior * Authenticates credentials and returns a session object. * Sets cookie: `projectname-access-token[-tenantCodename]` * Adds the same token in response headers. * Accepts either `username` or `email` fields (if both exist, `username` is prioritized). #### Example ```js axios.post("/login", { username: "user@example.com", password: "securePassword" }); ``` #### Success Response ```json { "sessionId": "e81c7d2b-4e95-9b1e-842e-3fb9c8c1df38", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", //... "accessToken": "ey7....", "userBucketToken": "e56d...." } ``` ### Error Responses * `401 Unauthorized`: Invalid credentials * `403 Forbidden`: Email/mobile verification or 2FA pending * `400 Bad Request`: Missing parameters --- ### `POST /logout` — User Logout **Purpose:** Terminates the current session and clears associated authentication tokens. #### Behavior * Invalidates the session (if it exists). * Clears cookie `projectname-access-token[-tenantCodename]`. * Returns a confirmation response (always `200 OK`). #### Example ```js axios.post("/logout", {}, { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` #### Notes * Can be called without a session (idempotent behavior). * Works for both cookie-based and token-based sessions. #### Success Response ```json { "status": "OK", "message": "User logged out successfully" } ``` ### `GET /currentuser` — Current Session **Purpose** Returns the currently authenticated user’s session. **Route Type** `sessionInfo` **Authentication** Requires a valid access token (header or cookie). #### Request *No parameters.* #### Example ```js axios.get("/currentuser", { headers: { Authorization: "Bearer " } }); ``` #### Success (200) Returns the session object (identity, tenancy, token metadata): ```json { "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", "roleId": "user", "tenantId": "abc123", "accessToken": "jwt-token-string", "...": "..." } ``` Note that the `currentuser` API returns a session object, so there is no `id` property, instead, the values for the user and session are exposed as `userId` and `sessionId`. The response is a mix of user and session information. #### Errors * **401 Unauthorized** — No active session/token ```json { "status": "ERR", "message": "No login found" } ``` **Notes** * Commonly called by web/mobile clients after login to hydrate session state. * Includes key identity/tenant fields and a token reference (if applicable). * Ensure a valid token is supplied to receive a 200 response. After you complete this first step, please ensure you have not made the following common mistakes: 1. When the application starts, please ensure that the `baseUrl` is set to the production server URL, and that the environment selector dropdown has the **Production** option selected by default. 2. Note that any api call to the application backend is based on a service base url, in this propmpt all auth apis should be called by `/auth-api` prefix after application's base url. 3. The `/currentuser` API returns a mix of session and user data. There is no `id` property —use `userId` and `sessionId`. 4. Please note that, the deployemnt environment selector will only be used in the home page. If any page is called directly bypassign home page, the page will use the stored or default environment. **After this prompt, the user may give you new instructions to update your first output or provide subsequent prompts about the project.** # **EBAYCCLONE** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 10 - AdminModeration Service** This document is a part of a REST API guide for the ebaycclone project. It is designed for AI agents that will generate frontend code to consume the project’s backend. This document provides extensive instruction for the usage of adminModeration ## Service Access AdminModeration service management is handled through service specific base urls. AdminModeration service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.). For the adminModeration service, the base URLs are: * **Preview:** `https://ebaycclone.prw.mindbricks.com/adminmoderation-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/adminmoderation-api` * **Production:** `https://ebaycclone.mindbricks.co/adminmoderation-api` ## Scope **AdminModeration Service Description** Administrative backend service for moderation and manual override actions. Responsible for logging all admin interventions (user/product/feedback/media/category/order/notification/searchindex moderation), triggering corrections via interservice calls, and providing comprehensive audit trails for compliance. AdminModeration service provides apis and business logic for following data objects in ebaycclone application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows. **`moderationAction` Data Object**: Audit record for all admin moderation/override actions affecting core business entities. Links to admin, timestamp, entity type/ID, action performed, and reason. ## AdminModeration Service Frontend Description By The Backend Architect Service is admin-only and never presented to buyers/sellers. All moderation actions (soft-delete, restore, update/correct) display audit information and confirmation dialogs. Admin views include filtering/search of moderation actions by entity type, date, and admin user. Admin-initiated corrections (like payment, feedback, or index fixes) always appear as explicit history entries. All endpoints require admin login; UI presents moderation action logs for compliance review, manual rollbacks, and traceability. ## API Structure ### Object Structure of a Successful Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client. **HTTP Status Codes:** * **200 OK**: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully. * **201 Created**: Returned for CREATE operations, indicating that the resource was created successfully. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling that the request executed successfully. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` * **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation. ### Additional Data Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature. ### Error Response If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity: * **400 Bad Request**: The request was improperly formatted or contained invalid parameters. * **401 Unauthorized**: The request lacked a valid authentication token; login is required. * **403 Forbidden**: The current token does not grant access to the requested resource. * **404 Not Found**: The requested resource was not found on the server. * **500 Internal Server Error**: The server encountered an unexpected condition. Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Bucket Management (This information is also given in PART 1 prompt.) This application has a bucket service used to store user files and other object-related files. The bucket service is login-agnostic, so for write operations or private reads, include a bucket token (provided by services) in the request’s Authorization header as a Bearer token. Please note that all other business services require the access token in the Bearer header, while the bucket service expects a bucket token because it is login-agnostic. Ensure you manage the required token injection properly; any auth interceptor should not replace the bucket token with the access token. **User Bucket** This bucket stores public user files for each user. When a user logs in—or in the `/currentuser` response—there is a `userBucketToken` to use when sending user-related public files to the bucket service. ```json { //... "userBucketToken": "e56d...." } ``` To upload a file `POST {baseUrl}/bucket/upload` The request body is form-data which includes the `bucketId` and the file binary in the `files` field. ```js { bucketId: "{userId}-public-user-bucket", files: {binary} } ``` Response status is 200 on success, e.g., body: ```json { "success": true, "data": [ { "fileId": "9da03f6d-0409-41ad-bb06-225a244ae408", "originalName": "test (10).png", "mimeType": "image/png", "size": 604063, "status": "uploaded", "bucketName": "f7103b85-fcda-4dec-92c6-c336f71fd3a2-public-user-bucket", "isPublic": true, "downloadUrl": "https://babilcom.mindbricks.co/bucket/download/9da03f6d-0409-41ad-bb06-225a244ae408" } ] } ``` To download a file from the bucket, you need its `fileId`. If you upload an avatar or other asset, ensure the download URL or the `fileId` is stored in the backend. Buckets are mostly used in object creations that require an additional file, such as a product image or user avatar. After uploading your image to the bucket, insert the returned download URL into the related property of the target object record. **Application Bucket** This Ebaycclone application also includes a common public bucket that anyone can read, but only users with the `superAdmin`, `admin`, or `saasAdmin` roles can write (upload) to it. When a user with one of these admin roles is logged in, the `/login` response or the `/currentuser` response also returns an `applicationBucketToken` field, which is used when uploading any file to the application bucket. ```json { //... "applicationBucketToken": "e23fd...." } ``` The common public application bucket ID is `"ebaycclone-public-common-bucket"` In certain admin areas—such as product management pages—since the user already has the application bucket token, they will be able to upload related object images. Please configure your UI to upload files to the application bucket using this bucket token whenever needed. **Object Buckets** Some objects may also return a bucket token for uploading or accessing files related to that object. For example, in a project management application, when you fetch a project’s data, a public or private bucket token may be provided to upload or download project-related files. These buckets will be used as described in the relevant object definitions. ## ModerationAction Data Object Audit record for all admin moderation/override actions affecting core business entities. Links to admin, timestamp, entity type/ID, action performed, and reason. ### ModerationAction Data Object Frontend Description By The Backend Architect Each moderationAction creates a visible traceable log for compliance. Moderation details (admin, target type/id, reason, timestamp) are rendered in the admin dashboard/AuditLog view. Editing/deleting moderation actions is restricted to superadmins or internal use for corrections. Actions are linked to actual domain changes for reference. ### ModerationAction Data Object Properties ModerationAction data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Description | |----------|------|---------|----------|-------------| | `adminId` | ID | false | Yes | ID of admin performing moderation action. | | `entityId` | ID | false | Yes | ID of target entity affected by moderation (user/product/etc). | | `actionTimestamp` | Date | false | Yes | Timestamp moderation action was performed/logged. | | `entityType` | Enum | false | Yes | Type of entity affected (USER, PRODUCT, FEEDBACK, MEDIA, CATEGORY, NOTIFICATION, ORDER, SEARCHINDEX). | | `reason` | String | false | Yes | Explanation or justification for the moderation action performed. | | `actionType` | Enum | false | Yes | Type of moderation action (e.g., SOFT_DELETE, RESTORE, UPDATE_ROLE, MANUAL_CORRECTION, MEDIA_FLAG, INDEX_REBUILD, PAYMENT_FIX, FEEDBACK_OVERRIDE, ADMIN_NOTE). | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options. - **entityType**: [USER, PRODUCT, FEEDBACK, MEDIA, CATEGORY, NOTIFICATION, ORDER, SEARCHINDEX] - **actionType**: [SOFT_DELETE, RESTORE, UPDATE_ROLE, MANUAL_CORRECTION, MEDIA_FLAG, INDEX_REBUILD, PAYMENT_FIX, FEEDBACK_OVERRIDE, ADMIN_NOTE] ### Relation Properties `adminId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **adminId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes ## API Reference ### `Get Moderationaction` API Get a single moderation action log by ID. Used to review admin audit trails; accessible only to platform admins. **Rest Route** The `getModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `getModerationAction` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | **moderationActionId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/moderationactions/:moderationActionId** ```js axios({ method: 'GET', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Moderationaction` API Soft-deletes a moderation action log record (dangerous; allowed only to superadmins or strict manual correction), primarily for audit correction or internal error cleanup. Usually, moderation logs are immutable. **Rest Route** The `deleteModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `deleteModerationAction` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | **moderationActionId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/moderationactions/:moderationActionId** ```js axios({ method: 'DELETE', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Moderationaction` API Logs an admin moderation or override action in the system for audit and traceability. Requires admin login, takes context from session, and creates an audit entry for any admin operation over any entity type. **Rest Route** The `createModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions` **Rest Request Parameters** The `createModerationAction` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | entityId | ID | true | request.body?.entityId | | entityType | Enum | true | request.body?.entityType | | reason | String | true | request.body?.reason | | actionType | Enum | true | request.body?.actionType | **entityId** : ID of target entity affected by moderation (user/product/etc). **entityType** : Type of entity affected (USER, PRODUCT, FEEDBACK, MEDIA, CATEGORY, NOTIFICATION, ORDER, SEARCHINDEX). **reason** : Explanation or justification for the moderation action performed. **actionType** : Type of moderation action (e.g., SOFT_DELETE, RESTORE, UPDATE_ROLE, MANUAL_CORRECTION, MEDIA_FLAG, INDEX_REBUILD, PAYMENT_FIX, FEEDBACK_OVERRIDE, ADMIN_NOTE). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/moderationactions** ```js axios({ method: 'POST', url: '/v1/moderationactions', data: { entityId:"ID", entityType:"Enum", reason:"String", actionType:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Moderationactions` API List moderation actions for admin dashboard/audit search. Supports filtering by admin, entityType, entityId, actionType, and date. Always sorted by most recent action. **Rest Route** The `listModerationActions` API REST controller can be triggered via the following route: `/v1/moderationactions` **Rest Request Parameters** The `listModerationActions` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/moderationactions** ```js axios({ method: 'GET', url: '/v1/moderationactions', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationActions", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "moderationActions": [ { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Moderationaction` API Allows update of explanation/note on a moderation action for correction (typically by admin or superadmin only). No entity/type/admin may be changed after creation; only 'reason' is editable for audit consistency. **Rest Route** The `updateModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `updateModerationAction` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | | reason | String | false | request.body?.reason | **moderationActionId** : This id paremeter is used to select the required data object that will be updated **reason** : Explanation or justification for the moderation action performed. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/moderationactions/:moderationActionId** ```js axios({ method: 'PATCH', url: `/v1/moderationactions/${moderationActionId}`, data: { reason:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` **After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.** # **EBAYCCLONE** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 11 - WatchlistCart Service** This document is a part of a REST API guide for the ebaycclone project. It is designed for AI agents that will generate frontend code to consume the project’s backend. This document provides extensive instruction for the usage of watchlistCart ## Service Access WatchlistCart service management is handled through service specific base urls. WatchlistCart service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.). For the watchlistCart service, the base URLs are: * **Preview:** `https://ebaycclone.prw.mindbricks.com/watchlistcart-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/watchlistcart-api` * **Production:** `https://ebaycclone.mindbricks.co/watchlistcart-api` ## Scope **WatchlistCart Service Description** Handles user watchlists (with custom folders) and shopping cart preparation for checkout, strictly enforcing only fixed-price products in carts, supporting item moves/bulk operations, and robust default/folder logic.. WatchlistCart service provides apis and business logic for following data objects in ebaycclone application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows. **`watchlistItem` Data Object**: Item in a user’s watchlist, optionally in a named folder; references product and user. **`cartItem` Data Object**: Single product pending checkout in a user’s cart. Only fixed-price products permitted; quantity supported for multi-unit purchases (if allowed). **`watchlistList` Data Object**: A named folder/list in a user’s watchlist. Default list exists for all users. Custom lists may be created and deleted. ## WatchlistCart Service Frontend Description By The Backend Architect - Users can create custom watchlist folders to organize products. There is always a default list/folder, which cannot be deleted. When a folder is deleted, items within it are moved to the default list, not removed. - Adding to cart is only allowed for products listed as FIXED-price type; AUCTION products cannot be added to cart and will show a user-facing error. - Duplicate products in watchlist/cart are not allowed; attempts to add will be blocked with a clear error message. - Cart UI must refresh count/quantities on changes and clear after successful checkout. - Bulk move/remove is supported on watchlist items, as is moving items between cart and watchlists via explicit controls. - If the referenced product is deleted/inactive, it should visibly indicate as unavailable in the list/cart; actions on such items should fail with an appropriate message. - itemCount shown in watchlist folders should always reflect the number of associated (not soft-deleted) items. ## API Structure ### Object Structure of a Successful Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client. **HTTP Status Codes:** * **200 OK**: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully. * **201 Created**: Returned for CREATE operations, indicating that the resource was created successfully. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling that the request executed successfully. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` * **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation. ### Additional Data Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature. ### Error Response If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity: * **400 Bad Request**: The request was improperly formatted or contained invalid parameters. * **401 Unauthorized**: The request lacked a valid authentication token; login is required. * **403 Forbidden**: The current token does not grant access to the requested resource. * **404 Not Found**: The requested resource was not found on the server. * **500 Internal Server Error**: The server encountered an unexpected condition. Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Bucket Management (This information is also given in PART 1 prompt.) This application has a bucket service used to store user files and other object-related files. The bucket service is login-agnostic, so for write operations or private reads, include a bucket token (provided by services) in the request’s Authorization header as a Bearer token. Please note that all other business services require the access token in the Bearer header, while the bucket service expects a bucket token because it is login-agnostic. Ensure you manage the required token injection properly; any auth interceptor should not replace the bucket token with the access token. **User Bucket** This bucket stores public user files for each user. When a user logs in—or in the `/currentuser` response—there is a `userBucketToken` to use when sending user-related public files to the bucket service. ```json { //... "userBucketToken": "e56d...." } ``` To upload a file `POST {baseUrl}/bucket/upload` The request body is form-data which includes the `bucketId` and the file binary in the `files` field. ```js { bucketId: "{userId}-public-user-bucket", files: {binary} } ``` Response status is 200 on success, e.g., body: ```json { "success": true, "data": [ { "fileId": "9da03f6d-0409-41ad-bb06-225a244ae408", "originalName": "test (10).png", "mimeType": "image/png", "size": 604063, "status": "uploaded", "bucketName": "f7103b85-fcda-4dec-92c6-c336f71fd3a2-public-user-bucket", "isPublic": true, "downloadUrl": "https://babilcom.mindbricks.co/bucket/download/9da03f6d-0409-41ad-bb06-225a244ae408" } ] } ``` To download a file from the bucket, you need its `fileId`. If you upload an avatar or other asset, ensure the download URL or the `fileId` is stored in the backend. Buckets are mostly used in object creations that require an additional file, such as a product image or user avatar. After uploading your image to the bucket, insert the returned download URL into the related property of the target object record. **Application Bucket** This Ebaycclone application also includes a common public bucket that anyone can read, but only users with the `superAdmin`, `admin`, or `saasAdmin` roles can write (upload) to it. When a user with one of these admin roles is logged in, the `/login` response or the `/currentuser` response also returns an `applicationBucketToken` field, which is used when uploading any file to the application bucket. ```json { //... "applicationBucketToken": "e23fd...." } ``` The common public application bucket ID is `"ebaycclone-public-common-bucket"` In certain admin areas—such as product management pages—since the user already has the application bucket token, they will be able to upload related object images. Please configure your UI to upload files to the application bucket using this bucket token whenever needed. **Object Buckets** Some objects may also return a bucket token for uploading or accessing files related to that object. For example, in a project management application, when you fetch a project’s data, a public or private bucket token may be provided to upload or download project-related files. These buckets will be used as described in the relevant object definitions. ## WatchlistItem Data Object Item in a user’s watchlist, optionally in a named folder; references product and user. ### WatchlistItem Data Object Frontend Description By The Backend Architect Displayed as a product tile in one of the user's folders or the default list. Cannot be duplicated for same product in the same folder/list. Moving items is a frequent action; deletion removes only from list, not the product. Inactive or unavailable products should be flagged visually; actions blocked. ### WatchlistItem Data Object Properties WatchlistItem data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Description | |----------|------|---------|----------|-------------| | `userId` | ID | false | Yes | Owner of the watchlist item. | | `addedAt` | Date | false | Yes | Timestamp watchlist item created. | | `productId` | ID | false | Yes | Referenced product in the watchlist. | | `listId` | ID | false | No | Owning watchlistList; null if in default watchlist. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Relation Properties `userId` `productId` `listId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **userId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **productId**: ID Relation to `productListingProduct`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **listId**: ID Relation to `watchlistList`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: No ## CartItem Data Object Single product pending checkout in a user’s cart. Only fixed-price products permitted; quantity supported for multi-unit purchases (if allowed). ### CartItem Data Object Frontend Description By The Backend Architect User’s cart is visible as a list of product tiles with quantity per item. Only one cartItem allowed per (user, product). Attempts to add an auction-type product will fail. Duplicates are rejected. Items may be transferred back to watchlist. ### CartItem Data Object Properties CartItem data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Description | |----------|------|---------|----------|-------------| | `addedAt` | Date | false | Yes | Timestamp added to cart. | | `userId` | ID | false | Yes | Cart owner. | | `quantity` | Integer | false | Yes | How many units (if product allows). | | `productId` | ID | false | Yes | Product being checked out. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Relation Properties `userId` `productId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **userId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **productId**: ID Relation to `productListingProduct`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes ## WatchlistList Data Object A named folder/list in a user’s watchlist. Default list exists for all users. Custom lists may be created and deleted. ### WatchlistList Data Object Frontend Description By The Backend Architect Default watchlist/folder is always present. When deleting a custom list, its items are moved to the default list; only empty lists can be deleted outright. itemCount shows count of non-deleted items. Folder organization is for user’s visual grouping only; does not affect cart or order flows. ### WatchlistList Data Object Properties WatchlistList data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Description | |----------|------|---------|----------|-------------| | `name` | String | false | Yes | Custom folder or list name. 'Default' is reserved (non-deletable for each user). | | `itemCount` | Integer | false | Yes | Number of (non-deleted) items in the list/folder. | | `userId` | ID | false | Yes | Owner of the watchlist list/folder. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Relation Properties `userId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **userId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes ### Filter Properties `name` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **name**: String has a filter named `name` ## API Reference ### `List Watchlistlist` API List all lists in user’s watchlists. Supports listing by listId for folders. **Rest Route** The `listWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists` **Rest Request Parameters** The `listWatchlistList` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/watchlistlists** ```js axios({ method: 'GET', url: '/v1/watchlistlists', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Cartitems` API List all cart items for a user (pending checkout). **Rest Route** The `listCartItems` API REST controller can be triggered via the following route: `/v1/cartitems` **Rest Request Parameters** The `listCartItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/cartitems** ```js axios({ method: 'GET', url: '/v1/cartitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "price": "Double", "title": "String", "type": "Enum", "type_idx": "Integer", "mediaAssetIds": "ID" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Cartitem` API Remove an item from the user’s cart. **Rest Route** The `deleteCartItem` API REST controller can be triggered via the following route: `/v1/cartitems/:cartItemId` **Rest Request Parameters** The `deleteCartItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | **cartItemId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/cartitems/:cartItemId** ```js axios({ method: 'DELETE', url: `/v1/cartitems/${cartItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Watchlistitem` API Add product to user’s watchlist (default or target list/folder). One (user, product, list) per item enforced. Block duplicates. **Rest Route** The `createWatchlistItem` API REST controller can be triggered via the following route: `/v1/watchlistitems` **Rest Request Parameters** The `createWatchlistItem` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | productId | ID | true | request.body?.productId | | listId | ID | false | request.body?.listId | **addedAt** : Timestamp watchlist item created. **productId** : Referenced product in the watchlist. **listId** : Owning watchlistList; null if in default watchlist. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/watchlistitems** ```js axios({ method: 'POST', url: '/v1/watchlistitems', data: { addedAt:"Date", productId:"ID", listId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Watchlistitems` API List all products in user’s watchlists. Supports listing by listId for folders. **Rest Route** The `listWatchlistItems` API REST controller can be triggered via the following route: `/v1/watchlistitems` **Rest Request Parameters** The `listWatchlistItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/watchlistitems** ```js axios({ method: 'GET', url: '/v1/watchlistitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Cartitemquantity` API Change the quantity for a cart item. User must own the item. **Rest Route** The `updateCartItemQuantity` API REST controller can be triggered via the following route: `/v1/cartitemquantity/:cartItemId` **Rest Request Parameters** The `updateCartItemQuantity` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | | quantity | Integer | false | request.body?.quantity | **cartItemId** : This id paremeter is used to select the required data object that will be updated **quantity** : How many units (if product allows). **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/cartitemquantity/:cartItemId** ```js axios({ method: 'PATCH', url: `/v1/cartitemquantity/${cartItemId}`, data: { quantity:"Integer", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Watchlistlist` API Create a new custom watchlist folder. Name must be unique per user; ‘Default’ is reserved for system. **Rest Route** The `createWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists` **Rest Request Parameters** The `createWatchlistList` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | name | String | true | request.body?.name | **name** : Custom folder or list name. 'Default' is reserved (non-deletable for each user). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/watchlistlists** ```js axios({ method: 'POST', url: '/v1/watchlistlists', data: { name:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Watchlistlist` API Delete a custom watchlist (folder). Items are reassigned to user’s default list. Cannot delete default list. **Rest Route** The `deleteWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists/:watchlistListId` **Rest Request Parameters** The `deleteWatchlistList` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistListId | ID | true | request.params?.watchlistListId | **watchlistListId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistlists/:watchlistListId** ```js axios({ method: 'DELETE', url: `/v1/watchlistlists/${watchlistListId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Watchlistitem` API Remove a product from a user’s watchlist. **Rest Route** The `deleteWatchlistItem` API REST controller can be triggered via the following route: `/v1/watchlistitems/:watchlistItemId` **Rest Request Parameters** The `deleteWatchlistItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistItemId | ID | true | request.params?.watchlistItemId | **watchlistItemId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistitems/:watchlistItemId** ```js axios({ method: 'DELETE', url: `/v1/watchlistitems/${watchlistItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Cartitem` API Add an item to the user’s cart. Only fixed-price products allowed. Duplicates not permitted. **Rest Route** The `createCartItem` API REST controller can be triggered via the following route: `/v1/cartitems` **Rest Request Parameters** The `createCartItem` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | **addedAt** : Timestamp added to cart. **quantity** : How many units (if product allows). **productId** : Product being checked out. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/cartitems** ```js axios({ method: 'POST', url: '/v1/cartitems', data: { addedAt:"Date", quantity:"Integer", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Do Userwatchlist` API userwatchlist **Rest Route** The `userwatchlist` API REST controller can be triggered via the following route: `/v1/userwatchlist` **Rest Request Parameters** The `userwatchlist` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userwatchlist** ```js axios({ method: 'GET', url: '/v1/userwatchlist', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Usercartitems` API list all cart items adde by user **Rest Route** The `listUserCartItems` API REST controller can be triggered via the following route: `/v1/usercartitems` **Rest Request Parameters** The `listUserCartItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/usercartitems** ```js axios({ method: 'GET', url: '/v1/usercartitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "shipping": "Double" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Do Userwatchlistlists` API list all watch lists created by user **Rest Route** The `userwatchlistlists` API REST controller can be triggered via the following route: `/v1/userwatchlistlists` **Rest Request Parameters** The `userwatchlistlists` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userwatchlistlists** ```js axios({ method: 'GET', url: '/v1/userwatchlistlists', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` **After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.** # **EBAYCCLONE** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 12 - ProductListing Service** This document is a part of a REST API guide for the ebaycclone project. It is designed for AI agents that will generate frontend code to consume the project’s backend. This document provides extensive instruction for the usage of productListing ## Service Access ProductListing service management is handled through service specific base urls. ProductListing service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.). For the productListing service, the base URLs are: * **Preview:** `https://ebaycclone.prw.mindbricks.com/productlisting-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/productlisting-api` * **Production:** `https://ebaycclone.mindbricks.co/productlisting-api` ## Scope **ProductListing Service Description** Handles product listings (both auction and fixed-price), image/media storage with validations, enforces immutable type, soft-delete, and public product discovery. ProductListing service provides apis and business logic for following data objects in ebaycclone application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows. **`productListingMedia` Data Object**: Stores and manages images/media associated with products, including secure URL, MIME type, and size validation. Each asset can be used by multiple products. **`productListingProduct` Data Object**: Represents a single product listing (fixed-price or auction) in the marketplace, with seller, category, type, price information, shipping details, media references, and dynamic auction fields. ## ProductListing Service Frontend Description By The Backend Architect # productListing Service UX Guidance - Product listings can be created/updated only by authenticated users, with fields conditional on type (fixed vs. auction). - Media upload endpoint returns array of validated mediaAssetIds for consumption in product creation or update forms. - In product details, always show category, subcategory, and seller info using available joins. - All public product queries must exclude inactive (soft-deleted) items. - Product type (auction/fixed) is displayed as immutable once created; UI to enforce as read-only for edits. - Media uploaded but not associated with a product may later be orphaned and subject to cleanup (handled by admin). ## API Structure ### Object Structure of a Successful Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client. **HTTP Status Codes:** * **200 OK**: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully. * **201 Created**: Returned for CREATE operations, indicating that the resource was created successfully. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling that the request executed successfully. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` * **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation. ### Additional Data Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature. ### Error Response If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity: * **400 Bad Request**: The request was improperly formatted or contained invalid parameters. * **401 Unauthorized**: The request lacked a valid authentication token; login is required. * **403 Forbidden**: The current token does not grant access to the requested resource. * **404 Not Found**: The requested resource was not found on the server. * **500 Internal Server Error**: The server encountered an unexpected condition. Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Bucket Management (This information is also given in PART 1 prompt.) This application has a bucket service used to store user files and other object-related files. The bucket service is login-agnostic, so for write operations or private reads, include a bucket token (provided by services) in the request’s Authorization header as a Bearer token. Please note that all other business services require the access token in the Bearer header, while the bucket service expects a bucket token because it is login-agnostic. Ensure you manage the required token injection properly; any auth interceptor should not replace the bucket token with the access token. **User Bucket** This bucket stores public user files for each user. When a user logs in—or in the `/currentuser` response—there is a `userBucketToken` to use when sending user-related public files to the bucket service. ```json { //... "userBucketToken": "e56d...." } ``` To upload a file `POST {baseUrl}/bucket/upload` The request body is form-data which includes the `bucketId` and the file binary in the `files` field. ```js { bucketId: "{userId}-public-user-bucket", files: {binary} } ``` Response status is 200 on success, e.g., body: ```json { "success": true, "data": [ { "fileId": "9da03f6d-0409-41ad-bb06-225a244ae408", "originalName": "test (10).png", "mimeType": "image/png", "size": 604063, "status": "uploaded", "bucketName": "f7103b85-fcda-4dec-92c6-c336f71fd3a2-public-user-bucket", "isPublic": true, "downloadUrl": "https://babilcom.mindbricks.co/bucket/download/9da03f6d-0409-41ad-bb06-225a244ae408" } ] } ``` To download a file from the bucket, you need its `fileId`. If you upload an avatar or other asset, ensure the download URL or the `fileId` is stored in the backend. Buckets are mostly used in object creations that require an additional file, such as a product image or user avatar. After uploading your image to the bucket, insert the returned download URL into the related property of the target object record. **Application Bucket** This Ebaycclone application also includes a common public bucket that anyone can read, but only users with the `superAdmin`, `admin`, or `saasAdmin` roles can write (upload) to it. When a user with one of these admin roles is logged in, the `/login` response or the `/currentuser` response also returns an `applicationBucketToken` field, which is used when uploading any file to the application bucket. ```json { //... "applicationBucketToken": "e23fd...." } ``` The common public application bucket ID is `"ebaycclone-public-common-bucket"` In certain admin areas—such as product management pages—since the user already has the application bucket token, they will be able to upload related object images. Please configure your UI to upload files to the application bucket using this bucket token whenever needed. **Object Buckets** Some objects may also return a bucket token for uploading or accessing files related to that object. For example, in a project management application, when you fetch a project’s data, a public or private bucket token may be provided to upload or download project-related files. These buckets will be used as described in the relevant object definitions. ## ProductListingMedia Data Object Stores and manages images/media associated with products, including secure URL, MIME type, and size validation. Each asset can be used by multiple products. ### ProductListingMedia Data Object Frontend Description By The Backend Architect - Images must be validated (size, MIME type) during upload. - Media assets are referenced from product listings (mediaAssetIds). - Preview of uploaded media is available immediately after upload using returned mediaAssetIds and URLs. - Orphan/unreferenced media assets may be flagged by admin for cleanup. ### ProductListingMedia Data Object Properties ProductListingMedia data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Description | |----------|------|---------|----------|-------------| | `mimeType` | String | false | Yes | MIME type of the uploaded media (e.g., image/jpeg) | | `productId` | ID | false | No | ID of product associated with this media asset | | `url` | String | false | Yes | Secure, validated URL for the media asset (S3 or equivalent) | | `size` | Integer | false | Yes | Media size in bytes (for validation and quota) | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Relation Properties `productId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **productId**: ID Relation to `productListingProduct`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: No ## ProductListingProduct Data Object Represents a single product listing (fixed-price or auction) in the marketplace, with seller, category, type, price information, shipping details, media references, and dynamic auction fields. ### ProductListingProduct Data Object Frontend Description By The Backend Architect - Title, description, and price/auction fields are required per listing type. - Once created, listing type (fixed vs auction) cannot be changed via update UI.
- Product media assets listed as thumbnails/lightbox from mediaAssetIds reference.
- Show seller and category info via joins. - For auctions, display real-time currentBid & highestBidder; for fixed, show price.
- Editing disabled for products currently engaged in transactions or bids (to be enforced at workflow level). ### ProductListingProduct Data Object Properties ProductListingProduct data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Description | |----------|------|---------|----------|-------------| | `currency` | String | false | Yes | ISO currency code (e.g. USD, EUR) | | `description` | Text | false | Yes | Product detailed description | | `condition` | Enum | false | Yes | Condition of product: BRAND_NEW, NEW, or USED | | `startBid` | Double | false | No | The opening bid value (for auction type products) | | `endPrice` | Double | false | No | Optional immediate sale/upper end price for auction (if AUCTION type) | | `price` | Double | false | No | Product price (required if fixed price type) | | `title` | String | false | Yes | Product title | | `startPrice` | Double | false | No | Minimum starting price for auction (required if AUCTION type) | | `type` | Enum | false | Yes | Product listing type, either FIXED or AUCTION (immutable after creation) | | `endBid` | Double | false | No | The upper (max) bid value for auction products (if any) | | `estimatedDelivery` | Date | false | No | Estimated delivery date for this product | | `shippingCurrency` | String | false | Yes | Currency code for shipping cost | | `sellerId` | ID | false | Yes | Reference to user who listed the product | | `mediaAssetIds` | ID | true | No | References to associated product/media assets | | `shippingMethod` | Enum | false | Yes | Shipping option for product: STANDARD, EXPRESS, or FREE | | `shipping` | Double | false | Yes | Shipping cost for this product | | `startBidDate` | Date | false | No | Date/time when auction bidding begins | | `subcategoryId` | ID | false | Yes | Reference to subcategory | | `categoryId` | ID | false | Yes | Reference to parent category | | `endBidDate` | Date | false | No | Date/time when auction bidding ends | | `currentBid` | Double | false | No | Current highest bid for auction-type product (updated atomically on bid placement) | | `highestBidderId` | ID | false | No | User ID of current highest bidder (auction-only, updated by auction microservice) | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Array Properties `mediaAssetIds` Array properties can hold multiple values. Array properties should be respected according to their multiple structure in the frontend in any user input for them. Please use multiple input components for the array proeprties when needed. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options. - **condition**: [BRAND_NEW, NEW, USED] - **type**: [FIXED, AUCTION] - **shippingMethod**: [STANDARD, EXPRESS, FREE] ### Relation Properties `sellerId` `mediaAssetIds` `subcategoryId` `categoryId` `highestBidderId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **sellerId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **mediaAssetIds**: ID Relation to `productListingMedia`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: No - **subcategoryId**: ID Relation to `subcategory`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **categoryId**: ID Relation to `category`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **highestBidderId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: No ### Filter Properties `currency` `condition` `price` `title` `type` `sellerId` `subcategoryId` `categoryId` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **currency**: String has a filter named `currency` - **condition**: Enum has a filter named `condition` - **price**: Double has a filter named `price` - **title**: String has a filter named `title` - **type**: Enum has a filter named `type` - **sellerId**: ID has a filter named `sellerId` - **subcategoryId**: ID has a filter named `subcategoryId` - **categoryId**: ID has a filter named `categoryId` ## API Reference ### `List Productlistingmedia` API List all media assets (admin or for media management/bulk preview). **Rest Route** The `listProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias` **Rest Request Parameters** The `listProductListingMedia` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias** ```js axios({ method: 'GET', url: '/v1/productlistingmedias', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedias", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingMedias": [ { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Productlistingproduct` API Get a single product listing. Checks isActive and public status. Includes media, category, subcategory, and seller info via joins. **Rest Route** The `getProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `getProductListingProduct` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | **productListingProductId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'GET', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Productlistingownproducts` API listing the loggedin user's products **Rest Route** The `listProductListingOwnProducts` API REST controller can be triggered via the following route: `/v1/productlistingownproducts` **Rest Request Parameters** The `listProductListingOwnProducts` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingownproducts** ```js axios({ method: 'GET', url: '/v1/productlistingownproducts', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Productlistingmedia` API Get a single media asset by ID (for admin or to display in product UI). **Rest Route** The `getProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` **Rest Request Parameters** The `getProductListingMedia` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | **productListingMediaId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'GET', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Productlistingproducts` API List public product listings. Only isActive=true records are returned. Includes category, subcategory, seller, media joins. Supports filtering. **Rest Route** The `listProductListingProducts` API REST controller can be triggered via the following route: `/v1/productlistingproducts` **Rest Request Parameters** The `listProductListingProducts` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts** ```js axios({ method: 'GET', url: '/v1/productlistingproducts', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Productlistingproduct` API Soft-delete a product listing. Only owner or admin can delete. **Rest Route** The `deleteProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `deleteProductListingProduct` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | **productListingProductId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'DELETE', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Productlistingproduct` API Update a product listing. Product type cannot be changed (immutable). **Rest Route** The `updateProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `updateProductListingProduct` api has got 21 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | | currency | String | false | request.body?.currency | | description | Text | false | request.body?.description | | condition | Enum | false | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | false | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | false | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | false | request.body?.shippingMethod | | shipping | Double | false | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | false | request.body?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | **productListingProductId** : This id paremeter is used to select the required data object that will be updated **currency** : ISO currency code (e.g. USD, EUR) **description** : Product detailed description **condition** : Condition of product: BRAND_NEW, NEW, or USED **startBid** : The opening bid value (for auction type products) **endPrice** : Optional immediate sale/upper end price for auction (if AUCTION type) **price** : Product price (required if fixed price type) **title** : Product title **startPrice** : Minimum starting price for auction (required if AUCTION type) **endBid** : The upper (max) bid value for auction products (if any) **estimatedDelivery** : Estimated delivery date for this product **shippingCurrency** : Currency code for shipping cost **mediaAssetIds** : References to associated product/media assets **shippingMethod** : Shipping option for product: STANDARD, EXPRESS, or FREE **shipping** : Shipping cost for this product **startBidDate** : Date/time when auction bidding begins **subcategoryId** : Reference to subcategory **categoryId** : Reference to parent category **endBidDate** : Date/time when auction bidding ends **currentBid** : Current highest bid for auction-type product (updated atomically on bid placement) **highestBidderId** : User ID of current highest bidder (auction-only, updated by auction microservice) **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'PATCH', url: `/v1/productlistingproducts/${productListingProductId}`, data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Productlistingproduct` API Create a new product listing (fixed or auction), conditioned on product type. Type is immutable after creation. **Rest Route** The `createProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts` **Rest Request Parameters** The `createProductListingProduct` api has got 21 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | description | Text | true | request.body?.description | | condition | Enum | true | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | true | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | type | Enum | true | request.body?.type | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | true | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | true | request.body?.shippingMethod | | shipping | Double | true | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | true | request.body?.subcategoryId | | categoryId | ID | true | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | **currency** : ISO currency code (e.g. USD, EUR) **description** : Product detailed description **condition** : Condition of product: BRAND_NEW, NEW, or USED **startBid** : The opening bid value (for auction type products) **endPrice** : Optional immediate sale/upper end price for auction (if AUCTION type) **price** : Product price (required if fixed price type) **title** : Product title **startPrice** : Minimum starting price for auction (required if AUCTION type) **type** : Product listing type, either FIXED or AUCTION (immutable after creation) **endBid** : The upper (max) bid value for auction products (if any) **estimatedDelivery** : Estimated delivery date for this product **shippingCurrency** : Currency code for shipping cost **mediaAssetIds** : References to associated product/media assets **shippingMethod** : Shipping option for product: STANDARD, EXPRESS, or FREE **shipping** : Shipping cost for this product **startBidDate** : Date/time when auction bidding begins **subcategoryId** : Reference to subcategory **categoryId** : Reference to parent category **endBidDate** : Date/time when auction bidding ends **currentBid** : Current highest bid for auction-type product (updated atomically on bid placement) **highestBidderId** : User ID of current highest bidder (auction-only, updated by auction microservice) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/productlistingproducts** ```js axios({ method: 'POST', url: '/v1/productlistingproducts', data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", type:"Enum", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Productlistingmedia` API Soft-delete a media asset (typically by admin or media owner for flagged/invalid content). **Rest Route** The `deleteProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` **Rest Request Parameters** The `deleteProductListingMedia` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | **productListingMediaId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'DELETE', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Productlistingmedia` API Create a new media asset record after validation. Used mainly by edge controller after upload. **Rest Route** The `createProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias` **Rest Request Parameters** The `createProductListingMedia` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | mimeType | String | true | request.body?.mimeType | | productId | ID | false | request.body?.productId | | url | String | true | request.body?.url | | size | Integer | true | request.body?.size | **mimeType** : MIME type of the uploaded media (e.g., image/jpeg) **productId** : ID of product associated with this media asset **url** : Secure, validated URL for the media asset (S3 or equivalent) **size** : Media size in bytes (for validation and quota) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/productlistingmedias** ```js axios({ method: 'POST', url: '/v1/productlistingmedias', data: { mimeType:"String", productId:"ID", url:"String", size:"Integer", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` **After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.** # **EBAYCCLONE** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 13 - OrderManagement Service** This document is a part of a REST API guide for the ebaycclone project. It is designed for AI agents that will generate frontend code to consume the project’s backend. This document provides extensive instruction for the usage of orderManagement ## Service Access OrderManagement service management is handled through service specific base urls. OrderManagement service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.). For the orderManagement service, the base URLs are: * **Preview:** `https://ebaycclone.prw.mindbricks.com/ordermanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/ordermanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/ordermanagement-api` ## Scope **OrderManagement Service Description** Handles all marketplace orders, manual checkout flows for fixed-price/offer/auction settlements, Stripe payment processing and webhook reconciliation, explicit status updates (shipping, delivery, cancellation), and feedback eligibility via orderItems. OrderManagement service provides apis and business logic for following data objects in ebaycclone application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows. **`orderManagementOrder` Data Object**: Marketplace order record. Stores buyer, shipping, status, items, Stripe payment data, and manual shipment/delivery events. Only accessible to admins or the buyer/seller of order items. **`orderManagementOrderItem` Data Object**: Order line item representing purchase of a single product from a specific seller as part of an order. Enables feedback, delivery, and per-seller analytics. Immutable after order creation. **`sys_orderManagementOrderPayment` Data Object**: A payment storage object to store the payment life cyle of orders based on orderManagementOrder object. It is autocreated based on the source object's checkout config **`sys_paymentCustomer` Data Object**: A payment storage object to store the customer values of the payment platform **`sys_paymentMethod` Data Object**: A payment storage object to store the payment methods of the platform customers ## OrderManagement Service Frontend Description By The Backend Architect # Order Management Service UX Guidance - Orders are created via fixed-price (cart, buy-now), accepted offer, or auction settlement; only fixed-price products eligible for cart checkout. - Every order contains a buyer, at least one orderItem, full shipping summary, Stripe payment references, and status. - Seller and buyer can see different order views (purchases vs sales). - Only seller can mark an order as shipped (manual input required). - Only buyer can confirm delivery/completion. - Feedback UI should only be surfaced for delivered orders, and only permit one feedback per orderItem per buyer. - Cancellation can only occur if the order is not shipped. - Refunds, when issued, are visible as a status; no automatic refunds. - All price, fee, shipping, and status changes are promptly reflected in the order status/history view. - Stripe paymentIntent update/callback events come via a single webhook endpoint. - Sensitive payment and card info is never shown to UI/backend outside of Stripe status and method reference. ## API Structure ### Object Structure of a Successful Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client. **HTTP Status Codes:** * **200 OK**: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully. * **201 Created**: Returned for CREATE operations, indicating that the resource was created successfully. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling that the request executed successfully. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` * **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation. ### Additional Data Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature. ### Error Response If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity: * **400 Bad Request**: The request was improperly formatted or contained invalid parameters. * **401 Unauthorized**: The request lacked a valid authentication token; login is required. * **403 Forbidden**: The current token does not grant access to the requested resource. * **404 Not Found**: The requested resource was not found on the server. * **500 Internal Server Error**: The server encountered an unexpected condition. Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Bucket Management (This information is also given in PART 1 prompt.) This application has a bucket service used to store user files and other object-related files. The bucket service is login-agnostic, so for write operations or private reads, include a bucket token (provided by services) in the request’s Authorization header as a Bearer token. Please note that all other business services require the access token in the Bearer header, while the bucket service expects a bucket token because it is login-agnostic. Ensure you manage the required token injection properly; any auth interceptor should not replace the bucket token with the access token. **User Bucket** This bucket stores public user files for each user. When a user logs in—or in the `/currentuser` response—there is a `userBucketToken` to use when sending user-related public files to the bucket service. ```json { //... "userBucketToken": "e56d...." } ``` To upload a file `POST {baseUrl}/bucket/upload` The request body is form-data which includes the `bucketId` and the file binary in the `files` field. ```js { bucketId: "{userId}-public-user-bucket", files: {binary} } ``` Response status is 200 on success, e.g., body: ```json { "success": true, "data": [ { "fileId": "9da03f6d-0409-41ad-bb06-225a244ae408", "originalName": "test (10).png", "mimeType": "image/png", "size": 604063, "status": "uploaded", "bucketName": "f7103b85-fcda-4dec-92c6-c336f71fd3a2-public-user-bucket", "isPublic": true, "downloadUrl": "https://babilcom.mindbricks.co/bucket/download/9da03f6d-0409-41ad-bb06-225a244ae408" } ] } ``` To download a file from the bucket, you need its `fileId`. If you upload an avatar or other asset, ensure the download URL or the `fileId` is stored in the backend. Buckets are mostly used in object creations that require an additional file, such as a product image or user avatar. After uploading your image to the bucket, insert the returned download URL into the related property of the target object record. **Application Bucket** This Ebaycclone application also includes a common public bucket that anyone can read, but only users with the `superAdmin`, `admin`, or `saasAdmin` roles can write (upload) to it. When a user with one of these admin roles is logged in, the `/login` response or the `/currentuser` response also returns an `applicationBucketToken` field, which is used when uploading any file to the application bucket. ```json { //... "applicationBucketToken": "e23fd...." } ``` The common public application bucket ID is `"ebaycclone-public-common-bucket"` In certain admin areas—such as product management pages—since the user already has the application bucket token, they will be able to upload related object images. Please configure your UI to upload files to the application bucket using this bucket token whenever needed. **Object Buckets** Some objects may also return a bucket token for uploading or accessing files related to that object. For example, in a project management application, when you fetch a project’s data, a public or private bucket token may be provided to upload or download project-related files. These buckets will be used as described in the relevant object definitions. ## OrderManagementOrder Data Object Marketplace order record. Stores buyer, shipping, status, items, Stripe payment data, and manual shipment/delivery events. Only accessible to admins or the buyer/seller of order items. ### OrderManagementOrder Data Object Frontend Description By The Backend Architect - Orders represent a single completed (or pending) marketplace transaction, either from buy-now, cart, offer, or auction. - Each order is associated with a unique orderNumber, buyer (userId), Stripe payment reference, shipping summary, and array of items (via orderItems). - Status workflow: PENDING_PAYMENT → PAID → (manual) PROCESSING/SHIPPED → DELIVERED or CANCELLED/REFUNDED. - Only the buyer and seller(s) of items contained can view details. - Seller(s) can mark as SHIPPED, entering tracking and carrier manually. - Only buyer can confirm delivery as DELIVERED. - Feedback opening is triggered on DELIVERED. ### OrderManagementOrder Data Object Properties OrderManagementOrder data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Description | |----------|------|---------|----------|-------------| | `orderNumber` | String | false | Yes | Unique, human-friendly order number (displayed to users); enforced unique. | | `items` | ID | true | No | Array of orderManagementOrderItem ids representing items in this order. | | `buyerId` | ID | false | Yes | User ID of the buyer placing the order. | | `status` | Enum | false | Yes | Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED | | `paymentMethodId` | String | false | Yes | Stripe paymentMethodId used for payment. Not stored if cash or other payment (future). | | `stripeCustomerId` | String | false | Yes | Stripe customerId of buyer; enables saved/paymentMethodId flows. | | `paymentIntentId` | String | false | No | Stripe paymentIntentId; enables webhook correlation and status sync. | | `shippingAddress` | Object | false | Yes | Shipping address for the order (copy of buyer address at purchase time). | | `summary` | Object | false | Yes | Object with total, subtotal, currency, shipping, discount breakdown as snapshot of order at time of purchase. | | `trackingNumber` | String | false | No | Optional tracking number entered by seller when marking as shipped. | | `estimatedDelivery` | Date | false | No | Estimated delivery date for order; copied from fastest estimated item or seller input. | | `cancelledAt` | Date | false | No | Timestamp when cancelled by buyer, seller, or admin before shipment. | | `paidAt` | Date | false | No | Timestamp when payment confirmed via Stripe or manual admin update. | | `deliveredAt` | Date | false | No | Timestamp when buyer confirms delivery. | | `shippedAt` | Date | false | No | Timestamp when seller marks as shipped. | | `carrier` | String | false | No | Optional carrier name entered by seller when marking as shipped. | | `_paymentConfirmation` | Enum | false | Yes | An automatic property that is used to check the confirmed status of the payment set by webhooks. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Array Properties `items` Array properties can hold multiple values. Array properties should be respected according to their multiple structure in the frontend in any user input for them. Please use multiple input components for the array proeprties when needed. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options. - **status**: [PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED] - **_paymentConfirmation**: [pending, processing, paid, canceled] ### Relation Properties `items` `buyerId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **items**: ID Relation to `orderManagementOrderItem`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: No - **buyerId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes ### Filter Properties `orderNumber` `status` `_paymentConfirmation` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **orderNumber**: String has a filter named `orderNumber` - **status**: Enum has a filter named `status` - **_paymentConfirmation**: Enum has a filter named `_paymentConfirmation` ## OrderManagementOrderItem Data Object Order line item representing purchase of a single product from a specific seller as part of an order. Enables feedback, delivery, and per-seller analytics. Immutable after order creation. ### OrderManagementOrderItem Data Object Frontend Description By The Backend Architect - Each orderManagementOrderItem represents a single product in an order, including productId, quantity, price, and its seller. - Feedback is referenced per (buyer, orderItemId), and status of delivery feedback is modeled via delivery date on parent order. - This object is never directly modifiable after creation, except for soft-deletion by admin or integrity actions. ### OrderManagementOrderItem Data Object Properties OrderManagementOrderItem data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Description | |----------|------|---------|----------|-------------| | `shipping` | Double | false | Yes | Shipping cost for this product (may be 0 for free shipping). | | `orderId` | ID | false | Yes | Parent order this item belongs to; enables join and lifecycle tracking. | | `quantity` | Integer | false | Yes | Number of units purchased for this product. | | `productId` | ID | false | Yes | ID of product purchased in this line item. | | `price` | Double | false | Yes | Unit price for this product at purchase time. | | `sellerId` | ID | false | Yes | UserId of seller (owner of product at purchase time). | | `title` | String | false | Yes | Product title at purchase time (copied for convenience/audit). | | `currency` | String | false | Yes | Currency code for price/shipping (ISO 4217). | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Relation Properties `orderId` `productId` `sellerId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **orderId**: ID Relation to `orderManagementOrder`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **productId**: ID Relation to `productListingProduct`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **sellerId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes ## Sys_orderManagementOrderPayment Data Object A payment storage object to store the payment life cyle of orders based on orderManagementOrder object. It is autocreated based on the source object's checkout config ### Sys_orderManagementOrderPayment Data Object Properties Sys_orderManagementOrderPayment data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Description | |----------|------|---------|----------|-------------| | `ownerId` | ID | false | No | An ID value to represent owner user who created the order | | `orderId` | ID | false | Yes | an ID value to represent the orderId which is the ID parameter of the source orderManagementOrder object | | `paymentId` | String | false | Yes | A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type | | `paymentStatus` | String | false | Yes | A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. | | `statusLiteral` | String | false | Yes | A string value to represent the logical payment status which belongs to the application lifecycle itself. | | `redirectUrl` | String | false | No | A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Filter Properties `ownerId` `orderId` `paymentId` `paymentStatus` `statusLiteral` `redirectUrl` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **ownerId**: ID has a filter named `ownerId` - **orderId**: ID has a filter named `orderId` - **paymentId**: String has a filter named `paymentId` - **paymentStatus**: String has a filter named `paymentStatus` - **statusLiteral**: String has a filter named `statusLiteral` - **redirectUrl**: String has a filter named `redirectUrl` ## Sys_paymentCustomer Data Object A payment storage object to store the customer values of the payment platform ### Sys_paymentCustomer Data Object Properties Sys_paymentCustomer data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Description | |----------|------|---------|----------|-------------| | `userId` | ID | false | No | An ID value to represent the user who is created as a stripe customer | | `customerId` | String | false | Yes | A string value to represent the customer id which is generated on the Stripe gateway. This id is used to represent the customer in the Stripe gateway | | `platform` | String | false | Yes | A String value to represent payment platform which is used to make the payment. It is stripe as default. It will be used to distinguesh the payment gateways in the future. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Filter Properties `userId` `customerId` `platform` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **userId**: ID has a filter named `userId` - **customerId**: String has a filter named `customerId` - **platform**: String has a filter named `platform` ## Sys_paymentMethod Data Object A payment storage object to store the payment methods of the platform customers ### Sys_paymentMethod Data Object Properties Sys_paymentMethod data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Description | |----------|------|---------|----------|-------------| | `paymentMethodId` | String | false | Yes | A string value to represent the id of the payment method on the payment platform. | | `userId` | ID | false | Yes | An ID value to represent the user who owns the payment method | | `customerId` | String | false | Yes | A string value to represent the customer id which is generated on the payment gateway. | | `cardHolderName` | String | false | No | A string value to represent the name of the card holder. It can be different than the registered customer. | | `cardHolderZip` | String | false | No | A string value to represent the zip code of the card holder. It is used for address verification in specific countries. | | `platform` | String | false | Yes | A String value to represent payment platform which teh paymentMethod belongs. It is stripe as default. It will be used to distinguesh the payment gateways in the future. | | `cardInfo` | Object | false | Yes | A Json value to store the card details of the payment method. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Filter Properties `paymentMethodId` `userId` `customerId` `cardHolderName` `cardHolderZip` `platform` `cardInfo` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **paymentMethodId**: String has a filter named `paymentMethodId` - **userId**: ID has a filter named `userId` - **customerId**: String has a filter named `customerId` - **cardHolderName**: String has a filter named `cardHolderName` - **cardHolderZip**: String has a filter named `cardHolderZip` - **platform**: String has a filter named `platform` - **cardInfo**: Object has a filter named `cardInfo` ## API Reference ### `List Ordermanagementorders` API List orders, filtered for buyer and/or seller, or by admin. Includes select orderItems. **Rest Route** The `listOrderManagementOrders` API REST controller can be triggered via the following route: `/v1/ordermanagementorders` **Rest Request Parameters** The `listOrderManagementOrders` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ordermanagementorders', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Ordermanagementorderitem` API Get a specific order item (for feedback/business logic). **Rest Route** The `getOrderManagementOrderItem` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems/:orderManagementOrderItemId` **Rest Request Parameters** The `getOrderManagementOrderItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderItemId | ID | true | request.params?.orderManagementOrderItemId | **orderManagementOrderItemId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems/:orderManagementOrderItemId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderitems/${orderManagementOrderItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Ordermanagementorder` API Soft-delete/cancel order by admin or eligible actor prior to shipment. Sets status to CANCELLED and cancels active payment intent if pending. Irreversible and blocks feedback. **Rest Route** The `deleteOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` **Rest Request Parameters** The `deleteOrderManagementOrder` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorder` API Get single order by ID. Only accessible to admin, buyer, or relevant sellers of items within this order. Includes all orderItems. **Rest Route** The `getOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` **Rest Request Parameters** The `getOrderManagementOrder` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | **orderManagementOrderId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Ordermanagementorderstatus` API Update order status (manual shipment, delivery, cancellation/refund). Restricted: only seller of all items can mark as shipped, only buyer can confirm delivery, only admin can set refund/cancelled. Timestamps updated as per business rule. **Rest Route** The `updateOrderManagementOrderStatus` API REST controller can be triggered via the following route: `/v1/ordermanagementorderstatus/:orderManagementOrderId` **Rest Request Parameters** The `updateOrderManagementOrderStatus` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **status** : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderstatus/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderstatus/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Complete Orderstripewebhook` API Webhook endpoint called by Stripe to reconcile payment state and update order status based on paymentIntentId and event data. No authentication required (Stripe IPs only). **Rest Route** The `completeOrderStripeWebhook` API REST controller can be triggered via the following route: `/v1/completeorderstripewebhook/:orderManagementOrderId` **Rest Request Parameters** The `completeOrderStripeWebhook` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **status** : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/completeorderstripewebhook/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/completeorderstripewebhook/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderbyproductid` API get orders by productId **Rest Route** The `getOrderManagementOrderByProductId` API REST controller can be triggered via the following route: `/v1/ordermanagementorderbyproductid/:items` **Rest Request Parameters** The `getOrderManagementOrderByProductId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | items | String | true | request.params?.items | **orderManagementOrderId** : This id paremeter is used to query the required data object. **items** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderbyproductid/:items** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderbyproductid/${items}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Ordermanagementorder` API Creates an order and initiates Stripe payment. Validates that all products in the order are fixed-price, populates orderItems, saves Stripe customer/paymentMethod/paymentIntentId for reconciliation. Only accessible to buyers for own checkouts and only allows fixed-price product checkout (no auction). **Rest Route** The `createOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders` **Rest Request Parameters** The `createOrderManagementOrder` api has got 14 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderNumber | String | true | request.body?.orderNumber | | items | ID | false | request.body?.items | | paymentMethodId | String | true | request.body?.paymentMethodId | | stripeCustomerId | String | true | request.body?.stripeCustomerId | | paymentIntentId | String | false | request.body?.paymentIntentId | | shippingAddress | Object | true | request.body?.shippingAddress | | summary | Object | true | request.body?.summary | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderNumber** : Unique, human-friendly order number (displayed to users); enforced unique. **items** : Array of orderManagementOrderItem ids representing items in this order. **paymentMethodId** : Stripe paymentMethodId used for payment. Not stored if cash or other payment (future). **stripeCustomerId** : Stripe customerId of buyer; enables saved/paymentMethodId flows. **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **shippingAddress** : Shipping address for the order (copy of buyer address at purchase time). **summary** : Object with total, subtotal, currency, shipping, discount breakdown as snapshot of order at time of purchase. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorders** ```js axios({ method: 'POST', url: '/v1/ordermanagementorders', data: { orderNumber:"String", items:"ID", paymentMethodId:"String", stripeCustomerId:"String", paymentIntentId:"String", shippingAddress:"Object", summary:"Object", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderitems` API List order items for a given order or for buyer/seller analytics. Used for feedback management. **Rest Route** The `listOrderManagementOrderItems` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems` **Rest Request Parameters** The `listOrderManagementOrderItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Ownordermanagementorders` API list the loggedin user orders **Rest Route** The `listOwnOrderManagementOrders` API REST controller can be triggered via the following route: `/v1/ownordermanagementorders` **Rest Request Parameters** The `listOwnOrderManagementOrders` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ownordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ownordermanagementorders', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Lis Ordermanagementownorderitem` API list the loggedin user's order items **Rest Route** The `lisOrderManagementOwnOrderItem` API REST controller can be triggered via the following route: `/v1/lisordermanagementownorderitem` **Rest Request Parameters** The `lisOrderManagementOwnOrderItem` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/lisordermanagementownorderitem** ```js axios({ method: 'GET', url: '/v1/lisordermanagementownorderitem', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Ordermanagementorderitem` API create order item **Rest Route** The `createOrderManagementOrderItem` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems` **Rest Request Parameters** The `createOrderManagementOrderItem` api has got 8 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | shipping | Double | true | request.body?.shipping | | orderId | ID | true | request.body?.orderId | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | | price | Double | true | request.body?.price | | sellerId | ID | true | request.body?.sellerId | | title | String | true | request.body?.title | | currency | String | true | request.body?.currency | **shipping** : Shipping cost for this product (may be 0 for free shipping). **orderId** : Parent order this item belongs to; enables join and lifecycle tracking. **quantity** : Number of units purchased for this product. **productId** : ID of product purchased in this line item. **price** : Unit price for this product at purchase time. **sellerId** : UserId of seller (owner of product at purchase time). **title** : Product title at purchase time (copied for convenience/audit). **currency** : Currency code for price/shipping (ISO 4217). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderitems** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderitems', data: { shipping:"Double", orderId:"ID", quantity:"Integer", productId:"ID", price:"Double", sellerId:"ID", title:"String", currency:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpayment2` API This route is used to get the payment information by ID. **Rest Route** The `getOrderManagementOrderPayment2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `getOrderManagementOrderPayment2` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderpayments2` API This route is used to list all payments. **Rest Route** The `listOrderManagementOrderPayments2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayments2` **Rest Request Parameters** The `listOrderManagementOrderPayments2` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Ordermanagementorderpayment` API This route is used to create a new payment. **Rest Route** The `createOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment` **Rest Request Parameters** The `createOrderManagementOrderPayment` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderId | ID | true | request.body?.orderId | | paymentId | String | true | request.body?.paymentId | | paymentStatus | String | true | request.body?.paymentStatus | | statusLiteral | String | true | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | **orderId** : an ID value to represent the orderId which is the ID parameter of the source orderManagementOrder object **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderpayment', data: { orderId:"ID", paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Ordermanagementorderpayment` API This route is used to update an existing payment. **Rest Route** The `updateOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `updateOrderManagementOrderPayment` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | false | request.body?.paymentId | | paymentStatus | String | false | request.body?.paymentStatus | | statusLiteral | String | false | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | **sys_orderManagementOrderPaymentId** : This id paremeter is used to select the required data object that will be updated **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Ordermanagementorderpayment` API This route is used to delete a payment. **Rest Route** The `deleteOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `deleteOrderManagementOrderPayment` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderpayments2` API This route is used to list all payments. **Rest Route** The `listOrderManagementOrderPayments2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayments2` **Rest Request Parameters** The `listOrderManagementOrderPayments2` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Ordermanagementorderpaymentbyorderid` API This route is used to get the payment information by order id. **Rest Route** The `getOrderManagementOrderPaymentByOrderId` API REST controller can be triggered via the following route: `/v1/orderManagementOrderpaymentbyorderid/:orderId` **Rest Request Parameters** The `getOrderManagementOrderPaymentByOrderId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | orderId | String | true | request.params?.orderId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **orderId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbyorderid/:orderId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbyorderid/${orderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpaymentbypaymentid` API This route is used to get the payment information by payment id. **Rest Route** The `getOrderManagementOrderPaymentByPaymentId` API REST controller can be triggered via the following route: `/v1/orderManagementOrderpaymentbypaymentid/:paymentId` **Rest Request Parameters** The `getOrderManagementOrderPaymentByPaymentId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | true | request.params?.paymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **paymentId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbypaymentid/:paymentId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbypaymentid/${paymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpayment2` API This route is used to get the payment information by ID. **Rest Route** The `getOrderManagementOrderPayment2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `getOrderManagementOrderPayment2` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Start Ordermanagementorderpayment` API Start payment for orderManagementOrder **Rest Route** The `startOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/startordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `startOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to start a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/startordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/startordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Refresh Ordermanagementorderpayment` API Refresh payment info for orderManagementOrder from Stripe **Rest Route** The `refreshOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/refreshordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `refreshOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to refresh a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/refreshordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/refreshordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Callback Ordermanagementorderpayment` API Refresh payment values by gateway webhook call for orderManagementOrder **Rest Route** The `callbackOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/callbackordermanagementorderpayment` **Rest Request Parameters** The `callbackOrderManagementOrderPayment` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.body?.orderManagementOrderId | **orderManagementOrderId** : The order id parameter that will be read from webhook callback params **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/callbackordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/callbackordermanagementorderpayment', data: { orderManagementOrderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Get Paymentcustomerbyuserid` API This route is used to get the payment customer information by user id. **Rest Route** The `getPaymentCustomerByUserId` API REST controller can be triggered via the following route: `/v1/paymentcustomers/:userId` **Rest Request Parameters** The `getPaymentCustomerByUserId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_paymentCustomerId | ID | true | request.params?.sys_paymentCustomerId | | userId | String | true | request.params?.userId | **sys_paymentCustomerId** : This id paremeter is used to query the required data object. **userId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomers/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_paymentCustomer": { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Paymentcustomers` API This route is used to list all payment customers. **Rest Route** The `listPaymentCustomers` API REST controller can be triggered via the following route: `/v1/paymentcustomers` **Rest Request Parameters** The `listPaymentCustomers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers** ```js axios({ method: 'GET', url: '/v1/paymentcustomers', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentCustomers": [ { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Paymentcustomermethods` API This route is used to list all payment customer methods. **Rest Route** The `listPaymentCustomerMethods` API REST controller can be triggered via the following route: `/v1/paymentcustomermethods/:userId` **Rest Request Parameters** The `listPaymentCustomerMethods` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | String | true | request.params?.userId | **userId** : This parameter will be used to select the data objects that want to be listed **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomermethods/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomermethods/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentMethods", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentMethods": [ { "id": "ID", "paymentMethodId": "String", "userId": "ID", "customerId": "String", "cardHolderName": "String", "cardHolderZip": "String", "platform": "String", "cardInfo": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` **After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.** # **EBAYCCLONE** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 14 - OrderManagement Service OrderManagementOrder Payment Flow** This document is a part of a REST API guide for the ebaycclone project. It is designed for AI agents that will generate frontend code to consume the project’s backend. ## Stripe Payment Flow For OrderManagementOrder `OrderManagementOrder` is a data object that stores order information used for Stripe payments. The payment flow can only start after an instance of this data object is created in the database. The ID of this data object—referenced as `orderManagementOrderId` in the general business logic—will be used as the `orderId` in the payment flow. ## Accessing the service API for the payment flow API The Ebaycclone application doesn’t have a separate payment service; the payment flow is handled within the same service that manages orders. To access the related APIs, use the base URL of the `orderManagement` service. Note that the application may be deployed to Preview, Staging, or Production. As with all API access, you should call the API using the base URL for the selected deployment. For the `orderManagement` service, the base URLs are: * **Preview:** `https://ebaycclone.prw.mindbricks.com/ordermanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/ordermanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/ordermanagement-api` ## Creating the OrderManagementOrder While creating the `orderManagementOrder` instance is part of the business logic and can be implemented according to your architecture, this instance acts as the central hub for the payment flow and its related data objects. The order object is typically created via its own API (see the Business API for the create route of `orderManagementOrder`). The payment flow begins **after** the object is created. Because of the data object’s **Stripe order settings**, the payment flow is aware of the following fields, references, and their purposes: - `id` (used as `orderId` or `${dataObject.objectName}Id`): The unique identifier of the data object instance at the center of the payment flow. - `orderId`: The order identifier is resolved from `this.orderManagementOrder.id`. - `amount`: The payment amount is resolved from `this.orderManagementOrder.summary.total`. - `currency`: The payment currency is resolved from `this.orderManagementOrder.summary.currency`. - `description`: The payment description is resolved from ``Order #${this.orderManagementOrder.orderNumber} for buyerId ${this.orderManagementOrder.buyerId}``. - `orderStatusProperty`: `status` is updated automatically by the payment flow using a mapped status value. - `orderStatusUpdateDateProperty`: `updatedAt` stores the timestamp of the latest payment status update. - `orderOwnerIdProperty`: `buyerId` is used by the payment flow to verify the order owner and match it with the current user’s ID. - `mapPaymentResultToOrderStatus`: The order status is written to the data object instance using the following mapping. **paymentResultStarted**: `"PENDING_PAYMENT"` **paymentResultCanceled**: `"CANCELLED"` **paymentResultFailed**: `"CANCELLED"` **paymentResultSuccess**: `"PAID"` ## Before Payment Flow Starts It is assumed that the frontend provides a **“Pay”** or **“Checkout”** button that initiates the payment flow. The following steps occur after the user clicks this button. Note that an `orderManagementOrder` instance must already exist to represent the order being paid, with its initial status set. A Stripe payment flow can be implemented in several ways, but the best practice is to use a **PaymentIntent** and manage it jointly from the backend and frontend. A *PaymentIntent* represents the intent to collect payment for a given order (or any payable entity). In the Ebaycclone application, the **PaymentIntent** is created in the backend, while the **PaymentMethod** (the user’s stored card information) is created in the frontend. Only the PaymentMethod ID and minimal metadata are stored in the backend for later reference. The frontend first requests the current user’s saved payment methods from the backend, displays them in a list, and provides UI options to **add or remove** payment methods. The user must select a Payment Method before starting the payment flow. ### Listing the Payment Methods for the User To list the payment methods of the currently logged-in user, call the following **system API** (unversioned): `GET /payment-methods/list` This endpoint requires no parameters and returns an array of payment methods belonging to the user — without any envelope. ```js const response = await fetch("$serviceUrl/payment-methods/list", { method: "GET", headers: { "Content-Type": "application/json" }, }); ```` Example response: ```json [ { "id": "19a5fbfd-3c25-405b-a7f7-06f023f2ca01", "paymentMethodId": "pm_1SQv9CP5uUv56Cse5BQ3nGW8", "userId": "f7103b85-fcda-4dec-92c6-c336f71fd3a2", "customerId": "cus_TNgWUw5QkmUPLa", "cardHolderName": "John Doe", "cardHolderZip": "34662", "platform": "stripe", "cardInfo": { "brand": "visa", "last4": "4242", "checks": { "cvc_check": "pass", "address_postal_code_check": "pass" }, "funding": "credit", "exp_month": 11, "exp_year": 2033 }, "isActive": true, "createdAt": "2025-11-07T19:16:38.469Z", "updatedAt": "2025-11-07T19:16:38.469Z", "_owner": "f7103b85-fcda-4dec-92c6-c336f71fd3a2" } ] ``` In each payment method object, the following fields are useful for displaying to the user: ```js for (const method of paymentMethods) { const brand = method.cardInfo.brand; // use brand for displaying VISA/MASTERCARD icons const paymentMethodId = method.paymentMethodId; // send this when initiating the payment flow const cardHolderName = method.cardHolderName; // show in list const number = `**** **** **** ${method.cardInfo.last4}`; // masked card number const expDate = `${method.cardInfo.exp_month}/${method.cardInfo.exp_year}`; // expiry date const id = method.id; // internal DB record ID, used for deletion const customerId = method.customerId; // Stripe customer reference } ``` If the list is empty, prompt the user to **add a new payment method**. ### Creating a Payment Method The payment page (or user profile page) should allow users to add a new payment method (credit card). Creating a Payment Method is a secure operation handled **entirely through Stripe.js** on the frontend — the backend never handles sensitive card data. After a card is successfully created, the backend only stores its reference (PaymentMethod ID) for reuse. Stripe provides multiple ways to collect card information, all through secure UI elements. Below is an example setup — refer to the latest Stripe documentation for alternative patterns. To initialize Stripe on the frontend, include your **public key**: ```html ``` ```js const stripe = Stripe("pk_test_51POkqt4.................."); const elements = stripe.elements(); const cardNumberElement = elements.create("cardNumber", { style: { base: { color: "#545454", fontSize: "16px" } }, }); cardNumberElement.mount("#card-number-element"); const cardExpiryElement = elements.create("cardExpiry", { style: { base: { color: "#545454", fontSize: "16px" } }, }); cardExpiryElement.mount("#card-expiry-element"); const cardCvcElement = elements.create("cardCvc", { style: { base: { color: "#545454", fontSize: "16px" } }, }); cardCvcElement.mount("#card-cvc-element"); // Note: cardholder name and ZIP code are collected via non-Stripe inputs (not secure). ``` You can dynamically show the card brand while typing: ```js cardNumberElement.on("change", (event) => { const cardBrand = event.brand; const cardNumberDiv = document.getElementById("card-number-element"); cardNumberDiv.style.backgroundImage = getBrandImageUrl(cardBrand); }); ``` Once the user completes the card form, create the Payment Method on Stripe. Note that the expiry and CVC fields are securely handled by Stripe.js and are never readable from your code. ```js const { paymentMethod, error } = await stripe.createPaymentMethod({ type: "card", card: cardNumberElement, billing_details: { name: cardholderName.value, address: { postal_code: cardholderZip.value }, }, }); ``` When a `paymentMethod` is successfully created, send its ID to your backend to attach it to the logged-in user’s account. Use the **system API** (unversioned): `POST /payment-methods/add` **Example:** ```js const response = await fetch("$serviceUrl/payment-methods/add", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ paymentMethodId: paymentMethod.id }), }); ``` When `addPaymentMethod` is called, the backend retrieves or creates the user’s Stripe Customer ID, attaches the Payment Method to that customer, and stores the reference in the local database for future use. Example response: ```json { "isActive": true, "cardHolderName": "John Doe", "userId": "f7103b85-fcda-4dec-92c6-c336f71fd3a2", "customerId": "cus_TNgWUw5QkmUPLa", "paymentMethodId": "pm_1SQw5aP5uUv56CseDGzT1dzP", "platform": "stripe", "cardHolderZip": "34662", "cardInfo": { "brand": "visa", "last4": "4242", "funding": "credit", "exp_month": 11, "exp_year": 2033 }, "id": "19a5ff70-4986-4760-8fc4-6b591bd6bbbf", "createdAt": "2025-11-07T20:16:55.451Z", "updatedAt": "2025-11-07T20:16:55.451Z" } ``` You can append this new entry directly to the UI list or refresh the list using the `listPaymentMethods` API. ### Deleting a Payment Method To remove a saved payment method from the current user’s account, call the **system API** (unversioned): `DELETE /payment-methods/delete/:paymentMethodId` **Example:** ```js await fetch( `$serviceUrl/payment-methods/delete/${paymentMethodId}`, { method: "DELETE", headers: { "Content-Type": "application/json" }, } ); ``` ## Starting the Payment Flow in Backend — Creation and Confirmation of the PaymentIntent Object The payment flow is initiated in the backend through the `startOrderManagementOrderPayment` API. This API must be called with one of the user’s existing payment methods. Therefore, ensure that the frontend **forces the user to select a payment method** before initiating the payment. The `startOrderManagementOrderPayment` API is a versioned **Business Logic API** and follows the same structure as other business APIs. In the Ebaycclone application, the payment flow starts by creating a **Stripe PaymentIntent** and confirming it in a single step within the backend. In a typical (“happy”) path, when the `startOrderManagementOrderPayment` API is called, the response will include a successful or failed PaymentIntent result inside the `paymentResult` object, along with the `orderManagementOrder` object. However, in certain edge cases—such as when 3D Secure (3DS) or other bank-level authentication is required—the confirmation step cannot complete immediately. In such cases, control should return to a frontend page to allow the user to finish the process. To enable this, a **`return_url`** must be provided during the PaymentIntent creation step. Although technically optional, it is **strongly recommended** to include a `return_url`. This ensures that the frontend payment result page can display both successful and failed payments and complete flows that require user interaction. The `return_url` must be a **frontend URL**. The `paymentUserParams` parameter of the `startOrderManagementOrderPayment` API contains the data necessary to create the Stripe PaymentIntent. Call the API as follows: ```js const response = await fetch( `$serviceUrl/v1/startorderManagementOrderpayment/${orderId}`, { method: "PATCH", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ paymentUserParams: { paymentMethodId, return_url: `${yourFrontendReturnUrl}`, }, }), } ); ```` The API response will contain a `paymentResult` object. If an error occurs, it will begin with `{ "result": "ERR" }`. Otherwise, it will include the PaymentIntent information: ```json { "paymentResult": { "success": true, "paymentTicketId": "19a60f8f-eeff-43a2-9954-58b18839e1da", "orderId": "19a60f84-56ee-40c4-b9c1-392f83877838", "paymentId": "pi_3SR0UHP5uUv56Cse1kwQWCK8", "paymentStatus": "succeeded", "paymentIntentInfo": { "paymentIntentId": "pi_3SR0UHP5uUv56Cse1kwQWCK8", "clientSecret": "pi_3SR0UHP5uUv56Cse1kwQWCK8_secret_PTc3DriD0YU5Th4isBepvDWdg", "publicKey": "pk_test_51POkqWP5uU", "status": "succeeded" }, "statusLiteral": "success", "amount": 10, "currency": "USD", "description": "Your credit card is charged for babilOrder for 10", "metadata": { "order": "Purchase-Purchase-order", "orderId": "19a60f84-56ee-40c4-b9c1-392f83877838", "checkoutName": "babilOrder" }, "paymentUserParams": { "paymentMethodId": "pm_1SQw5aP5uUv56CseDGzT1dzP", "return_url": "${yourFrontendReturnUrl}" } } } ``` ### `Start Ordermanagementorderpayment` API Start payment for orderManagementOrder **Rest Route** The `startOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/startordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `startOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to start a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/startordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/startordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ## Analyzing the API Response After calling the `startOrderManagementOrderPayment` API, the most common expected outcome is a confirmed and completed payment. However, several alternate cases should be handled on the frontend. ### System Error Case The API may return a classic service-level error (unrelated to payment). Check the HTTP status code of the response. It should be `200` or `201`. Any `400`, `401`, `403`, or `404` indicates a system error. ```json { "result": "ERR", "status": 404, "message": "Record not found", "date": "2025-11-08T00:57:54.820Z" } ``` **Handle system errors on the payment page** (show a retry option). Do not navigate to the result page. ### Payment Error Case The API performs both database operations and the Stripe payment operation. If the payment fails but the service logic succeeds, the API may still return a `200 OK` status, with the failure recorded in the `paymentResult`. In this case, show an error message and allow the user to retry. ```json { "status": "OK", "statusCode": "200", "orderManagementOrder": { "id": "19a60f8f-eeff-43a2-9954-58b18839e1da", "status": "failed" }, "paymentResult": { "result": "ERR", "status": 500, "message": "Stripe error message: Your card number is incorrect.", "errCode": "invalid_number", "date": "2025-11-08T00:57:54.820Z" } } ``` **Payment errors should be handled on the payment page** (retry option). Do not go to the result page. --- ### Happy Case When both the service and payment result succeed, this is considered the *happy path*. In this case, use the `orderManagementOrder` and `paymentResult` objects in the response to display a success message to the user. `amount` and `description` values are included to help you show payment details on the result page. ```json { "status": "OK", "statusCode": "200", "order": { "id": "19a60f8f-eeff-43a2-9954-58b18839e1da", "status": "paid" }, "paymentResult": { "success": true, "paymentStatus": "succeeded", "paymentIntentInfo": { "status": "succeeded" }, "amount": 10, "currency": "USD", "description": "Your credit card is charged for babilOrder for 10" } } ``` To verify success: ```js if (paymentResult.paymentIntentInfo.status === "succeeded") { // Redirect to result page } ``` > Note: A successful result does not trigger fulfillment immediately. > Fulfillment begins only after the Stripe webhook updates the database. > It’s recommended to show a short “success” toast, wait a few milliseconds, and then navigate to the result page. **Handle the happy case in the result page** by sending the `orderManagementOrderId` and the payment intent secret. ```js const orderId = new URLSearchParams(window.location.search).get("orderId"); const url = new URL(`$yourResultPageUrl`, location.origin); url.searchParams.set("orderId", orderId); url.searchParams.set("payment_intent_client_secret", currentPaymentIntent.clientSecret); setTimeout(() => { window.location.href = url.toString(); }, 600); ``` --- ### Edge Cases Although `startOrderManagementOrderPayment` is designed to handle both creation and confirmation in one step, Stripe may return an incomplete result if third-party authentication or redirect steps are required. You must handle these cases in **both the payment page and the result page**, because some next actions are available immediately, while others occur only after a redirect. If the `paymentIntentInfo.status` equals `"requires_action"`, handle it using Stripe.js as shown below: ```js if (paymentResult.paymentIntentInfo.status === "requires_action") { await runNextAction( paymentResult.paymentIntentInfo.clientSecret, paymentResult.paymentIntentInfo.publicKey ); } ``` Helper function: ```js async function runNextAction(clientSecret, publicKey) { const stripe = Stripe(publicKey); const { error } = await stripe.handleNextAction({ clientSecret }); if (error) { console.log("next_action error:", error); showToast(error.code + ": " + error.message, "fa-circle-xmark text-red-500"); throw new Error(error.message); } } ``` After handling the next action, re-fetch the PaymentIntent from Stripe, evaluate its status, show appropriate feedback, and navigate to the result page. ```js const { paymentIntent } = await stripe.retrievePaymentIntent(clientSecret); if (paymentIntent.status === "succeeded") { showToast("Payment successful!", "fa-circle-check text-green-500"); } else if (paymentIntent.status === "processing") { showToast("Payment is processing…", "fa-circle-info text-blue-500"); } else if (paymentIntent.status === "requires_payment_method") { showToast("Payment failed. Try another card.", "fa-circle-xmark text-red-500"); } const orderId = new URLSearchParams(window.location.search).get("orderId"); const url = new URL(`$yourResultPageUrl`, location.origin); url.searchParams.set("orderId", orderId); url.searchParams.set("payment_intent_client_secret", currentPaymentIntent.clientSecret); setTimeout(() => { window.location.href = url.toString(); }, 600); ``` --- ## The Result Page The payment result page should handle the following steps: 1. Read `orderId` and `payment_intent_client_secret` from the query parameters. 2. Retrieve the PaymentIntent from Stripe and check its status. 3. If required, handle any `next_action` and re-fetch the PaymentIntent. 4. If the status is `"succeeded"`, display a clear visual confirmation. 5. Fetch the `orderManagementOrder` instance from the backend to display any additional order or fulfillment details. Note that paymentIntent status only gives information about the Stripe side. The `orderManagementOrder` instance in the service should also ve updated to start the fulfillment. In most cases, the `startorderManagementOrderPayment` api updates the status of the order using the response of the paymentIntent confirmation, but as stated above in some cases this update can be done only when the webhook executes. So in teh result page always get the final payment status in the `orderManagementOrder. To ensure that service i To fetch the `orderManagementOrder` instance, you van use the related api which is given before, and to ensure that the service is updated with the latest status read the _paymentConfirmation field of the `orderManagementOrder` instance. ```js if (orderManagementOrder._paymentConfirmation == "canceled") { // the payment is canceled, user can be informed that they should try again } if (orderManagementOrder._paymentConfirmation == "paid") { // service knows that payment is done, user can be informed that fullfillment started } else { // it may be pending, processing // Fetch the object again until a canceled or paid status } ``` # **EBAYCCLONE** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 15 - Feedback Service** This document is a part of a REST API guide for the ebaycclone project. It is designed for AI agents that will generate frontend code to consume the project’s backend. This document provides extensive instruction for the usage of feedback ## Service Access Feedback service management is handled through service specific base urls. Feedback service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.). For the feedback service, the base URLs are: * **Preview:** `https://ebaycclone.prw.mindbricks.com/feedback-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/feedback-api` * **Production:** `https://ebaycclone.mindbricks.co/feedback-api` ## Scope **Feedback Service Description** Handles feedback for order items: one feedback per buyer/orderItem, attached to sellerId for analytical feedback/rating aggregation and reputation tracking. Enables querying feedbacks received/given for sellers and buyers. test Feedback service provides apis and business logic for following data objects in ebaycclone application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows. **`feedback` Data Object**: One feedback per (buyer, orderItem). Stores rating (1-5), comment, ties to seller for analytics. Created only after delivery confirmed on order item. ## Feedback Service Frontend Description By The Backend Architect # feedback service (AI UX prompt) - Feedback can be left by buyers *only* after confirming delivery for an order item. - When leaving feedback, show the purchased item and seller context. - Display rating as 1-5 stars and an optional textual comment field (limit: 500 chars). - For seller public profile, aggregate and display feedback score (average of ratings, total count) and show up to N recent comments/ratings. - For buyer's purchase history, display feedback status and allow edit/delete if permitted by backend policy. - Feedback left is always visible to seller (as receiver) and buyer (as author); public listing controlled per guideline. - One feedback per purchased order item per buyer (attempt to enforce in UI as well). - When updating feedback, pre-fill prior text/rating. - Feedback should be timestamped by createdAt. ## API Structure ### Object Structure of a Successful Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client. **HTTP Status Codes:** * **200 OK**: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully. * **201 Created**: Returned for CREATE operations, indicating that the resource was created successfully. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling that the request executed successfully. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` * **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation. ### Additional Data Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature. ### Error Response If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity: * **400 Bad Request**: The request was improperly formatted or contained invalid parameters. * **401 Unauthorized**: The request lacked a valid authentication token; login is required. * **403 Forbidden**: The current token does not grant access to the requested resource. * **404 Not Found**: The requested resource was not found on the server. * **500 Internal Server Error**: The server encountered an unexpected condition. Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Bucket Management (This information is also given in PART 1 prompt.) This application has a bucket service used to store user files and other object-related files. The bucket service is login-agnostic, so for write operations or private reads, include a bucket token (provided by services) in the request’s Authorization header as a Bearer token. Please note that all other business services require the access token in the Bearer header, while the bucket service expects a bucket token because it is login-agnostic. Ensure you manage the required token injection properly; any auth interceptor should not replace the bucket token with the access token. **User Bucket** This bucket stores public user files for each user. When a user logs in—or in the `/currentuser` response—there is a `userBucketToken` to use when sending user-related public files to the bucket service. ```json { //... "userBucketToken": "e56d...." } ``` To upload a file `POST {baseUrl}/bucket/upload` The request body is form-data which includes the `bucketId` and the file binary in the `files` field. ```js { bucketId: "{userId}-public-user-bucket", files: {binary} } ``` Response status is 200 on success, e.g., body: ```json { "success": true, "data": [ { "fileId": "9da03f6d-0409-41ad-bb06-225a244ae408", "originalName": "test (10).png", "mimeType": "image/png", "size": 604063, "status": "uploaded", "bucketName": "f7103b85-fcda-4dec-92c6-c336f71fd3a2-public-user-bucket", "isPublic": true, "downloadUrl": "https://babilcom.mindbricks.co/bucket/download/9da03f6d-0409-41ad-bb06-225a244ae408" } ] } ``` To download a file from the bucket, you need its `fileId`. If you upload an avatar or other asset, ensure the download URL or the `fileId` is stored in the backend. Buckets are mostly used in object creations that require an additional file, such as a product image or user avatar. After uploading your image to the bucket, insert the returned download URL into the related property of the target object record. **Application Bucket** This Ebaycclone application also includes a common public bucket that anyone can read, but only users with the `superAdmin`, `admin`, or `saasAdmin` roles can write (upload) to it. When a user with one of these admin roles is logged in, the `/login` response or the `/currentuser` response also returns an `applicationBucketToken` field, which is used when uploading any file to the application bucket. ```json { //... "applicationBucketToken": "e23fd...." } ``` The common public application bucket ID is `"ebaycclone-public-common-bucket"` In certain admin areas—such as product management pages—since the user already has the application bucket token, they will be able to upload related object images. Please configure your UI to upload files to the application bucket using this bucket token whenever needed. **Object Buckets** Some objects may also return a bucket token for uploading or accessing files related to that object. For example, in a project management application, when you fetch a project’s data, a public or private bucket token may be provided to upload or download project-related files. These buckets will be used as described in the relevant object definitions. ## Feedback Data Object One feedback per (buyer, orderItem). Stores rating (1-5), comment, ties to seller for analytics. Created only after delivery confirmed on order item. ### Feedback Data Object Frontend Description By The Backend Architect # feedback object (AI UX prompt) - Show both buyer (author) and seller (recipient) for feedback context UI. - Rating must be displayed as 1-5 stars. Text comment is optional. - Feedback becomes available only after buyer confirms delivery (see delivery status on purchased item). - Block duplicate submissions in frontend (only one feedback per item per buyer). - Expose feedback in buyer profile (given) and seller profile (received). - Show createdAt timestamp in UI. - If backend allows update/delete, populate forms with old values or display moderation status. ### Feedback Data Object Properties Feedback data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Description | |----------|------|---------|----------|-------------| | `rating` | Integer | false | Yes | Rating (1-5 stars) submitted by buyer. Required. | | `orderId` | ID | false | Yes | Order containing this purchased item. Used for aggregation and validation. | | `buyerId` | ID | false | Yes | User/buyer leaving feedback. Authenticated user, must match order item buyer. | | `orderItemId` | ID | false | Yes | Purchased item (line item) in order. Feedback is per (buyer, orderItem). | | `sellerId` | ID | false | Yes | Seller of product for analytics/aggregation. Not author; used for querying feedback about sellers. | | `comment` | String | false | No | Optional textual feedback comment, max ~500 chars. | | `productId` | ID | false | Yes | The product listing being reviewed (snapshot at order time). | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Relation Properties `orderId` `buyerId` `orderItemId` `sellerId` `productId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **orderId**: ID Relation to `orderManagementOrder`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **buyerId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **orderItemId**: ID Relation to `orderManagementOrderItem`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **sellerId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **productId**: ID Relation to `productListingProduct`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes ### Filter Properties `rating` `orderId` `buyerId` `orderItemId` `sellerId` `productId` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **rating**: Integer has a filter named `rating` - **orderId**: ID has a filter named `orderId` - **buyerId**: ID has a filter named `buyerId` - **orderItemId**: ID has a filter named `orderItemId` - **sellerId**: ID has a filter named `sellerId` - **productId**: ID has a filter named `productId` ## API Reference ### `List Feedbacks` API List feedback with filtering by buyerId (given), sellerId (received), productId, or orderItemId. Used for showing seller profile, buyer profile, or order analytics. **Rest Route** The `listFeedbacks` API REST controller can be triggered via the following route: `/v1/feedbacks` **Rest Request Parameters** The `listFeedbacks` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/feedbacks** ```js axios({ method: 'GET', url: '/v1/feedbacks', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedbacks", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "feedbacks": [ { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Feedback` API Get a single feedback by id. Accessible to public (for seller profile, product, or audit views). **Rest Route** The `getFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `getFeedback` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | **feedbackId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/feedbacks/:feedbackId** ```js axios({ method: 'GET', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Feedback` API Update feedback (comment/rating) for existing feedback record (buyer only). Admin can update as override. **Rest Route** The `updateFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `updateFeedback` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | | rating | Integer | false | request.body?.rating | | comment | String | false | request.body?.comment | **feedbackId** : This id paremeter is used to select the required data object that will be updated **rating** : Rating (1-5 stars) submitted by buyer. Required. **comment** : Optional textual feedback comment, max ~500 chars. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/feedbacks/:feedbackId** ```js axios({ method: 'PATCH', url: `/v1/feedbacks/${feedbackId}`, data: { rating:"Integer", comment:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Feedback` API Delete (soft-delete) feedback (by buyer or admin). Only feedback owner or admin. **Rest Route** The `deleteFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `deleteFeedback` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | **feedbackId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/feedbacks/:feedbackId** ```js axios({ method: 'DELETE', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Feedback` API Buyer creates feedback for a delivered order item. Only allowed once per (buyer, orderItemId). Allowed only once order item is delivered. **Rest Route** The `createFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks` **Rest Request Parameters** The `createFeedback` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | rating | Integer | true | request.body?.rating | | orderId | ID | true | request.body?.orderId | | orderItemId | ID | true | request.body?.orderItemId | | sellerId | ID | true | request.body?.sellerId | | comment | String | false | request.body?.comment | | productId | ID | true | request.body?.productId | **rating** : Rating (1-5 stars) submitted by buyer. Required. **orderId** : Order containing this purchased item. Used for aggregation and validation. **orderItemId** : Purchased item (line item) in order. Feedback is per (buyer, orderItem). **sellerId** : Seller of product for analytics/aggregation. Not author; used for querying feedback about sellers. **comment** : Optional textual feedback comment, max ~500 chars. **productId** : The product listing being reviewed (snapshot at order time). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/feedbacks** ```js axios({ method: 'POST', url: '/v1/feedbacks', data: { rating:"Integer", orderId:"ID", orderItemId:"ID", sellerId:"ID", comment:"String", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` **After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.** # **EBAYCCLONE** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 2 - Verification Management** This document is a part of a REST API guide for the ebaycclone project. It is designed for AI agents that will generate frontend code to consume the project’s backend. This document includes the verification processes for the autheitcation flow. Please read it carefully and implement all requirements described here. The project has 1 auth service, 1 notification service, 1 BFF service, and 10 business services, plus other helper services such as bucket and realtime. In this document you will be informed only about the auth service. Each service is a separate microservice application and listens for HTTP requests at different service URLs. Services may be deployed to the preview server, staging server, or production server. Therefore, each service has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the home page. ## Accessing the backend Each backend service has its own URL for each deployment environment. Users may want to test the frontend in one of the three deployments—preview, staging, or production. Please ensure that the home page includes a deployment server selection option so that, as the frontend coding agent, you can set the base URL for all services. For the auth service, the base URLs are: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` Any request that requires login must include a valid token in the Bearer authorization header. ## After User Registration Frontend should also be aware of verification after any login attempt. The login request may return a 401 or 403 with the error codes that indicates the verification needs. ```json { //... "errCode": "EmailVerificationNeeded", // or "errCode": "MobileVerificationNeeded", } ``` ## Email Verification In the registration response, check the `emailVerificationNeeded` property in the response root. If it is `true`, start the email verification flow. After the login process, if you receive an HTTP error and the response contains an `errCode` with the value `EmailVerificationNeeded`, start the email verification flow. 1. Call the email verification `start` route of the backend (described below) with the user’s email. The backend will send a secret code to the provided email address. **The backend can send the email if the architect has configured a real mail service or SMTP server. During development, the backend also returns the secret code to the frontend. You can read this code from the `secretCode` property of the response.** 2. The secret code in the email will be a 6-digit code. Provide an input page so the user can paste this code into the frontend application. Navigate to this input page after starting the verification process. **If the `secretCode` is sent to the frontend for testing, display it on the input page so the user can copy and paste it.** 3. The `start` response includes a `codeIndex` property. Display its value on the input page so the user can match the index in the message with the one on the screen. 4. When the user submits the code, complete the email verification using the `complete` route of the backend (described below) with the user’s email and the secret code. 5. After a successful email verification response, please check the response object to have the property 'mobileVerificationNeeded' as `true`, if so navigate to the mobile verification flow as described below. **If no mobile verification is needed then just navigate the login page.** Below are the `start` and `complete` routes for email verification. These are system routes and therefore are not versioned. #### `POST /verification-services/email-verification/start` **Purpose:** Starts email verification by generating and sending a secret code. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `email` | String | Yes | User’s email address to verify | **Example Request** ```json { "email": "user@example.com" } ``` **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid" } ``` > ⚠️ In production, `secretCode` is **not** returned — it is only sent via email. **Error Responses** * `400 Bad Request`: Already verified * `403 Forbidden`: Too many attempts (rate limit) --- #### `POST /verification-services/email-verification/complete` **Purpose:** Completes verification using the received code. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `email` | String | Yes | User’s email | | `secretCode` | String | Yes | Verification code | **Success Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid" } ``` **Error Responses** * `403 Forbidden`: Code expired or mismatched * `404 Not Found`: No verification in progress --- ## Mobile Verification In the registration response, check the `mobileVerificationNeeded` property in the response root. If it is `true`, start the mobile verification flow. After the login process, if you receive a 403 error and the response contains an `errCode` with the value `MobileVerificationNeeded`, start the mobile verification flow. 1. Call the mobile verification `start` route of the backend (described below) with the user’s email. The backend will send a secret code to the user’s mobile number. **If a real texting service is configured, the backend sends the SMS. During development, the backend also returns the secret code to the frontend in the `secretCode` property.** 2. The secret code in the SMS will be a 6-digit code. Provide an input page so the user can paste this code. Navigate to this input page after starting the verification process. **If the `secretCode` is returned for testing, display it on the input page for easy copy/paste.** 3. When the user submits the code, complete mobile verification using the `complete` route of the backend (described below) with the user’s email and the secret code. 4. The `start` response includes a `codeIndex` property. Display its value on the input page so the user can match the index shown in the message with the one on the screen. 5. After a successful mobile verification response, navigate to the login page. **Verification Order** If both `emailVerificationNeeded` and `mobileVerificationNeeded` are `true`, handle both verification flows in order. First complete email verification, then mobile verification. Below are the `start` and `complete` routes for mobile verification. These are system routes and therefore are not versioned. #### `POST /verification-services/mobile-verification/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------ | | `email` | String | Yes | User’s email to locate mobile record | **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 180, "verificationType": "byCode", // in testMode "secretCode": "123456", "userId": "user-uuid" } ``` > ⚠️ `secretCode` is returned only in development. **Errors** * `400 Bad Request`: Already verified * `403 Forbidden`: Rate-limited --- #### `POST /verification-services/mobile-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------------- | | `email` | String | Yes | Associated email | | `secretCode` | String | Yes | Code received via SMS | **Success Response** ```json { "status": "OK", "isVerified": true, "mobile": "+1 333 ...", // in testMode "userId": "user-uuid" } ``` --- ## Resetting Password Users can reset their forgotten passwords without a login required, through email and mobile verification. To be able to start a password reset flow, users will click on the "Reset Password" link in the login page. Since there are two verification methods, by email or by mobile, for password reset, when the reset password link is clicked, frontend should ask user if they want to make the verification through email of mobile. According to the users selection the frontend shoudl start the related flow as explaned below step by step. ## Password Reset By Email Flow 1. Call the password reset by email verification `start` route of the backend (described below) with the user’s email. The backend will send a secret code to the provided email address. **The backend can send the email if the architect has configured a real mail service or SMTP server. During development, the backend also returns the secret code to the frontend. You can read this code from the `secretCode` property of the response.** 2. The secret code in the email will be a 6-digit code. Provide an input page so the user can paste this code into the frontend application. Navigate to this input page after starting the verification process. **If the `secretCode` is sent to the frontend for testing, display it on the input page so the user can copy and paste it.** 3. The `start` response includes a `codeIndex` property. Display its value on the input page so the user can match the index in the message with the one on the screen. 4. The input page should also include a double input area for the user to enter and confirm their new password. 5. When the user submits the code and the new password, complete the password reset by email using the `complete` route of the backend (described below) with the user’s email , the secret code and new password. 6. After a successful verification response, navigate to the login page. Below are the `start` and `complete` routes for password reset by email verification. These are system routes and therefore are not versioned. #### POST `/verification-services/password-reset-by-email/start` **Purpose**: Starts the password reset process by generating and sending a secret verification code. #### Request Body | Parameter | Type | Required | Description | |-----------|--------|----------|-------------------------------------| | email | String | Yes | The email address of the user | ```json { "email": "user@example.com" } ``` **Success Response** Returns secret code details (only in development environment) and confirmation that the verification step has been started. ```json { "userId": "user-uuid", "email": "user@example.com", "codeIndex": 1, "secretCode": "123456", "timeStamp": 1765484354, "expireTime": 86400, "date": "2024-04-29T10:00:00.000Z", "verificationType": "byLink", } ``` ⚠️ In production, the secret code is only sent via email and not exposed in the API response. **Error Responses** - `401 NotAuthenticated`: Email address not found or not associated with a user. - `403 Forbidden`: Sending a code too frequently (spam prevention). --- #### POST `/verification-services/password-reset-by-email/complete` **Purpose**: Completes the password reset process by validating the secret code and updating the user's password. #### Request Body | Parameter | Type | Required | Description | |-------------|--------|----------|----------------------------------------------| | email | String | Yes | The email address of the user | | secretCode | String | Yes | The code received via email | | password | String | Yes | The new password the user wants to set | ```json { "email": "user@example.com", "secretCode": "123456", "password": "newSecurePassword123" } ``` **Success Response** ```json { "userId": "user-uuid", "email": "user@example.com", "isVerified": true } ``` **Error Responses** - `403 Forbidden`: - Secret code mismatch - Secret code expired - No ongoing verification found --- ## Password Reset By Mobile Flow 1. Call the password reset by mobile verification `start` route of the backend (described below) with the user’s email. The backend will send a secret code to the user’s mobile number. **If a real texting service is configured, the backend sends the SMS. During development, the backend also returns the secret code to the frontend in the `secretCode` property.** 2. The secret code in the SMS will be a 6-digit code. Provide an input page so the user can paste this code. Navigate to this input page after starting the verification process. **If the `secretCode` is returned for testing, display it on the input page for easy copy/paste.** 3. The `start` response includes a `codeIndex` property. Display its value on the input page so the user can match the index in the message with the one on the screen. Also display the half masked `mobile`number that comes in the response, to tell the user that their code is sent to this number. 4. The input page should also include a double input area for the user to enter and confirm their new password. 5. When the user submits the code, complete mobile verification using the `complete` route of the backend (described below) with the user’s email and the secret code. 6. After a successful mobile verification response, navigate to the login page. Below are the `start` and `complete` routes for password reset by mobile verification. These are system routes and therefore are not versioned. #### POST `/verification-services/password-reset-by-mobile/start` **Purpose**: Initiates the mobile-based password reset by sending a verification code to the user's mobile. #### Request Body | Parameter | Type | Required | Description | |-----------|--------|----------|------------------------------| | email | String | Yes | The email of the user that resets the pssword | ```json { "email": "user@user.com" } ``` ### Success Response Returns the verification context (code returned only in development): ```json { "status": "OK", "codeIndex": 1, timeStamp: 133241255, "mobile": "+905.....67", "secretCode": "123456", "expireTime": 86400, "date": "2024-04-29T10:00:00.000Z", verificationType: "byLink" } ``` ⚠️ In production, the `secretCode` is not included in the response and is only sent via SMS. ### Error Responses - **400 Bad Request**: Mobile already verified - **403 Forbidden**: Rate-limited (code already sent recently) - **404 Not Found**: User with provided mobile not found --- #### POST `/verification-services/password-reset-by-mobile/complete` **Purpose**: Finalizes the password reset process by validating the received verification code and updating the user’s password. #### Request Body | Parameter | Type | Required | Description | |-------------|--------|----------|-------------------------------------------------| | email | String | Yes | The email address of the user | | secretCode | String | Yes | The code received via SMS | | password | String | Yes | The new password to assign | ```json { "email": "user@example.com", "secretCode": "123456", "password": "NewSecurePassword123!" } ``` ### Success Response ```json { "userId": "user-uuid", "isVerified": true } ``` --- ** Please dont forget to arrange the code to be able to navigate to the verification pages both after registrations and login attempts if verification is needed.** **After this prompt, the user may give you new instructions to update your first output or provide subsequent prompts about the project.** # **EBAYCCLONE** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 3 - Profile Management** This document is a part of a REST API guide for the ebaycclone project. It is designed for AI agents that will generate frontend code to consume the project’s backend. This document includes information and api descriptions about building a **profile page** in the frontend using the auth service profile api calls, and also in this document the bucket service will be introduced to manage the avatar. The project has 1 auth service, 1 notification service, 1 BFF service, and 10 business services, plus other helper services such as bucket and realtime. In this document you will use the auth service and bucket service. Each service is a separate microservice application and listens for HTTP requests at different service URLs. Services may be deployed to the preview server, staging server, or production server. Therefore, each service has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the home page. ## Accessing the backend Each backend service has its own URL for each deployment environment. Users may want to test the frontend in one of the three deployments—preview, staging, or production. Please ensure that the register and login pages include a deployment server selection option so that, as the frontend coding agent, you can set the base URL for all services. The base URL of the application in each environment is as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com` * **Staging:** `https://ebaycclone-stage.mindbricks.co` * **Production:** `https://ebaycclone.mindbricks.co` For the auth service, service urls are as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` For each other service, the service URL will be given in the service sections. Any request that requires login must include a valid token in the Bearer authorization header. ## Bucket Management This application has a bucket service used to store user files and other object-related files. The bucket service is login-agnostic, so for write operations or private reads, include a bucket token (provided by services) in the request’s Authorization header as a Bearer token. Please note that all other business services require the access token in the Bearer header, while the bucket service expects a bucket token because it is login-agnostic. Ensure you manage the required token injection properly; any auth interceptor should not replace the bucket token with the access token. To access the bucket service in each environement use the bucket service api urls below: * **Preview:** `https://ebaycclone.prw.mindbricks.com/bucket` * **Staging:** `https://ebaycclone-stage.mindbricks.co/bucket` * **Production:** `https://ebaycclone.mindbricks.co/bucket` **User Bucket** This bucket stores public user files for each user. When a user logs in—or in the `/currentuser` response—there is a `userBucketToken` to use when sending user-related public files to the bucket service. ```json { //... "userBucketToken": "e56d...." } ``` To upload a file `POST {bucketServiceUrl}/upload` The request body is form-data which includes the `bucketId` and the file binary in the `files` field. ```js { bucketId: "{userId}-public-user-bucket", files: {binary} } ``` Response status is 200 on success, e.g., body: ```json { "success": true, "data": [ { "fileId": "9da03f6d-0409-41ad-bb06-225a244ae408", "originalName": "test (10).png", "mimeType": "image/png", "size": 604063, "status": "uploaded", "bucketName": "f7103b85-fcda-4dec-92c6-c336f71fd3a2-public-user-bucket", "isPublic": true, "downloadUrl": "https://babilcom.mindbricks.co/bucket/download/9da03f6d-0409-41ad-bb06-225a244ae408" } ] } ``` To download a file from the bucket, you need its `fileId`. If you upload an avatar or other asset, ensure the download URL or the `fileId` is stored in the backend. Buckets are mostly used in object creations that require an additional file, such as a product image or user avatar. After uploading your image to the bucket, insert the returned download URL into the related property of the target object record. **Application Bucket** This Ebaycclone application also includes a common public bucket that anyone can read, but only users with the `superAdmin`, `admin`, or `saasAdmin` roles can write (upload) to it. When a user with one of these admin roles is logged in, the `/login` response or the `/currentuser` response also returns an `applicationBucketToken` field, which is used when uploading any file to the application bucket. ```json { //... "applicationBucketToken": "e23fd...." } ``` The common public application bucket ID is `"ebaycclone-public-common-bucket"` In certain admin areas—such as product management pages—since the user already has the application bucket token, they will be able to upload related object images. Please configure your UI to upload files to the application bucket using this bucket token whenever needed. **Object Buckets** Some objects may also return a bucket token for uploading or accessing files related to that object. For example, in a project management application, when you fetch a project’s data, a public or private bucket token may be provided to upload or download project-related files. These buckets will be used as described in the relevant object definitions. ## Profile Page Design a profile page to manage (view and edit) user information. The profile page should also be able to upload the user avatar to the user’s public bucket. For bucket information, see the Bucket Management section above. On the profile page, you will need 4 business APIs: `getUser` , `updateProfile`, `updateUserPassword` and `archiveProfile`. Do not rely on the `/currentuser` response for profile data, because it contains session information. The most recent user data is in the user database and should be accessed via the `getUser` business API. The `updateProfile`, `updateUserPassword` and `archiveProfile` api can only be called by the users themselves. They are designed specific to the profile page. The avatar upload component should include an image-cropping component with zoom and pan capabilities. The frontend will send the image to the bucket after it is scaled and cropped. Do not implement your own cropping component; instead, use the library component `react-easy-crop` by installing it. **Note that the user cannot change/update their `email` or `roleId`.** For password update you should make a separate block in the UI, so that user can enter old password, new password and confirm new password before calling the `updateUserPassword`. Here are the 3 auth APIs—`getUser` , `updateProfile` and `updateUserPassword`— as follows: You can access these APIs through the auth service base URL, `{appUrl}/auth-api`. ### `Get User` API This api is used by admin roles or the users themselves to get the user profile information. **Rest Route** The `getUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `getUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users/:userId** ```js axios({ method: 'GET', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Profile` API This route is used by users to update their profiles. **Rest Route** The `updateProfile` API REST controller can be triggered via the following route: `/v1/profile/:userId` **Rest Request Parameters** The `updateProfile` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/profile/:userId** ```js axios({ method: 'PATCH', url: `/v1/profile/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpassword` API This route is used to update the password of users in the profile page by users themselves **Rest Route** The `updateUserPassword` API REST controller can be triggered via the following route: `/v1/userpassword/:userId` **Rest Request Parameters** The `updateUserPassword` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | oldPassword | String | true | request.body?.oldPassword | | newPassword | String | true | request.body?.newPassword | **userId** : This id paremeter is used to select the required data object that will be updated **oldPassword** : The old password of the user that will be overridden bu the new one. Send for double check. **newPassword** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpassword/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpassword/${userId}`, data: { oldPassword:"String", newPassword:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### Archiving A Profile A user may want to archive their profile. So the profile page should include an archive section for the users to archive their accounts. When an account is archived, it is marked as archived and an aarchiveDate is atteched to the profile. All user data is kept in the database for 1 month after user archived. If user tries to login or register with the same email, the account will be activated again. But if no login or register occures in 1 month after archiving, the profile and its related data will be deleted permanenetly. So in the profile page, 1. The arcihve options should be accepted after user writes a text like ("ARCHİVE MY ACCOUNT") to a confirmation dialog, so that frontend UX can ensure this is not an unconscious request. 2. The user should be warned about the process, that his account will be available for a restore for 1 month. The archive api, can only be called by the users themselves and its used as follows. ### `Archive Profile` API This api is used by users to archive their profiles. **Rest Route** The `archiveProfile` API REST controller can be triggered via the following route: `/v1/archiveprofile/:userId` **Rest Request Parameters** The `archiveProfile` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/archiveprofile/:userId** ```js axios({ method: 'DELETE', url: `/v1/archiveprofile/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` --- After you complete this step, please ensure you have not made the following common mistakes: 1. The auth API and bucket API are different services, and both URLs should be set according to the selected environment (production, staging, preview). 2. Note that any api call to the application backend is based on a service base url, in this propmpt all auth apis should be called by `/auth-api` prefix after application's base url, and bucket apis should be called by `/bucket` prefix after base url. 3. The auth API and bucket API use different tokens. The auth API requires the `accessToken` in the Bearer header; the bucket API requires bucket-specific tokens such as `userBucketToken` or other application-specific bucket tokens. You may need two separate Axios clients: one for auth (always using the access token) and one for bucket operations (using the relevant bucket token). 4. On the profile page, fetch the latest user data from the service using `getUser`. The `/currentuser` API is session-stored data; the latest data is in the database. 5. When you upload the avatar image on the profile page, use the returned download URL as the user’s `avatar` property and update the user record when the Save button is clicked. **After this prompt, the user may give you new instructions to update your first output or provide subsequent prompts about the project.** # **EBAYCCLONE** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 4 - User Management** This document is the 2nd part of a REST API guide for the ebaycclone project. It is designed for AI agents that will generate frontend code to consume the project’s backend. This document provides extensive instruction for administrative user management. ## Service Access User management is handled through auth service again. Auth service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.). For the auth service, the base URLs are: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` Please note that any feature in this document is open to admins only. When the user logins, the response includes a roleId field. This roleId should one of these following admin roles. `superAdmin`, `admin`, ## Scope Auth service provides following feature for user management in ebaycclone application. These features are already handled in the previous part. 1. User Registration 2. User Authentication 3. Password Reset 3. Email (and/or) Mobile Verification 4. Profile Management These features will be handled in this part. - User Management - User Groups Management - Permission Manageemnt ## API Structure ### Object Structure of a Successful Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client. **HTTP Status Codes:** * **200 OK**: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully. * **201 Created**: Returned for CREATE operations, indicating that the resource was created successfully. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling that the request executed successfully. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` * **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation. ### Additional Data Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature. ### Error Response If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity: * **400 Bad Request**: The request was improperly formatted or contained invalid parameters. * **401 Unauthorized**: The request lacked a valid authentication token; login is required. * **403 Forbidden**: The current token does not grant access to the requested resource. * **404 Not Found**: The requested resource was not found on the server. * **500 Internal Server Error**: The server encountered an unexpected condition. Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## User Management User management will be one of the main parts of the administrative manageemnts, so there will be a minimal but fancy `users` page in the admin dashboard. ### User Roles - `superadmin` : The first creator of the backend, the owner of the application, root user, has got an absolute authroization on all actions. It can not be assgined any other user. It can't be unassigned. Super admin user can not be deleted in any way. - `admin` : The role that can be assigned to any user by the super admin. This role includes most permissions that super admin have, but admins can't assign admin roles, can't unassign an admin role, can't delete other users who have admin role. In addition to these limitations, some critical actions in the business services may also be open to only super admin. - `user` : The standard role that is assgined to every user when first created or registered. This role doesnt have any privilages and can access to their own data or public data. The roles object is a hardcoded object in the generated code, and it contains the following roles: ```json { "superAdmin": "'superAdmin'", "admin": "'admin'", "user": "'user'" } ``` Each user may have only one role, and it is given in `/login` , `/currentuser` or `/users/:userId` response as follows ```json { // ... "roleId":"superAdmin", // ... } ``` ## Listing Users You can list users using the `listUsers` api. ### `List Users` API The list of users is filtered by the tenantId. **Rest Route** The `listUsers` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `listUsers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users** ```js axios({ method: 'GET', url: '/v1/users', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ## Searching Users You may search users with their full names and emails. The search is done in elasticsearch index of the user table so a fast response is provided by the backend. You can send search request on each character update in the search box but start searching after 3 chars. The keyword parameter that is used in the business logic of the api, is read from the keyword query parameter. eg: `GET /v1/searchusers?keyword=Joe` When the user deletes the search keyword, use the `listUsers` api to get the full list again. ### `Search Users` API The list of users is filtered by the tenantId. **Rest Route** The `searchUsers` API REST controller can be triggered via the following route: `/v1/searchusers` **Rest Request Parameters** The `searchUsers` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | keyword | String | true | request.query?.keyword | **keyword** : **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchusers** ```js axios({ method: 'GET', url: '/v1/searchusers', data: { }, params: { keyword:'"String"', } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` #### Pagination When you list the users please use pagination. To be able to use pagination you should provide a `pageNumber` paramater in the query. The default row count for one page is 25, add an option for user to change it to 50 or 100. You can provide this value to the api through the `pageRowCount` parameter; `GET /users?pageNumber=1&pageRowCount=50` ## Creatng Users The user management console in the admin dashboard should provide UX components for user creating by admins. When creating users, it should also be possible to upload user avatar. Note that when creating, updating users , admins can not set emailVerified (or mobileVerified if exists) as true, since it is a logical mechanism and should be verified only through verification processes. ### `Create User` API This api is used by admin roles to create a new user manually from admin panels **Rest Route** The `createUser` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `createUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | email | String | true | request.body?.email | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **email** : A string value to represent the user's email. **password** : A string value to represent the user's password. It will be stored as hashed. **fullname** : A string value to represent the fullname of the user **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/users** ```js axios({ method: 'POST', url: '/v1/users', data: { avatar:"String", email:"String", password:"String", fullname:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### Avatar Upload Normally when user registers by his own, the avatar is uploaded to the logged in user's public bucket, however in this user admin panel, if any avatar upload is needed, it should be uploaded to the application public bucket. To access this application bucket, the `applicationBucketToken` should be used in the bearer header, and the bucketId in the payload should be given as `"ebaycclone-public-common-bucket"` . Before the avatar upload, a specific componenet from `react-easy-crop` lib should be used for zoom, pan and crop. This component also requested in the PART 1 prompt for profile page, so ensure taht you reuse the previous code if exists. ## Updating Users User update is possible by `updateUser`api. However since this update api is also called by teh user themselves it is lmited with name and avatar change (or any other user related property). For roleId and password updates seperate apis are used. So arrange the user update UI as to update the user info, as to set roleId and as to update password. ### `Update User` API This route is used by admins to update user profiles. **Rest Route** The `updateUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `updateUser` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/users/:userId** ```js axios({ method: 'PATCH', url: `/v1/users/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` For role updates there are some rules. 1. Superadmin role can not be unassigned even by superadmin. 2. Admin roles can be assgined or unassgined only by superadmin. 3. All other roles can be assigned and unassgined by admins and superadmin. For password updates there are some rules. 1. Superadmin and admin passwords can be updated only by superadmin. 2. Admins can update only non-admin passwords. ### `Update Userrole` API This route is used by admin roles to update the user role.The default role is user when a user is registered. A user's role can be updated by superAdmin or admin **Rest Route** The `updateUserRole` API REST controller can be triggered via the following route: `/v1/userrole/:userId` **Rest Request Parameters** The `updateUserRole` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | roleId | String | true | request.body?.roleId | **userId** : This id paremeter is used to select the required data object that will be updated **roleId** : The new roleId of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userrole/:userId** ```js axios({ method: 'PATCH', url: `/v1/userrole/${userId}`, data: { roleId:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpasswordbyadmin` API This route is used to change any user password by admins only. Superadmin can chnage all passwords, admins can change only nonadmin passwords **Rest Route** The `updateUserPasswordByAdmin` API REST controller can be triggered via the following route: `/v1/userpasswordbyadmin/:userId` **Rest Request Parameters** The `updateUserPasswordByAdmin` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | password | String | true | request.body?.password | **userId** : This id paremeter is used to select the required data object that will be updated **password** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpasswordbyadmin/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpasswordbyadmin/${userId}`, data: { password:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### Deleting Users Deleting users is possible in certain conditions. 1. SuperAdmin can not be deleted. 2. Admins can be deleted by only superadmin. 3. Users can be deleted by admins or superadmin. ### `Delete User` API This api is used by admins to delete user profiles. **Rest Route** The `deleteUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `deleteUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/users/:userId** ```js axios({ method: 'DELETE', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` --- When you list user group members, a `user` object will also be inserted in each userGroupMember object, with fullname, avatar and email. ## Bucket Management (This information is also given in PART 1 prompt.) This application has a bucket service used to store user files and other object-related files. The bucket service is login-agnostic, so for write operations or private reads, include a bucket token (provided by services) in the request’s Authorization header as a Bearer token. Please note that all other business services require the access token in the Bearer header, while the bucket service expects a bucket token because it is login-agnostic. Ensure you manage the required token injection properly; any auth interceptor should not replace the bucket token with the access token. **User Bucket** This bucket stores public user files for each user. When a user logs in—or in the `/currentuser` response—there is a `userBucketToken` to use when sending user-related public files to the bucket service. ```json { //... "userBucketToken": "e56d...." } ``` To upload a file `POST {baseUrl}/bucket/upload` The request body is form-data which includes the `bucketId` and the file binary in the `files` field. ```js { bucketId: "{userId}-public-user-bucket", files: {binary} } ``` Response status is 200 on success, e.g., body: ```json { "success": true, "data": [ { "fileId": "9da03f6d-0409-41ad-bb06-225a244ae408", "originalName": "test (10).png", "mimeType": "image/png", "size": 604063, "status": "uploaded", "bucketName": "f7103b85-fcda-4dec-92c6-c336f71fd3a2-public-user-bucket", "isPublic": true, "downloadUrl": "https://babilcom.mindbricks.co/bucket/download/9da03f6d-0409-41ad-bb06-225a244ae408" } ] } ``` To download a file from the bucket, you need its `fileId`. If you upload an avatar or other asset, ensure the download URL or the `fileId` is stored in the backend. Buckets are mostly used in object creations that require an additional file, such as a product image or user avatar. After uploading your image to the bucket, insert the returned download URL into the related property of the target object record. **Application Bucket** This Ebaycclone application also includes a common public bucket that anyone can read, but only users with the `superAdmin`, `admin`, or `saasAdmin` roles can write (upload) to it. When a user with one of these admin roles is logged in, the `/login` response or the `/currentuser` response also returns an `applicationBucketToken` field, which is used when uploading any file to the application bucket. ```json { //... "applicationBucketToken": "e23fd...." } ``` The common public application bucket ID is `"ebaycclone-public-common-bucket"` In certain admin areas—such as product management pages—since the user already has the application bucket token, they will be able to upload related object images. Please configure your UI to upload files to the application bucket using this bucket token whenever needed. **Object Buckets** Some objects may also return a bucket token for uploading or accessing files related to that object. For example, in a project management application, when you fetch a project’s data, a public or private bucket token may be provided to upload or download project-related files. These buckets will be used as described in the relevant object definitions. **After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.** # **EBAYCCLONE** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 5 - AuctionOffer Service** This document is a part of a REST API guide for the ebaycclone project. It is designed for AI agents that will generate frontend code to consume the project’s backend. This document provides extensive instruction for the usage of auctionOffer ## Service Access AuctionOffer service management is handled through service specific base urls. AuctionOffer service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.). For the auctionOffer service, the base URLs are: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auctionoffer-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auctionoffer-api` * **Production:** `https://ebaycclone.mindbricks.co/auctionoffer-api` ## Scope **AuctionOffer Service Description** Handles auction bids and fixed-price offers for product listings, enforces real-time auction state, handles strict offer workflows including counter-offers, and triggers domain events for bid/offer notifications. No payment or frontend aggregation logic included. AuctionOffer service provides apis and business logic for following data objects in ebaycclone application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows. **`auctionOfferOffer` Data Object**: Represents an offer (best offer/counter-offer) made on a fixed-price product. Tracks buyer, seller, amounts, currency, state transitions, counter-offers, and expiry. **`auctionOfferBid` Data Object**: Represents an individual bid placed on an auction-type product. Linked to product and user, tracks bid amount, currency, status (ACTIVE, WON, LOST, CANCELLED), and time placed. ## AuctionOffer Service Frontend Description By The Backend Architect ### auctionOffer Service UX Prompt - Provides backend bid/offer flows; surfaces only valid actions per product type and state. - Bids can be placed only on active AUCTION products not owned by the user, with validation for auction timing and minimum bid increments per product type. - Offers and counter-offers only eligible for FIXED products with acceptOffers enabled; UI must fetch product type/details before allowing offer flow. - All offer/bid actions automatically trigger downstream notification events; UI should be prepared for backend event-driven updates (bids outbid, offers accepted/declined, etc.). - For offers: strict status transitions—UI enforces only one possible action per party/state (pending offers can be accepted, declined, or countered by seller; buyer can only withdraw prior to response). - For counter-offers, navigate chain via counterOfferId. Show clear status/history/expiry for each user’s offers. - All APIs require authentication, show errors for forbidden actions. No direct notification/inbox UI exposed here—consume notification events to show relevant updates. ## API Structure ### Object Structure of a Successful Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client. **HTTP Status Codes:** * **200 OK**: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully. * **201 Created**: Returned for CREATE operations, indicating that the resource was created successfully. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling that the request executed successfully. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` * **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation. ### Additional Data Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature. ### Error Response If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity: * **400 Bad Request**: The request was improperly formatted or contained invalid parameters. * **401 Unauthorized**: The request lacked a valid authentication token; login is required. * **403 Forbidden**: The current token does not grant access to the requested resource. * **404 Not Found**: The requested resource was not found on the server. * **500 Internal Server Error**: The server encountered an unexpected condition. Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Bucket Management (This information is also given in PART 1 prompt.) This application has a bucket service used to store user files and other object-related files. The bucket service is login-agnostic, so for write operations or private reads, include a bucket token (provided by services) in the request’s Authorization header as a Bearer token. Please note that all other business services require the access token in the Bearer header, while the bucket service expects a bucket token because it is login-agnostic. Ensure you manage the required token injection properly; any auth interceptor should not replace the bucket token with the access token. **User Bucket** This bucket stores public user files for each user. When a user logs in—or in the `/currentuser` response—there is a `userBucketToken` to use when sending user-related public files to the bucket service. ```json { //... "userBucketToken": "e56d...." } ``` To upload a file `POST {baseUrl}/bucket/upload` The request body is form-data which includes the `bucketId` and the file binary in the `files` field. ```js { bucketId: "{userId}-public-user-bucket", files: {binary} } ``` Response status is 200 on success, e.g., body: ```json { "success": true, "data": [ { "fileId": "9da03f6d-0409-41ad-bb06-225a244ae408", "originalName": "test (10).png", "mimeType": "image/png", "size": 604063, "status": "uploaded", "bucketName": "f7103b85-fcda-4dec-92c6-c336f71fd3a2-public-user-bucket", "isPublic": true, "downloadUrl": "https://babilcom.mindbricks.co/bucket/download/9da03f6d-0409-41ad-bb06-225a244ae408" } ] } ``` To download a file from the bucket, you need its `fileId`. If you upload an avatar or other asset, ensure the download URL or the `fileId` is stored in the backend. Buckets are mostly used in object creations that require an additional file, such as a product image or user avatar. After uploading your image to the bucket, insert the returned download URL into the related property of the target object record. **Application Bucket** This Ebaycclone application also includes a common public bucket that anyone can read, but only users with the `superAdmin`, `admin`, or `saasAdmin` roles can write (upload) to it. When a user with one of these admin roles is logged in, the `/login` response or the `/currentuser` response also returns an `applicationBucketToken` field, which is used when uploading any file to the application bucket. ```json { //... "applicationBucketToken": "e23fd...." } ``` The common public application bucket ID is `"ebaycclone-public-common-bucket"` In certain admin areas—such as product management pages—since the user already has the application bucket token, they will be able to upload related object images. Please configure your UI to upload files to the application bucket using this bucket token whenever needed. **Object Buckets** Some objects may also return a bucket token for uploading or accessing files related to that object. For example, in a project management application, when you fetch a project’s data, a public or private bucket token may be provided to upload or download project-related files. These buckets will be used as described in the relevant object definitions. ## AuctionOfferOffer Data Object Represents an offer (best offer/counter-offer) made on a fixed-price product. Tracks buyer, seller, amounts, currency, state transitions, counter-offers, and expiry. ### AuctionOfferOffer Data Object Frontend Description By The Backend Architect One offer or counteroffer for a product. Displays offer amount, parties, messages, expiry, and current status. Allow accept, decline, or counter on eligible state. Only one open 'PENDING' per buyer/product. ### AuctionOfferOffer Data Object Properties AuctionOfferOffer data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Description | |----------|------|---------|----------|-------------| | `buyerId` | ID | false | Yes | Buyer making the offer. | | `currency` | String | false | Yes | ISO currency (e.g., USD, EUR) for the offer. | | `productId` | ID | false | Yes | Product the offer applies to (must be fixed-price, acceptOffers true). | | `counterOfferId` | ID | false | No | References another offer (counter-offer chain). | | `counterMessage` | String | false | No | Message accompanying seller's counter-offer (optional). | | `counterAmount` | Double | false | No | Counter-offer amount (when offer is COUNTERED). | | `offerAmount` | Double | false | Yes | Primary offer amount from buyer. | | `message` | String | false | No | Message/special notes from buyer (optional). | | `sellerId` | ID | false | Yes | Seller of the product (recipient of offer; auto-fetched from product). | | `status` | Enum | false | Yes | Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). | | `expiresAt` | Date | false | No | When this offer expires (optional). | | `respondedAt` | Date | false | No | When the seller (or buyer, for counter-offer) responded/updated the offer status. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options. - **status**: [PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED] ### Relation Properties `buyerId` `productId` `counterOfferId` `sellerId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **buyerId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **productId**: ID Relation to `productListingProduct`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **counterOfferId**: ID Relation to `auctionOfferOffer`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: No - **sellerId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes ### Filter Properties `buyerId` `currency` `productId` `offerAmount` `sellerId` `status` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **buyerId**: ID has a filter named `buyerId` - **currency**: String has a filter named `currency` - **productId**: ID has a filter named `productId` - **offerAmount**: Double has a filter named `offerAmount` - **sellerId**: ID has a filter named `sellerId` - **status**: Enum has a filter named `status` ## AuctionOfferBid Data Object Represents an individual bid placed on an auction-type product. Linked to product and user, tracks bid amount, currency, status (ACTIVE, WON, LOST, CANCELLED), and time placed. ### AuctionOfferBid Data Object Frontend Description By The Backend Architect A single bid on an auction product. Display bid amount, user, time placed, and status. UX should allow placing new bids only within valid auction window, show status (e.g. ACTIVE, WON/LOST). Soft-deleted/cancelled bids never shown in auction history. ### AuctionOfferBid Data Object Properties AuctionOfferBid data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Description | |----------|------|---------|----------|-------------| | `userId` | ID | false | Yes | User placing the bid. | | `bidAmount` | Double | false | Yes | Bid amount placed by the user. | | `placedAt` | Date | false | No | When the bid was placed. | | `currency` | String | false | Yes | ISO currency for the bid (e.g., USD, EUR). | | `status` | Enum | false | Yes | Bid status: ACTIVE, WON, LOST, CANCELLED. | | `productId` | ID | false | Yes | Product being bid on (must be AUCTION type). | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options. - **status**: [ACTIVE, WON, LOST, CANCELLED] ### Relation Properties `userId` `productId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **userId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **productId**: ID Relation to `productListingProduct`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes ### Filter Properties `userId` `bidAmount` `currency` `status` `productId` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **userId**: ID has a filter named `userId` - **bidAmount**: Double has a filter named `bidAmount` - **currency**: String has a filter named `currency` - **status**: Enum has a filter named `status` - **productId**: ID has a filter named `productId` ## API Reference ### `Update Auctionofferoffer` API Updates offer: accepts/declines/counters by seller, withdraws by buyer before response. Enforces status transition rules, sets respondedAt. Triggers event. **Rest Route** The `updateAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `updateAuctionOfferOffer` api has got 8 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | message | String | false | request.body?.message | | status | Enum | false | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | **auctionOfferOfferId** : This id paremeter is used to select the required data object that will be updated **counterOfferId** : References another offer (counter-offer chain). **counterMessage** : Message accompanying seller's counter-offer (optional). **counterAmount** : Counter-offer amount (when offer is COUNTERED). **message** : Message/special notes from buyer (optional). **status** : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). **expiresAt** : When this offer expires (optional). **respondedAt** : When the seller (or buyer, for counter-offer) responded/updated the offer status. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Auctionofferbid` API Creates a new bid for an auction product. Validates auction status, not seller, product type, bid window, and ensures min. increment. Updates product.currentBid and product.highestBidderId atomically. Triggers notification event. **Rest Route** The `createAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids` **Rest Request Parameters** The `createAuctionOfferBid` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | bidAmount | Double | true | request.body?.bidAmount | | currency | String | true | request.body?.currency | | status | Enum | true | request.body?.status | | productId | ID | true | request.body?.productId | **bidAmount** : Bid amount placed by the user. **currency** : ISO currency for the bid (e.g., USD, EUR). **status** : Bid status: ACTIVE, WON, LOST, CANCELLED. **productId** : Product being bid on (must be AUCTION type). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/auctionofferbids** ```js axios({ method: 'POST', url: '/v1/auctionofferbids', data: { bidAmount:"Double", currency:"String", status:"Enum", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Auctionofferbid` API Gets a single bid (only visible to owner/admin or for auction history). **Rest Route** The `getAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `getAuctionOfferBid` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | **auctionOfferBidId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'GET', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Auctionofferoffer` API Gets a single offer (shown to buyer/seller or admin). **Rest Route** The `getAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `getAuctionOfferOffer` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | **auctionOfferOfferId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'GET', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Auctionofferoffers` API Lists offers by product, user, status, or counterOffer chain. **Rest Route** The `listAuctionOfferOffers` API REST controller can be triggered via the following route: `/v1/auctionofferoffers` **Rest Request Parameters** The `listAuctionOfferOffers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers** ```js axios({ method: 'GET', url: '/v1/auctionofferoffers', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferOffers": [ { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Auctionofferbid` API Updates a bid’s status (allow only status update, e.g. CANCELLED, WIN/LOSE on admin settlement). Only owner/admin, and only if auction not ended or not settled. Triggers notification event. **Rest Route** The `updateAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `updateAuctionOfferBid` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | | status | Enum | false | request.body?.status | **auctionOfferBidId** : This id paremeter is used to select the required data object that will be updated **status** : Bid status: ACTIVE, WON, LOST, CANCELLED. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { status:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Auctionofferoffer` API Creates a new offer for a fixed-price product, validating acceptOffers, type, eligibility, and product/seller/buyer active. Defaults to PENDING state. Triggers notification event. **Rest Route** The `createAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers` **Rest Request Parameters** The `createAuctionOfferOffer` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | productId | ID | true | request.body?.productId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | offerAmount | Double | true | request.body?.offerAmount | | message | String | false | request.body?.message | | status | Enum | true | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | **currency** : ISO currency (e.g., USD, EUR) for the offer. **productId** : Product the offer applies to (must be fixed-price, acceptOffers true). **counterOfferId** : References another offer (counter-offer chain). **counterMessage** : Message accompanying seller's counter-offer (optional). **counterAmount** : Counter-offer amount (when offer is COUNTERED). **offerAmount** : Primary offer amount from buyer. **message** : Message/special notes from buyer (optional). **status** : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). **expiresAt** : When this offer expires (optional). **respondedAt** : When the seller (or buyer, for counter-offer) responded/updated the offer status. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/auctionofferoffers** ```js axios({ method: 'POST', url: '/v1/auctionofferoffers', data: { currency:"String", productId:"ID", counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", offerAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Auctionofferbids` API Lists bids by product, user, or auction, supports history/analytics. **Rest Route** The `listAuctionOfferBids` API REST controller can be triggered via the following route: `/v1/auctionofferbids` **Rest Request Parameters** The `listAuctionOfferBids` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids** ```js axios({ method: 'GET', url: '/v1/auctionofferbids', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBids", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferBids": [ { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Auctionofferbid` API Soft-deletes a bid (for admin or self before auction ends). **Rest Route** The `deleteAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `deleteAuctionOfferBid` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | **auctionOfferBidId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Auctionofferoffer` API Soft-deletes an offer (allowed only in non-accepted/expired state). **Rest Route** The `deleteAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `deleteAuctionOfferOffer` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | **auctionOfferOfferId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` **After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.** # **EBAYCCLONE** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 6 - CategoryManagement Service** This document is a part of a REST API guide for the ebaycclone project. It is designed for AI agents that will generate frontend code to consume the project’s backend. This document provides extensive instruction for the usage of categoryManagement ## Service Access CategoryManagement service management is handled through service specific base urls. CategoryManagement service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.). For the categoryManagement service, the base URLs are: * **Preview:** `https://ebaycclone.prw.mindbricks.com/categorymanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/categorymanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/categorymanagement-api` ## Scope **CategoryManagement Service Description** Handles product categories and subcategories for marketplace browsing and classification, supporting public discovery plus admin-only management. CategoryManagement service provides apis and business logic for following data objects in ebaycclone application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows. **`category` Data Object**: Represents a product category in the marketplace (e.g., Electronics, Clothing, Toys), used for browsing, filtering, and discovery. Admins manage categories. **`subcategory` Data Object**: Represents a subcategory within a parent category (e.g., 'Smartphones' under 'Electronics'). Used for more granular product discovery and navigation. 'group' categorizes special display logic. ## CategoryManagement Service Frontend Description By The Backend Architect This service provides APIs for frontend public discovery and filtering of product categories and subcategories (including 'MOST_POPULAR' status for special sections), with soft-deleted records always hidden. Normal users only browse (read), while admins may create, update, or delete categories/subcategories. Subcategory 'group' field maps to enums for UX grouping/tabs in filters and landing sections. ## API Structure ### Object Structure of a Successful Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client. **HTTP Status Codes:** * **200 OK**: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully. * **201 Created**: Returned for CREATE operations, indicating that the resource was created successfully. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling that the request executed successfully. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` * **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation. ### Additional Data Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature. ### Error Response If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity: * **400 Bad Request**: The request was improperly formatted or contained invalid parameters. * **401 Unauthorized**: The request lacked a valid authentication token; login is required. * **403 Forbidden**: The current token does not grant access to the requested resource. * **404 Not Found**: The requested resource was not found on the server. * **500 Internal Server Error**: The server encountered an unexpected condition. Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Bucket Management (This information is also given in PART 1 prompt.) This application has a bucket service used to store user files and other object-related files. The bucket service is login-agnostic, so for write operations or private reads, include a bucket token (provided by services) in the request’s Authorization header as a Bearer token. Please note that all other business services require the access token in the Bearer header, while the bucket service expects a bucket token because it is login-agnostic. Ensure you manage the required token injection properly; any auth interceptor should not replace the bucket token with the access token. **User Bucket** This bucket stores public user files for each user. When a user logs in—or in the `/currentuser` response—there is a `userBucketToken` to use when sending user-related public files to the bucket service. ```json { //... "userBucketToken": "e56d...." } ``` To upload a file `POST {baseUrl}/bucket/upload` The request body is form-data which includes the `bucketId` and the file binary in the `files` field. ```js { bucketId: "{userId}-public-user-bucket", files: {binary} } ``` Response status is 200 on success, e.g., body: ```json { "success": true, "data": [ { "fileId": "9da03f6d-0409-41ad-bb06-225a244ae408", "originalName": "test (10).png", "mimeType": "image/png", "size": 604063, "status": "uploaded", "bucketName": "f7103b85-fcda-4dec-92c6-c336f71fd3a2-public-user-bucket", "isPublic": true, "downloadUrl": "https://babilcom.mindbricks.co/bucket/download/9da03f6d-0409-41ad-bb06-225a244ae408" } ] } ``` To download a file from the bucket, you need its `fileId`. If you upload an avatar or other asset, ensure the download URL or the `fileId` is stored in the backend. Buckets are mostly used in object creations that require an additional file, such as a product image or user avatar. After uploading your image to the bucket, insert the returned download URL into the related property of the target object record. **Application Bucket** This Ebaycclone application also includes a common public bucket that anyone can read, but only users with the `superAdmin`, `admin`, or `saasAdmin` roles can write (upload) to it. When a user with one of these admin roles is logged in, the `/login` response or the `/currentuser` response also returns an `applicationBucketToken` field, which is used when uploading any file to the application bucket. ```json { //... "applicationBucketToken": "e23fd...." } ``` The common public application bucket ID is `"ebaycclone-public-common-bucket"` In certain admin areas—such as product management pages—since the user already has the application bucket token, they will be able to upload related object images. Please configure your UI to upload files to the application bucket using this bucket token whenever needed. **Object Buckets** Some objects may also return a bucket token for uploading or accessing files related to that object. For example, in a project management application, when you fetch a project’s data, a public or private bucket token may be provided to upload or download project-related files. These buckets will be used as described in the relevant object definitions. ## Category Data Object Represents a product category in the marketplace (e.g., Electronics, Clothing, Toys), used for browsing, filtering, and discovery. Admins manage categories. ### Category Data Object Frontend Description By The Backend Architect Public categories are displayed as top-level navigation and landing page filters. Each category includes a title, subtitle, and optionally an image (URL). Only active categories appear in listings; admins create/edit/remove categories. ### Category Data Object Properties Category data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Description | |----------|------|---------|----------|-------------| | `imageUrl` | String | false | No | URL for category image/avatar (optional, used for homepage visuals). | | `subtitle` | String | false | No | Optional short description for UI/tooltips. | | `title` | String | false | Yes | Display name of the category. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Filter Properties `title` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **title**: String has a filter named `title` ## Subcategory Data Object Represents a subcategory within a parent category (e.g., 'Smartphones' under 'Electronics'). Used for more granular product discovery and navigation. 'group' categorizes special display logic. ### Subcategory Data Object Frontend Description By The Backend Architect Subcategories are displayed as filters/tabs within categories. Most-popular subcategories can be shown in special sections/tabs depending on their 'group' enum. Only active subcategories are visible to public; admins may manage all. ### Subcategory Data Object Properties Subcategory data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Description | |----------|------|---------|----------|-------------| | `categoryId` | ID | false | Yes | Reference to the parent category (category.id). | | `name` | String | false | Yes | Display name of the subcategory. | | `group` | Enum | false | Yes | Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options. - **group**: [MOST_POPULAR, MORE] ### Relation Properties `categoryId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **categoryId**: ID Relation to `category`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes ### Filter Properties `categoryId` `name` `group` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **categoryId**: ID has a filter named `categoryId` - **name**: String has a filter named `name` - **group**: Enum has a filter named `group` ## API Reference ### `Delete Category` API Soft-delete a category (admin-only). **Rest Route** The `deleteCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `deleteCategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | **categoryId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/categories/:categoryId** ```js axios({ method: 'DELETE', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Subcategory` API Get a subcategory by ID. Public - only active subcategories returned except for admin. **Rest Route** The `getSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `getSubcategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | **subcategoryId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/subcategories/:subcategoryId** ```js axios({ method: 'GET', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Category` API Get a single category by ID. Public - only active categories returned (for non-admins). **Rest Route** The `getCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `getCategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | **categoryId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/categories/:categoryId** ```js axios({ method: 'GET', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Subcategory` API Update subcategory (admin-only), including group enum change. **Rest Route** The `updateSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `updateSubcategory` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | name | String | false | request.body?.name | | group | Enum | false | request.body?.group | **subcategoryId** : This id paremeter is used to select the required data object that will be updated **categoryId** : Reference to the parent category (category.id). **name** : Display name of the subcategory. **group** : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/subcategories/:subcategoryId** ```js axios({ method: 'PATCH', url: `/v1/subcategories/${subcategoryId}`, data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Subcategories` API List all subcategories for browsing/filtering, with support for group enum and parent category queries. Only active subcategories shown to public/non-admin users. **Rest Route** The `listSubcategories` API REST controller can be triggered via the following route: `/v1/subcategories` **Rest Request Parameters** The `listSubcategories` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/subcategories** ```js axios({ method: 'GET', url: '/v1/subcategories', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "subcategories": [ { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Subcategory` API Soft-delete a subcategory (admin-only). **Rest Route** The `deleteSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `deleteSubcategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | **subcategoryId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/subcategories/:subcategoryId** ```js axios({ method: 'DELETE', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Categories` API List all categories for browsing and filtering. Only active categories shown to public/non-admin users. **Rest Route** The `listCategories` API REST controller can be triggered via the following route: `/v1/categories` **Rest Request Parameters** The `listCategories` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/categories** ```js axios({ method: 'GET', url: '/v1/categories', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "categories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "categories": [ { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Category` API Update category details (admin-only). **Rest Route** The `updateCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `updateCategory` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | false | request.body?.title | **categoryId** : This id paremeter is used to select the required data object that will be updated **imageUrl** : URL for category image/avatar (optional, used for homepage visuals). **subtitle** : Optional short description for UI/tooltips. **title** : Display name of the category. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/categories/:categoryId** ```js axios({ method: 'PATCH', url: `/v1/categories/${categoryId}`, data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Subcategory` API Create a new subcategory under a given category (admin-only), with enum group constraint. **Rest Route** The `createSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories` **Rest Request Parameters** The `createSubcategory` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.body?.categoryId | | name | String | true | request.body?.name | | group | Enum | true | request.body?.group | **categoryId** : Reference to the parent category (category.id). **name** : Display name of the subcategory. **group** : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/subcategories** ```js axios({ method: 'POST', url: '/v1/subcategories', data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Category` API Create a new category (admin-only) for product classification. **Rest Route** The `createCategory` API REST controller can be triggered via the following route: `/v1/categories` **Rest Request Parameters** The `createCategory` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | true | request.body?.title | **imageUrl** : URL for category image/avatar (optional, used for homepage visuals). **subtitle** : Optional short description for UI/tooltips. **title** : Display name of the category. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/categories** ```js axios({ method: 'POST', url: '/v1/categories', data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` **After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.** # **EBAYCCLONE** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 7 - Messaging Service** This document is a part of a REST API guide for the ebaycclone project. It is designed for AI agents that will generate frontend code to consume the project’s backend. This document provides extensive instruction for the usage of messaging ## Service Access Messaging service management is handled through service specific base urls. Messaging service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.). For the messaging service, the base URLs are: * **Preview:** `https://ebaycclone.prw.mindbricks.com/messaging-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/messaging-api` * **Production:** `https://ebaycclone.mindbricks.co/messaging-api` ## Scope **Messaging Service Description** In-app messaging service for direct user-to-user text messages (buyers/sellers). Stores, retrieves, and manages user conversations. Launch version: text-only. Messaging service provides apis and business logic for following data objects in ebaycclone application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows. **`messagingMessage` Data Object**: A direct, text-only in-app message between two users (buyer/seller); stores sender, recipient, content, read status, and timestamp. ## Messaging Service Frontend Description By The Backend Architect # Messaging Service (Frontend Guidance) - Supports private buyer/seller text messaging only—no attachments at launch. - Each message is between two users (sender/recipient), not group chats. - Users can view full conversation threads they participate in (sorted by time). - Messages are soft-deletable. 'Deleted' means user can no longer access message; the other party still can if not deleted on their side. - UI should distinguish sent vs. received messages and allow marking as read/unread. - Unread counts can be displayed per conversation. - Editing messages is not supported in MVP. - Conversation page composed by filtering all messages between logged-in user and chosen counterpart. - Sender/recipient fullName/avatar can be fetched from user profile for each message (frontend should join with user API as needed or via BFF). - For launch: text only. UI should not allow image/file upload yet. ## API Structure ### Object Structure of a Successful Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client. **HTTP Status Codes:** * **200 OK**: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully. * **201 Created**: Returned for CREATE operations, indicating that the resource was created successfully. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling that the request executed successfully. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` * **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation. ### Additional Data Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature. ### Error Response If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity: * **400 Bad Request**: The request was improperly formatted or contained invalid parameters. * **401 Unauthorized**: The request lacked a valid authentication token; login is required. * **403 Forbidden**: The current token does not grant access to the requested resource. * **404 Not Found**: The requested resource was not found on the server. * **500 Internal Server Error**: The server encountered an unexpected condition. Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Bucket Management (This information is also given in PART 1 prompt.) This application has a bucket service used to store user files and other object-related files. The bucket service is login-agnostic, so for write operations or private reads, include a bucket token (provided by services) in the request’s Authorization header as a Bearer token. Please note that all other business services require the access token in the Bearer header, while the bucket service expects a bucket token because it is login-agnostic. Ensure you manage the required token injection properly; any auth interceptor should not replace the bucket token with the access token. **User Bucket** This bucket stores public user files for each user. When a user logs in—or in the `/currentuser` response—there is a `userBucketToken` to use when sending user-related public files to the bucket service. ```json { //... "userBucketToken": "e56d...." } ``` To upload a file `POST {baseUrl}/bucket/upload` The request body is form-data which includes the `bucketId` and the file binary in the `files` field. ```js { bucketId: "{userId}-public-user-bucket", files: {binary} } ``` Response status is 200 on success, e.g., body: ```json { "success": true, "data": [ { "fileId": "9da03f6d-0409-41ad-bb06-225a244ae408", "originalName": "test (10).png", "mimeType": "image/png", "size": 604063, "status": "uploaded", "bucketName": "f7103b85-fcda-4dec-92c6-c336f71fd3a2-public-user-bucket", "isPublic": true, "downloadUrl": "https://babilcom.mindbricks.co/bucket/download/9da03f6d-0409-41ad-bb06-225a244ae408" } ] } ``` To download a file from the bucket, you need its `fileId`. If you upload an avatar or other asset, ensure the download URL or the `fileId` is stored in the backend. Buckets are mostly used in object creations that require an additional file, such as a product image or user avatar. After uploading your image to the bucket, insert the returned download URL into the related property of the target object record. **Application Bucket** This Ebaycclone application also includes a common public bucket that anyone can read, but only users with the `superAdmin`, `admin`, or `saasAdmin` roles can write (upload) to it. When a user with one of these admin roles is logged in, the `/login` response or the `/currentuser` response also returns an `applicationBucketToken` field, which is used when uploading any file to the application bucket. ```json { //... "applicationBucketToken": "e23fd...." } ``` The common public application bucket ID is `"ebaycclone-public-common-bucket"` In certain admin areas—such as product management pages—since the user already has the application bucket token, they will be able to upload related object images. Please configure your UI to upload files to the application bucket using this bucket token whenever needed. **Object Buckets** Some objects may also return a bucket token for uploading or accessing files related to that object. For example, in a project management application, when you fetch a project’s data, a public or private bucket token may be provided to upload or download project-related files. These buckets will be used as described in the relevant object definitions. ## MessagingMessage Data Object A direct, text-only in-app message between two users (buyer/seller); stores sender, recipient, content, read status, and timestamp. ### MessagingMessage Data Object Frontend Description By The Backend Architect - Single private message entity joining sender and recipient by user IDs. - Text-only content; file/attachment fields are not present at launch. - Timestamped at send time. - isRead is for recipient's in-app unread status display. - Messages are not editable after sending; only isRead and deletion are updatable. - Soft-delete: Only sender or recipient sees own deleted messages as removed; other party still can see unless deleted by both. ### MessagingMessage Data Object Properties MessagingMessage data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Description | |----------|------|---------|----------|-------------| | `fromUserId` | ID | false | Yes | Sender (user) of this message. | | `toUserId` | ID | false | Yes | Recipient (user) of this message. | | `content` | String | false | Yes | Text content of the message. No files or attachments for launch. | | `isRead` | Boolean | false | Yes | If true, recipient has marked this message as read. | | `sentAt` | Date | false | No | Time the message was sent. If not set, will be createdAt. Used for ordering. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Relation Properties `fromUserId` `toUserId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **fromUserId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes - **toUserId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes ### Filter Properties `fromUserId` `toUserId` `isRead` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **fromUserId**: ID has a filter named `fromUserId` - **toUserId**: ID has a filter named `toUserId` - **isRead**: Boolean has a filter named `isRead` ## API Reference ### `List Messagingmessages` API List all messages in the conversation between the logged-in user and another party, ordered by sentAt descending. Can filter unread with isRead. Returns only messages visible to user (isActive). **Rest Route** The `listMessagingMessages` API REST controller can be triggered via the following route: `/v1/messagingmessages` **Rest Request Parameters** The `listMessagingMessages` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages** ```js axios({ method: 'GET', url: '/v1/messagingmessages', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessages", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "messagingMessages": [ { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Messagingmessage` API Send a new text message from the logged-in user to a recipient. Sender is set from session. Launch version supports only text content. **Rest Route** The `createMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages` **Rest Request Parameters** The `createMessagingMessage` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | toUserId | ID | true | request.body?.toUserId | | content | String | true | request.body?.content | | isRead | Boolean | true | request.body?.isRead | **toUserId** : Recipient (user) of this message. **content** : Text content of the message. No files or attachments for launch. **isRead** : If true, recipient has marked this message as read. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/messagingmessages** ```js axios({ method: 'POST', url: '/v1/messagingmessages', data: { toUserId:"ID", content:"String", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Messagingmessage` API Update a message (mark as read/unread). Only the recipient or admin can change isRead. No content edits. Sender, content, sentAt are immutable. **Rest Route** The `updateMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `updateMessagingMessage` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | | isRead | Boolean | false | request.body?.isRead | **messagingMessageId** : This id paremeter is used to select the required data object that will be updated **isRead** : If true, recipient has marked this message as read. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'PATCH', url: `/v1/messagingmessages/${messagingMessageId}`, data: { isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Messagingmessage` API Get a message by ID. Only accessible to the sender, the recipient, or an admin. Used for message detail view or reading a single message in a thread. **Rest Route** The `getMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `getMessagingMessage` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | **messagingMessageId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'GET', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Messagingmessage` API Delete a message (soft-delete). Only sender, recipient, or admin may delete a message. Deletion only hides it for the user; not a full erase unless both delete. **Rest Route** The `deleteMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `deleteMessagingMessage` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | **messagingMessageId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'DELETE', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` **After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.** # **EBAYCCLONE** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 8 - NotificationManagement Service** This document is a part of a REST API guide for the ebaycclone project. It is designed for AI agents that will generate frontend code to consume the project’s backend. This document provides extensive instruction for the usage of notificationManagement ## Service Access NotificationManagement service management is handled through service specific base urls. NotificationManagement service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.). For the notificationManagement service, the base URLs are: * **Preview:** `https://ebaycclone.prw.mindbricks.com/notificationmanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/notificationmanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/notificationmanagement-api` ## Scope **NotificationManagement Service Description** Handles storage, management, and event-driven delivery of in-app and email notifications for user-impacting system events (bids, offers, orders, feedback, messaging, etc.). Supports marking notifications as read/unread, structured filtering by event type/channel, and always returns in-app notifications ordered by recency. NotificationManagement service provides apis and business logic for following data objects in ebaycclone application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows. **`notification` Data Object**: Stores and manages in-app and email notifications tied to user-facing events like bids, offers, orders, messaging, shipment, and feedback. Includes event type (notificationType) for filter/search, arbitrary event payload, and delivery channel. Soft-delete enforced. In-app notifications always sorted by createdAt DESC on retrieval. ## NotificationManagement Service Frontend Description By The Backend Architect AI PROMPT — NOTIFICATION UX: - Always present in-app notifications to the user in descending createdAt order (newest first). - Show notificationType as the primary discriminator for icons/titles; group by unread/read states. - For channel == IN_APP, support real-time badge/bubble for isRead==false. For EMAIL, always treat notifications as isRead == true. - Use payload fields dynamically per notificationType for event contextual details. - Support inline filtering (notificationType, isRead) and batch mark-as-read. Badge/unread count should reflect only IN_APP/unread. - Clicking a notification marks it as read (unless already isRead). ## API Structure ### Object Structure of a Successful Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client. **HTTP Status Codes:** * **200 OK**: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully. * **201 Created**: Returned for CREATE operations, indicating that the resource was created successfully. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling that the request executed successfully. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` * **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation. ### Additional Data Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature. ### Error Response If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity: * **400 Bad Request**: The request was improperly formatted or contained invalid parameters. * **401 Unauthorized**: The request lacked a valid authentication token; login is required. * **403 Forbidden**: The current token does not grant access to the requested resource. * **404 Not Found**: The requested resource was not found on the server. * **500 Internal Server Error**: The server encountered an unexpected condition. Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Bucket Management (This information is also given in PART 1 prompt.) This application has a bucket service used to store user files and other object-related files. The bucket service is login-agnostic, so for write operations or private reads, include a bucket token (provided by services) in the request’s Authorization header as a Bearer token. Please note that all other business services require the access token in the Bearer header, while the bucket service expects a bucket token because it is login-agnostic. Ensure you manage the required token injection properly; any auth interceptor should not replace the bucket token with the access token. **User Bucket** This bucket stores public user files for each user. When a user logs in—or in the `/currentuser` response—there is a `userBucketToken` to use when sending user-related public files to the bucket service. ```json { //... "userBucketToken": "e56d...." } ``` To upload a file `POST {baseUrl}/bucket/upload` The request body is form-data which includes the `bucketId` and the file binary in the `files` field. ```js { bucketId: "{userId}-public-user-bucket", files: {binary} } ``` Response status is 200 on success, e.g., body: ```json { "success": true, "data": [ { "fileId": "9da03f6d-0409-41ad-bb06-225a244ae408", "originalName": "test (10).png", "mimeType": "image/png", "size": 604063, "status": "uploaded", "bucketName": "f7103b85-fcda-4dec-92c6-c336f71fd3a2-public-user-bucket", "isPublic": true, "downloadUrl": "https://babilcom.mindbricks.co/bucket/download/9da03f6d-0409-41ad-bb06-225a244ae408" } ] } ``` To download a file from the bucket, you need its `fileId`. If you upload an avatar or other asset, ensure the download URL or the `fileId` is stored in the backend. Buckets are mostly used in object creations that require an additional file, such as a product image or user avatar. After uploading your image to the bucket, insert the returned download URL into the related property of the target object record. **Application Bucket** This Ebaycclone application also includes a common public bucket that anyone can read, but only users with the `superAdmin`, `admin`, or `saasAdmin` roles can write (upload) to it. When a user with one of these admin roles is logged in, the `/login` response or the `/currentuser` response also returns an `applicationBucketToken` field, which is used when uploading any file to the application bucket. ```json { //... "applicationBucketToken": "e23fd...." } ``` The common public application bucket ID is `"ebaycclone-public-common-bucket"` In certain admin areas—such as product management pages—since the user already has the application bucket token, they will be able to upload related object images. Please configure your UI to upload files to the application bucket using this bucket token whenever needed. **Object Buckets** Some objects may also return a bucket token for uploading or accessing files related to that object. For example, in a project management application, when you fetch a project’s data, a public or private bucket token may be provided to upload or download project-related files. These buckets will be used as described in the relevant object definitions. ## Notification Data Object Stores and manages in-app and email notifications tied to user-facing events like bids, offers, orders, messaging, shipment, and feedback. Includes event type (notificationType) for filter/search, arbitrary event payload, and delivery channel. Soft-delete enforced. In-app notifications always sorted by createdAt DESC on retrieval. ### Notification Data Object Frontend Description By The Backend Architect AI PROMPT — NOTIFICATION DATA OBJECT: - Show notification type using a friendly label/icon corresponding to notificationType field. - Render object-specific fields (payload) in notification card per notificationType. - Mark as read/unread on tap/click, with visual cue (badge, shading, etc.). Only user specified by userId or admins can see or update/read the notification. - Filter options: notificationType (enum), isRead (boolean), channel (enum), all exposed for user management and badge counts. ### Notification Data Object Properties Notification data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Description | |----------|------|---------|----------|-------------| | `notificationType` | Enum | false | Yes | Type of event triggering notification (e.g., BID_UPDATED, ORDER_SHIPPED, MESSAGE_RECEIVED, etc.). Used for display/icon and query filter. | | `userId` | ID | false | Yes | User receiving the notification (recipient). | | `channel` | Enum | false | Yes | Channel by which notification is delivered: IN_APP or EMAIL. | | `payload` | Object | false | Yes | Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. | | `isRead` | Boolean | false | Yes | Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options. - **notificationType**: [BID_UPDATED, BID_OUTBID, BID_WON, OFFER_PLACED, OFFER_ACCEPTED, OFFER_DECLINED, OFFER_COUNTERED, ORDER_PLACED, ORDER_PAID, ORDER_SHIPPED, ORDER_DELIVERED, ORDER_CANCELLED, FEEDBACK_RECEIVED, FEEDBACK_REQUESTED, MESSAGE_RECEIVED, MESSAGE_SENT, SYSTEM_ALERT] - **channel**: [IN_APP, EMAIL] ### Relation Properties `userId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one. In frontend, please ensure that, 1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field. - **userId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. Required: Yes ### Filter Properties `notificationType` `userId` `channel` `isRead` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **notificationType**: Enum has a filter named `notificationType` - **userId**: ID has a filter named `userId` - **channel**: Enum has a filter named `channel` - **isRead**: Boolean has a filter named `isRead` ## API Reference ### `Create Notification` API Creates a notification entry in response to a system/business event. Only allowed for system/event processes and admins (not standard user/action). Typically event-driven, receives userId, notificationType, payload, and channel. **Rest Route** The `createNotification` API REST controller can be triggered via the following route: `/v1/notifications` **Rest Request Parameters** The `createNotification` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationType | Enum | true | request.body?.notificationType | | userId | ID | true | request.body?.userId | | channel | Enum | true | request.body?.channel | | payload | Object | true | request.body?.payload | | isRead | Boolean | true | request.body?.isRead | **notificationType** : Type of event triggering notification (e.g., BID_UPDATED, ORDER_SHIPPED, MESSAGE_RECEIVED, etc.). Used for display/icon and query filter. **userId** : User receiving the notification (recipient). **channel** : Channel by which notification is delivered: IN_APP or EMAIL. **payload** : Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. **isRead** : Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/notifications** ```js axios({ method: 'POST', url: '/v1/notifications', data: { notificationType:"Enum", userId:"ID", channel:"Enum", payload:"Object", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Notification` API Updates a notification (mark as read/unread, payload patch for e.g. admin fix). Only receiver (userId) or admins may update. isRead is primary update scenario; others very limited. **Rest Route** The `updateNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `updateNotification` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | | payload | Object | false | request.body?.payload | | isRead | Boolean | false | request.body?.isRead | **notificationId** : This id paremeter is used to select the required data object that will be updated **payload** : Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. **isRead** : Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/notifications/:notificationId** ```js axios({ method: 'PATCH', url: `/v1/notifications/${notificationId}`, data: { payload:"Object", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Notifications` API Returns filtered list of notifications for a user, with optional filters: notificationType, isRead, channel. Always sorted by createdAt (descending) for in-app notifications. Only retrieval allowed for owner/admin. **Rest Route** The `listNotifications` API REST controller can be triggered via the following route: `/v1/notifications` **Rest Request Parameters** The `listNotifications` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/notifications** ```js axios({ method: 'GET', url: '/v1/notifications', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notifications", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "notifications": [ { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Notification` API Soft-delete a notification record. Only receiver or admin may delete. **Rest Route** The `deleteNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `deleteNotification` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | **notificationId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/notifications/:notificationId** ```js axios({ method: 'DELETE', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Notification` API Retrieves a notification for the receiver or admin. Used to populate content on detail/expanded view. **Rest Route** The `getNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `getNotification` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | **notificationId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/notifications/:notificationId** ```js axios({ method: 'GET', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` **After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.** # **EBAYCCLONE** **FRONTEND GUIDE FOR AI CODING AGENTS - PART 9 - SearchIndexing Service** This document is a part of a REST API guide for the ebaycclone project. It is designed for AI agents that will generate frontend code to consume the project’s backend. This document provides extensive instruction for the usage of searchIndexing ## Service Access SearchIndexing service management is handled through service specific base urls. SearchIndexing service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.). For the searchIndexing service, the base URLs are: * **Preview:** `https://ebaycclone.prw.mindbricks.com/searchindexing-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/searchindexing-api` * **Production:** `https://ebaycclone.mindbricks.co/searchindexing-api` ## Scope **SearchIndexing Service Description** Maintains the denormalized search index (materialized view) for global, public search across products, sellers, categories, and subcategories. Handles indexing in response to entity events and exposes optimized query endpoints for BFF/aggregator. SearchIndexing service provides apis and business logic for following data objects in ebaycclone application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows. **`searchIndex` Data Object**: Materialized/denormalized search index record for a marketplace entity (product, seller, category, subcategory). Used exclusively for high-speed querying in BFF global/public search. ## SearchIndexing Service Frontend Description By The Backend Architect # SearchIndexing Service UX Notes - This is an internal service; there is no direct frontend. All query/search UX is handled through BFF by reading from here. - Data is always denormalized (copy of product/seller/category/subcategory), so cache can be safely used. - If search returns fewer items than expected or appears stale, an admin may trigger a forced 'rebuild' via backend tools (not user-triggerable). ## API Structure ### Object Structure of a Successful Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client. **HTTP Status Codes:** * **200 OK**: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully. * **201 Created**: Returned for CREATE operations, indicating that the resource was created successfully. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling that the request executed successfully. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` * **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation. ### Additional Data Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature. ### Error Response If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity: * **400 Bad Request**: The request was improperly formatted or contained invalid parameters. * **401 Unauthorized**: The request lacked a valid authentication token; login is required. * **403 Forbidden**: The current token does not grant access to the requested resource. * **404 Not Found**: The requested resource was not found on the server. * **500 Internal Server Error**: The server encountered an unexpected condition. Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Bucket Management (This information is also given in PART 1 prompt.) This application has a bucket service used to store user files and other object-related files. The bucket service is login-agnostic, so for write operations or private reads, include a bucket token (provided by services) in the request’s Authorization header as a Bearer token. Please note that all other business services require the access token in the Bearer header, while the bucket service expects a bucket token because it is login-agnostic. Ensure you manage the required token injection properly; any auth interceptor should not replace the bucket token with the access token. **User Bucket** This bucket stores public user files for each user. When a user logs in—or in the `/currentuser` response—there is a `userBucketToken` to use when sending user-related public files to the bucket service. ```json { //... "userBucketToken": "e56d...." } ``` To upload a file `POST {baseUrl}/bucket/upload` The request body is form-data which includes the `bucketId` and the file binary in the `files` field. ```js { bucketId: "{userId}-public-user-bucket", files: {binary} } ``` Response status is 200 on success, e.g., body: ```json { "success": true, "data": [ { "fileId": "9da03f6d-0409-41ad-bb06-225a244ae408", "originalName": "test (10).png", "mimeType": "image/png", "size": 604063, "status": "uploaded", "bucketName": "f7103b85-fcda-4dec-92c6-c336f71fd3a2-public-user-bucket", "isPublic": true, "downloadUrl": "https://babilcom.mindbricks.co/bucket/download/9da03f6d-0409-41ad-bb06-225a244ae408" } ] } ``` To download a file from the bucket, you need its `fileId`. If you upload an avatar or other asset, ensure the download URL or the `fileId` is stored in the backend. Buckets are mostly used in object creations that require an additional file, such as a product image or user avatar. After uploading your image to the bucket, insert the returned download URL into the related property of the target object record. **Application Bucket** This Ebaycclone application also includes a common public bucket that anyone can read, but only users with the `superAdmin`, `admin`, or `saasAdmin` roles can write (upload) to it. When a user with one of these admin roles is logged in, the `/login` response or the `/currentuser` response also returns an `applicationBucketToken` field, which is used when uploading any file to the application bucket. ```json { //... "applicationBucketToken": "e23fd...." } ``` The common public application bucket ID is `"ebaycclone-public-common-bucket"` In certain admin areas—such as product management pages—since the user already has the application bucket token, they will be able to upload related object images. Please configure your UI to upload files to the application bucket using this bucket token whenever needed. **Object Buckets** Some objects may also return a bucket token for uploading or accessing files related to that object. For example, in a project management application, when you fetch a project’s data, a public or private bucket token may be provided to upload or download project-related files. These buckets will be used as described in the relevant object definitions. ## SearchIndex Data Object Materialized/denormalized search index record for a marketplace entity (product, seller, category, subcategory). Used exclusively for high-speed querying in BFF global/public search. ### SearchIndex Data Object Frontend Description By The Backend Architect - Not user visible: purely backend/infra. - Fields mirror original entity for search; must be promptly updated/deleted with entity changes. - If searching returns incomplete/stale results, ask admin to trigger a reindex operation. ### SearchIndex Data Object Properties SearchIndex data object has got following properties that are represented as table fields in the database scheme. These properties don't stand just for data storage, but each may have different settings to manage the business logic. | Property | Type | IsArray | Required | Description | |----------|------|---------|----------|-------------| | `documentType` | Enum | false | Yes | Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY | | `document` | Object | false | Yes | Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. | | `referenceId` | ID | false | Yes | ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. | | `indexedAt` | Date | false | Yes | Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options. - **documentType**: [PRODUCT, SELLER, CATEGORY, SUBCATEGORY] ### Filter Properties `documentType` `referenceId` `indexedAt` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's. - **documentType**: Enum has a filter named `documentType` - **referenceId**: ID has a filter named `referenceId` - **indexedAt**: Date has a filter named `indexedAt` ## API Reference ### `List Searchindexes` API List/search search index entries by type or referenceId (used by BFF/global search). Always excludes inactive (soft-deleted) records. Supports filtering and full-text search filters by documentType/referenceId for admin/maintenance use. **Rest Route** The `listSearchIndexes` API REST controller can be triggered via the following route: `/v1/searchindexes` **Rest Request Parameters** The `listSearchIndexes` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchindexes** ```js axios({ method: 'GET', url: '/v1/searchindexes', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndices", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "searchIndices": [ { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Searchindex` API Update an existing searchIndex record (by (documentType, referenceId) or id). Used in response to events (entity edit, data change); internal/automation/admin only. **Rest Route** The `updateSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `updateSearchIndex` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | | documentType | Enum | false | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | false | request.body?.indexedAt | **searchIndexId** : This id paremeter is used to select the required data object that will be updated **documentType** : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY **document** : Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. **referenceId** : ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. **indexedAt** : Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/searchindexs/:searchIndexId** ```js axios({ method: 'PATCH', url: `/v1/searchindexs/${searchIndexId}`, data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Searchindex` API Soft-delete a searchIndex record (by id or by (documentType, referenceId)). Typical use: in response to entity soft-delete; internal/automation/admin only. **Rest Route** The `deleteSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `deleteSearchIndex` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | **searchIndexId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/searchindexs/:searchIndexId** ```js axios({ method: 'DELETE', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Searchindex` API Create a new searchIndex record (internal, used by event triggers and admin tools only). Typically called when a new product/seller/category/subcategory is created. **Rest Route** The `createSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs` **Rest Request Parameters** The `createSearchIndex` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | documentType | Enum | true | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | true | request.body?.indexedAt | **documentType** : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY **document** : Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. **referenceId** : ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. **indexedAt** : Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/searchindexs** ```js axios({ method: 'POST', url: '/v1/searchindexs', data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Searchindex` API Get a single denormalized index record (by id, or documentType+referenceId). Used by BFF for full entity search. Always excludes inactive records unless forced (admin only path). **Rest Route** The `getSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `getSearchIndex` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | **searchIndexId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchindexs/:searchIndexId** ```js axios({ method: 'GET', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` **After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.** # EVENT GUIDE ## ebaycclone-messaging-service In-app messaging service for direct user-to-user text messages (buyers/sellers). Stores, retrieves, and manages user conversations. Launch version: text-only. ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to: Email: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. # Documentation Scope Welcome to the official documentation for the `Messaging` Service Event descriptions. This guide is dedicated to detailing how to subscribe to and listen for state changes within the `Messaging` Service, offering an exclusive focus on event subscription mechanisms. **Intended Audience** This documentation is aimed at developers and integrators looking to monitor `Messaging` Service state changes. It is especially relevant for those wishing to implement or enhance business logic based on interactions with `Messaging` objects. **Overview** This section provides detailed instructions on monitoring service events, covering payload structures and demonstrating typical use cases through examples. # Authentication and Authorization Access to the `Messaging` service's events is facilitated through the project's Kafka server, which is not accessible to the public. Subscription to a Kafka topic requires being on the same network and possessing valid Kafka user credentials. This document presupposes that readers have existing access to the Kafka server. Additionally, the service offers a public subscription option via REST for real-time data management in frontend applications, secured through REST API authentication and authorization mechanisms. To subscribe to service events via the REST API, please consult the Realtime REST API Guide. # Database Events Database events are triggered at the database layer, automatically and atomically, in response to any modifications at the data level. These events serve to notify subscribers about the creation, update, or deletion of objects within the database, distinct from any overarching business logic. Listening to database events is particularly beneficial for those focused on tracking changes at the database level. A typical use case for subscribing to database events is to replicate the data store of one service within another service's scope, ensuring data consistency and syncronization across services. For example, while a business operation such as "approve membership" might generate a high-level business event like `membership-approved`, the underlying database changes could involve multiple state updates to different entities. These might be published as separate events, such as `dbevent-member-updated` and `dbevent-user-updated`, reflecting the granular changes at the database level. Such detailed eventing provides a robust foundation for building responsive, data-driven applications, enabling fine-grained observability and reaction to the dynamics of the data landscape. It also facilitates the architectural pattern of event sourcing, where state changes are captured as a sequence of events, allowing for high-fidelity data replication and history replay for analytical or auditing purposes. ## DbEvent messagingMessage-created **Event topic**: `ebaycclone-messaging-service-dbevent-messagingmessage-created` This event is triggered upon the creation of a `messagingMessage` data object in the database. The event payload encompasses the newly created data, encapsulated within the root of the paylod. **Event payload**: ```json {"id":"ID","fromUserId":"ID","toUserId":"ID","content":"String","isRead":"Boolean","sentAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent messagingMessage-updated **Event topic**: `ebaycclone-messaging-service-dbevent-messagingmessage-updated` Activation of this event follows the update of a `messagingMessage` data object. The payload contains the updated information under the `messagingMessage` attribute, along with the original data prior to update, labeled as `old_messagingMessage` and also you can find the old and new versions of updated-only portion of the data.. **Event payload**: ```json { old_messagingMessage:{"id":"ID","fromUserId":"ID","toUserId":"ID","content":"String","isRead":"Boolean","sentAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, messagingMessage:{"id":"ID","fromUserId":"ID","toUserId":"ID","content":"String","isRead":"Boolean","sentAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, oldDataValues, newDataValues } ``` ## DbEvent messagingMessage-deleted **Event topic**: `ebaycclone-messaging-service-dbevent-messagingmessage-deleted` This event announces the deletion of a `messagingMessage` data object, covering both hard deletions (permanent removal) and soft deletions (where the `isActive` attribute is set to false). Regardless of the deletion type, the event payload will present the data as it was immediately before deletion, highlighting an `isActive` status of false for soft deletions. **Event payload**: ```json {"id":"ID","fromUserId":"ID","toUserId":"ID","content":"String","isRead":"Boolean","sentAt":"Date","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` # ElasticSearch Index Events Within the `Messaging` service, most data objects are mirrored in ElasticSearch indices, ensuring these indices remain syncronized with their database counterparts through creation, updates, and deletions. These indices serve dual purposes: they act as a data source for external services and furnish aggregated data tailored to enhance frontend user experiences. Consequently, an ElasticSearch index might encapsulate data in its original form or aggregate additional information from other data objects. These aggregations can include both one-to-one and one-to-many relationships not only with database objects within the same service but also across different services. This capability allows developers to access comprehensive, aggregated data efficiently. By subscribing to ElasticSearch index events, developers are notified when an index is updated and can directly obtain the aggregated entity within the event payload, bypassing the need for separate ElasticSearch queries. It's noteworthy that some services may augment another service's index by appending to the entity’s `extends` object. In such scenarios, an `*-extended` event will contain only the newly added data. Should you require the complete dataset, you would need to retrieve the full ElasticSearch index entity using the provided ID. This approach to indexing and event handling facilitates a modular, interconnected architecture where services can seamlessly integrate and react to changes, enriching the overall data ecosystem and enabling more dynamic, responsive applications. ## Index Event messagingmessage-created **Event topic**: `elastic-index-ebaycclone_messagingmessage-created` **Event payload**: ```json {"id":"ID","fromUserId":"ID","toUserId":"ID","content":"String","isRead":"Boolean","sentAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event messagingmessage-updated **Event topic**: `elastic-index-ebaycclone_messagingmessage-created` **Event payload**: ```json {"id":"ID","fromUserId":"ID","toUserId":"ID","content":"String","isRead":"Boolean","sentAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event messagingmessage-deleted **Event topic**: `elastic-index-ebaycclone_messagingmessage-deleted` **Event payload**: ```json {"id":"ID","fromUserId":"ID","toUserId":"ID","content":"String","isRead":"Boolean","sentAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event messagingmessage-extended **Event topic**: `elastic-index-ebaycclone_messagingmessage-extended` **Event payload**: ```js { id: id, extends: { [extendName]: "Object", [extendName + "_count"]: "Number", }, } ``` # Route Events Route events are emitted following the successful execution of a route. While most routes perform CRUD (Create, Read, Update, Delete) operations on data objects, resulting in route events that closely resemble database events, there are distinctions worth noting. A single route execution might trigger multiple CRUD actions and ElasticSearch indexing operations. However, for those primarily concerned with the overarching business logic and its outcomes, listening to the consolidated route event, published once at the conclusion of the route's execution, is more pertinent. Moreover, routes often deliver aggregated data beyond the primary database object, catering to specific client needs. For instance, creating a data object via a route might not only return the entity's data but also route-specific metrics, such as the executing user's permissions related to the entity. Alternatively, a route might automatically generate default child entities following the creation of a parent object. Consequently, the route event encapsulates a unified dataset encompassing both the parent and its children, in contrast to individual events triggered for each entity created. Therefore, subscribing to route events can offer a richer, more contextually relevant set of information aligned with business logic. The payload of a route event mirrors the REST response JSON of the route, providing a direct and comprehensive reflection of the data and metadata communicated to the client. This ensures that subscribers to route events receive a payload that encapsulates both the primary data involved and any additional information deemed significant at the business level, facilitating a deeper understanding and integration of the service's functional outcomes. ## Route Event messagingmessages-listed **Event topic** : `ebaycclone-messaging-service-messagingmessages-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `messagingMessages` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`messagingMessages`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"messagingMessages","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","messagingMessages":[{"id":"ID","fromUserId":"ID","toUserId":"ID","content":"String","isRead":"Boolean","sentAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event messagingmessage-created **Event topic** : `ebaycclone-messaging-service-messagingmessage-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `messagingMessage` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`messagingMessage`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"messagingMessage","method":"POST","action":"create","appVersion":"Version","rowCount":1,"messagingMessage":{"id":"ID","fromUserId":"ID","toUserId":"ID","content":"String","isRead":"Boolean","sentAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event messagingmessage-updated **Event topic** : `ebaycclone-messaging-service-messagingmessage-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `messagingMessage` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`messagingMessage`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"messagingMessage","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"messagingMessage":{"id":"ID","fromUserId":"ID","toUserId":"ID","content":"String","isRead":"Boolean","sentAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event messagingmessage-retrived **Event topic** : `ebaycclone-messaging-service-messagingmessage-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `messagingMessage` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`messagingMessage`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"messagingMessage","method":"GET","action":"get","appVersion":"Version","rowCount":1,"messagingMessage":{"id":"ID","fromUserId":"ID","toUserId":"ID","content":"String","isRead":"Boolean","sentAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event messagingmessage-deleted **Event topic** : `ebaycclone-messaging-service-messagingmessage-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `messagingMessage` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`messagingMessage`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"messagingMessage","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"messagingMessage":{"id":"ID","fromUserId":"ID","toUserId":"ID","content":"String","isRead":"Boolean","sentAt":"Date","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` # Copyright All sources, documents and other digital materials are copyright of . # About Us For more information please visit our website: . . . # **EBAYCCLONE** FRONTEND GUIDE FOR AI CODING AGENTS This document is a rest api guide for the ebaycclone project. The document is designed for AI agents who will generate frontend code that will consume the project backend. The project has got 1 auth service, 1 notification service, 1 bff service and business services. Each service is a separate microservice application and listens the HTTP request from different service urls. The services may be in preview server, staging server or real production server. So each service have got 3 acess urls. Frontend application should support all deployemnt servers in the development phase, and user should be able to select the target api server in the login page. ## Project Introduction ebaycClone is a comprehensive backend for an online marketplace supporting auctions and fixed-price sales of physical goods, with role-based access, public user registration, Stripe payments, notifications, and robust ownership enforcement. ## API Structure ### Object Structure of a Successfull Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client. **HTTP Status Codes:** - **200 OK**: This status code is returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request has been processed successfully. - **201 Created**: This status code is specific to CREATE operations, signifying that the requested resource has been successfully created. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling the successful execution of the request. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` - **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation performed. ### Additional Data Each api may have include addtional data other than the main data object according to the business logic of the API. They will be given in each API's response signature. ### Error Response If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity: - **400 Bad Request**: The request was improperly formatted or contained invalid parameters, preventing the server from processing it. - **401 Unauthorized**: The request lacked valid authentication token , login required - **403 Forbidden Error** Curent token provided do not grant access to the requested resource. - **404 Not Found**: The requested resource was not found on the server. - **500 Internal Server Error**: The server encountered an unexpected condition that prevented it from fulfilling the request. Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Accessing the backend Each service of the backend has got its own url according to the deployment environement. User may want to test the frontend in one of the 3 deployments of the application, preview, staging and production. Please ensure that register and login pages do have a deployemnt server selection option, so as the frontned coding agent you can arrange the base url path of all services. The base url of the application in each environment is as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com` * **Staging:** `https://ebaycclone-stage.mindbricks.co` * **Production:** `https://ebaycclone.mindbricks.co` For the auth service the base url is as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` For each other service, the service base url will be given in service sections. Any login requied request to the backend should have a valid token, when a user makes a successfull login, the ressponse JSON includes a JWT access token in the `accessToken`fields. In normal conditions, this token is also set to the cookie and then consumed automatically, but since AI coding agents preview options may fail to use cookies, please ensure that in each request include the access token in the bearer auth header. ## Registration Management First of all please ensure that register and login pages do have a deployemnt server selection option, so as the frontned coding agent you can arrange the base url path of all services. Start with a landing page and arranging register, verification and login flow. So at the first step, you need a general knowledge of the application to make a good landing page and the authetication flow. ### How To Register Using `registeruser` route of auth api, send the required fields to the backend in your registration page. The registerUser api in in `auth` service, is described with request and response structure below. Note that since `registerUser` api is a business api, it has a version control, so please call it with the given version like `/v1/registeruser` ### `Register User` API This api is used by public users to register themselves **Rest Route** The `registerUser` API REST controller can be triggered via the following route: `/v1/registeruser` **Rest Request Parameters** The `registerUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **password** : The password defined by the the user that is being registered. **fullname** : The fullname defined by the the user that is being registered. **email** : The email defined by the the user that is being registered. **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` After a successful registration, frontend code should handle the verification needs. The registration response will have a `user` object in the root envelope, this object will have user information with an `id` parameter. ### Email Verification In the registration response, you should check the property `emailVerificationNeeded` in the reponse root, and if this property is true you should start the email verification flow. After login process, if you get an HTTP error status, and if there is an `errCode` property in the response with `EmailVerificationNeeded` value, you should start the email verification flow. 1. Call the email verification `start` route of the backend (described below) with the user email, backend will send a secret code to the given email adresss. **Backend can send the email message if the architect defined a real mail service or smtp server, so during the development time backend will send the secret code also to the frontend. You can get this secret code from the response within the `secretCode` property**. 2. The secret code in the sent email message will be a 6 digits code , and you should arrange an input page so that the user can paste this code to the frontend application. Please navigate to this input page after you start the verification process. **If the secretCode is sent to the frontend for test purposes, then you should show it as info in the input page, so that user can copy and paste it**. 3. There is a `codeIndex` property in the start response, please show it's value on the input page, so that user can match the index in the message with the one on the screen. 4. When the user submits the code, please complete the email verification using the `complete` route of the backend (described below) with the user email and the secret code. 5. After you get a successful response from email verification, you can navigate to the login page. Here is the `start`and `complete` routes of email verification. These are system routes , so they dont have a version control. #### `POST /verification-services/email-verification/start` **Purpose:** Starts the email verification by generating and sending a secret code. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `email` | String | Yes | User’s email address to verify | **Example Request** ```json { "email": "user@example.com" } ``` **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ In production, `secretCode` is **not** returned — only sent via email. **Error Responses** * `400 Bad Request`: Already verified * `403 Forbidden`: Too many attempts (rate limit) --- #### `POST /verification-services/email-verification/complete` **Purpose:** Completes the verification using the received code. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `email` | String | Yes | User’s email | | `secretCode` | String | Yes | Verification code | **Success Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` **Error Responses** * `403 Forbidden`: Code expired or mismatched * `404 Not Found`: No verification in progress --- ## Login Management After a successfull login and completing required verifications, user can now login. Please make a fancy minimal login page where user can enter his email and password. ## Bucket Management This application has a bucket service and is used to store user or other objects related files. Bucket service is login agnostic, so when accessing for write or private read, you should insert a bucket token (given by services) to your request authorization header as bearer token. **User Bucket** This bucket is used to store public user files for each user. When a user logs in, or in /currentuser response there is `userBucketToken` to be used when sending user related public files to the bucket service. To upload `POST {baseUrl}/bucket/upload` Request body is form data which includes the bucketId and the file as binary in `files` property. ```js { bucketId: "{userId}-public-user-bucket", files: {binary} } ``` Response status is 200 on succesfull result, eg body: ```json { "success": true, "data": [ { "fileId": "9da03f6d-0409-41ad-bb06-225a244ae408", "originalName": "test (10).png", "mimeType": "image/png", "size": 604063, "status": "uploaded", "bucketName": "f7103b85-fcda-4dec-92c6-c336f71fd3a2-public-user-bucket", "isPublic": true, "downloadUrl": "https://babilcom.mindbricks.co/bucket/download/9da03f6d-0409-41ad-bb06-225a244ae408" } ] } ``` To download a file from the bucket, you should know its fileId, so if youupload an avatar or something else, be sure that the download url or the fileId is stored in backend. Bucket is mostly used, in object creations where alos demands an addtional file like a product image or user avatar. So after you upload your image to the bucket, insert the returned download url to the related property in the related object creation. **Application Bucket** This Ebaycclone application alos has common public bucket which everybody has a read access, but only users who have `superAdmin`, `admin` or `saasAdmin` roles can write (upload) to the bucket. The common public project bucket id is `"ebaycclone-public-common-bucket"` and in certain areas like product image uploads, since the user will already have the admin bucket token, he will be able to upload realted object images. Please make your UI arrangements as able to upload files to the bucket using these bucket tokens. **Object Buckets** Some objects may return also a bucket token, to upload or access related files with object. For example, when you get a project's data in a project management application, if there is a public or private bucket token, this is provided mostly for uploading project related files or downloading them with the token. These buckets will be used according to the descriptions given along with the object definitions. ## Role Management This Ebaycclone may have different role names defined fro different business logic. But unless another case is asked by the user, respect to the admin roles which may be `superAdmin`, `admin` or `saasAdmin` in the currentuser or login response given with the `roleId`property. ```json { // ... "roleId":"superAdmin", // ... } ``` If the application needs an admin panel, or any admin related page, please use these roleId's to decide if the user can access those pages or not. ## 1. Authentication Routes ### 1.1 `POST /login` — User Login **Purpose:** Verifies user credentials and creates an authenticated session with a JWT access token. **Access Routes:** * `GET /login`: Returns a minimal HTML login page (for browser-based testing). * `POST /login`: Authenticates user credentials and returns an access token and session. #### Request Parameters | Parameter | Type | Required | Source | | ---------- | ------ | -------- | ----------------------- | | `username` | String | Yes | `request.body.username` | | `password` | String | Yes | `request.body.password` | #### Behavior * Authenticates credentials and returns a session object. * Sets cookie: `projectname-access-token[-tenantCodename]` * Adds the same token in response headers. * Accepts either `username` or `email` fields (if both exist, `username` is prioritized). #### Example ```js axios.post("/login", { username: "user@example.com", password: "securePassword" }); ``` #### Success Response ```json { "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", //... } ``` #### Error Responses * `401 Unauthorized`: Invalid credentials * `403 Forbidden`: Email/mobile verification or 2FA pending * `400 Bad Request`: Missing parameters --- ### 1.2 `POST /logout` — User Logout **Purpose:** Terminates the current session and clears associated authentication tokens. #### Behavior * Invalidates session (if exists). * Clears cookie `projectname-access-token[-tenantCodename]`. * Returns a confirmation response (always `200 OK`). #### Example ```js axios.post("/logout", {}, { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` #### Notes * Can be called without a session (idempotent behavior). * Works for both cookie-based and token-based sessions. #### Success Response ```json { "status": "OK", "message": "User logged out successfully" } ``` --- ## 2. Verification Services Overview All verification routes are grouped under the `/verification-services` base path. They follow a **two-step verification pattern**: `start` → `complete`. --- ## 3. Email Verification ### 3.1 Trigger Scenarios * After registration (`emailVerificationRequiredForLogin` = true) * When updating email address * When login fails due to unverified email ### 3.2 Flow Summary 1. `/start` → Generate & send code via email. 2. `/complete` → Verify code and mark email as verified. ** PLEASE NOTE ** Email verification is a frontend triiggered process. After user registers, the frontend should start the email verification process and navigate to its code input page. --- ### 3.3 `POST /verification-services/email-verification/start` **Purpose:** Starts the email verification by generating and sending a secret code. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `email` | String | Yes | User’s email address to verify | **Example Request** ```json { "email": "user@example.com" } ``` **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ In production, `secretCode` is **not** returned — only sent via email. **Error Responses** * `400 Bad Request`: Already verified * `403 Forbidden`: Too many attempts (rate limit) --- ### 3.4 `POST /verification-services/email-verification/complete` **Purpose:** Completes the verification using the received code. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `email` | String | Yes | User’s email | | `secretCode` | String | Yes | Verification code | **Success Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` **Error Responses** * `403 Forbidden`: Code expired or mismatched * `404 Not Found`: No verification in progress --- ### 3.5 Behavioral Notes * **Resend Cooldown:** `resendTimeWindow` (e.g. 60s) * **Expiration:** Codes expire after `expireTimeWindow` (e.g. 1 day) * **Single Active Session:** One verification per user --- ## 4. Mobile Verification ### 4.1 Trigger Scenarios * After registration (`mobileVerificationRequiredForLogin` = true) * When updating phone number * On login requiring mobile verification ### 4.2 Flow 1. `/start` → Sends verification code via SMS 2. `/complete` → Validates code and confirms number --- ### 4.3 `POST /verification-services/mobile-verification/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------ | | `email` | String | Yes | User’s email to locate mobile record | **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 180, "verificationType": "byCode", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ `secretCode` returned only in development. **Errors** * `400 Bad Request`: Already verified * `403 Forbidden`: Rate-limited --- ### 4.4 `POST /verification-services/mobile-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------------- | | `email` | String | Yes | Associated email | | `secretCode` | String | Yes | Code received via SMS | **Success Response** ```json { "status": "OK", "isVerified": true, "mobile": "+1 333 ...", // in testMode "userId": "user-uuid", } ``` --- ### 4.5 Behavioral Notes * **Cooldown:** One code per minute * **Expiration:** Codes valid for 1 day * **One Session Per User** --- ## 5. Two-Factor Authentication (2FA) ### 5.1 Email 2FA **Flow** 1. `/start` → Generates and sends email code 2. `/complete` → Verifies code and updates session --- #### `POST /verification-services/email-2factor-verification/start` | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ---------------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Current session | | `client` | String | No | Optional context | | `reason` | String | No | Reason for 2FA | **Response** ```json { "status": "OK", "sessionId": "user session id UUID", "userId": "user-uuid", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", } ``` --- #### `POST /verification-services/email-2factor-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `secretCode` | String | Yes | Code from email | **Response** ```json { // user session data "sessionId": "session-uuid", // ... } ``` --- ### 5.2 Mobile 2FA **Flow** 1. `/start` → Sends SMS code 2. `/complete` → Validates and finalizes session --- #### `POST /verification-services/mobile-2factor-verification/start` | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ----------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `client` | String | No | Context | | `reason` | String | No | Reason | **Response** ```json { "status": "OK", "sessionId": "user session id UUID", "userId": "user-uuid", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", } ``` --- #### `POST /verification-services/mobile-2factor-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------ | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `secretCode` | String | Yes | Code via SMS | **Response** ```json { // user session data "sessionId": "session-uuid", // ... } ``` --- ### 5.3 2FA Behavioral Notes * One active code per session * Cooldown: `resendTimeWindow` (e.g., 60s) * Expiration: `expireTimeWindow` (e.g., 5m) --- ## 6. Password Reset ### 6.1 By Email **Flow** 1. `/start` → Sends verification code via email 2. `/complete` → Validates and resets password --- #### `POST /verification-services/password-reset-by-email/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------- | | `email` | String | Yes | User email | **Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` #### `POST /verification-services/password-reset-by-email/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------- | | `email` | String | Yes | User email | | `secretCode` | String | Yes | Code received | | `password` | String | Yes | New password | **Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` --- ### 6.2 By Mobile **Flow** 1. `/start` → Sends SMS code 2. `/complete` → Validates and resets password --- #### `POST /verification-services/password-reset-by-mobile/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------- | | `mobile` | String | Yes | Mobile number | **Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` #### `POST /verification-services/password-reset-by-mobile/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ---------------- | | `email` | String | Yes | Associated email | | `secretCode` | String | Yes | Code via SMS | | `password` | String | Yes | New password | **Response** ```json { "status": "OK", "isVerified": true, "mobile": "+1 444 ....", // in testMode "userId": "user-uuid", } ``` --- ### 6.3 Behavioral Notes * Cooldown: 60s resend * Expiration: 24h * One session per user * Works without an active login session --- ## 7. Verification Method Types ### 7.1 `byCode` User manually enters the 6-digit code in frontend. ### 7.2 `byLink` Frontend handles a one-click verification via email/SMS link containing code parameters. ## 8) `GET /currentuser` — Current Session **Purpose** Return the currently authenticated user’s session. **Route Type** `sessionInfo` **Authentication** Requires a valid access token (header or cookie). ### Request *No parameters.* ### Example ```js axios.get("/currentuser", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) Returns the session object (identity, tenancy, token metadata): ```json { "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", "roleId": "user", "tenantId": "abc123", "accessToken": "jwt-token-string", "...": "..." } ``` ### Errors * **401 Unauthorized** — No active session/token ```json { "status": "ERR", "message": "No login found" } ``` **Notes** * Commonly called by web/mobile clients after login to hydrate session state. * Includes key identity/tenant fields and a token reference (if applicable). * Ensure a valid token is supplied to receive a 200 response. --- ## 9) `GET /permissions` — List Effective Permissions **Purpose** Return all effective permission grants for the current user. **Route Type** `permissionFetch` **Authentication** Requires a valid access token. ### Request *No parameters.* ### Example ```js axios.get("/permissions", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) Array of permission grants (aligned with `givenPermissions`): ```json [ { "id": "perm1", "permissionName": "adminPanel.access", "roleId": "admin", "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" }, { "id": "perm2", "permissionName": "orders.manage", "roleId": null, "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" } ] ``` **Field meanings (per item):** * `permissionName`: Granted permission key. * `roleId`: Present if granted via role. * `subjectUserId`: Present if granted directly to the user. * `subjectUserGroupId`: Present if granted via group. * `objectId`: Present if scoped to a specific object (OBAC). * `canDo`: `true` if enabled, `false` if restricted. ### Errors * **401 Unauthorized** — No active session ```json { "status": "ERR", "message": "No login found" } ``` * **500 Internal Server Error** — Unexpected failure **Notes** * Available on all Mindbricks-generated services (not only Auth). * **Auth service:** Reads live `givenPermissions` from DB. * **Other services:** Typically respond from a cached/projected view (e.g., ElasticSearch) for faster checks. > **Tip:** Cache permission results client-side/server-side and refresh after login or permission updates. --- ## 10) `GET /permissions/:permissionName` — Check Permission Scope **Purpose** Check whether the current user has a specific permission and return any scoped object exceptions/inclusions. **Route Type** `permissionScopeCheck` **Authentication** Requires a valid access token. ### Path Parameters | Name | Type | Required | Source | | ---------------- | ------ | -------- | ------------------------------- | | `permissionName` | String | Yes | `request.params.permissionName` | ### Example ```js axios.get("/permissions/orders.manage", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) ```json { "canDo": true, "exceptions": [ "a1f2e3d4-xxxx-yyyy-zzzz-object1", "b2c3d4e5-xxxx-yyyy-zzzz-object2" ] } ``` **Interpretation** * If `canDo: true`: permission is generally granted **except** the listed `exceptions` (restrictions). * If `canDo: false`: permission is generally **not** granted, **only** allowed for the listed `exceptions` (selective overrides). * `exceptions` contains object IDs (UUID strings) from the relevant domain model. ### Errors * **401 Unauthorized** — No active session/token. ## Services And Data Object ## Auth Service Authentication service for the project ### Auth Service Data Objects **User** A data object that stores the user information and handles login settings. ### Auth Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` ### `Get User` API This api is used by admin roles or the users themselves to get the user profile information. **Rest Route** The `getUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `getUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users/:userId** ```js axios({ method: 'GET', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update User` API This route is used by admins to update user profiles. **Rest Route** The `updateUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `updateUser` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/users/:userId** ```js axios({ method: 'PATCH', url: `/v1/users/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Profile` API This route is used by users to update their profiles. **Rest Route** The `updateProfile` API REST controller can be triggered via the following route: `/v1/profile/:userId` **Rest Request Parameters** The `updateProfile` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/profile/:userId** ```js axios({ method: 'PATCH', url: `/v1/profile/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create User` API This api is used by admin roles to create a new user manually from admin panels **Rest Route** The `createUser` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `createUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | email | String | true | request.body?.email | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **email** : A string value to represent the user's email. **password** : A string value to represent the user's password. It will be stored as hashed. **fullname** : A string value to represent the fullname of the user **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/users** ```js axios({ method: 'POST', url: '/v1/users', data: { avatar:"String", email:"String", password:"String", fullname:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete User` API This api is used by admins to delete user profiles. **Rest Route** The `deleteUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `deleteUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/users/:userId** ```js axios({ method: 'DELETE', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Archive Profile` API This api is used by users to archive their profiles. **Rest Route** The `archiveProfile` API REST controller can be triggered via the following route: `/v1/archiveprofile/:userId` **Rest Request Parameters** The `archiveProfile` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/archiveprofile/:userId** ```js axios({ method: 'DELETE', url: `/v1/archiveprofile/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Users` API The list of users is filtered by the tenantId. **Rest Route** The `listUsers` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `listUsers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users** ```js axios({ method: 'GET', url: '/v1/users', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Search Users` API The list of users is filtered by the tenantId. **Rest Route** The `searchUsers` API REST controller can be triggered via the following route: `/v1/searchusers` **Rest Request Parameters** The `searchUsers` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | keyword | String | true | request.query?.keyword | **keyword** : **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchusers** ```js axios({ method: 'GET', url: '/v1/searchusers', data: { }, params: { keyword:'"String"', } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Userrole` API This route is used by admin roles to update the user role.The default role is user when a user is registered. A user's role can be updated by superAdmin or admin **Rest Route** The `updateUserRole` API REST controller can be triggered via the following route: `/v1/userrole/:userId` **Rest Request Parameters** The `updateUserRole` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | roleId | String | true | request.body?.roleId | **userId** : This id paremeter is used to select the required data object that will be updated **roleId** : The new roleId of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userrole/:userId** ```js axios({ method: 'PATCH', url: `/v1/userrole/${userId}`, data: { roleId:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpassword` API This route is used to update the password of users in the profile page by users themselves **Rest Route** The `updateUserPassword` API REST controller can be triggered via the following route: `/v1/userpassword/:userId` **Rest Request Parameters** The `updateUserPassword` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | oldPassword | String | true | request.body?.oldPassword | | newPassword | String | true | request.body?.newPassword | **userId** : This id paremeter is used to select the required data object that will be updated **oldPassword** : The old password of the user that will be overridden bu the new one. Send for double check. **newPassword** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpassword/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpassword/${userId}`, data: { oldPassword:"String", newPassword:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpasswordbyadmin` API This route is used to change any user password by admins only. Superadmin can chnage all passwords, admins can change only nonadmin passwords **Rest Route** The `updateUserPasswordByAdmin` API REST controller can be triggered via the following route: `/v1/userpasswordbyadmin/:userId` **Rest Request Parameters** The `updateUserPasswordByAdmin` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | password | String | true | request.body?.password | **userId** : This id paremeter is used to select the required data object that will be updated **password** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpasswordbyadmin/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpasswordbyadmin/${userId}`, data: { password:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Briefuser` API This route is used by public to get simple user profile information. **Rest Route** The `getBriefUser` API REST controller can be triggered via the following route: `/v1/briefuser/:userId` **Rest Request Parameters** The `getBriefUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/briefuser/:userId** ```js axios({ method: 'GET', url: `/v1/briefuser/${userId}`, data: { }, params: { } }); ``` **REST Response** This route's response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "fullname": "String", "avatar": "String", "isActive": true } } ``` ### `Register User` API This api is used by public users to register themselves **Rest Route** The `registerUser` API REST controller can be triggered via the following route: `/v1/registeruser` **Rest Request Parameters** The `registerUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **password** : The password defined by the the user that is being registered. **fullname** : The fullname defined by the the user that is being registered. **email** : The email defined by the the user that is being registered. **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## AuctionOffer Service Handles auction bids and fixed-price offers for product listings, enforces real-time auction state, handles strict offer workflows including counter-offers, and triggers domain events for bid/offer notifications. No payment or frontend aggregation logic included. ### AuctionOffer Service Data Objects **AuctionOfferOffer** Represents an offer (best offer/counter-offer) made on a fixed-price product. Tracks buyer, seller, amounts, currency, state transitions, counter-offers, and expiry. **AuctionOfferBid** Represents an individual bid placed on an auction-type product. Linked to product and user, tracks bid amount, currency, status (ACTIVE, WON, LOST, CANCELLED), and time placed. ### AuctionOffer Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auctionoffer-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auctionoffer-api` * **Production:** `https://ebaycclone.mindbricks.co/auctionoffer-api` ### `Update Auctionofferoffer` API Updates offer: accepts/declines/counters by seller, withdraws by buyer before response. Enforces status transition rules, sets respondedAt. Triggers event. **Rest Route** The `updateAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `updateAuctionOfferOffer` api has got 8 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | message | String | false | request.body?.message | | status | Enum | false | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | **auctionOfferOfferId** : This id paremeter is used to select the required data object that will be updated **counterOfferId** : References another offer (counter-offer chain). **counterMessage** : Message accompanying seller's counter-offer (optional). **counterAmount** : Counter-offer amount (when offer is COUNTERED). **message** : Message/special notes from buyer (optional). **status** : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). **expiresAt** : When this offer expires (optional). **respondedAt** : When the seller (or buyer, for counter-offer) responded/updated the offer status. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Auctionofferbid` API Creates a new bid for an auction product. Validates auction status, not seller, product type, bid window, and ensures min. increment. Updates product.currentBid and product.highestBidderId atomically. Triggers notification event. **Rest Route** The `createAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids` **Rest Request Parameters** The `createAuctionOfferBid` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | bidAmount | Double | true | request.body?.bidAmount | | currency | String | true | request.body?.currency | | status | Enum | true | request.body?.status | | productId | ID | true | request.body?.productId | **bidAmount** : Bid amount placed by the user. **currency** : ISO currency for the bid (e.g., USD, EUR). **status** : Bid status: ACTIVE, WON, LOST, CANCELLED. **productId** : Product being bid on (must be AUCTION type). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/auctionofferbids** ```js axios({ method: 'POST', url: '/v1/auctionofferbids', data: { bidAmount:"Double", currency:"String", status:"Enum", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Auctionofferbid` API Gets a single bid (only visible to owner/admin or for auction history). **Rest Route** The `getAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `getAuctionOfferBid` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | **auctionOfferBidId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'GET', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Auctionofferoffer` API Gets a single offer (shown to buyer/seller or admin). **Rest Route** The `getAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `getAuctionOfferOffer` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | **auctionOfferOfferId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'GET', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Auctionofferoffers` API Lists offers by product, user, status, or counterOffer chain. **Rest Route** The `listAuctionOfferOffers` API REST controller can be triggered via the following route: `/v1/auctionofferoffers` **Rest Request Parameters** The `listAuctionOfferOffers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers** ```js axios({ method: 'GET', url: '/v1/auctionofferoffers', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferOffers": [ { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Auctionofferbid` API Updates a bid’s status (allow only status update, e.g. CANCELLED, WIN/LOSE on admin settlement). Only owner/admin, and only if auction not ended or not settled. Triggers notification event. **Rest Route** The `updateAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `updateAuctionOfferBid` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | | status | Enum | false | request.body?.status | **auctionOfferBidId** : This id paremeter is used to select the required data object that will be updated **status** : Bid status: ACTIVE, WON, LOST, CANCELLED. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { status:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Auctionofferoffer` API Creates a new offer for a fixed-price product, validating acceptOffers, type, eligibility, and product/seller/buyer active. Defaults to PENDING state. Triggers notification event. **Rest Route** The `createAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers` **Rest Request Parameters** The `createAuctionOfferOffer` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | productId | ID | true | request.body?.productId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | offerAmount | Double | true | request.body?.offerAmount | | message | String | false | request.body?.message | | status | Enum | true | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | **currency** : ISO currency (e.g., USD, EUR) for the offer. **productId** : Product the offer applies to (must be fixed-price, acceptOffers true). **counterOfferId** : References another offer (counter-offer chain). **counterMessage** : Message accompanying seller's counter-offer (optional). **counterAmount** : Counter-offer amount (when offer is COUNTERED). **offerAmount** : Primary offer amount from buyer. **message** : Message/special notes from buyer (optional). **status** : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). **expiresAt** : When this offer expires (optional). **respondedAt** : When the seller (or buyer, for counter-offer) responded/updated the offer status. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/auctionofferoffers** ```js axios({ method: 'POST', url: '/v1/auctionofferoffers', data: { currency:"String", productId:"ID", counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", offerAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Auctionofferbids` API Lists bids by product, user, or auction, supports history/analytics. **Rest Route** The `listAuctionOfferBids` API REST controller can be triggered via the following route: `/v1/auctionofferbids` **Rest Request Parameters** The `listAuctionOfferBids` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids** ```js axios({ method: 'GET', url: '/v1/auctionofferbids', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBids", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferBids": [ { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Auctionofferbid` API Soft-deletes a bid (for admin or self before auction ends). **Rest Route** The `deleteAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `deleteAuctionOfferBid` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | **auctionOfferBidId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Auctionofferoffer` API Soft-deletes an offer (allowed only in non-accepted/expired state). **Rest Route** The `deleteAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `deleteAuctionOfferOffer` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | **auctionOfferOfferId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## CategoryManagement Service Handles product categories and subcategories for marketplace browsing and classification, supporting public discovery plus admin-only management. ### CategoryManagement Service Data Objects **Category** Represents a product category in the marketplace (e.g., Electronics, Clothing, Toys), used for browsing, filtering, and discovery. Admins manage categories. **Subcategory** Represents a subcategory within a parent category (e.g., 'Smartphones' under 'Electronics'). Used for more granular product discovery and navigation. 'group' categorizes special display logic. ### CategoryManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/categorymanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/categorymanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/categorymanagement-api` ### `Delete Category` API Soft-delete a category (admin-only). **Rest Route** The `deleteCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `deleteCategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | **categoryId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/categories/:categoryId** ```js axios({ method: 'DELETE', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Subcategory` API Get a subcategory by ID. Public - only active subcategories returned except for admin. **Rest Route** The `getSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `getSubcategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | **subcategoryId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/subcategories/:subcategoryId** ```js axios({ method: 'GET', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Category` API Get a single category by ID. Public - only active categories returned (for non-admins). **Rest Route** The `getCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `getCategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | **categoryId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/categories/:categoryId** ```js axios({ method: 'GET', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Subcategory` API Update subcategory (admin-only), including group enum change. **Rest Route** The `updateSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `updateSubcategory` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | name | String | false | request.body?.name | | group | Enum | false | request.body?.group | **subcategoryId** : This id paremeter is used to select the required data object that will be updated **categoryId** : Reference to the parent category (category.id). **name** : Display name of the subcategory. **group** : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/subcategories/:subcategoryId** ```js axios({ method: 'PATCH', url: `/v1/subcategories/${subcategoryId}`, data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Subcategories` API List all subcategories for browsing/filtering, with support for group enum and parent category queries. Only active subcategories shown to public/non-admin users. **Rest Route** The `listSubcategories` API REST controller can be triggered via the following route: `/v1/subcategories` **Rest Request Parameters** The `listSubcategories` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/subcategories** ```js axios({ method: 'GET', url: '/v1/subcategories', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "subcategories": [ { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Subcategory` API Soft-delete a subcategory (admin-only). **Rest Route** The `deleteSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `deleteSubcategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | **subcategoryId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/subcategories/:subcategoryId** ```js axios({ method: 'DELETE', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Categories` API List all categories for browsing and filtering. Only active categories shown to public/non-admin users. **Rest Route** The `listCategories` API REST controller can be triggered via the following route: `/v1/categories` **Rest Request Parameters** The `listCategories` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/categories** ```js axios({ method: 'GET', url: '/v1/categories', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "categories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "categories": [ { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Category` API Update category details (admin-only). **Rest Route** The `updateCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `updateCategory` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | false | request.body?.title | **categoryId** : This id paremeter is used to select the required data object that will be updated **imageUrl** : URL for category image/avatar (optional, used for homepage visuals). **subtitle** : Optional short description for UI/tooltips. **title** : Display name of the category. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/categories/:categoryId** ```js axios({ method: 'PATCH', url: `/v1/categories/${categoryId}`, data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Subcategory` API Create a new subcategory under a given category (admin-only), with enum group constraint. **Rest Route** The `createSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories` **Rest Request Parameters** The `createSubcategory` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.body?.categoryId | | name | String | true | request.body?.name | | group | Enum | true | request.body?.group | **categoryId** : Reference to the parent category (category.id). **name** : Display name of the subcategory. **group** : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/subcategories** ```js axios({ method: 'POST', url: '/v1/subcategories', data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Category` API Create a new category (admin-only) for product classification. **Rest Route** The `createCategory` API REST controller can be triggered via the following route: `/v1/categories` **Rest Request Parameters** The `createCategory` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | true | request.body?.title | **imageUrl** : URL for category image/avatar (optional, used for homepage visuals). **subtitle** : Optional short description for UI/tooltips. **title** : Display name of the category. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/categories** ```js axios({ method: 'POST', url: '/v1/categories', data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## Messaging Service In-app messaging service for direct user-to-user text messages (buyers/sellers). Stores, retrieves, and manages user conversations. Launch version: text-only. ### Messaging Service Data Objects **MessagingMessage** A direct, text-only in-app message between two users (buyer/seller); stores sender, recipient, content, read status, and timestamp. ### Messaging Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/messaging-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/messaging-api` * **Production:** `https://ebaycclone.mindbricks.co/messaging-api` ### `List Messagingmessages` API List all messages in the conversation between the logged-in user and another party, ordered by sentAt descending. Can filter unread with isRead. Returns only messages visible to user (isActive). **Rest Route** The `listMessagingMessages` API REST controller can be triggered via the following route: `/v1/messagingmessages` **Rest Request Parameters** The `listMessagingMessages` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages** ```js axios({ method: 'GET', url: '/v1/messagingmessages', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessages", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "messagingMessages": [ { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Messagingmessage` API Send a new text message from the logged-in user to a recipient. Sender is set from session. Launch version supports only text content. **Rest Route** The `createMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages` **Rest Request Parameters** The `createMessagingMessage` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | toUserId | ID | true | request.body?.toUserId | | content | String | true | request.body?.content | | isRead | Boolean | true | request.body?.isRead | **toUserId** : Recipient (user) of this message. **content** : Text content of the message. No files or attachments for launch. **isRead** : If true, recipient has marked this message as read. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/messagingmessages** ```js axios({ method: 'POST', url: '/v1/messagingmessages', data: { toUserId:"ID", content:"String", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Messagingmessage` API Update a message (mark as read/unread). Only the recipient or admin can change isRead. No content edits. Sender, content, sentAt are immutable. **Rest Route** The `updateMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `updateMessagingMessage` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | | isRead | Boolean | false | request.body?.isRead | **messagingMessageId** : This id paremeter is used to select the required data object that will be updated **isRead** : If true, recipient has marked this message as read. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'PATCH', url: `/v1/messagingmessages/${messagingMessageId}`, data: { isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Messagingmessage` API Get a message by ID. Only accessible to the sender, the recipient, or an admin. Used for message detail view or reading a single message in a thread. **Rest Route** The `getMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `getMessagingMessage` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | **messagingMessageId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'GET', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Messagingmessage` API Delete a message (soft-delete). Only sender, recipient, or admin may delete a message. Deletion only hides it for the user; not a full erase unless both delete. **Rest Route** The `deleteMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `deleteMessagingMessage` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | **messagingMessageId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'DELETE', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## NotificationManagement Service Handles storage, management, and event-driven delivery of in-app and email notifications for user-impacting system events (bids, offers, orders, feedback, messaging, etc.). Supports marking notifications as read/unread, structured filtering by event type/channel, and always returns in-app notifications ordered by recency. ### NotificationManagement Service Data Objects **Notification** Stores and manages in-app and email notifications tied to user-facing events like bids, offers, orders, messaging, shipment, and feedback. Includes event type (notificationType) for filter/search, arbitrary event payload, and delivery channel. Soft-delete enforced. In-app notifications always sorted by createdAt DESC on retrieval. ### NotificationManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/notificationmanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/notificationmanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/notificationmanagement-api` ### `Create Notification` API Creates a notification entry in response to a system/business event. Only allowed for system/event processes and admins (not standard user/action). Typically event-driven, receives userId, notificationType, payload, and channel. **Rest Route** The `createNotification` API REST controller can be triggered via the following route: `/v1/notifications` **Rest Request Parameters** The `createNotification` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationType | Enum | true | request.body?.notificationType | | userId | ID | true | request.body?.userId | | channel | Enum | true | request.body?.channel | | payload | Object | true | request.body?.payload | | isRead | Boolean | true | request.body?.isRead | **notificationType** : Type of event triggering notification (e.g., BID_UPDATED, ORDER_SHIPPED, MESSAGE_RECEIVED, etc.). Used for display/icon and query filter. **userId** : User receiving the notification (recipient). **channel** : Channel by which notification is delivered: IN_APP or EMAIL. **payload** : Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. **isRead** : Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/notifications** ```js axios({ method: 'POST', url: '/v1/notifications', data: { notificationType:"Enum", userId:"ID", channel:"Enum", payload:"Object", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Notification` API Updates a notification (mark as read/unread, payload patch for e.g. admin fix). Only receiver (userId) or admins may update. isRead is primary update scenario; others very limited. **Rest Route** The `updateNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `updateNotification` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | | payload | Object | false | request.body?.payload | | isRead | Boolean | false | request.body?.isRead | **notificationId** : This id paremeter is used to select the required data object that will be updated **payload** : Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. **isRead** : Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/notifications/:notificationId** ```js axios({ method: 'PATCH', url: `/v1/notifications/${notificationId}`, data: { payload:"Object", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Notifications` API Returns filtered list of notifications for a user, with optional filters: notificationType, isRead, channel. Always sorted by createdAt (descending) for in-app notifications. Only retrieval allowed for owner/admin. **Rest Route** The `listNotifications` API REST controller can be triggered via the following route: `/v1/notifications` **Rest Request Parameters** The `listNotifications` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/notifications** ```js axios({ method: 'GET', url: '/v1/notifications', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notifications", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "notifications": [ { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Notification` API Soft-delete a notification record. Only receiver or admin may delete. **Rest Route** The `deleteNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `deleteNotification` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | **notificationId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/notifications/:notificationId** ```js axios({ method: 'DELETE', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Notification` API Retrieves a notification for the receiver or admin. Used to populate content on detail/expanded view. **Rest Route** The `getNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `getNotification` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | **notificationId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/notifications/:notificationId** ```js axios({ method: 'GET', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## SearchIndexing Service Maintains the denormalized search index (materialized view) for global, public search across products, sellers, categories, and subcategories. Handles indexing in response to entity events and exposes optimized query endpoints for BFF/aggregator. ### SearchIndexing Service Data Objects **SearchIndex** Materialized/denormalized search index record for a marketplace entity (product, seller, category, subcategory). Used exclusively for high-speed querying in BFF global/public search. ### SearchIndexing Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/searchindexing-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/searchindexing-api` * **Production:** `https://ebaycclone.mindbricks.co/searchindexing-api` ### `List Searchindexes` API List/search search index entries by type or referenceId (used by BFF/global search). Always excludes inactive (soft-deleted) records. Supports filtering and full-text search filters by documentType/referenceId for admin/maintenance use. **Rest Route** The `listSearchIndexes` API REST controller can be triggered via the following route: `/v1/searchindexes` **Rest Request Parameters** The `listSearchIndexes` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchindexes** ```js axios({ method: 'GET', url: '/v1/searchindexes', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndices", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "searchIndices": [ { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Searchindex` API Update an existing searchIndex record (by (documentType, referenceId) or id). Used in response to events (entity edit, data change); internal/automation/admin only. **Rest Route** The `updateSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `updateSearchIndex` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | | documentType | Enum | false | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | false | request.body?.indexedAt | **searchIndexId** : This id paremeter is used to select the required data object that will be updated **documentType** : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY **document** : Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. **referenceId** : ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. **indexedAt** : Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/searchindexs/:searchIndexId** ```js axios({ method: 'PATCH', url: `/v1/searchindexs/${searchIndexId}`, data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Searchindex` API Soft-delete a searchIndex record (by id or by (documentType, referenceId)). Typical use: in response to entity soft-delete; internal/automation/admin only. **Rest Route** The `deleteSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `deleteSearchIndex` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | **searchIndexId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/searchindexs/:searchIndexId** ```js axios({ method: 'DELETE', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Searchindex` API Create a new searchIndex record (internal, used by event triggers and admin tools only). Typically called when a new product/seller/category/subcategory is created. **Rest Route** The `createSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs` **Rest Request Parameters** The `createSearchIndex` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | documentType | Enum | true | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | true | request.body?.indexedAt | **documentType** : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY **document** : Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. **referenceId** : ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. **indexedAt** : Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/searchindexs** ```js axios({ method: 'POST', url: '/v1/searchindexs', data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Searchindex` API Get a single denormalized index record (by id, or documentType+referenceId). Used by BFF for full entity search. Always excludes inactive records unless forced (admin only path). **Rest Route** The `getSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `getSearchIndex` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | **searchIndexId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchindexs/:searchIndexId** ```js axios({ method: 'GET', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## AdminModeration Service Administrative backend service for moderation and manual override actions. Responsible for logging all admin interventions (user/product/feedback/media/category/order/notification/searchindex moderation), triggering corrections via interservice calls, and providing comprehensive audit trails for compliance. ### AdminModeration Service Data Objects **ModerationAction** Audit record for all admin moderation/override actions affecting core business entities. Links to admin, timestamp, entity type/ID, action performed, and reason. ### AdminModeration Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/adminmoderation-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/adminmoderation-api` * **Production:** `https://ebaycclone.mindbricks.co/adminmoderation-api` ### `Get Moderationaction` API Get a single moderation action log by ID. Used to review admin audit trails; accessible only to platform admins. **Rest Route** The `getModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `getModerationAction` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | **moderationActionId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/moderationactions/:moderationActionId** ```js axios({ method: 'GET', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Moderationaction` API Soft-deletes a moderation action log record (dangerous; allowed only to superadmins or strict manual correction), primarily for audit correction or internal error cleanup. Usually, moderation logs are immutable. **Rest Route** The `deleteModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `deleteModerationAction` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | **moderationActionId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/moderationactions/:moderationActionId** ```js axios({ method: 'DELETE', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Moderationaction` API Logs an admin moderation or override action in the system for audit and traceability. Requires admin login, takes context from session, and creates an audit entry for any admin operation over any entity type. **Rest Route** The `createModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions` **Rest Request Parameters** The `createModerationAction` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | entityId | ID | true | request.body?.entityId | | entityType | Enum | true | request.body?.entityType | | reason | String | true | request.body?.reason | | actionType | Enum | true | request.body?.actionType | **entityId** : ID of target entity affected by moderation (user/product/etc). **entityType** : Type of entity affected (USER, PRODUCT, FEEDBACK, MEDIA, CATEGORY, NOTIFICATION, ORDER, SEARCHINDEX). **reason** : Explanation or justification for the moderation action performed. **actionType** : Type of moderation action (e.g., SOFT_DELETE, RESTORE, UPDATE_ROLE, MANUAL_CORRECTION, MEDIA_FLAG, INDEX_REBUILD, PAYMENT_FIX, FEEDBACK_OVERRIDE, ADMIN_NOTE). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/moderationactions** ```js axios({ method: 'POST', url: '/v1/moderationactions', data: { entityId:"ID", entityType:"Enum", reason:"String", actionType:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Moderationactions` API List moderation actions for admin dashboard/audit search. Supports filtering by admin, entityType, entityId, actionType, and date. Always sorted by most recent action. **Rest Route** The `listModerationActions` API REST controller can be triggered via the following route: `/v1/moderationactions` **Rest Request Parameters** The `listModerationActions` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/moderationactions** ```js axios({ method: 'GET', url: '/v1/moderationactions', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationActions", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "moderationActions": [ { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Moderationaction` API Allows update of explanation/note on a moderation action for correction (typically by admin or superadmin only). No entity/type/admin may be changed after creation; only 'reason' is editable for audit consistency. **Rest Route** The `updateModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `updateModerationAction` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | | reason | String | false | request.body?.reason | **moderationActionId** : This id paremeter is used to select the required data object that will be updated **reason** : Explanation or justification for the moderation action performed. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/moderationactions/:moderationActionId** ```js axios({ method: 'PATCH', url: `/v1/moderationactions/${moderationActionId}`, data: { reason:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## WatchlistCart Service Handles user watchlists (with custom folders) and shopping cart preparation for checkout, strictly enforcing only fixed-price products in carts, supporting item moves/bulk operations, and robust default/folder logic.. ### WatchlistCart Service Data Objects **WatchlistItem** Item in a user’s watchlist, optionally in a named folder; references product and user. **CartItem** Single product pending checkout in a user’s cart. Only fixed-price products permitted; quantity supported for multi-unit purchases (if allowed). **WatchlistList** A named folder/list in a user’s watchlist. Default list exists for all users. Custom lists may be created and deleted. ### WatchlistCart Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/watchlistcart-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/watchlistcart-api` * **Production:** `https://ebaycclone.mindbricks.co/watchlistcart-api` ### `List Watchlistlist` API List all lists in user’s watchlists. Supports listing by listId for folders. **Rest Route** The `listWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists` **Rest Request Parameters** The `listWatchlistList` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/watchlistlists** ```js axios({ method: 'GET', url: '/v1/watchlistlists', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Cartitems` API List all cart items for a user (pending checkout). **Rest Route** The `listCartItems` API REST controller can be triggered via the following route: `/v1/cartitems` **Rest Request Parameters** The `listCartItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/cartitems** ```js axios({ method: 'GET', url: '/v1/cartitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "price": "Double", "title": "String", "type": "Enum", "type_idx": "Integer", "mediaAssetIds": "ID" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Cartitem` API Remove an item from the user’s cart. **Rest Route** The `deleteCartItem` API REST controller can be triggered via the following route: `/v1/cartitems/:cartItemId` **Rest Request Parameters** The `deleteCartItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | **cartItemId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/cartitems/:cartItemId** ```js axios({ method: 'DELETE', url: `/v1/cartitems/${cartItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Watchlistitem` API Add product to user’s watchlist (default or target list/folder). One (user, product, list) per item enforced. Block duplicates. **Rest Route** The `createWatchlistItem` API REST controller can be triggered via the following route: `/v1/watchlistitems` **Rest Request Parameters** The `createWatchlistItem` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | productId | ID | true | request.body?.productId | | listId | ID | false | request.body?.listId | **addedAt** : Timestamp watchlist item created. **productId** : Referenced product in the watchlist. **listId** : Owning watchlistList; null if in default watchlist. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/watchlistitems** ```js axios({ method: 'POST', url: '/v1/watchlistitems', data: { addedAt:"Date", productId:"ID", listId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Watchlistitems` API List all products in user’s watchlists. Supports listing by listId for folders. **Rest Route** The `listWatchlistItems` API REST controller can be triggered via the following route: `/v1/watchlistitems` **Rest Request Parameters** The `listWatchlistItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/watchlistitems** ```js axios({ method: 'GET', url: '/v1/watchlistitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Cartitemquantity` API Change the quantity for a cart item. User must own the item. **Rest Route** The `updateCartItemQuantity` API REST controller can be triggered via the following route: `/v1/cartitemquantity/:cartItemId` **Rest Request Parameters** The `updateCartItemQuantity` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | | quantity | Integer | false | request.body?.quantity | **cartItemId** : This id paremeter is used to select the required data object that will be updated **quantity** : How many units (if product allows). **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/cartitemquantity/:cartItemId** ```js axios({ method: 'PATCH', url: `/v1/cartitemquantity/${cartItemId}`, data: { quantity:"Integer", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Watchlistlist` API Create a new custom watchlist folder. Name must be unique per user; ‘Default’ is reserved for system. **Rest Route** The `createWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists` **Rest Request Parameters** The `createWatchlistList` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | name | String | true | request.body?.name | **name** : Custom folder or list name. 'Default' is reserved (non-deletable for each user). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/watchlistlists** ```js axios({ method: 'POST', url: '/v1/watchlistlists', data: { name:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Watchlistlist` API Delete a custom watchlist (folder). Items are reassigned to user’s default list. Cannot delete default list. **Rest Route** The `deleteWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists/:watchlistListId` **Rest Request Parameters** The `deleteWatchlistList` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistListId | ID | true | request.params?.watchlistListId | **watchlistListId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistlists/:watchlistListId** ```js axios({ method: 'DELETE', url: `/v1/watchlistlists/${watchlistListId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Watchlistitem` API Remove a product from a user’s watchlist. **Rest Route** The `deleteWatchlistItem` API REST controller can be triggered via the following route: `/v1/watchlistitems/:watchlistItemId` **Rest Request Parameters** The `deleteWatchlistItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistItemId | ID | true | request.params?.watchlistItemId | **watchlistItemId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistitems/:watchlistItemId** ```js axios({ method: 'DELETE', url: `/v1/watchlistitems/${watchlistItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Cartitem` API Add an item to the user’s cart. Only fixed-price products allowed. Duplicates not permitted. **Rest Route** The `createCartItem` API REST controller can be triggered via the following route: `/v1/cartitems` **Rest Request Parameters** The `createCartItem` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | **addedAt** : Timestamp added to cart. **quantity** : How many units (if product allows). **productId** : Product being checked out. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/cartitems** ```js axios({ method: 'POST', url: '/v1/cartitems', data: { addedAt:"Date", quantity:"Integer", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Do Userwatchlist` API userwatchlist **Rest Route** The `userwatchlist` API REST controller can be triggered via the following route: `/v1/userwatchlist` **Rest Request Parameters** The `userwatchlist` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userwatchlist** ```js axios({ method: 'GET', url: '/v1/userwatchlist', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Usercartitems` API list all cart items adde by user **Rest Route** The `listUserCartItems` API REST controller can be triggered via the following route: `/v1/usercartitems` **Rest Request Parameters** The `listUserCartItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/usercartitems** ```js axios({ method: 'GET', url: '/v1/usercartitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "shipping": "Double" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Do Userwatchlistlists` API list all watch lists created by user **Rest Route** The `userwatchlistlists` API REST controller can be triggered via the following route: `/v1/userwatchlistlists` **Rest Request Parameters** The `userwatchlistlists` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userwatchlistlists** ```js axios({ method: 'GET', url: '/v1/userwatchlistlists', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ## ProductListing Service Handles product listings (both auction and fixed-price), image/media storage with validations, enforces immutable type, soft-delete, and public product discovery. ### ProductListing Service Data Objects **ProductListingMedia** Stores and manages images/media associated with products, including secure URL, MIME type, and size validation. Each asset can be used by multiple products. **ProductListingProduct** Represents a single product listing (fixed-price or auction) in the marketplace, with seller, category, type, price information, shipping details, media references, and dynamic auction fields. ### ProductListing Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/productlisting-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/productlisting-api` * **Production:** `https://ebaycclone.mindbricks.co/productlisting-api` ### `List Productlistingmedia` API List all media assets (admin or for media management/bulk preview). **Rest Route** The `listProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias` **Rest Request Parameters** The `listProductListingMedia` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias** ```js axios({ method: 'GET', url: '/v1/productlistingmedias', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedias", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingMedias": [ { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Productlistingproduct` API Get a single product listing. Checks isActive and public status. Includes media, category, subcategory, and seller info via joins. **Rest Route** The `getProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `getProductListingProduct` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | **productListingProductId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'GET', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Productlistingownproducts` API listing the loggedin user's products **Rest Route** The `listProductListingOwnProducts` API REST controller can be triggered via the following route: `/v1/productlistingownproducts` **Rest Request Parameters** The `listProductListingOwnProducts` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingownproducts** ```js axios({ method: 'GET', url: '/v1/productlistingownproducts', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Productlistingmedia` API Get a single media asset by ID (for admin or to display in product UI). **Rest Route** The `getProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` **Rest Request Parameters** The `getProductListingMedia` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | **productListingMediaId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'GET', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Productlistingproducts` API List public product listings. Only isActive=true records are returned. Includes category, subcategory, seller, media joins. Supports filtering. **Rest Route** The `listProductListingProducts` API REST controller can be triggered via the following route: `/v1/productlistingproducts` **Rest Request Parameters** The `listProductListingProducts` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts** ```js axios({ method: 'GET', url: '/v1/productlistingproducts', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Productlistingproduct` API Soft-delete a product listing. Only owner or admin can delete. **Rest Route** The `deleteProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `deleteProductListingProduct` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | **productListingProductId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'DELETE', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Productlistingproduct` API Update a product listing. Product type cannot be changed (immutable). **Rest Route** The `updateProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `updateProductListingProduct` api has got 21 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | | currency | String | false | request.body?.currency | | description | Text | false | request.body?.description | | condition | Enum | false | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | false | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | false | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | false | request.body?.shippingMethod | | shipping | Double | false | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | false | request.body?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | **productListingProductId** : This id paremeter is used to select the required data object that will be updated **currency** : ISO currency code (e.g. USD, EUR) **description** : Product detailed description **condition** : Condition of product: BRAND_NEW, NEW, or USED **startBid** : The opening bid value (for auction type products) **endPrice** : Optional immediate sale/upper end price for auction (if AUCTION type) **price** : Product price (required if fixed price type) **title** : Product title **startPrice** : Minimum starting price for auction (required if AUCTION type) **endBid** : The upper (max) bid value for auction products (if any) **estimatedDelivery** : Estimated delivery date for this product **shippingCurrency** : Currency code for shipping cost **mediaAssetIds** : References to associated product/media assets **shippingMethod** : Shipping option for product: STANDARD, EXPRESS, or FREE **shipping** : Shipping cost for this product **startBidDate** : Date/time when auction bidding begins **subcategoryId** : Reference to subcategory **categoryId** : Reference to parent category **endBidDate** : Date/time when auction bidding ends **currentBid** : Current highest bid for auction-type product (updated atomically on bid placement) **highestBidderId** : User ID of current highest bidder (auction-only, updated by auction microservice) **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'PATCH', url: `/v1/productlistingproducts/${productListingProductId}`, data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Productlistingproduct` API Create a new product listing (fixed or auction), conditioned on product type. Type is immutable after creation. **Rest Route** The `createProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts` **Rest Request Parameters** The `createProductListingProduct` api has got 21 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | description | Text | true | request.body?.description | | condition | Enum | true | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | true | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | type | Enum | true | request.body?.type | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | true | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | true | request.body?.shippingMethod | | shipping | Double | true | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | true | request.body?.subcategoryId | | categoryId | ID | true | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | **currency** : ISO currency code (e.g. USD, EUR) **description** : Product detailed description **condition** : Condition of product: BRAND_NEW, NEW, or USED **startBid** : The opening bid value (for auction type products) **endPrice** : Optional immediate sale/upper end price for auction (if AUCTION type) **price** : Product price (required if fixed price type) **title** : Product title **startPrice** : Minimum starting price for auction (required if AUCTION type) **type** : Product listing type, either FIXED or AUCTION (immutable after creation) **endBid** : The upper (max) bid value for auction products (if any) **estimatedDelivery** : Estimated delivery date for this product **shippingCurrency** : Currency code for shipping cost **mediaAssetIds** : References to associated product/media assets **shippingMethod** : Shipping option for product: STANDARD, EXPRESS, or FREE **shipping** : Shipping cost for this product **startBidDate** : Date/time when auction bidding begins **subcategoryId** : Reference to subcategory **categoryId** : Reference to parent category **endBidDate** : Date/time when auction bidding ends **currentBid** : Current highest bid for auction-type product (updated atomically on bid placement) **highestBidderId** : User ID of current highest bidder (auction-only, updated by auction microservice) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/productlistingproducts** ```js axios({ method: 'POST', url: '/v1/productlistingproducts', data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", type:"Enum", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Productlistingmedia` API Soft-delete a media asset (typically by admin or media owner for flagged/invalid content). **Rest Route** The `deleteProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` **Rest Request Parameters** The `deleteProductListingMedia` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | **productListingMediaId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'DELETE', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Productlistingmedia` API Create a new media asset record after validation. Used mainly by edge controller after upload. **Rest Route** The `createProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias` **Rest Request Parameters** The `createProductListingMedia` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | mimeType | String | true | request.body?.mimeType | | productId | ID | false | request.body?.productId | | url | String | true | request.body?.url | | size | Integer | true | request.body?.size | **mimeType** : MIME type of the uploaded media (e.g., image/jpeg) **productId** : ID of product associated with this media asset **url** : Secure, validated URL for the media asset (S3 or equivalent) **size** : Media size in bytes (for validation and quota) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/productlistingmedias** ```js axios({ method: 'POST', url: '/v1/productlistingmedias', data: { mimeType:"String", productId:"ID", url:"String", size:"Integer", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## OrderManagement Service Handles all marketplace orders, manual checkout flows for fixed-price/offer/auction settlements, Stripe payment processing and webhook reconciliation, explicit status updates (shipping, delivery, cancellation), and feedback eligibility via orderItems. ### OrderManagement Service Data Objects **OrderManagementOrder** Marketplace order record. Stores buyer, shipping, status, items, Stripe payment data, and manual shipment/delivery events. Only accessible to admins or the buyer/seller of order items. **OrderManagementOrderItem** Order line item representing purchase of a single product from a specific seller as part of an order. Enables feedback, delivery, and per-seller analytics. Immutable after order creation. **Sys_orderManagementOrderPayment** A payment storage object to store the payment life cyle of orders based on orderManagementOrder object. It is autocreated based on the source object's checkout config **Sys_paymentCustomer** A payment storage object to store the customer values of the payment platform **Sys_paymentMethod** A payment storage object to store the payment methods of the platform customers ### OrderManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/ordermanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/ordermanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/ordermanagement-api` ### `List Ordermanagementorders` API List orders, filtered for buyer and/or seller, or by admin. Includes select orderItems. **Rest Route** The `listOrderManagementOrders` API REST controller can be triggered via the following route: `/v1/ordermanagementorders` **Rest Request Parameters** The `listOrderManagementOrders` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ordermanagementorders', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Ordermanagementorderitem` API Get a specific order item (for feedback/business logic). **Rest Route** The `getOrderManagementOrderItem` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems/:orderManagementOrderItemId` **Rest Request Parameters** The `getOrderManagementOrderItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderItemId | ID | true | request.params?.orderManagementOrderItemId | **orderManagementOrderItemId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems/:orderManagementOrderItemId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderitems/${orderManagementOrderItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Ordermanagementorder` API Soft-delete/cancel order by admin or eligible actor prior to shipment. Sets status to CANCELLED and cancels active payment intent if pending. Irreversible and blocks feedback. **Rest Route** The `deleteOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` **Rest Request Parameters** The `deleteOrderManagementOrder` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorder` API Get single order by ID. Only accessible to admin, buyer, or relevant sellers of items within this order. Includes all orderItems. **Rest Route** The `getOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` **Rest Request Parameters** The `getOrderManagementOrder` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | **orderManagementOrderId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Ordermanagementorderstatus` API Update order status (manual shipment, delivery, cancellation/refund). Restricted: only seller of all items can mark as shipped, only buyer can confirm delivery, only admin can set refund/cancelled. Timestamps updated as per business rule. **Rest Route** The `updateOrderManagementOrderStatus` API REST controller can be triggered via the following route: `/v1/ordermanagementorderstatus/:orderManagementOrderId` **Rest Request Parameters** The `updateOrderManagementOrderStatus` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **status** : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderstatus/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderstatus/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Complete Orderstripewebhook` API Webhook endpoint called by Stripe to reconcile payment state and update order status based on paymentIntentId and event data. No authentication required (Stripe IPs only). **Rest Route** The `completeOrderStripeWebhook` API REST controller can be triggered via the following route: `/v1/completeorderstripewebhook/:orderManagementOrderId` **Rest Request Parameters** The `completeOrderStripeWebhook` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **status** : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/completeorderstripewebhook/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/completeorderstripewebhook/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderbyproductid` API get orders by productId **Rest Route** The `getOrderManagementOrderByProductId` API REST controller can be triggered via the following route: `/v1/ordermanagementorderbyproductid/:items` **Rest Request Parameters** The `getOrderManagementOrderByProductId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | items | String | true | request.params?.items | **orderManagementOrderId** : This id paremeter is used to query the required data object. **items** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderbyproductid/:items** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderbyproductid/${items}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Ordermanagementorder` API Creates an order and initiates Stripe payment. Validates that all products in the order are fixed-price, populates orderItems, saves Stripe customer/paymentMethod/paymentIntentId for reconciliation. Only accessible to buyers for own checkouts and only allows fixed-price product checkout (no auction). **Rest Route** The `createOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders` **Rest Request Parameters** The `createOrderManagementOrder` api has got 14 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderNumber | String | true | request.body?.orderNumber | | items | ID | false | request.body?.items | | paymentMethodId | String | true | request.body?.paymentMethodId | | stripeCustomerId | String | true | request.body?.stripeCustomerId | | paymentIntentId | String | false | request.body?.paymentIntentId | | shippingAddress | Object | true | request.body?.shippingAddress | | summary | Object | true | request.body?.summary | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderNumber** : Unique, human-friendly order number (displayed to users); enforced unique. **items** : Array of orderManagementOrderItem ids representing items in this order. **paymentMethodId** : Stripe paymentMethodId used for payment. Not stored if cash or other payment (future). **stripeCustomerId** : Stripe customerId of buyer; enables saved/paymentMethodId flows. **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **shippingAddress** : Shipping address for the order (copy of buyer address at purchase time). **summary** : Object with total, subtotal, currency, shipping, discount breakdown as snapshot of order at time of purchase. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorders** ```js axios({ method: 'POST', url: '/v1/ordermanagementorders', data: { orderNumber:"String", items:"ID", paymentMethodId:"String", stripeCustomerId:"String", paymentIntentId:"String", shippingAddress:"Object", summary:"Object", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderitems` API List order items for a given order or for buyer/seller analytics. Used for feedback management. **Rest Route** The `listOrderManagementOrderItems` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems` **Rest Request Parameters** The `listOrderManagementOrderItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Ownordermanagementorders` API list the loggedin user orders **Rest Route** The `listOwnOrderManagementOrders` API REST controller can be triggered via the following route: `/v1/ownordermanagementorders` **Rest Request Parameters** The `listOwnOrderManagementOrders` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ownordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ownordermanagementorders', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Lis Ordermanagementownorderitem` API list the loggedin user's order items **Rest Route** The `lisOrderManagementOwnOrderItem` API REST controller can be triggered via the following route: `/v1/lisordermanagementownorderitem` **Rest Request Parameters** The `lisOrderManagementOwnOrderItem` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/lisordermanagementownorderitem** ```js axios({ method: 'GET', url: '/v1/lisordermanagementownorderitem', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Ordermanagementorderitem` API create order item **Rest Route** The `createOrderManagementOrderItem` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems` **Rest Request Parameters** The `createOrderManagementOrderItem` api has got 8 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | shipping | Double | true | request.body?.shipping | | orderId | ID | true | request.body?.orderId | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | | price | Double | true | request.body?.price | | sellerId | ID | true | request.body?.sellerId | | title | String | true | request.body?.title | | currency | String | true | request.body?.currency | **shipping** : Shipping cost for this product (may be 0 for free shipping). **orderId** : Parent order this item belongs to; enables join and lifecycle tracking. **quantity** : Number of units purchased for this product. **productId** : ID of product purchased in this line item. **price** : Unit price for this product at purchase time. **sellerId** : UserId of seller (owner of product at purchase time). **title** : Product title at purchase time (copied for convenience/audit). **currency** : Currency code for price/shipping (ISO 4217). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderitems** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderitems', data: { shipping:"Double", orderId:"ID", quantity:"Integer", productId:"ID", price:"Double", sellerId:"ID", title:"String", currency:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpayment2` API This route is used to get the payment information by ID. **Rest Route** The `getOrderManagementOrderPayment2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `getOrderManagementOrderPayment2` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderpayments2` API This route is used to list all payments. **Rest Route** The `listOrderManagementOrderPayments2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayments2` **Rest Request Parameters** The `listOrderManagementOrderPayments2` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Ordermanagementorderpayment` API This route is used to create a new payment. **Rest Route** The `createOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment` **Rest Request Parameters** The `createOrderManagementOrderPayment` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderId | ID | true | request.body?.orderId | | paymentId | String | true | request.body?.paymentId | | paymentStatus | String | true | request.body?.paymentStatus | | statusLiteral | String | true | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | **orderId** : an ID value to represent the orderId which is the ID parameter of the source orderManagementOrder object **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderpayment', data: { orderId:"ID", paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Ordermanagementorderpayment` API This route is used to update an existing payment. **Rest Route** The `updateOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `updateOrderManagementOrderPayment` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | false | request.body?.paymentId | | paymentStatus | String | false | request.body?.paymentStatus | | statusLiteral | String | false | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | **sys_orderManagementOrderPaymentId** : This id paremeter is used to select the required data object that will be updated **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Ordermanagementorderpayment` API This route is used to delete a payment. **Rest Route** The `deleteOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `deleteOrderManagementOrderPayment` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderpayments2` API This route is used to list all payments. **Rest Route** The `listOrderManagementOrderPayments2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayments2` **Rest Request Parameters** The `listOrderManagementOrderPayments2` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Ordermanagementorderpaymentbyorderid` API This route is used to get the payment information by order id. **Rest Route** The `getOrderManagementOrderPaymentByOrderId` API REST controller can be triggered via the following route: `/v1/orderManagementOrderpaymentbyorderid/:orderId` **Rest Request Parameters** The `getOrderManagementOrderPaymentByOrderId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | orderId | String | true | request.params?.orderId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **orderId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbyorderid/:orderId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbyorderid/${orderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpaymentbypaymentid` API This route is used to get the payment information by payment id. **Rest Route** The `getOrderManagementOrderPaymentByPaymentId` API REST controller can be triggered via the following route: `/v1/orderManagementOrderpaymentbypaymentid/:paymentId` **Rest Request Parameters** The `getOrderManagementOrderPaymentByPaymentId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | true | request.params?.paymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **paymentId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbypaymentid/:paymentId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbypaymentid/${paymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpayment2` API This route is used to get the payment information by ID. **Rest Route** The `getOrderManagementOrderPayment2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `getOrderManagementOrderPayment2` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Start Ordermanagementorderpayment` API Start payment for orderManagementOrder **Rest Route** The `startOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/startordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `startOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to start a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/startordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/startordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Refresh Ordermanagementorderpayment` API Refresh payment info for orderManagementOrder from Stripe **Rest Route** The `refreshOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/refreshordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `refreshOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to refresh a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/refreshordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/refreshordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Callback Ordermanagementorderpayment` API Refresh payment values by gateway webhook call for orderManagementOrder **Rest Route** The `callbackOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/callbackordermanagementorderpayment` **Rest Request Parameters** The `callbackOrderManagementOrderPayment` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.body?.orderManagementOrderId | **orderManagementOrderId** : The order id parameter that will be read from webhook callback params **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/callbackordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/callbackordermanagementorderpayment', data: { orderManagementOrderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Get Paymentcustomerbyuserid` API This route is used to get the payment customer information by user id. **Rest Route** The `getPaymentCustomerByUserId` API REST controller can be triggered via the following route: `/v1/paymentcustomers/:userId` **Rest Request Parameters** The `getPaymentCustomerByUserId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_paymentCustomerId | ID | true | request.params?.sys_paymentCustomerId | | userId | String | true | request.params?.userId | **sys_paymentCustomerId** : This id paremeter is used to query the required data object. **userId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomers/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_paymentCustomer": { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Paymentcustomers` API This route is used to list all payment customers. **Rest Route** The `listPaymentCustomers` API REST controller can be triggered via the following route: `/v1/paymentcustomers` **Rest Request Parameters** The `listPaymentCustomers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers** ```js axios({ method: 'GET', url: '/v1/paymentcustomers', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentCustomers": [ { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Paymentcustomermethods` API This route is used to list all payment customer methods. **Rest Route** The `listPaymentCustomerMethods` API REST controller can be triggered via the following route: `/v1/paymentcustomermethods/:userId` **Rest Request Parameters** The `listPaymentCustomerMethods` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | String | true | request.params?.userId | **userId** : This parameter will be used to select the data objects that want to be listed **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomermethods/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomermethods/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentMethods", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentMethods": [ { "id": "ID", "paymentMethodId": "String", "userId": "ID", "customerId": "String", "cardHolderName": "String", "cardHolderZip": "String", "platform": "String", "cardInfo": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ## Feedback Service Handles feedback for order items: one feedback per buyer/orderItem, attached to sellerId for analytical feedback/rating aggregation and reputation tracking. Enables querying feedbacks received/given for sellers and buyers. test ### Feedback Service Data Objects **Feedback** One feedback per (buyer, orderItem). Stores rating (1-5), comment, ties to seller for analytics. Created only after delivery confirmed on order item. ### Feedback Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/feedback-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/feedback-api` * **Production:** `https://ebaycclone.mindbricks.co/feedback-api` ### `List Feedbacks` API List feedback with filtering by buyerId (given), sellerId (received), productId, or orderItemId. Used for showing seller profile, buyer profile, or order analytics. **Rest Route** The `listFeedbacks` API REST controller can be triggered via the following route: `/v1/feedbacks` **Rest Request Parameters** The `listFeedbacks` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/feedbacks** ```js axios({ method: 'GET', url: '/v1/feedbacks', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedbacks", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "feedbacks": [ { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Feedback` API Get a single feedback by id. Accessible to public (for seller profile, product, or audit views). **Rest Route** The `getFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `getFeedback` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | **feedbackId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/feedbacks/:feedbackId** ```js axios({ method: 'GET', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Feedback` API Update feedback (comment/rating) for existing feedback record (buyer only). Admin can update as override. **Rest Route** The `updateFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `updateFeedback` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | | rating | Integer | false | request.body?.rating | | comment | String | false | request.body?.comment | **feedbackId** : This id paremeter is used to select the required data object that will be updated **rating** : Rating (1-5 stars) submitted by buyer. Required. **comment** : Optional textual feedback comment, max ~500 chars. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/feedbacks/:feedbackId** ```js axios({ method: 'PATCH', url: `/v1/feedbacks/${feedbackId}`, data: { rating:"Integer", comment:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Feedback` API Delete (soft-delete) feedback (by buyer or admin). Only feedback owner or admin. **Rest Route** The `deleteFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `deleteFeedback` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | **feedbackId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/feedbacks/:feedbackId** ```js axios({ method: 'DELETE', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Feedback` API Buyer creates feedback for a delivered order item. Only allowed once per (buyer, orderItemId). Allowed only once order item is delivered. **Rest Route** The `createFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks` **Rest Request Parameters** The `createFeedback` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | rating | Integer | true | request.body?.rating | | orderId | ID | true | request.body?.orderId | | orderItemId | ID | true | request.body?.orderItemId | | sellerId | ID | true | request.body?.sellerId | | comment | String | false | request.body?.comment | | productId | ID | true | request.body?.productId | **rating** : Rating (1-5 stars) submitted by buyer. Required. **orderId** : Order containing this purchased item. Used for aggregation and validation. **orderItemId** : Purchased item (line item) in order. Feedback is per (buyer, orderItem). **sellerId** : Seller of product for analytics/aggregation. Not author; used for querying feedback about sellers. **comment** : Optional textual feedback comment, max ~500 chars. **productId** : The product listing being reviewed (snapshot at order time). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/feedbacks** ```js axios({ method: 'POST', url: '/v1/feedbacks', data: { rating:"Integer", orderId:"ID", orderItemId:"ID", sellerId:"ID", comment:"String", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # REST API GUIDE ## ebaycclone-messaging-service In-app messaging service for direct user-to-user text messages (buyers/sellers). Stores, retrieves, and manages user conversations. Launch version: text-only. ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to: Email: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. ## Documentation Scope Welcome to the official documentation for the Messaging Service's REST API. This document is designed to provide a comprehensive guide to interfacing with our Messaging Service exclusively through RESTful API endpoints. **Intended Audience** This documentation is intended for developers and integrators who are looking to interact with the Messaging Service via HTTP requests for purposes such as creating, updating, deleting and querying Messaging objects. **Overview** Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases. Beyond REST It's important to note that the Messaging Service also supports alternative methods of interaction, such as gRPC and messaging via a Message Broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation. ## Authentication And Authorization To ensure secure access to the Messaging service's protected endpoints, a project-wide access token is required. This token serves as the primary method for authenticating requests to our service. However, it's important to note that access control varies across different routes: **Protected API**: Certain API (routes) require specific authorization levels. Access to these routes is contingent upon the possession of a valid access token that meets the route-specific authorization criteria. Unauthorized requests to these routes will be rejected. **Public API **: The service also includes public API (routes) that are accessible without authentication. These public endpoints are designed for open access and do not require an access token. ### Token Locations When including your access token in a request, ensure it is placed in one of the following specified locations. The service will sequentially search these locations for the token, utilizing the first one it encounters. | Location | Token Name / Param Name | | ---------------------- | ---------------------------- | | Query | access_token | | Authorization Header | Bearer | | Header | ebaycclone-access-token| | Cookie | ebaycclone-access-token| Please ensure the token is correctly placed in one of these locations, using the appropriate label as indicated. The service prioritizes these locations in the order listed, processing the first token it successfully identifies. ## Api Definitions This section outlines the API endpoints available within the Messaging service. Each endpoint can receive parameters through various methods, meticulously described in the following definitions. It's important to understand the flexibility in how parameters can be included in requests to effectively interact with the Messaging service. This service is configured to listen for HTTP requests on port `3008`, serving both the main API interface and default administrative endpoints. The following routes are available by default: * **API Test Interface (API Face):** `/` * **Swagger Documentation:** `/swagger` * **Postman Collection Download:** `/getPostmanCollection` * **Health Checks:** `/health` and `/admin/health` * **Current Session Info:** `/currentuser` * **Favicon:** `/favicon.ico` This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/messaging-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/messaging-api` * **Production:** `https://ebaycclone.mindbricks.co/messaging-api` **Parameter Inclusion Methods:** Parameters can be incorporated into API requests in several ways, each with its designated location. Understanding these methods is crucial for correctly constructing your requests: **Query Parameters:** Included directly in the URL's query string. **Path Parameters:** Embedded within the URL's path. **Body Parameters:** Sent within the JSON body of the request. **Session Parameters:** Automatically read from the session object. This method is used for parameters that are intrinsic to the user's session, such as userId. When using an API that involves session parameters, you can omit these from your request. The service will automatically bind them to the API layer, provided that a session is associated with your request. **Note on Session Parameters:** Session parameters represent a unique method of parameter inclusion, relying on the context of the user's session. A common example of a session parameter is userId, which the service automatically associates with your request when a session exists. This feature ensures seamless integration of user-specific data without manual input for each request. By adhering to the specified parameter inclusion methods, you can effectively utilize the Messaging service's API endpoints. For detailed information on each endpoint, including required parameters and their accepted locations, refer to the individual API definitions below. ### Common Parameters The `Messaging` service's business API support several common parameters designed to modify and enhance the behavior of API requests. These parameters are not individually listed in the API route definitions to avoid repetition. Instead, refer to this section to understand how to leverage these common behaviors across different routes. Note that all common parameters should be included in the query part of the URL. ### Supported Common Parameters: - **getJoins (BOOLEAN)**: Controls whether to retrieve associated objects along with the main object. By default, `getJoins` is assumed to be `true`. Set it to `false` if you prefer to receive only the main fields of an object, excluding its associations. - **excludeCQRS (BOOLEAN)**: Applicable only when `getJoins` is `true`. By default, `excludeCQRS` is set to `false`. Enabling this parameter (`true`) omits non-local associations, which are typically more resource-intensive as they require querying external services like ElasticSearch for additional information. Use this to optimize response times and resource usage. - **requestId (String)**: Identifies a request to enable tracking through the service's log chain. A random hex string of 32 characters is assigned by default. If you wish to use a custom `requestId`, simply include it in your query parameters. - **caching (BOOLEAN)**: Determines the use of caching for query API. By default, caching is enabled (`true`). To ensure the freshest data directly from the database, set this parameter to `false`, bypassing the cache. - **cacheTTL (Integer)**: Specifies the Time-To-Live (TTL) for query caching, in seconds. This is particularly useful for adjusting the default caching duration (5 minutes) for `get list` queries. Setting a custom `cacheTTL` allows you to fine-tune the cache lifespan to meet your needs. - **pageNumber (Integer)**: For paginated `get list` API's, this parameter selects which page of results to retrieve. The default is `1`, indicating the first page. To disable pagination and retrieve all results, set `pageNumber` to `0`. - **pageRowCount (Integer)**: In conjunction with paginated API's, this parameter defines the number of records per page. The default value is `25`. Adjusting `pageRowCount` allows you to control the volume of data returned in a single request. By utilizing these common parameters, you can tailor the behavior of API requests to suit your specific requirements, ensuring optimal performance and usability of the `Messaging` service. ### Error Response If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity: - **400 Bad Request**: The request was improperly formatted or contained invalid parameters, preventing the server from processing it. - **401 Unauthorized**: The request lacked valid authentication credentials or the credentials provided do not grant access to the requested resource. - **404 Not Found**: The requested resource was not found on the server. - **500 Internal Server Error**: The server encountered an unexpected condition that prevented it from fulfilling the request. Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ### Object Structure of a Successfull Response When the `Messaging` service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client. **Key Characteristics of the Response Envelope:** - **Data Presentation**: Depending on the nature of the request, the service returns either a single data object or an array of objects encapsulated within the JSON envelope. - **Creation and Update API**: These API routes return the unmodified (pure) form of the data object(s), without any associations to other data objects. - **Delete API**: Even though the data is removed from the database, the last known state of the data object(s) is returned in its pure form. - **Get Requests**: A single data object is returned in JSON format. - **Get List Requests**: An array of data objects is provided, reflecting a collection of resources. - **Data Structure and Joins**: The complexity of the data structure in the response can vary based on the API's architectural design and the join options specified in the request. The architecture might inherently limit join operations, or they might be dynamically controlled through query parameters. - **Pure Data Forms**: In some cases, the response mirrors the exact structure found in the primary data table, without extensions. - **Extended Data Forms**: Alternatively, responses might include data extended through joins with tables within the same service or aggregated from external sources, such as ElasticSearch indices related to other services. - **Join Varieties**: The extensions might involve one-to-one joins, resulting in single object associations, or one-to-many joins, leading to an array of objects. In certain instances, the data might even feature nested inclusions from other data objects. **Design Considerations**: The structure of a API's response data is meticulously crafted during the service's architectural planning. This design ensures that responses adequately reflect the intended data relationships and service logic, providing clients with rich and meaningful information. **Brief Data**: Certain API's return a condensed version of the object data, intentionally selecting only specific fields deemed useful for that request. In such instances, the API documentation will detail the properties included in the response, guiding developers on what to expect. ### API Response Structure The API utilizes a standardized JSON envelope to encapsulate responses. This envelope is designed to consistently deliver both the requested data and essential metadata, ensuring that clients can efficiently interpret and utilize the response. **HTTP Status Codes:** - **200 OK**: This status code is returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request has been processed successfully. - **201 Created**: This status code is specific to CREATE operations, signifying that the requested resource has been successfully created. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling the successful execution of the request. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3 "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` - **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation performed. **Handling Errors:** For details on handling error scenarios and understanding the structure of error responses, please refer to the "Error Response" section provided earlier in this documentation. It outlines how error conditions are communicated, including the use of HTTP status codes and standardized JSON structures for error messages. ## Resources Messaging service provides the following resources which are stored in its own database as a data object. Note that a resource for an api access is a data object for the service. ### MessagingMessage resource *Resource Definition* : A direct, text-only in-app message between two users (buyer/seller); stores sender, recipient, content, read status, and timestamp. *MessagingMessage Resource Properties* | Name | Type | Required | Default | Definition | | ---- | ---- | -------- | ------- | ---------- | | **fromUserId** | ID | | | *Sender (user) of this message.* | | **toUserId** | ID | | | *Recipient (user) of this message.* | | **content** | String | | | *Text content of the message. No files or attachments for launch.* | | **isRead** | Boolean | | | *If true, recipient has marked this message as read.* | | **sentAt** | Date | | | *Time the message was sent. If not set, will be createdAt. Used for ordering.* | ## Business Api ### List Messagingmessages API *API Definition* : List all messages in the conversation between the logged-in user and another party, ordered by sentAt descending. Can filter unread with isRead. Returns only messages visible to user (isActive). *API Crud Type* : list *Default access route* : *GET* `/v1/messagingmessages` The listMessagingMessages api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages** ```js axios({ method: 'GET', url: '/v1/messagingmessages', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`messagingMessages`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"messagingMessages","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","messagingMessages":[{"id":"ID","fromUserId":"ID","toUserId":"ID","content":"String","isRead":"Boolean","sentAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For List Messagingmessages](businessApi/listMessagingMessages). ### Create Messagingmessage API *API Definition* : Send a new text message from the logged-in user to a recipient. Sender is set from session. Launch version supports only text content. *API Crud Type* : create *Default access route* : *POST* `/v1/messagingmessages` #### Parameters The createMessagingMessage api has got 3 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | toUserId | ID | true | request.body?.toUserId | | content | String | true | request.body?.content | | isRead | Boolean | true | request.body?.isRead | To access the api you can use the **REST** controller with the path **POST /v1/messagingmessages** ```js axios({ method: 'POST', url: '/v1/messagingmessages', data: { toUserId:"ID", content:"String", isRead:"Boolean", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`messagingMessage`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"messagingMessage","method":"POST","action":"create","appVersion":"Version","rowCount":1,"messagingMessage":{"id":"ID","fromUserId":"ID","toUserId":"ID","content":"String","isRead":"Boolean","sentAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Create Messagingmessage](businessApi/createMessagingMessage). ### Update Messagingmessage API *API Definition* : Update a message (mark as read/unread). Only the recipient or admin can change isRead. No content edits. Sender, content, sentAt are immutable. *API Crud Type* : update *Default access route* : *PATCH* `/v1/messagingmessages/:messagingMessageId` #### Parameters The updateMessagingMessage api has got 2 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | | isRead | Boolean | false | request.body?.isRead | To access the api you can use the **REST** controller with the path **PATCH /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'PATCH', url: `/v1/messagingmessages/${messagingMessageId}`, data: { isRead:"Boolean", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`messagingMessage`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"messagingMessage","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"messagingMessage":{"id":"ID","fromUserId":"ID","toUserId":"ID","content":"String","isRead":"Boolean","sentAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Update Messagingmessage](businessApi/updateMessagingMessage). ### Get Messagingmessage API *API Definition* : Get a message by ID. Only accessible to the sender, the recipient, or an admin. Used for message detail view or reading a single message in a thread. *API Crud Type* : get *Default access route* : *GET* `/v1/messagingmessages/:messagingMessageId` #### Parameters The getMessagingMessage api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'GET', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`messagingMessage`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"messagingMessage","method":"GET","action":"get","appVersion":"Version","rowCount":1,"messagingMessage":{"id":"ID","fromUserId":"ID","toUserId":"ID","content":"String","isRead":"Boolean","sentAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Get Messagingmessage](businessApi/getMessagingMessage). ### Delete Messagingmessage API *API Definition* : Delete a message (soft-delete). Only sender, recipient, or admin may delete a message. Deletion only hides it for the user; not a full erase unless both delete. *API Crud Type* : delete *Default access route* : *DELETE* `/v1/messagingmessages/:messagingMessageId` #### Parameters The deleteMessagingMessage api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | To access the api you can use the **REST** controller with the path **DELETE /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'DELETE', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`messagingMessage`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"messagingMessage","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"messagingMessage":{"id":"ID","fromUserId":"ID","toUserId":"ID","content":"String","isRead":"Boolean","sentAt":"Date","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Delete Messagingmessage](businessApi/deleteMessagingMessage). ### Authentication Specific Routes ### Common Routes ### Route: currentuser *Route Definition*: Retrieves the currently authenticated user's session information. *Route Type*: sessionInfo *Access Route*: `GET /currentuser` #### Parameters This route does **not** require any request parameters. #### Behavior - Returns the authenticated session object associated with the current access token. - If no valid session exists, responds with a 401 Unauthorized. ```js // Sample GET /currentuser call axios.get("/currentuser", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** Returns the session object, including user-related data and token information. ``` { "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", "roleId": "user", "tenantId": "abc123", "accessToken": "jwt-token-string", ... } ``` **Error Response** **401 Unauthorized:** No active session found. ``` { "status": "ERR", "message": "No login found" } ``` **Notes** * This route is typically used by frontend or mobile applications to fetch the current session state after login. * The returned session includes key user identity fields, tenant information (if applicable), and the access token for further authenticated requests. * Always ensure a valid access token is provided in the request to retrieve the session. ### Route: permissions `*Route Definition*`: Retrieves all effective permission records assigned to the currently authenticated user. `*Route Type*`: permissionFetch *Access Route*: `GET /permissions` #### Parameters This route does **not** require any request parameters. #### Behavior - Fetches all active permission records (`givenPermissions` entries) associated with the current user session. - Returns a full array of permission objects. - Requires a valid session (`access token`) to be available. ```js // Sample GET /permissions call axios.get("/permissions", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** Returns an array of permission objects. ```json [ { "id": "perm1", "permissionName": "adminPanel.access", "roleId": "admin", "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" }, { "id": "perm2", "permissionName": "orders.manage", "roleId": null, "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" } ] ``` Each object reflects a single permission grant, aligned with the givenPermissions model: - `**permissionName**`: The permission the user has. - `**roleId**`: If the permission was granted through a role. -` **subjectUserId**`: If directly granted to the user. - `**subjectUserGroupId**`: If granted through a group. - `**objectId**`: If tied to a specific object (OBAC). - `**canDo**`: True or false flag to represent if permission is active or restricted. **Error Responses** * **401 Unauthorized**: No active session found. ```json { "status": "ERR", "message": "No login found" } ``` * **500 Internal Server Error**: Unexpected error fetching permissions. **Notes** * The /permissions route is available across all backend services generated by Mindbricks, not just the auth service. * Auth service: Fetches permissions freshly from the live database (givenPermissions table). * Other services: Typically use a cached or projected view of permissions stored in a common ElasticSearch store, optimized for faster authorization checks. > **Tip**: > Applications can cache permission results client-side or server-side, but should occasionally refresh by calling this endpoint, especially after login or permission-changing operations. ### Route: permissions/:permissionName *Route Definition*: Checks whether the current user has access to a specific permission, and provides a list of scoped object exceptions or inclusions. *Route Type*: permissionScopeCheck *Access Route*: `GET /permissions/:permissionName` #### Parameters | Parameter | Type | Required | Population | |------------------|--------|----------|------------------------| | permissionName | String | Yes | `request.params.permissionName` | #### Behavior - Evaluates whether the current user **has access** to the given `permissionName`. - Returns a structured object indicating: - Whether the permission is generally granted (`canDo`) - Which object IDs are explicitly included or excluded from access (`exceptions`) - Requires a valid session (`access token`). ```js // Sample GET /permissions/orders.manage axios.get("/permissions/orders.manage", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** ```json { "canDo": true, "exceptions": [ "a1f2e3d4-xxxx-yyyy-zzzz-object1", "b2c3d4e5-xxxx-yyyy-zzzz-object2" ] } ``` * If `canDo` is `true`, the user generally has the permission, but not for the objects listed in `exceptions` (i.e., restrictions). * If `canDo` is `false`, the user does not have the permission by default — but only for the objects in `exceptions`, they do have permission (i.e., selective overrides). * The exceptions array contains valid **UUID strings**, each corresponding to an object ID (typically from the data model targeted by the permission). ## Copyright All sources, documents and other digital materials are copyright of . ## About Us For more information please visit our website: . . . # Service Design Specification **ebaycclone-messaging-service** documentation -Version:**`1.0.0`** ## Scope This document provides a structured architectural overview of the `messaging` microservice, detailing its configuration, data model, authorization logic, business rules, and API design. It has been automatically generated based on the service definition within Mindbricks, ensuring that the information reflects the source of truth used during code generation and deployment. The document is intended to serve multiple audiences: * **Service architects** can use it to validate design decisions and ensure alignment with broader architectural goals. * **Developers and maintainers** will find it useful for understanding the structure and behavior of the service, facilitating easier debugging, feature extension, and integration with other systems. * **Stakeholders and reviewers** can use it to gain a clear understanding of the service's capabilities and domain logic. > **Note for Frontend Developers**: While this document is valuable for understanding business logic and data interactions, please refer to the [Service API Documentation](#) for endpoint-level specifications and integration details. > **Note for Backend Developers**: Since the code for this service is automatically generated by Mindbricks, you typically won't need to implement or modify it manually. However, this document is especially valuable when you're building other services—whether within Mindbricks or externally—that need to interact with or depend on this service. It provides a clear reference to the service's data contracts, business rules, and API structure, helping ensure compatibility and correct integration. ## `Messaging` Service Settings [**Edit**](messaging/serviceSettings) In-app messaging service for direct user-to-user text messages (buyers/sellers). Stores, retrieves, and manages user conversations. Launch version: text-only. ### Service Overview This service is configured to listen for HTTP requests on port `3008`, serving both the main API interface and default administrative endpoints. The following routes are available by default: * **API Test Interface (API Face):** `/` * **Swagger Documentation:** `/swagger` * **Postman Collection Download:** `/getPostmanCollection` * **Health Checks:** `/health` and `/admin/health` * **Current Session Info:** `/currentuser` * **Favicon:** `/favicon.ico` The service uses a **PostgreSQL** database for data storage, with the database name set to `ebaycclone-messaging-service`. This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/messaging-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/messaging-api` * **Production:** `https://ebaycclone.mindbricks.co/messaging-api` ### Authentication & Security - **Login Required**: Yes This service requires user authentication for access. It supports both JWT and RSA-based authentication mechanisms, ensuring secure user sessions and data integrity. If a crud route also is configured to require login, it will check a valid JWT token in the request query/header/bearer/cookie. If the token is valid, it will extract the user information from the token and make the fetched session data available in the request context. ### Service Data Objects The service uses a **PostgreSQL** database for data storage, with the database name set to `ebaycclone-messaging-service`. Data deletion is managed using a **soft delete** strategy. Instead of removing records from the database, they are flagged as inactive by setting the `isActive` field to `false`. | Object Name | Description | Public Access | |-------------|-------------|---------------| | `messagingMessage` | A direct, text-only in-app message between two users (buyer/seller); stores sender, recipient, content, read status, and timestamp. | accessPrivate | ## messagingMessage Data Object ### Object Overview **Description:** A direct, text-only in-app message between two users (buyer/seller); stores sender, recipient, content, read status, and timestamp. This object represents a core data structure within the service and acts as the blueprint for database interaction, API generation, and business logic enforcement. It is defined using the `ObjectSettings` pattern, which governs its behavior, access control, caching strategy, and integration points with other systems such as Stripe and Redis. ### Core Configuration - **Soft Delete:** Enabled — Determines whether records are marked inactive (`isActive = false`) instead of being physically deleted. - **Public Access:** accessPrivate — If enabled, anonymous users may access this object’s data depending on API-level rules. ### Composite Indexes - **betweenUsersSentAtDesc**: [fromUserId, toUserId, sentAt] This composite index is defined to optimize query performance for complex queries involving multiple fields. The index also defines a conflict resolution strategy for duplicate key violations. When a new record would violate this composite index, the following action will be taken: **On Duplicate**: `` ### Properties Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `fromUserId` | ID | Yes | Sender (user) of this message. | | `toUserId` | ID | Yes | Recipient (user) of this message. | | `content` | String | Yes | Text content of the message. No files or attachments for launch. | | `isRead` | Boolean | Yes | If true, recipient has marked this message as read. | | `sentAt` | Date | No | Time the message was sent. If not set, will be createdAt. Used for ordering. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value is set. ### Default Values Default values are automatically assigned to properties when a new object is created, if no value is provided in the request body. Since default values are applied on db level, they should be literal values, not expressions.If you want to use expressions, you can use transposed parameters in any business API to set default values dynamically. - **fromUserId**: '00000000-0000-0000-0000-000000000000' - **toUserId**: '00000000-0000-0000-0000-000000000000' - **content**: 'default' ### Constant Properties `fromUserId` `toUserId` `content` `sentAt` Constant properties are defined to be immutable after creation, meaning they cannot be updated or changed once set. They are typically used for properties that should remain constant throughout the object's lifecycle. A property is set to be constant if the `Allow Update` option is set to `false`. ### Auto Update Properties `isRead` An update crud API created with the option `Auto Params` enabled will automatically update these properties with the provided values in the request body. If you want to update any property in your own business logic not by user input, you can set the `Allow Auto Update` option to false. These properties will be added to the update API's body parameters and can be updated by the user if any value is provided in the request body. ### Elastic Search Indexing `fromUserId` `toUserId` `content` `isRead` `sentAt` Properties that are indexed in Elastic Search will be searchable via the Elastic Search API. While all properties are stored in the elastic search index of the data object, only those marked for Elastic Search indexing will be available for search queries. ### Database Indexing `fromUserId` `toUserId` `isRead` `sentAt` Properties that are indexed in the database will be optimized for query performance, allowing for faster data retrieval. Make a property indexed in the database if you want to use it frequently in query filters or sorting. ### Cache Select Properties `fromUserId` `toUserId` Cache select properties are used to collect data from Redis entity cache with a different key than the data object id. This allows you to cache data that is not directly related to the data object id, but a frequently used filter. ### Relation Properties `fromUserId` `toUserId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. You can define relations in the data object properties, which will be used to create foreign key constraints in the database. For complex joins operations, Mindbricks supportsa BFF pattern, where you can view dynamic and static views based on Elastic Search Indexes. Use db level relations for simple one-to-one or one-to-many relationships, and use BFF views for complex joins that require multiple data objects to be joined together. - **fromUserId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes - **toUserId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes ### Session Data Properties `fromUserId` Session data properties are used to store data that is specific to the user session, allowing for personalized experiences and temporary data storage. If a property is configured as session data, it will be automatically mapped to the related field in the user session during CRUD operations. Note that session data properties can not be mutated by the user, but only by the system. - **fromUserId**: ID property will be mapped to the session parameter `userId`. ### Formula Properties `sentAt` Formula properties are used to define calculated fields that derive their values from other properties or external data. These properties are automatically calculated based on the defined formula and can be used for dynamic data retrieval. - **sentAt**: Date - Formula: `this.sentAt ?? this.createdAt` - Calculate After Instance: No ### Filter Properties `fromUserId` `toUserId` `isRead` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's that have "Auto Params" enabled. - **fromUserId**: ID has a filter named `fromUserId` - **toUserId**: ID has a filter named `toUserId` - **isRead**: Boolean has a filter named `isRead` ## Business Logic messaging has got 5 Business APIs to manage its internal and crud logic. For the details of each business API refer to its chapter. * [List Messagingmessages](/businessLogic/listmessagingmessages) * [Create Messagingmessage](/businessLogic/createmessagingmessage) * [Update Messagingmessage](/businessLogic/updatemessagingmessage) * [Get Messagingmessage](/businessLogic/getmessagingmessage) * [Delete Messagingmessage](/businessLogic/deletemessagingmessage) ## Edge Controllers No edge controllers defined for this service. --- ## Service Library ### Functions No general functions defined. ### Hook Functions No hook functions defined. ### Edge Functions No edge functions defined. ### Templates No templates defined. ### Assets No assets defined. ### Public Assets No public assets defined. --- ### Event Emission --- ## Integration Patterns ## Deployment Considerations ### Environment Configuration - **HTTP Port**: `3008` - **Database Type**: MongoDB - **Global Soft Delete**: Enabled ## Implementation Guidelines ### Development Workflow 1. **Data Model Implementation**: Generate database schema from data object definitions 2. **CRUD Route Generation**: Implement auto-generated routes with custom logic 3. **Custom Logic Integration**: Implement hook functions and edge functions 4. **Authentication Integration**: Configure with project-level authentication 5. **Testing**: Unit and integration testing for all components ### Code Generation Expectations - **Database Schema**: Auto-generated from data objects and relationships - **API Routes**: REST endpoints with customizable behavior - **Validation Logic**: Input validation from property definitions - **Access Control**: Authentication and authorization middleware ### Custom Code Integration Points - **Hook Functions**: Lifecycle-specific custom logic - **Edge Functions**: Full request/response control - **Library Functions**: Reusable business logic - **Templates**: Dynamic content rendering ### Testing Strategy #### Unit Testing - Test all custom library functions - Test validation logic and business rules - Test hook function implementations #### Integration Testing - Test API endpoints with authentication scenarios - Test database operations and transactions - Test external integrations - Test event emission and Kafka integration #### Performance Testing - Load test high-traffic endpoints - Test caching effectiveness - Monitor database query performance - Test scalability under load --- ## Appendices ### Data Type Reference | Type | Description | Storage | |------|-------------|---------| | ID | Unique identifier | UUID (SQL) / ObjectID (NoSQL) | | String | Short text (≤255 chars) | VARCHAR | | Text | Long-form text | TEXT | | Integer | 32-bit whole numbers | INT | | Boolean | True/false values | BOOLEAN | | Double | 64-bit floating point | DOUBLE | | Float | 32-bit floating point | FLOAT | | Short | 16-bit integers | SMALLINT | | Object | JSON object | JSONB (PostgreSQL) / Object (MongoDB) | | Date | ISO 8601 timestamp | TIMESTAMP | | Enum | Fixed numeric values | SMALLINT with lookup | ### Enum Value Mappings #### Request Locations - `0`: Bearer token in Authorization header - `1`: Cookie value - `2`: Custom HTTP header - `3`: Query parameter - `4`: Request body property - `5`: URL path parameter - `6`: Session data - `7`: Root request object #### HTTP Methods - `0`: GET - `1`: POST - `2`: PUT - `3`: PATCH - `4`: DELETE ### Edge Function Signature ```javascript async function edgeFunction(request) { // Custom request processing // Return response object or throw error return { data: {}, status: 200, message: "Success" }; } ``` --- *This document was generated from the service architecture definition and should be kept in sync with implementation changes.* # EVENT API GUIDE ## NOTIFICATION SERVICE The Notification service is a microservice that allows sending notifications through SMS, Email, and Push channels. Providers can be configured dynamically through the `.env` file. ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to. For inquiries, feedback, or further information regarding the architecture, please direct your communication to: **Email**: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. ## Documentation Scope Welcome to the official documentation for the Notification Service Event Publishers and Listeners. This document provides a comprehensive overview of the event-driven architecture employed in the Notification Service, detailing the various events that are published and consumed within the system. **Intended Audience** This documentation is intended for developers, architects, and system administrators involved in the design, implementation, and maintenance of the Notification Service. It assumes familiarity with microservices architecture and the Kafka messaging system. **Overview** This document outlines the key components of the Notification Service's event-driven architecture, including the events that are published and consumed, the Kafka topics used, and the expected payloads for each event. It serves as a reference guide for understanding how events flow through the system and how different components interact with each other. ## Kafka Event Publishers ### Kafka Event Publisher: sendEmailNotification **Event Topic**: `ebaycclone-notification-service-notification-email` When a notification is sent through the Email channel, this publisher is responsible for sending the notification to the Kafka topic `ebaycclone-notification-service-notification-email`. The payload of the event includes the necessary information for sending the email, such as recipient details, subject, and message body. ### Kafka Event Publisher: sendPushNotification **Event Topic**: `ebaycclone-notification-service-notification-push` When a notification is sent through the Push channel, this publisher is responsible for sending the notification to the Kafka topic `ebaycclone-notification-service-notification-push`. The payload of the event includes the necessary information for sending the push notification, such as recipient details, title, and message body. ### Kafka Event Publisher: sendSmsNotification **Event Topic**: ebaycclone-notification-service-notification-sms` When a notification is sent through the SMS channel, this publisher is responsible for sending the notification to the Kafka topic `ebaycclone-notification-service-notification-sms`. The payload of the event includes the necessary information for sending the SMS, such as recipient details and message body. ## Kafka Event Listeners ### Kafka Event Listener: runEmailSenderListener **Event Topic**: `ebaycclone-notification-service-notification-email` When a notification is sent through the Email channel, this listener is triggered. It consumes messages from the `ebaycclone-notification-service-notification-email` topic, parses the payload, and uses the dynamically configured email provider to send the notification. ### Kafka Event Listener: runPushSenderListener **Event Topic**: `ebaycclone-notification-service-notification-push` When a notification is sent through the Push channel, this listener is triggered. It consumes messages from the `ebaycclone-notification-service-notification-push` topic, parses the payload, and uses the dynamically configured push provider to send the notification. ### Kafka Event Listener: runSmsSenderListener **Event Topic**: `ebaycclone-notification-service-notification-sms` When a notification is sent through the SMS channel, this listener is triggered. It consumes messages from the `ebaycclone-notification-service-notification-sms` topic, parses the payload, and uses the dynamically configured SMS provider to send the notification. ### Kafka Event Listener: runemailVerification1Listener **Event Topic**: `auth.user.created` When a notification is sent through the `auth.user.created` topic, this listener is triggered. It processes the message, extracts required metadata, and constructs a notification payload using a predefined template (`[object Object]`). It supports condition-based filtering and optionally enriches the payload by retrieving data from ElasticSearch if the `dataView` source is used (``). The notification is sent to the target(s) identified in the payload or in the retrieved data source using the Notification Service. ### Kafka Event Listener: runorderPlacedBuyerListener **Event Topic**: `orderManagement.order.created` When a notification is sent through the `orderManagement.order.created` topic, this listener is triggered. It processes the message, extracts required metadata, and constructs a notification payload using a predefined template (`[object Object]`). It supports condition-based filtering and optionally enriches the payload by retrieving data from ElasticSearch if the `dataView` source is used (`OrderNotificationView`). The notification is sent to the target(s) identified in the payload or in the retrieved data source using the Notification Service. ### Kafka Event Listener: runorderPlacedSellerListener **Event Topic**: `orderManagement.order.created` When a notification is sent through the `orderManagement.order.created` topic, this listener is triggered. It processes the message, extracts required metadata, and constructs a notification payload using a predefined template (`[object Object]`). It supports condition-based filtering and optionally enriches the payload by retrieving data from ElasticSearch if the `dataView` source is used (`OrderNotificationView`). The notification is sent to the target(s) identified in the payload or in the retrieved data source using the Notification Service. ### Kafka Event Listener: runorderShippedListener **Event Topic**: `orderManagement.order.statusUpdated` When a notification is sent through the `orderManagement.order.statusUpdated` topic, this listener is triggered. It processes the message, extracts required metadata, and constructs a notification payload using a predefined template (`[object Object]`). It supports condition-based filtering and optionally enriches the payload by retrieving data from ElasticSearch if the `dataView` source is used (`OrderNotificationView`). The notification is sent to the target(s) identified in the payload or in the retrieved data source using the Notification Service. ### Kafka Event Listener: runorderDeliveredListener **Event Topic**: `orderManagement.order.statusUpdated` When a notification is sent through the `orderManagement.order.statusUpdated` topic, this listener is triggered. It processes the message, extracts required metadata, and constructs a notification payload using a predefined template (`[object Object]`). It supports condition-based filtering and optionally enriches the payload by retrieving data from ElasticSearch if the `dataView` source is used (`OrderNotificationView`). The notification is sent to the target(s) identified in the payload or in the retrieved data source using the Notification Service. ### Kafka Event Listener: runbidOutbidListener **Event Topic**: `auctionOffer.bid.updated` When a notification is sent through the `auctionOffer.bid.updated` topic, this listener is triggered. It processes the message, extracts required metadata, and constructs a notification payload using a predefined template (`[object Object]`). It supports condition-based filtering and optionally enriches the payload by retrieving data from ElasticSearch if the `dataView` source is used (`BidNotificationView`). The notification is sent to the target(s) identified in the payload or in the retrieved data source using the Notification Service. ### Kafka Event Listener: runbidWonListener **Event Topic**: `auctionOffer.bid.statusUpdated` When a notification is sent through the `auctionOffer.bid.statusUpdated` topic, this listener is triggered. It processes the message, extracts required metadata, and constructs a notification payload using a predefined template (`[object Object]`). It supports condition-based filtering and optionally enriches the payload by retrieving data from ElasticSearch if the `dataView` source is used (`BidNotificationView`). The notification is sent to the target(s) identified in the payload or in the retrieved data source using the Notification Service. ### Kafka Event Listener: runofferReceivedListener **Event Topic**: `auctionOffer.offer.created` When a notification is sent through the `auctionOffer.offer.created` topic, this listener is triggered. It processes the message, extracts required metadata, and constructs a notification payload using a predefined template (`[object Object]`). It supports condition-based filtering and optionally enriches the payload by retrieving data from ElasticSearch if the `dataView` source is used (`OfferNotificationView`). The notification is sent to the target(s) identified in the payload or in the retrieved data source using the Notification Service. ### Kafka Event Listener: runofferAcceptedListener **Event Topic**: `auctionOffer.offer.updated` When a notification is sent through the `auctionOffer.offer.updated` topic, this listener is triggered. It processes the message, extracts required metadata, and constructs a notification payload using a predefined template (`[object Object]`). It supports condition-based filtering and optionally enriches the payload by retrieving data from ElasticSearch if the `dataView` source is used (`OfferNotificationView`). The notification is sent to the target(s) identified in the payload or in the retrieved data source using the Notification Service. ### Kafka Event Listener: runfeedbackReceivedListener **Event Topic**: `feedback.feedback.created` When a notification is sent through the `feedback.feedback.created` topic, this listener is triggered. It processes the message, extracts required metadata, and constructs a notification payload using a predefined template (`[object Object]`). It supports condition-based filtering and optionally enriches the payload by retrieving data from ElasticSearch if the `dataView` source is used (`FeedbackNotificationView`). The notification is sent to the target(s) identified in the payload or in the retrieved data source using the Notification Service. ### Kafka Event Listener: runmessageReceivedListener **Event Topic**: `messaging.messagingMessage.created` When a notification is sent through the `messaging.messagingMessage.created` topic, this listener is triggered. It processes the message, extracts required metadata, and constructs a notification payload using a predefined template (`[object Object]`). It supports condition-based filtering and optionally enriches the payload by retrieving data from ElasticSearch if the `dataView` source is used (`MessageNotificationView`). The notification is sent to the target(s) identified in the payload or in the retrieved data source using the Notification Service. ### Kafka Event Listener: runemailVerification2Listener **Event Topic**: `ebaycclone-user-service-email-verification-start` When a notification is sent through the `ebaycclone-user-service-email-verification-start` topic, this listener is triggered. It processes the message, extracts required metadata, and constructs a notification payload using a predefined template (`[object Object]`). It supports condition-based filtering and optionally enriches the payload by retrieving data from ElasticSearch if the `dataView` source is used (``). The notification is sent to the target(s) identified in the payload or in the retrieved data source using the Notification Service. ### Kafka Event Listener: runmobileVerificationListener **Event Topic**: `ebaycclone-user-service-mobile-verification-start` When a notification is sent through the `ebaycclone-user-service-mobile-verification-start` topic, this listener is triggered. It processes the message, extracts required metadata, and constructs a notification payload using a predefined template (`[object Object]`). It supports condition-based filtering and optionally enriches the payload by retrieving data from ElasticSearch if the `dataView` source is used (``). The notification is sent to the target(s) identified in the payload or in the retrieved data source using the Notification Service. ### Kafka Event Listener: runpasswordResetByEmailListener **Event Topic**: `ebaycclone-user-service-password-reset-by-email-start` When a notification is sent through the `ebaycclone-user-service-password-reset-by-email-start` topic, this listener is triggered. It processes the message, extracts required metadata, and constructs a notification payload using a predefined template (`[object Object]`). It supports condition-based filtering and optionally enriches the payload by retrieving data from ElasticSearch if the `dataView` source is used (``). The notification is sent to the target(s) identified in the payload or in the retrieved data source using the Notification Service. ### Kafka Event Listener: runpasswordResetByMobileListener **Event Topic**: `ebaycclone-user-service-password-reset-by-mobile-start` When a notification is sent through the `ebaycclone-user-service-password-reset-by-mobile-start` topic, this listener is triggered. It processes the message, extracts required metadata, and constructs a notification payload using a predefined template (`[object Object]`). It supports condition-based filtering and optionally enriches the payload by retrieving data from ElasticSearch if the `dataView` source is used (``). The notification is sent to the target(s) identified in the payload or in the retrieved data source using the Notification Service. ### Kafka Event Listener: runemail2FactorListener **Event Topic**: `ebaycclone-user-service-email-2FA-start` When a notification is sent through the `ebaycclone-user-service-email-2FA-start` topic, this listener is triggered. It processes the message, extracts required metadata, and constructs a notification payload using a predefined template (`[object Object]`). It supports condition-based filtering and optionally enriches the payload by retrieving data from ElasticSearch if the `dataView` source is used (``). The notification is sent to the target(s) identified in the payload or in the retrieved data source using the Notification Service. ### Kafka Event Listener: runmobile2FactorListener **Event Topic**: `ebaycclone-user-service-mobile-2FA-start` When a notification is sent through the `ebaycclone-user-service-mobile-2FA-start` topic, this listener is triggered. It processes the message, extracts required metadata, and constructs a notification payload using a predefined template (`[object Object]`). It supports condition-based filtering and optionally enriches the payload by retrieving data from ElasticSearch if the `dataView` source is used (``). The notification is sent to the target(s) identified in the payload or in the retrieved data source using the Notification Service. # REST API GUIDE ## NOTIFICATION SERVICE The Notification service is a microservice that allows sending notifications through SMS, Email, and Push channels. Providers can be configured dynamically through the `.env` file. ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to. For inquiries, feedback, or further information regarding the architecture, please direct your communication to: **Email**: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. ## Documentation Scope Welcome to the official documentation for the Notification Service REST API. This document provides a comprehensive overview of the available endpoints, how they work, and how to use them efficiently. **Intended Audience** This documentation is intended for developers, architects, and system administrators involved in the design, implementation, and maintenance of the Notification Service. It assumes familiarity with microservices architecture and RESTful APIs. **Overview** Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases. **Beyond REST** It's important to note that the Notification Service also supports alternative methods of interaction, such as messaging via a Kafka message broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation. --- ## Routes ### Route: Register Device _Route Definition_: Registers a device for a user. _Route Type_: create _Default access route_: _POST_ `/devices/register` ### Parameters | Parameter | Type | Required | Population | |-----------|--------|----------|-------------| | device | Object | Yes | body | | userId | ID | Yes | req.userId | ```js axios({ method: "POST", url: `/devices/register`, data: { device:"Object" }, params:{} }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. Any validation errors will return status code `400` with an error message. ### Route: Unregister Device _Route Definition_: Removes a registered device. _Route Type_: delete _Default access route_: _DELETE_ `/devices/unregister/:deviceId` ### Parameters | Parameter | Type | Required | Population | |-----------|--------|----------|-------------| | deviceId | ID | Yes | path.param | | userId | ID | Yes | req.userId | ```js axios({ method: "DELETE", url: `/devices/unregister/${deviceId}`, data:{}, params:{} }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. Any validation errors will return status code `400` with an error message. ### Route: Get Notifications _Route Definition_: Retrieves a paginated list of notifications. _Route Type_: get _Default access route_: _GET_ `/notifications` ### Parameters | Parameter | Type | Required | Population | |-----------|--------|----------|-------------| | page | Number | No | query.page | | limit | Number | No | query.limit | | sortBy | String | No | query.sortBy| | userId | ID | Yes | req.userId | ```js axios({ method: "GET", url: `/notifications`, data:{}, params: { page: "Number", limit: "Number", sortBy: "String" } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. Any validation errors will return status code `400` with an error message. ### Route: Send Notification _Route Definition_: Sends a notification to specified recipients. _Route Type_: create _Default access route_: _POST_ `/notifications` ### Parameters | Parameter | Type | Required | Population | |---------------|--------|----------|------------| |notification | Object | Yes | body | ```js axios({ method: "POST", url: `/notifications`, data: { notification:"Object" }, params:{} }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. Any validation errors will return status code `400` with an error message. ### Route: Mark Notifications as Seen _Route Definition_: Marks selected notifications as seen. _Route Type_: update _Default access route_: _POST_ `/notifications/seen` ### Parameters | Parameter | Type | Required | Population | |------------------ |--------|----------|------------| | notificationIds | Array | Yes | body | | userId | ID | Yes | req.userId | ```js axios({ method: "POST", url: `/notifications/seen`, data: { notificationIds:"Object" }, params:{} }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. Any validation errors will return status code `400` with an error message. --- # Service Design Specification **Notification Service Documentation** **Version:** `1.0` --- ## Scope This document provides a comprehensive architectural overview of the **Notification Service**, which is responsible for sending multi-channel notifications via Email, SMS, and Push. The service supports both REST and gRPC interfaces and utilizes an event-driven architecture through Kafka. This document is intended for: * **Backend Developers** integrating notification capabilities. * **DevOps Engineers** deploying or monitoring the notification system. * **Architects** evaluating extensibility, observability, and scalability. > For detailed REST interface, refer to the \[REST API Guide]. > For Kafka-based publishing and consumption flows, refer to the \[Event API Guide]. --- ## Service Settings * **Port**: Configurable via `HTTP_PORT`, default: `3000` * **Primary Interfaces**: * REST over Express * gRPC over Proto3 * Kafka via event topics * **Database**: PostgreSQL (via Sequelize) * **Optional**: Redis (for caching or state sharing) * **Email/SMS/Push Provider Configuration**: Dynamically switchable via `.env` --- ## Interfaces Overview ### REST API Exposes endpoints to: * Register/unregister devices * Fetch user notifications * Send new notifications * Mark notifications as seen For full list and parameters, refer to the **REST API Guide**. ### gRPC API Defined via `notification.sender.proto`: * `SendNotice()` RPC triggers notification dispatch for all specified channels. * Used for inter-service communication where synchronous flow is preferred. ### Kafka Events * The service **publishes** to and **subscribes** from: * `-notification-email` * `-notification-push` * `-notification-sms` For event structure and consumption logic, refer to the **Event API Guide**. --- ## Provider Architecture Each channel (SMS, Email, Push) is pluggable using a provider pattern. Providers can be toggled via env vars. ### Email Providers * SendGrid * SMTP * AmazonSES * FakeProvider (for dev/test) ### Push Providers * Firebase (FCM) * OneSignal * AmazonSNS * FakeProvider ### SMS Providers * Twilio * AmazonSNS * NetGSM * Vonage * FakeProvider Each provider implements a common `send(payload)` method and logs delivery result. --- ## Storage Mode Notifications can be optionally stored in the PostgreSQL database if `STORED_NOTICE=true` and `notificationBody.isStored=true`. Stored data includes: * `userId`, `title`, `body` * `metadata` (JSON) * `isSeen` flag * `createdAt` / `updatedAt` timestamps --- ## Aggregation & Templating Notification body and title can be: * Directly passed as raw strings * Or dynamically populated via predefined templates: * `WELCOME` * `OTP` * `RESETPASSWORD` * `NONE` (no template) Template rendering supports interpolation with `metadata`. Separate template files exist for: * Email (HTML) * SMS (Text) * Push (structured JSON) --- ## Middleware ### Error Handling * `ApiError` used for standard error shaping * `errorConverter`, `errorHandler` used globally ### Validation * All routes use Joi schema validation * Validations available for: * Device registration * Notification send * Pagination and sort filters * Mark-as-seen by IDs ### Utilities * `pick()`: Selects allowed keys from request * `pagination()`: Sequelize-based paginated query utility --- ## Lifecycle & Boot Process 1. Loads configuration from `.env` using `dotenv` 2. Initializes: * Express HTTP Server * gRPC Server (if `GRPC_ACTIVE=true`) * Kafka listeners * Redis connection * PostgreSQL connection 3. Injects OpenAPI/Swagger via `api-face` 4. Registers REST routes and middleware 5. Launches any scheduled cron jobs 6. Handles graceful shutdown via `SIGINT` --- ## Environment Variables | Variable | Description | | ---------------------- | ----------------------------------- | | `HTTP_PORT` | Express HTTP port (default: 3000) | | `GRPC_PORT` | gRPC server port (default: 50051) | | `SERVICE_URL` | Used to build auth redirect paths | | `SERVICE_SHORT_NAME` | Used for auth hostname substitution | | `PG_USER`, `PG_PASS` | PostgreSQL credentials | | `REDIS_HOST` | Redis connection string | | `STORED_NOTICE` | Whether to persist notifications | | `SENDGRID_API_KEY` | SendGrid API token | | `SMTP_USER/PASS/PORT` | SMTP credentials | | `TWILIO_*`, `NETGSM_*` | SMS provider credentials | | `ONESIGNAL_API_KEY` | OneSignal Push key | --- ## Testing Strategy ### Unit Tests * Provider `.send()` methods * Templating with metadata * Validation schema boundaries ### Integration Tests * REST endpoint workflows * Kafka → Listener execution * gRPC request handling ### End-to-End (Optional) * Simulate a full pipeline: Send → Store → Fetch → Mark as Seen --- ## Observability & Logging * Each send call logs payload & result to console * Provider-specific errors include stack traces # EVENT GUIDE ## ebaycclone-notificationmanagement-service Handles storage, management, and event-driven delivery of in-app and email notifications for user-impacting system events (bids, offers, orders, feedback, messaging, etc.). Supports marking notifications as read/unread, structured filtering by event type/channel, and always returns in-app notifications ordered by recency. ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to: Email: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. # Documentation Scope Welcome to the official documentation for the `NotificationManagement` Service Event descriptions. This guide is dedicated to detailing how to subscribe to and listen for state changes within the `NotificationManagement` Service, offering an exclusive focus on event subscription mechanisms. **Intended Audience** This documentation is aimed at developers and integrators looking to monitor `NotificationManagement` Service state changes. It is especially relevant for those wishing to implement or enhance business logic based on interactions with `NotificationManagement` objects. **Overview** This section provides detailed instructions on monitoring service events, covering payload structures and demonstrating typical use cases through examples. # Authentication and Authorization Access to the `NotificationManagement` service's events is facilitated through the project's Kafka server, which is not accessible to the public. Subscription to a Kafka topic requires being on the same network and possessing valid Kafka user credentials. This document presupposes that readers have existing access to the Kafka server. Additionally, the service offers a public subscription option via REST for real-time data management in frontend applications, secured through REST API authentication and authorization mechanisms. To subscribe to service events via the REST API, please consult the Realtime REST API Guide. # Database Events Database events are triggered at the database layer, automatically and atomically, in response to any modifications at the data level. These events serve to notify subscribers about the creation, update, or deletion of objects within the database, distinct from any overarching business logic. Listening to database events is particularly beneficial for those focused on tracking changes at the database level. A typical use case for subscribing to database events is to replicate the data store of one service within another service's scope, ensuring data consistency and syncronization across services. For example, while a business operation such as "approve membership" might generate a high-level business event like `membership-approved`, the underlying database changes could involve multiple state updates to different entities. These might be published as separate events, such as `dbevent-member-updated` and `dbevent-user-updated`, reflecting the granular changes at the database level. Such detailed eventing provides a robust foundation for building responsive, data-driven applications, enabling fine-grained observability and reaction to the dynamics of the data landscape. It also facilitates the architectural pattern of event sourcing, where state changes are captured as a sequence of events, allowing for high-fidelity data replication and history replay for analytical or auditing purposes. ## DbEvent notification-created **Event topic**: `ebaycclone-notificationmanagement-service-dbevent-notification-created` This event is triggered upon the creation of a `notification` data object in the database. The event payload encompasses the newly created data, encapsulated within the root of the paylod. **Event payload**: ```json {"id":"ID","notificationType":"Enum","notificationType_idx":"Integer","userId":"ID","channel":"Enum","channel_idx":"Integer","payload":"Object","isRead":"Boolean","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent notification-updated **Event topic**: `ebaycclone-notificationmanagement-service-dbevent-notification-updated` Activation of this event follows the update of a `notification` data object. The payload contains the updated information under the `notification` attribute, along with the original data prior to update, labeled as `old_notification` and also you can find the old and new versions of updated-only portion of the data.. **Event payload**: ```json { old_notification:{"id":"ID","notificationType":"Enum","notificationType_idx":"Integer","userId":"ID","channel":"Enum","channel_idx":"Integer","payload":"Object","isRead":"Boolean","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, notification:{"id":"ID","notificationType":"Enum","notificationType_idx":"Integer","userId":"ID","channel":"Enum","channel_idx":"Integer","payload":"Object","isRead":"Boolean","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, oldDataValues, newDataValues } ``` ## DbEvent notification-deleted **Event topic**: `ebaycclone-notificationmanagement-service-dbevent-notification-deleted` This event announces the deletion of a `notification` data object, covering both hard deletions (permanent removal) and soft deletions (where the `isActive` attribute is set to false). Regardless of the deletion type, the event payload will present the data as it was immediately before deletion, highlighting an `isActive` status of false for soft deletions. **Event payload**: ```json {"id":"ID","notificationType":"Enum","notificationType_idx":"Integer","userId":"ID","channel":"Enum","channel_idx":"Integer","payload":"Object","isRead":"Boolean","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` # ElasticSearch Index Events Within the `NotificationManagement` service, most data objects are mirrored in ElasticSearch indices, ensuring these indices remain syncronized with their database counterparts through creation, updates, and deletions. These indices serve dual purposes: they act as a data source for external services and furnish aggregated data tailored to enhance frontend user experiences. Consequently, an ElasticSearch index might encapsulate data in its original form or aggregate additional information from other data objects. These aggregations can include both one-to-one and one-to-many relationships not only with database objects within the same service but also across different services. This capability allows developers to access comprehensive, aggregated data efficiently. By subscribing to ElasticSearch index events, developers are notified when an index is updated and can directly obtain the aggregated entity within the event payload, bypassing the need for separate ElasticSearch queries. It's noteworthy that some services may augment another service's index by appending to the entity’s `extends` object. In such scenarios, an `*-extended` event will contain only the newly added data. Should you require the complete dataset, you would need to retrieve the full ElasticSearch index entity using the provided ID. This approach to indexing and event handling facilitates a modular, interconnected architecture where services can seamlessly integrate and react to changes, enriching the overall data ecosystem and enabling more dynamic, responsive applications. ## Index Event notification-created **Event topic**: `elastic-index-ebaycclone_notification-created` **Event payload**: ```json {"id":"ID","notificationType":"Enum","notificationType_idx":"Integer","userId":"ID","channel":"Enum","channel_idx":"Integer","payload":"Object","isRead":"Boolean","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event notification-updated **Event topic**: `elastic-index-ebaycclone_notification-created` **Event payload**: ```json {"id":"ID","notificationType":"Enum","notificationType_idx":"Integer","userId":"ID","channel":"Enum","channel_idx":"Integer","payload":"Object","isRead":"Boolean","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event notification-deleted **Event topic**: `elastic-index-ebaycclone_notification-deleted` **Event payload**: ```json {"id":"ID","notificationType":"Enum","notificationType_idx":"Integer","userId":"ID","channel":"Enum","channel_idx":"Integer","payload":"Object","isRead":"Boolean","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event notification-extended **Event topic**: `elastic-index-ebaycclone_notification-extended` **Event payload**: ```js { id: id, extends: { [extendName]: "Object", [extendName + "_count"]: "Number", }, } ``` # Route Events Route events are emitted following the successful execution of a route. While most routes perform CRUD (Create, Read, Update, Delete) operations on data objects, resulting in route events that closely resemble database events, there are distinctions worth noting. A single route execution might trigger multiple CRUD actions and ElasticSearch indexing operations. However, for those primarily concerned with the overarching business logic and its outcomes, listening to the consolidated route event, published once at the conclusion of the route's execution, is more pertinent. Moreover, routes often deliver aggregated data beyond the primary database object, catering to specific client needs. For instance, creating a data object via a route might not only return the entity's data but also route-specific metrics, such as the executing user's permissions related to the entity. Alternatively, a route might automatically generate default child entities following the creation of a parent object. Consequently, the route event encapsulates a unified dataset encompassing both the parent and its children, in contrast to individual events triggered for each entity created. Therefore, subscribing to route events can offer a richer, more contextually relevant set of information aligned with business logic. The payload of a route event mirrors the REST response JSON of the route, providing a direct and comprehensive reflection of the data and metadata communicated to the client. This ensures that subscribers to route events receive a payload that encapsulates both the primary data involved and any additional information deemed significant at the business level, facilitating a deeper understanding and integration of the service's functional outcomes. ## Route Event notification-created **Event topic** : `ebaycclone-notificationmanagement-service-notification-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `notification` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`notification`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"notification","method":"POST","action":"create","appVersion":"Version","rowCount":1,"notification":{"id":"ID","notificationType":"Enum","notificationType_idx":"Integer","userId":"ID","channel":"Enum","channel_idx":"Integer","payload":"Object","isRead":"Boolean","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event notification-updated **Event topic** : `ebaycclone-notificationmanagement-service-notification-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `notification` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`notification`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"notification","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"notification":{"id":"ID","notificationType":"Enum","notificationType_idx":"Integer","userId":"ID","channel":"Enum","channel_idx":"Integer","payload":"Object","isRead":"Boolean","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event notifications-listed **Event topic** : `ebaycclone-notificationmanagement-service-notifications-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `notifications` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`notifications`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"notifications","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","notifications":[{"id":"ID","notificationType":"Enum","notificationType_idx":"Integer","userId":"ID","channel":"Enum","channel_idx":"Integer","payload":"Object","isRead":"Boolean","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event notification-deleted **Event topic** : `ebaycclone-notificationmanagement-service-notification-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `notification` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`notification`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"notification","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"notification":{"id":"ID","notificationType":"Enum","notificationType_idx":"Integer","userId":"ID","channel":"Enum","channel_idx":"Integer","payload":"Object","isRead":"Boolean","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event notification-retrived **Event topic** : `ebaycclone-notificationmanagement-service-notification-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `notification` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`notification`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"notification","method":"GET","action":"get","appVersion":"Version","rowCount":1,"notification":{"id":"ID","notificationType":"Enum","notificationType_idx":"Integer","userId":"ID","channel":"Enum","channel_idx":"Integer","payload":"Object","isRead":"Boolean","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` # Copyright All sources, documents and other digital materials are copyright of . # About Us For more information please visit our website: . . . # **EBAYCCLONE** FRONTEND GUIDE FOR AI CODING AGENTS This document is a rest api guide for the ebaycclone project. The document is designed for AI agents who will generate frontend code that will consume the project backend. The project has got 1 auth service, 1 notification service, 1 bff service and business services. Each service is a separate microservice application and listens the HTTP request from different service urls. The services may be in preview server, staging server or real production server. So each service have got 3 acess urls. Frontend application should support all deployemnt servers in the development phase, and user should be able to select the target api server in the login page. ## Project Introduction ebaycClone is a comprehensive backend for an online marketplace supporting auctions and fixed-price sales of physical goods, with role-based access, public user registration, Stripe payments, notifications, and robust ownership enforcement. ## API Structure ### Object Structure of a Successfull Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client. **HTTP Status Codes:** - **200 OK**: This status code is returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request has been processed successfully. - **201 Created**: This status code is specific to CREATE operations, signifying that the requested resource has been successfully created. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling the successful execution of the request. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` - **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation performed. ### Additional Data Each api may have include addtional data other than the main data object according to the business logic of the API. They will be given in each API's response signature. ### Error Response If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity: - **400 Bad Request**: The request was improperly formatted or contained invalid parameters, preventing the server from processing it. - **401 Unauthorized**: The request lacked valid authentication token , login required - **403 Forbidden Error** Curent token provided do not grant access to the requested resource. - **404 Not Found**: The requested resource was not found on the server. - **500 Internal Server Error**: The server encountered an unexpected condition that prevented it from fulfilling the request. Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Accessing the backend Each service of the backend has got its own url according to the deployment environement. User may want to test the frontend in one of the 3 deployments of the application, preview, staging and production. Please ensure that register and login pages do have a deployemnt server selection option, so as the frontned coding agent you can arrange the base url path of all services. The base url of the application in each environment is as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com` * **Staging:** `https://ebaycclone-stage.mindbricks.co` * **Production:** `https://ebaycclone.mindbricks.co` For the auth service the base url is as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` For each other service, the service base url will be given in service sections. Any login requied request to the backend should have a valid token, when a user makes a successfull login, the ressponse JSON includes a JWT access token in the `accessToken`fields. In normal conditions, this token is also set to the cookie and then consumed automatically, but since AI coding agents preview options may fail to use cookies, please ensure that in each request include the access token in the bearer auth header. ## Registration Management First of all please ensure that register and login pages do have a deployemnt server selection option, so as the frontned coding agent you can arrange the base url path of all services. Start with a landing page and arranging register, verification and login flow. So at the first step, you need a general knowledge of the application to make a good landing page and the authetication flow. ### How To Register Using `registeruser` route of auth api, send the required fields to the backend in your registration page. The registerUser api in in `auth` service, is described with request and response structure below. Note that since `registerUser` api is a business api, it has a version control, so please call it with the given version like `/v1/registeruser` ### `Register User` API This api is used by public users to register themselves **Rest Route** The `registerUser` API REST controller can be triggered via the following route: `/v1/registeruser` **Rest Request Parameters** The `registerUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **password** : The password defined by the the user that is being registered. **fullname** : The fullname defined by the the user that is being registered. **email** : The email defined by the the user that is being registered. **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` After a successful registration, frontend code should handle the verification needs. The registration response will have a `user` object in the root envelope, this object will have user information with an `id` parameter. ### Email Verification In the registration response, you should check the property `emailVerificationNeeded` in the reponse root, and if this property is true you should start the email verification flow. After login process, if you get an HTTP error status, and if there is an `errCode` property in the response with `EmailVerificationNeeded` value, you should start the email verification flow. 1. Call the email verification `start` route of the backend (described below) with the user email, backend will send a secret code to the given email adresss. **Backend can send the email message if the architect defined a real mail service or smtp server, so during the development time backend will send the secret code also to the frontend. You can get this secret code from the response within the `secretCode` property**. 2. The secret code in the sent email message will be a 6 digits code , and you should arrange an input page so that the user can paste this code to the frontend application. Please navigate to this input page after you start the verification process. **If the secretCode is sent to the frontend for test purposes, then you should show it as info in the input page, so that user can copy and paste it**. 3. There is a `codeIndex` property in the start response, please show it's value on the input page, so that user can match the index in the message with the one on the screen. 4. When the user submits the code, please complete the email verification using the `complete` route of the backend (described below) with the user email and the secret code. 5. After you get a successful response from email verification, you can navigate to the login page. Here is the `start`and `complete` routes of email verification. These are system routes , so they dont have a version control. #### `POST /verification-services/email-verification/start` **Purpose:** Starts the email verification by generating and sending a secret code. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `email` | String | Yes | User’s email address to verify | **Example Request** ```json { "email": "user@example.com" } ``` **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ In production, `secretCode` is **not** returned — only sent via email. **Error Responses** * `400 Bad Request`: Already verified * `403 Forbidden`: Too many attempts (rate limit) --- #### `POST /verification-services/email-verification/complete` **Purpose:** Completes the verification using the received code. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `email` | String | Yes | User’s email | | `secretCode` | String | Yes | Verification code | **Success Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` **Error Responses** * `403 Forbidden`: Code expired or mismatched * `404 Not Found`: No verification in progress --- ## Login Management After a successfull login and completing required verifications, user can now login. Please make a fancy minimal login page where user can enter his email and password. ## Bucket Management This application has a bucket service and is used to store user or other objects related files. Bucket service is login agnostic, so when accessing for write or private read, you should insert a bucket token (given by services) to your request authorization header as bearer token. **User Bucket** This bucket is used to store public user files for each user. When a user logs in, or in /currentuser response there is `userBucketToken` to be used when sending user related public files to the bucket service. To upload `POST {baseUrl}/bucket/upload` Request body is form data which includes the bucketId and the file as binary in `files` property. ```js { bucketId: "{userId}-public-user-bucket", files: {binary} } ``` Response status is 200 on succesfull result, eg body: ```json { "success": true, "data": [ { "fileId": "9da03f6d-0409-41ad-bb06-225a244ae408", "originalName": "test (10).png", "mimeType": "image/png", "size": 604063, "status": "uploaded", "bucketName": "f7103b85-fcda-4dec-92c6-c336f71fd3a2-public-user-bucket", "isPublic": true, "downloadUrl": "https://babilcom.mindbricks.co/bucket/download/9da03f6d-0409-41ad-bb06-225a244ae408" } ] } ``` To download a file from the bucket, you should know its fileId, so if youupload an avatar or something else, be sure that the download url or the fileId is stored in backend. Bucket is mostly used, in object creations where alos demands an addtional file like a product image or user avatar. So after you upload your image to the bucket, insert the returned download url to the related property in the related object creation. **Application Bucket** This Ebaycclone application alos has common public bucket which everybody has a read access, but only users who have `superAdmin`, `admin` or `saasAdmin` roles can write (upload) to the bucket. The common public project bucket id is `"ebaycclone-public-common-bucket"` and in certain areas like product image uploads, since the user will already have the admin bucket token, he will be able to upload realted object images. Please make your UI arrangements as able to upload files to the bucket using these bucket tokens. **Object Buckets** Some objects may return also a bucket token, to upload or access related files with object. For example, when you get a project's data in a project management application, if there is a public or private bucket token, this is provided mostly for uploading project related files or downloading them with the token. These buckets will be used according to the descriptions given along with the object definitions. ## Role Management This Ebaycclone may have different role names defined fro different business logic. But unless another case is asked by the user, respect to the admin roles which may be `superAdmin`, `admin` or `saasAdmin` in the currentuser or login response given with the `roleId`property. ```json { // ... "roleId":"superAdmin", // ... } ``` If the application needs an admin panel, or any admin related page, please use these roleId's to decide if the user can access those pages or not. ## 1. Authentication Routes ### 1.1 `POST /login` — User Login **Purpose:** Verifies user credentials and creates an authenticated session with a JWT access token. **Access Routes:** * `GET /login`: Returns a minimal HTML login page (for browser-based testing). * `POST /login`: Authenticates user credentials and returns an access token and session. #### Request Parameters | Parameter | Type | Required | Source | | ---------- | ------ | -------- | ----------------------- | | `username` | String | Yes | `request.body.username` | | `password` | String | Yes | `request.body.password` | #### Behavior * Authenticates credentials and returns a session object. * Sets cookie: `projectname-access-token[-tenantCodename]` * Adds the same token in response headers. * Accepts either `username` or `email` fields (if both exist, `username` is prioritized). #### Example ```js axios.post("/login", { username: "user@example.com", password: "securePassword" }); ``` #### Success Response ```json { "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", //... } ``` #### Error Responses * `401 Unauthorized`: Invalid credentials * `403 Forbidden`: Email/mobile verification or 2FA pending * `400 Bad Request`: Missing parameters --- ### 1.2 `POST /logout` — User Logout **Purpose:** Terminates the current session and clears associated authentication tokens. #### Behavior * Invalidates session (if exists). * Clears cookie `projectname-access-token[-tenantCodename]`. * Returns a confirmation response (always `200 OK`). #### Example ```js axios.post("/logout", {}, { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` #### Notes * Can be called without a session (idempotent behavior). * Works for both cookie-based and token-based sessions. #### Success Response ```json { "status": "OK", "message": "User logged out successfully" } ``` --- ## 2. Verification Services Overview All verification routes are grouped under the `/verification-services` base path. They follow a **two-step verification pattern**: `start` → `complete`. --- ## 3. Email Verification ### 3.1 Trigger Scenarios * After registration (`emailVerificationRequiredForLogin` = true) * When updating email address * When login fails due to unverified email ### 3.2 Flow Summary 1. `/start` → Generate & send code via email. 2. `/complete` → Verify code and mark email as verified. ** PLEASE NOTE ** Email verification is a frontend triiggered process. After user registers, the frontend should start the email verification process and navigate to its code input page. --- ### 3.3 `POST /verification-services/email-verification/start` **Purpose:** Starts the email verification by generating and sending a secret code. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `email` | String | Yes | User’s email address to verify | **Example Request** ```json { "email": "user@example.com" } ``` **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ In production, `secretCode` is **not** returned — only sent via email. **Error Responses** * `400 Bad Request`: Already verified * `403 Forbidden`: Too many attempts (rate limit) --- ### 3.4 `POST /verification-services/email-verification/complete` **Purpose:** Completes the verification using the received code. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `email` | String | Yes | User’s email | | `secretCode` | String | Yes | Verification code | **Success Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` **Error Responses** * `403 Forbidden`: Code expired or mismatched * `404 Not Found`: No verification in progress --- ### 3.5 Behavioral Notes * **Resend Cooldown:** `resendTimeWindow` (e.g. 60s) * **Expiration:** Codes expire after `expireTimeWindow` (e.g. 1 day) * **Single Active Session:** One verification per user --- ## 4. Mobile Verification ### 4.1 Trigger Scenarios * After registration (`mobileVerificationRequiredForLogin` = true) * When updating phone number * On login requiring mobile verification ### 4.2 Flow 1. `/start` → Sends verification code via SMS 2. `/complete` → Validates code and confirms number --- ### 4.3 `POST /verification-services/mobile-verification/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------ | | `email` | String | Yes | User’s email to locate mobile record | **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 180, "verificationType": "byCode", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ `secretCode` returned only in development. **Errors** * `400 Bad Request`: Already verified * `403 Forbidden`: Rate-limited --- ### 4.4 `POST /verification-services/mobile-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------------- | | `email` | String | Yes | Associated email | | `secretCode` | String | Yes | Code received via SMS | **Success Response** ```json { "status": "OK", "isVerified": true, "mobile": "+1 333 ...", // in testMode "userId": "user-uuid", } ``` --- ### 4.5 Behavioral Notes * **Cooldown:** One code per minute * **Expiration:** Codes valid for 1 day * **One Session Per User** --- ## 5. Two-Factor Authentication (2FA) ### 5.1 Email 2FA **Flow** 1. `/start` → Generates and sends email code 2. `/complete` → Verifies code and updates session --- #### `POST /verification-services/email-2factor-verification/start` | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ---------------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Current session | | `client` | String | No | Optional context | | `reason` | String | No | Reason for 2FA | **Response** ```json { "status": "OK", "sessionId": "user session id UUID", "userId": "user-uuid", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", } ``` --- #### `POST /verification-services/email-2factor-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `secretCode` | String | Yes | Code from email | **Response** ```json { // user session data "sessionId": "session-uuid", // ... } ``` --- ### 5.2 Mobile 2FA **Flow** 1. `/start` → Sends SMS code 2. `/complete` → Validates and finalizes session --- #### `POST /verification-services/mobile-2factor-verification/start` | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ----------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `client` | String | No | Context | | `reason` | String | No | Reason | **Response** ```json { "status": "OK", "sessionId": "user session id UUID", "userId": "user-uuid", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", } ``` --- #### `POST /verification-services/mobile-2factor-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------ | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `secretCode` | String | Yes | Code via SMS | **Response** ```json { // user session data "sessionId": "session-uuid", // ... } ``` --- ### 5.3 2FA Behavioral Notes * One active code per session * Cooldown: `resendTimeWindow` (e.g., 60s) * Expiration: `expireTimeWindow` (e.g., 5m) --- ## 6. Password Reset ### 6.1 By Email **Flow** 1. `/start` → Sends verification code via email 2. `/complete` → Validates and resets password --- #### `POST /verification-services/password-reset-by-email/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------- | | `email` | String | Yes | User email | **Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` #### `POST /verification-services/password-reset-by-email/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------- | | `email` | String | Yes | User email | | `secretCode` | String | Yes | Code received | | `password` | String | Yes | New password | **Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` --- ### 6.2 By Mobile **Flow** 1. `/start` → Sends SMS code 2. `/complete` → Validates and resets password --- #### `POST /verification-services/password-reset-by-mobile/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------- | | `mobile` | String | Yes | Mobile number | **Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` #### `POST /verification-services/password-reset-by-mobile/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ---------------- | | `email` | String | Yes | Associated email | | `secretCode` | String | Yes | Code via SMS | | `password` | String | Yes | New password | **Response** ```json { "status": "OK", "isVerified": true, "mobile": "+1 444 ....", // in testMode "userId": "user-uuid", } ``` --- ### 6.3 Behavioral Notes * Cooldown: 60s resend * Expiration: 24h * One session per user * Works without an active login session --- ## 7. Verification Method Types ### 7.1 `byCode` User manually enters the 6-digit code in frontend. ### 7.2 `byLink` Frontend handles a one-click verification via email/SMS link containing code parameters. ## 8) `GET /currentuser` — Current Session **Purpose** Return the currently authenticated user’s session. **Route Type** `sessionInfo` **Authentication** Requires a valid access token (header or cookie). ### Request *No parameters.* ### Example ```js axios.get("/currentuser", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) Returns the session object (identity, tenancy, token metadata): ```json { "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", "roleId": "user", "tenantId": "abc123", "accessToken": "jwt-token-string", "...": "..." } ``` ### Errors * **401 Unauthorized** — No active session/token ```json { "status": "ERR", "message": "No login found" } ``` **Notes** * Commonly called by web/mobile clients after login to hydrate session state. * Includes key identity/tenant fields and a token reference (if applicable). * Ensure a valid token is supplied to receive a 200 response. --- ## 9) `GET /permissions` — List Effective Permissions **Purpose** Return all effective permission grants for the current user. **Route Type** `permissionFetch` **Authentication** Requires a valid access token. ### Request *No parameters.* ### Example ```js axios.get("/permissions", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) Array of permission grants (aligned with `givenPermissions`): ```json [ { "id": "perm1", "permissionName": "adminPanel.access", "roleId": "admin", "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" }, { "id": "perm2", "permissionName": "orders.manage", "roleId": null, "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" } ] ``` **Field meanings (per item):** * `permissionName`: Granted permission key. * `roleId`: Present if granted via role. * `subjectUserId`: Present if granted directly to the user. * `subjectUserGroupId`: Present if granted via group. * `objectId`: Present if scoped to a specific object (OBAC). * `canDo`: `true` if enabled, `false` if restricted. ### Errors * **401 Unauthorized** — No active session ```json { "status": "ERR", "message": "No login found" } ``` * **500 Internal Server Error** — Unexpected failure **Notes** * Available on all Mindbricks-generated services (not only Auth). * **Auth service:** Reads live `givenPermissions` from DB. * **Other services:** Typically respond from a cached/projected view (e.g., ElasticSearch) for faster checks. > **Tip:** Cache permission results client-side/server-side and refresh after login or permission updates. --- ## 10) `GET /permissions/:permissionName` — Check Permission Scope **Purpose** Check whether the current user has a specific permission and return any scoped object exceptions/inclusions. **Route Type** `permissionScopeCheck` **Authentication** Requires a valid access token. ### Path Parameters | Name | Type | Required | Source | | ---------------- | ------ | -------- | ------------------------------- | | `permissionName` | String | Yes | `request.params.permissionName` | ### Example ```js axios.get("/permissions/orders.manage", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) ```json { "canDo": true, "exceptions": [ "a1f2e3d4-xxxx-yyyy-zzzz-object1", "b2c3d4e5-xxxx-yyyy-zzzz-object2" ] } ``` **Interpretation** * If `canDo: true`: permission is generally granted **except** the listed `exceptions` (restrictions). * If `canDo: false`: permission is generally **not** granted, **only** allowed for the listed `exceptions` (selective overrides). * `exceptions` contains object IDs (UUID strings) from the relevant domain model. ### Errors * **401 Unauthorized** — No active session/token. ## Services And Data Object ## Auth Service Authentication service for the project ### Auth Service Data Objects **User** A data object that stores the user information and handles login settings. ### Auth Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` ### `Get User` API This api is used by admin roles or the users themselves to get the user profile information. **Rest Route** The `getUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `getUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users/:userId** ```js axios({ method: 'GET', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update User` API This route is used by admins to update user profiles. **Rest Route** The `updateUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `updateUser` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/users/:userId** ```js axios({ method: 'PATCH', url: `/v1/users/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Profile` API This route is used by users to update their profiles. **Rest Route** The `updateProfile` API REST controller can be triggered via the following route: `/v1/profile/:userId` **Rest Request Parameters** The `updateProfile` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/profile/:userId** ```js axios({ method: 'PATCH', url: `/v1/profile/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create User` API This api is used by admin roles to create a new user manually from admin panels **Rest Route** The `createUser` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `createUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | email | String | true | request.body?.email | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **email** : A string value to represent the user's email. **password** : A string value to represent the user's password. It will be stored as hashed. **fullname** : A string value to represent the fullname of the user **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/users** ```js axios({ method: 'POST', url: '/v1/users', data: { avatar:"String", email:"String", password:"String", fullname:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete User` API This api is used by admins to delete user profiles. **Rest Route** The `deleteUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `deleteUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/users/:userId** ```js axios({ method: 'DELETE', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Archive Profile` API This api is used by users to archive their profiles. **Rest Route** The `archiveProfile` API REST controller can be triggered via the following route: `/v1/archiveprofile/:userId` **Rest Request Parameters** The `archiveProfile` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/archiveprofile/:userId** ```js axios({ method: 'DELETE', url: `/v1/archiveprofile/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Users` API The list of users is filtered by the tenantId. **Rest Route** The `listUsers` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `listUsers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users** ```js axios({ method: 'GET', url: '/v1/users', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Search Users` API The list of users is filtered by the tenantId. **Rest Route** The `searchUsers` API REST controller can be triggered via the following route: `/v1/searchusers` **Rest Request Parameters** The `searchUsers` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | keyword | String | true | request.query?.keyword | **keyword** : **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchusers** ```js axios({ method: 'GET', url: '/v1/searchusers', data: { }, params: { keyword:'"String"', } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Userrole` API This route is used by admin roles to update the user role.The default role is user when a user is registered. A user's role can be updated by superAdmin or admin **Rest Route** The `updateUserRole` API REST controller can be triggered via the following route: `/v1/userrole/:userId` **Rest Request Parameters** The `updateUserRole` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | roleId | String | true | request.body?.roleId | **userId** : This id paremeter is used to select the required data object that will be updated **roleId** : The new roleId of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userrole/:userId** ```js axios({ method: 'PATCH', url: `/v1/userrole/${userId}`, data: { roleId:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpassword` API This route is used to update the password of users in the profile page by users themselves **Rest Route** The `updateUserPassword` API REST controller can be triggered via the following route: `/v1/userpassword/:userId` **Rest Request Parameters** The `updateUserPassword` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | oldPassword | String | true | request.body?.oldPassword | | newPassword | String | true | request.body?.newPassword | **userId** : This id paremeter is used to select the required data object that will be updated **oldPassword** : The old password of the user that will be overridden bu the new one. Send for double check. **newPassword** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpassword/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpassword/${userId}`, data: { oldPassword:"String", newPassword:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpasswordbyadmin` API This route is used to change any user password by admins only. Superadmin can chnage all passwords, admins can change only nonadmin passwords **Rest Route** The `updateUserPasswordByAdmin` API REST controller can be triggered via the following route: `/v1/userpasswordbyadmin/:userId` **Rest Request Parameters** The `updateUserPasswordByAdmin` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | password | String | true | request.body?.password | **userId** : This id paremeter is used to select the required data object that will be updated **password** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpasswordbyadmin/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpasswordbyadmin/${userId}`, data: { password:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Briefuser` API This route is used by public to get simple user profile information. **Rest Route** The `getBriefUser` API REST controller can be triggered via the following route: `/v1/briefuser/:userId` **Rest Request Parameters** The `getBriefUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/briefuser/:userId** ```js axios({ method: 'GET', url: `/v1/briefuser/${userId}`, data: { }, params: { } }); ``` **REST Response** This route's response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "fullname": "String", "avatar": "String", "isActive": true } } ``` ### `Register User` API This api is used by public users to register themselves **Rest Route** The `registerUser` API REST controller can be triggered via the following route: `/v1/registeruser` **Rest Request Parameters** The `registerUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **password** : The password defined by the the user that is being registered. **fullname** : The fullname defined by the the user that is being registered. **email** : The email defined by the the user that is being registered. **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## AuctionOffer Service Handles auction bids and fixed-price offers for product listings, enforces real-time auction state, handles strict offer workflows including counter-offers, and triggers domain events for bid/offer notifications. No payment or frontend aggregation logic included. ### AuctionOffer Service Data Objects **AuctionOfferOffer** Represents an offer (best offer/counter-offer) made on a fixed-price product. Tracks buyer, seller, amounts, currency, state transitions, counter-offers, and expiry. **AuctionOfferBid** Represents an individual bid placed on an auction-type product. Linked to product and user, tracks bid amount, currency, status (ACTIVE, WON, LOST, CANCELLED), and time placed. ### AuctionOffer Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auctionoffer-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auctionoffer-api` * **Production:** `https://ebaycclone.mindbricks.co/auctionoffer-api` ### `Update Auctionofferoffer` API Updates offer: accepts/declines/counters by seller, withdraws by buyer before response. Enforces status transition rules, sets respondedAt. Triggers event. **Rest Route** The `updateAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `updateAuctionOfferOffer` api has got 8 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | message | String | false | request.body?.message | | status | Enum | false | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | **auctionOfferOfferId** : This id paremeter is used to select the required data object that will be updated **counterOfferId** : References another offer (counter-offer chain). **counterMessage** : Message accompanying seller's counter-offer (optional). **counterAmount** : Counter-offer amount (when offer is COUNTERED). **message** : Message/special notes from buyer (optional). **status** : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). **expiresAt** : When this offer expires (optional). **respondedAt** : When the seller (or buyer, for counter-offer) responded/updated the offer status. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Auctionofferbid` API Creates a new bid for an auction product. Validates auction status, not seller, product type, bid window, and ensures min. increment. Updates product.currentBid and product.highestBidderId atomically. Triggers notification event. **Rest Route** The `createAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids` **Rest Request Parameters** The `createAuctionOfferBid` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | bidAmount | Double | true | request.body?.bidAmount | | currency | String | true | request.body?.currency | | status | Enum | true | request.body?.status | | productId | ID | true | request.body?.productId | **bidAmount** : Bid amount placed by the user. **currency** : ISO currency for the bid (e.g., USD, EUR). **status** : Bid status: ACTIVE, WON, LOST, CANCELLED. **productId** : Product being bid on (must be AUCTION type). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/auctionofferbids** ```js axios({ method: 'POST', url: '/v1/auctionofferbids', data: { bidAmount:"Double", currency:"String", status:"Enum", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Auctionofferbid` API Gets a single bid (only visible to owner/admin or for auction history). **Rest Route** The `getAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `getAuctionOfferBid` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | **auctionOfferBidId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'GET', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Auctionofferoffer` API Gets a single offer (shown to buyer/seller or admin). **Rest Route** The `getAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `getAuctionOfferOffer` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | **auctionOfferOfferId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'GET', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Auctionofferoffers` API Lists offers by product, user, status, or counterOffer chain. **Rest Route** The `listAuctionOfferOffers` API REST controller can be triggered via the following route: `/v1/auctionofferoffers` **Rest Request Parameters** The `listAuctionOfferOffers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers** ```js axios({ method: 'GET', url: '/v1/auctionofferoffers', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferOffers": [ { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Auctionofferbid` API Updates a bid’s status (allow only status update, e.g. CANCELLED, WIN/LOSE on admin settlement). Only owner/admin, and only if auction not ended or not settled. Triggers notification event. **Rest Route** The `updateAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `updateAuctionOfferBid` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | | status | Enum | false | request.body?.status | **auctionOfferBidId** : This id paremeter is used to select the required data object that will be updated **status** : Bid status: ACTIVE, WON, LOST, CANCELLED. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { status:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Auctionofferoffer` API Creates a new offer for a fixed-price product, validating acceptOffers, type, eligibility, and product/seller/buyer active. Defaults to PENDING state. Triggers notification event. **Rest Route** The `createAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers` **Rest Request Parameters** The `createAuctionOfferOffer` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | productId | ID | true | request.body?.productId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | offerAmount | Double | true | request.body?.offerAmount | | message | String | false | request.body?.message | | status | Enum | true | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | **currency** : ISO currency (e.g., USD, EUR) for the offer. **productId** : Product the offer applies to (must be fixed-price, acceptOffers true). **counterOfferId** : References another offer (counter-offer chain). **counterMessage** : Message accompanying seller's counter-offer (optional). **counterAmount** : Counter-offer amount (when offer is COUNTERED). **offerAmount** : Primary offer amount from buyer. **message** : Message/special notes from buyer (optional). **status** : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). **expiresAt** : When this offer expires (optional). **respondedAt** : When the seller (or buyer, for counter-offer) responded/updated the offer status. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/auctionofferoffers** ```js axios({ method: 'POST', url: '/v1/auctionofferoffers', data: { currency:"String", productId:"ID", counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", offerAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Auctionofferbids` API Lists bids by product, user, or auction, supports history/analytics. **Rest Route** The `listAuctionOfferBids` API REST controller can be triggered via the following route: `/v1/auctionofferbids` **Rest Request Parameters** The `listAuctionOfferBids` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids** ```js axios({ method: 'GET', url: '/v1/auctionofferbids', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBids", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferBids": [ { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Auctionofferbid` API Soft-deletes a bid (for admin or self before auction ends). **Rest Route** The `deleteAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `deleteAuctionOfferBid` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | **auctionOfferBidId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Auctionofferoffer` API Soft-deletes an offer (allowed only in non-accepted/expired state). **Rest Route** The `deleteAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `deleteAuctionOfferOffer` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | **auctionOfferOfferId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## CategoryManagement Service Handles product categories and subcategories for marketplace browsing and classification, supporting public discovery plus admin-only management. ### CategoryManagement Service Data Objects **Category** Represents a product category in the marketplace (e.g., Electronics, Clothing, Toys), used for browsing, filtering, and discovery. Admins manage categories. **Subcategory** Represents a subcategory within a parent category (e.g., 'Smartphones' under 'Electronics'). Used for more granular product discovery and navigation. 'group' categorizes special display logic. ### CategoryManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/categorymanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/categorymanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/categorymanagement-api` ### `Delete Category` API Soft-delete a category (admin-only). **Rest Route** The `deleteCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `deleteCategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | **categoryId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/categories/:categoryId** ```js axios({ method: 'DELETE', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Subcategory` API Get a subcategory by ID. Public - only active subcategories returned except for admin. **Rest Route** The `getSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `getSubcategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | **subcategoryId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/subcategories/:subcategoryId** ```js axios({ method: 'GET', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Category` API Get a single category by ID. Public - only active categories returned (for non-admins). **Rest Route** The `getCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `getCategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | **categoryId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/categories/:categoryId** ```js axios({ method: 'GET', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Subcategory` API Update subcategory (admin-only), including group enum change. **Rest Route** The `updateSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `updateSubcategory` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | name | String | false | request.body?.name | | group | Enum | false | request.body?.group | **subcategoryId** : This id paremeter is used to select the required data object that will be updated **categoryId** : Reference to the parent category (category.id). **name** : Display name of the subcategory. **group** : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/subcategories/:subcategoryId** ```js axios({ method: 'PATCH', url: `/v1/subcategories/${subcategoryId}`, data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Subcategories` API List all subcategories for browsing/filtering, with support for group enum and parent category queries. Only active subcategories shown to public/non-admin users. **Rest Route** The `listSubcategories` API REST controller can be triggered via the following route: `/v1/subcategories` **Rest Request Parameters** The `listSubcategories` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/subcategories** ```js axios({ method: 'GET', url: '/v1/subcategories', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "subcategories": [ { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Subcategory` API Soft-delete a subcategory (admin-only). **Rest Route** The `deleteSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `deleteSubcategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | **subcategoryId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/subcategories/:subcategoryId** ```js axios({ method: 'DELETE', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Categories` API List all categories for browsing and filtering. Only active categories shown to public/non-admin users. **Rest Route** The `listCategories` API REST controller can be triggered via the following route: `/v1/categories` **Rest Request Parameters** The `listCategories` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/categories** ```js axios({ method: 'GET', url: '/v1/categories', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "categories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "categories": [ { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Category` API Update category details (admin-only). **Rest Route** The `updateCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `updateCategory` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | false | request.body?.title | **categoryId** : This id paremeter is used to select the required data object that will be updated **imageUrl** : URL for category image/avatar (optional, used for homepage visuals). **subtitle** : Optional short description for UI/tooltips. **title** : Display name of the category. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/categories/:categoryId** ```js axios({ method: 'PATCH', url: `/v1/categories/${categoryId}`, data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Subcategory` API Create a new subcategory under a given category (admin-only), with enum group constraint. **Rest Route** The `createSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories` **Rest Request Parameters** The `createSubcategory` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.body?.categoryId | | name | String | true | request.body?.name | | group | Enum | true | request.body?.group | **categoryId** : Reference to the parent category (category.id). **name** : Display name of the subcategory. **group** : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/subcategories** ```js axios({ method: 'POST', url: '/v1/subcategories', data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Category` API Create a new category (admin-only) for product classification. **Rest Route** The `createCategory` API REST controller can be triggered via the following route: `/v1/categories` **Rest Request Parameters** The `createCategory` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | true | request.body?.title | **imageUrl** : URL for category image/avatar (optional, used for homepage visuals). **subtitle** : Optional short description for UI/tooltips. **title** : Display name of the category. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/categories** ```js axios({ method: 'POST', url: '/v1/categories', data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## Messaging Service In-app messaging service for direct user-to-user text messages (buyers/sellers). Stores, retrieves, and manages user conversations. Launch version: text-only. ### Messaging Service Data Objects **MessagingMessage** A direct, text-only in-app message between two users (buyer/seller); stores sender, recipient, content, read status, and timestamp. ### Messaging Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/messaging-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/messaging-api` * **Production:** `https://ebaycclone.mindbricks.co/messaging-api` ### `List Messagingmessages` API List all messages in the conversation between the logged-in user and another party, ordered by sentAt descending. Can filter unread with isRead. Returns only messages visible to user (isActive). **Rest Route** The `listMessagingMessages` API REST controller can be triggered via the following route: `/v1/messagingmessages` **Rest Request Parameters** The `listMessagingMessages` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages** ```js axios({ method: 'GET', url: '/v1/messagingmessages', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessages", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "messagingMessages": [ { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Messagingmessage` API Send a new text message from the logged-in user to a recipient. Sender is set from session. Launch version supports only text content. **Rest Route** The `createMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages` **Rest Request Parameters** The `createMessagingMessage` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | toUserId | ID | true | request.body?.toUserId | | content | String | true | request.body?.content | | isRead | Boolean | true | request.body?.isRead | **toUserId** : Recipient (user) of this message. **content** : Text content of the message. No files or attachments for launch. **isRead** : If true, recipient has marked this message as read. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/messagingmessages** ```js axios({ method: 'POST', url: '/v1/messagingmessages', data: { toUserId:"ID", content:"String", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Messagingmessage` API Update a message (mark as read/unread). Only the recipient or admin can change isRead. No content edits. Sender, content, sentAt are immutable. **Rest Route** The `updateMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `updateMessagingMessage` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | | isRead | Boolean | false | request.body?.isRead | **messagingMessageId** : This id paremeter is used to select the required data object that will be updated **isRead** : If true, recipient has marked this message as read. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'PATCH', url: `/v1/messagingmessages/${messagingMessageId}`, data: { isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Messagingmessage` API Get a message by ID. Only accessible to the sender, the recipient, or an admin. Used for message detail view or reading a single message in a thread. **Rest Route** The `getMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `getMessagingMessage` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | **messagingMessageId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'GET', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Messagingmessage` API Delete a message (soft-delete). Only sender, recipient, or admin may delete a message. Deletion only hides it for the user; not a full erase unless both delete. **Rest Route** The `deleteMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `deleteMessagingMessage` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | **messagingMessageId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'DELETE', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## NotificationManagement Service Handles storage, management, and event-driven delivery of in-app and email notifications for user-impacting system events (bids, offers, orders, feedback, messaging, etc.). Supports marking notifications as read/unread, structured filtering by event type/channel, and always returns in-app notifications ordered by recency. ### NotificationManagement Service Data Objects **Notification** Stores and manages in-app and email notifications tied to user-facing events like bids, offers, orders, messaging, shipment, and feedback. Includes event type (notificationType) for filter/search, arbitrary event payload, and delivery channel. Soft-delete enforced. In-app notifications always sorted by createdAt DESC on retrieval. ### NotificationManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/notificationmanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/notificationmanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/notificationmanagement-api` ### `Create Notification` API Creates a notification entry in response to a system/business event. Only allowed for system/event processes and admins (not standard user/action). Typically event-driven, receives userId, notificationType, payload, and channel. **Rest Route** The `createNotification` API REST controller can be triggered via the following route: `/v1/notifications` **Rest Request Parameters** The `createNotification` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationType | Enum | true | request.body?.notificationType | | userId | ID | true | request.body?.userId | | channel | Enum | true | request.body?.channel | | payload | Object | true | request.body?.payload | | isRead | Boolean | true | request.body?.isRead | **notificationType** : Type of event triggering notification (e.g., BID_UPDATED, ORDER_SHIPPED, MESSAGE_RECEIVED, etc.). Used for display/icon and query filter. **userId** : User receiving the notification (recipient). **channel** : Channel by which notification is delivered: IN_APP or EMAIL. **payload** : Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. **isRead** : Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/notifications** ```js axios({ method: 'POST', url: '/v1/notifications', data: { notificationType:"Enum", userId:"ID", channel:"Enum", payload:"Object", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Notification` API Updates a notification (mark as read/unread, payload patch for e.g. admin fix). Only receiver (userId) or admins may update. isRead is primary update scenario; others very limited. **Rest Route** The `updateNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `updateNotification` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | | payload | Object | false | request.body?.payload | | isRead | Boolean | false | request.body?.isRead | **notificationId** : This id paremeter is used to select the required data object that will be updated **payload** : Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. **isRead** : Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/notifications/:notificationId** ```js axios({ method: 'PATCH', url: `/v1/notifications/${notificationId}`, data: { payload:"Object", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Notifications` API Returns filtered list of notifications for a user, with optional filters: notificationType, isRead, channel. Always sorted by createdAt (descending) for in-app notifications. Only retrieval allowed for owner/admin. **Rest Route** The `listNotifications` API REST controller can be triggered via the following route: `/v1/notifications` **Rest Request Parameters** The `listNotifications` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/notifications** ```js axios({ method: 'GET', url: '/v1/notifications', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notifications", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "notifications": [ { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Notification` API Soft-delete a notification record. Only receiver or admin may delete. **Rest Route** The `deleteNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `deleteNotification` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | **notificationId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/notifications/:notificationId** ```js axios({ method: 'DELETE', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Notification` API Retrieves a notification for the receiver or admin. Used to populate content on detail/expanded view. **Rest Route** The `getNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `getNotification` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | **notificationId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/notifications/:notificationId** ```js axios({ method: 'GET', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## SearchIndexing Service Maintains the denormalized search index (materialized view) for global, public search across products, sellers, categories, and subcategories. Handles indexing in response to entity events and exposes optimized query endpoints for BFF/aggregator. ### SearchIndexing Service Data Objects **SearchIndex** Materialized/denormalized search index record for a marketplace entity (product, seller, category, subcategory). Used exclusively for high-speed querying in BFF global/public search. ### SearchIndexing Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/searchindexing-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/searchindexing-api` * **Production:** `https://ebaycclone.mindbricks.co/searchindexing-api` ### `List Searchindexes` API List/search search index entries by type or referenceId (used by BFF/global search). Always excludes inactive (soft-deleted) records. Supports filtering and full-text search filters by documentType/referenceId for admin/maintenance use. **Rest Route** The `listSearchIndexes` API REST controller can be triggered via the following route: `/v1/searchindexes` **Rest Request Parameters** The `listSearchIndexes` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchindexes** ```js axios({ method: 'GET', url: '/v1/searchindexes', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndices", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "searchIndices": [ { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Searchindex` API Update an existing searchIndex record (by (documentType, referenceId) or id). Used in response to events (entity edit, data change); internal/automation/admin only. **Rest Route** The `updateSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `updateSearchIndex` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | | documentType | Enum | false | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | false | request.body?.indexedAt | **searchIndexId** : This id paremeter is used to select the required data object that will be updated **documentType** : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY **document** : Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. **referenceId** : ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. **indexedAt** : Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/searchindexs/:searchIndexId** ```js axios({ method: 'PATCH', url: `/v1/searchindexs/${searchIndexId}`, data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Searchindex` API Soft-delete a searchIndex record (by id or by (documentType, referenceId)). Typical use: in response to entity soft-delete; internal/automation/admin only. **Rest Route** The `deleteSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `deleteSearchIndex` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | **searchIndexId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/searchindexs/:searchIndexId** ```js axios({ method: 'DELETE', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Searchindex` API Create a new searchIndex record (internal, used by event triggers and admin tools only). Typically called when a new product/seller/category/subcategory is created. **Rest Route** The `createSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs` **Rest Request Parameters** The `createSearchIndex` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | documentType | Enum | true | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | true | request.body?.indexedAt | **documentType** : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY **document** : Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. **referenceId** : ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. **indexedAt** : Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/searchindexs** ```js axios({ method: 'POST', url: '/v1/searchindexs', data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Searchindex` API Get a single denormalized index record (by id, or documentType+referenceId). Used by BFF for full entity search. Always excludes inactive records unless forced (admin only path). **Rest Route** The `getSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `getSearchIndex` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | **searchIndexId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchindexs/:searchIndexId** ```js axios({ method: 'GET', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## AdminModeration Service Administrative backend service for moderation and manual override actions. Responsible for logging all admin interventions (user/product/feedback/media/category/order/notification/searchindex moderation), triggering corrections via interservice calls, and providing comprehensive audit trails for compliance. ### AdminModeration Service Data Objects **ModerationAction** Audit record for all admin moderation/override actions affecting core business entities. Links to admin, timestamp, entity type/ID, action performed, and reason. ### AdminModeration Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/adminmoderation-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/adminmoderation-api` * **Production:** `https://ebaycclone.mindbricks.co/adminmoderation-api` ### `Get Moderationaction` API Get a single moderation action log by ID. Used to review admin audit trails; accessible only to platform admins. **Rest Route** The `getModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `getModerationAction` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | **moderationActionId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/moderationactions/:moderationActionId** ```js axios({ method: 'GET', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Moderationaction` API Soft-deletes a moderation action log record (dangerous; allowed only to superadmins or strict manual correction), primarily for audit correction or internal error cleanup. Usually, moderation logs are immutable. **Rest Route** The `deleteModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `deleteModerationAction` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | **moderationActionId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/moderationactions/:moderationActionId** ```js axios({ method: 'DELETE', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Moderationaction` API Logs an admin moderation or override action in the system for audit and traceability. Requires admin login, takes context from session, and creates an audit entry for any admin operation over any entity type. **Rest Route** The `createModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions` **Rest Request Parameters** The `createModerationAction` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | entityId | ID | true | request.body?.entityId | | entityType | Enum | true | request.body?.entityType | | reason | String | true | request.body?.reason | | actionType | Enum | true | request.body?.actionType | **entityId** : ID of target entity affected by moderation (user/product/etc). **entityType** : Type of entity affected (USER, PRODUCT, FEEDBACK, MEDIA, CATEGORY, NOTIFICATION, ORDER, SEARCHINDEX). **reason** : Explanation or justification for the moderation action performed. **actionType** : Type of moderation action (e.g., SOFT_DELETE, RESTORE, UPDATE_ROLE, MANUAL_CORRECTION, MEDIA_FLAG, INDEX_REBUILD, PAYMENT_FIX, FEEDBACK_OVERRIDE, ADMIN_NOTE). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/moderationactions** ```js axios({ method: 'POST', url: '/v1/moderationactions', data: { entityId:"ID", entityType:"Enum", reason:"String", actionType:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Moderationactions` API List moderation actions for admin dashboard/audit search. Supports filtering by admin, entityType, entityId, actionType, and date. Always sorted by most recent action. **Rest Route** The `listModerationActions` API REST controller can be triggered via the following route: `/v1/moderationactions` **Rest Request Parameters** The `listModerationActions` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/moderationactions** ```js axios({ method: 'GET', url: '/v1/moderationactions', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationActions", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "moderationActions": [ { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Moderationaction` API Allows update of explanation/note on a moderation action for correction (typically by admin or superadmin only). No entity/type/admin may be changed after creation; only 'reason' is editable for audit consistency. **Rest Route** The `updateModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `updateModerationAction` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | | reason | String | false | request.body?.reason | **moderationActionId** : This id paremeter is used to select the required data object that will be updated **reason** : Explanation or justification for the moderation action performed. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/moderationactions/:moderationActionId** ```js axios({ method: 'PATCH', url: `/v1/moderationactions/${moderationActionId}`, data: { reason:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## WatchlistCart Service Handles user watchlists (with custom folders) and shopping cart preparation for checkout, strictly enforcing only fixed-price products in carts, supporting item moves/bulk operations, and robust default/folder logic.. ### WatchlistCart Service Data Objects **WatchlistItem** Item in a user’s watchlist, optionally in a named folder; references product and user. **CartItem** Single product pending checkout in a user’s cart. Only fixed-price products permitted; quantity supported for multi-unit purchases (if allowed). **WatchlistList** A named folder/list in a user’s watchlist. Default list exists for all users. Custom lists may be created and deleted. ### WatchlistCart Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/watchlistcart-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/watchlistcart-api` * **Production:** `https://ebaycclone.mindbricks.co/watchlistcart-api` ### `List Watchlistlist` API List all lists in user’s watchlists. Supports listing by listId for folders. **Rest Route** The `listWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists` **Rest Request Parameters** The `listWatchlistList` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/watchlistlists** ```js axios({ method: 'GET', url: '/v1/watchlistlists', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Cartitems` API List all cart items for a user (pending checkout). **Rest Route** The `listCartItems` API REST controller can be triggered via the following route: `/v1/cartitems` **Rest Request Parameters** The `listCartItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/cartitems** ```js axios({ method: 'GET', url: '/v1/cartitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "price": "Double", "title": "String", "type": "Enum", "type_idx": "Integer", "mediaAssetIds": "ID" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Cartitem` API Remove an item from the user’s cart. **Rest Route** The `deleteCartItem` API REST controller can be triggered via the following route: `/v1/cartitems/:cartItemId` **Rest Request Parameters** The `deleteCartItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | **cartItemId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/cartitems/:cartItemId** ```js axios({ method: 'DELETE', url: `/v1/cartitems/${cartItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Watchlistitem` API Add product to user’s watchlist (default or target list/folder). One (user, product, list) per item enforced. Block duplicates. **Rest Route** The `createWatchlistItem` API REST controller can be triggered via the following route: `/v1/watchlistitems` **Rest Request Parameters** The `createWatchlistItem` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | productId | ID | true | request.body?.productId | | listId | ID | false | request.body?.listId | **addedAt** : Timestamp watchlist item created. **productId** : Referenced product in the watchlist. **listId** : Owning watchlistList; null if in default watchlist. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/watchlistitems** ```js axios({ method: 'POST', url: '/v1/watchlistitems', data: { addedAt:"Date", productId:"ID", listId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Watchlistitems` API List all products in user’s watchlists. Supports listing by listId for folders. **Rest Route** The `listWatchlistItems` API REST controller can be triggered via the following route: `/v1/watchlistitems` **Rest Request Parameters** The `listWatchlistItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/watchlistitems** ```js axios({ method: 'GET', url: '/v1/watchlistitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Cartitemquantity` API Change the quantity for a cart item. User must own the item. **Rest Route** The `updateCartItemQuantity` API REST controller can be triggered via the following route: `/v1/cartitemquantity/:cartItemId` **Rest Request Parameters** The `updateCartItemQuantity` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | | quantity | Integer | false | request.body?.quantity | **cartItemId** : This id paremeter is used to select the required data object that will be updated **quantity** : How many units (if product allows). **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/cartitemquantity/:cartItemId** ```js axios({ method: 'PATCH', url: `/v1/cartitemquantity/${cartItemId}`, data: { quantity:"Integer", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Watchlistlist` API Create a new custom watchlist folder. Name must be unique per user; ‘Default’ is reserved for system. **Rest Route** The `createWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists` **Rest Request Parameters** The `createWatchlistList` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | name | String | true | request.body?.name | **name** : Custom folder or list name. 'Default' is reserved (non-deletable for each user). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/watchlistlists** ```js axios({ method: 'POST', url: '/v1/watchlistlists', data: { name:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Watchlistlist` API Delete a custom watchlist (folder). Items are reassigned to user’s default list. Cannot delete default list. **Rest Route** The `deleteWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists/:watchlistListId` **Rest Request Parameters** The `deleteWatchlistList` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistListId | ID | true | request.params?.watchlistListId | **watchlistListId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistlists/:watchlistListId** ```js axios({ method: 'DELETE', url: `/v1/watchlistlists/${watchlistListId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Watchlistitem` API Remove a product from a user’s watchlist. **Rest Route** The `deleteWatchlistItem` API REST controller can be triggered via the following route: `/v1/watchlistitems/:watchlistItemId` **Rest Request Parameters** The `deleteWatchlistItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistItemId | ID | true | request.params?.watchlistItemId | **watchlistItemId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistitems/:watchlistItemId** ```js axios({ method: 'DELETE', url: `/v1/watchlistitems/${watchlistItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Cartitem` API Add an item to the user’s cart. Only fixed-price products allowed. Duplicates not permitted. **Rest Route** The `createCartItem` API REST controller can be triggered via the following route: `/v1/cartitems` **Rest Request Parameters** The `createCartItem` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | **addedAt** : Timestamp added to cart. **quantity** : How many units (if product allows). **productId** : Product being checked out. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/cartitems** ```js axios({ method: 'POST', url: '/v1/cartitems', data: { addedAt:"Date", quantity:"Integer", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Do Userwatchlist` API userwatchlist **Rest Route** The `userwatchlist` API REST controller can be triggered via the following route: `/v1/userwatchlist` **Rest Request Parameters** The `userwatchlist` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userwatchlist** ```js axios({ method: 'GET', url: '/v1/userwatchlist', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Usercartitems` API list all cart items adde by user **Rest Route** The `listUserCartItems` API REST controller can be triggered via the following route: `/v1/usercartitems` **Rest Request Parameters** The `listUserCartItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/usercartitems** ```js axios({ method: 'GET', url: '/v1/usercartitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "shipping": "Double" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Do Userwatchlistlists` API list all watch lists created by user **Rest Route** The `userwatchlistlists` API REST controller can be triggered via the following route: `/v1/userwatchlistlists` **Rest Request Parameters** The `userwatchlistlists` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userwatchlistlists** ```js axios({ method: 'GET', url: '/v1/userwatchlistlists', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ## ProductListing Service Handles product listings (both auction and fixed-price), image/media storage with validations, enforces immutable type, soft-delete, and public product discovery. ### ProductListing Service Data Objects **ProductListingMedia** Stores and manages images/media associated with products, including secure URL, MIME type, and size validation. Each asset can be used by multiple products. **ProductListingProduct** Represents a single product listing (fixed-price or auction) in the marketplace, with seller, category, type, price information, shipping details, media references, and dynamic auction fields. ### ProductListing Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/productlisting-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/productlisting-api` * **Production:** `https://ebaycclone.mindbricks.co/productlisting-api` ### `List Productlistingmedia` API List all media assets (admin or for media management/bulk preview). **Rest Route** The `listProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias` **Rest Request Parameters** The `listProductListingMedia` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias** ```js axios({ method: 'GET', url: '/v1/productlistingmedias', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedias", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingMedias": [ { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Productlistingproduct` API Get a single product listing. Checks isActive and public status. Includes media, category, subcategory, and seller info via joins. **Rest Route** The `getProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `getProductListingProduct` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | **productListingProductId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'GET', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Productlistingownproducts` API listing the loggedin user's products **Rest Route** The `listProductListingOwnProducts` API REST controller can be triggered via the following route: `/v1/productlistingownproducts` **Rest Request Parameters** The `listProductListingOwnProducts` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingownproducts** ```js axios({ method: 'GET', url: '/v1/productlistingownproducts', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Productlistingmedia` API Get a single media asset by ID (for admin or to display in product UI). **Rest Route** The `getProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` **Rest Request Parameters** The `getProductListingMedia` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | **productListingMediaId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'GET', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Productlistingproducts` API List public product listings. Only isActive=true records are returned. Includes category, subcategory, seller, media joins. Supports filtering. **Rest Route** The `listProductListingProducts` API REST controller can be triggered via the following route: `/v1/productlistingproducts` **Rest Request Parameters** The `listProductListingProducts` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts** ```js axios({ method: 'GET', url: '/v1/productlistingproducts', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Productlistingproduct` API Soft-delete a product listing. Only owner or admin can delete. **Rest Route** The `deleteProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `deleteProductListingProduct` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | **productListingProductId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'DELETE', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Productlistingproduct` API Update a product listing. Product type cannot be changed (immutable). **Rest Route** The `updateProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `updateProductListingProduct` api has got 21 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | | currency | String | false | request.body?.currency | | description | Text | false | request.body?.description | | condition | Enum | false | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | false | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | false | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | false | request.body?.shippingMethod | | shipping | Double | false | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | false | request.body?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | **productListingProductId** : This id paremeter is used to select the required data object that will be updated **currency** : ISO currency code (e.g. USD, EUR) **description** : Product detailed description **condition** : Condition of product: BRAND_NEW, NEW, or USED **startBid** : The opening bid value (for auction type products) **endPrice** : Optional immediate sale/upper end price for auction (if AUCTION type) **price** : Product price (required if fixed price type) **title** : Product title **startPrice** : Minimum starting price for auction (required if AUCTION type) **endBid** : The upper (max) bid value for auction products (if any) **estimatedDelivery** : Estimated delivery date for this product **shippingCurrency** : Currency code for shipping cost **mediaAssetIds** : References to associated product/media assets **shippingMethod** : Shipping option for product: STANDARD, EXPRESS, or FREE **shipping** : Shipping cost for this product **startBidDate** : Date/time when auction bidding begins **subcategoryId** : Reference to subcategory **categoryId** : Reference to parent category **endBidDate** : Date/time when auction bidding ends **currentBid** : Current highest bid for auction-type product (updated atomically on bid placement) **highestBidderId** : User ID of current highest bidder (auction-only, updated by auction microservice) **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'PATCH', url: `/v1/productlistingproducts/${productListingProductId}`, data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Productlistingproduct` API Create a new product listing (fixed or auction), conditioned on product type. Type is immutable after creation. **Rest Route** The `createProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts` **Rest Request Parameters** The `createProductListingProduct` api has got 21 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | description | Text | true | request.body?.description | | condition | Enum | true | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | true | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | type | Enum | true | request.body?.type | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | true | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | true | request.body?.shippingMethod | | shipping | Double | true | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | true | request.body?.subcategoryId | | categoryId | ID | true | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | **currency** : ISO currency code (e.g. USD, EUR) **description** : Product detailed description **condition** : Condition of product: BRAND_NEW, NEW, or USED **startBid** : The opening bid value (for auction type products) **endPrice** : Optional immediate sale/upper end price for auction (if AUCTION type) **price** : Product price (required if fixed price type) **title** : Product title **startPrice** : Minimum starting price for auction (required if AUCTION type) **type** : Product listing type, either FIXED or AUCTION (immutable after creation) **endBid** : The upper (max) bid value for auction products (if any) **estimatedDelivery** : Estimated delivery date for this product **shippingCurrency** : Currency code for shipping cost **mediaAssetIds** : References to associated product/media assets **shippingMethod** : Shipping option for product: STANDARD, EXPRESS, or FREE **shipping** : Shipping cost for this product **startBidDate** : Date/time when auction bidding begins **subcategoryId** : Reference to subcategory **categoryId** : Reference to parent category **endBidDate** : Date/time when auction bidding ends **currentBid** : Current highest bid for auction-type product (updated atomically on bid placement) **highestBidderId** : User ID of current highest bidder (auction-only, updated by auction microservice) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/productlistingproducts** ```js axios({ method: 'POST', url: '/v1/productlistingproducts', data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", type:"Enum", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Productlistingmedia` API Soft-delete a media asset (typically by admin or media owner for flagged/invalid content). **Rest Route** The `deleteProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` **Rest Request Parameters** The `deleteProductListingMedia` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | **productListingMediaId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'DELETE', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Productlistingmedia` API Create a new media asset record after validation. Used mainly by edge controller after upload. **Rest Route** The `createProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias` **Rest Request Parameters** The `createProductListingMedia` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | mimeType | String | true | request.body?.mimeType | | productId | ID | false | request.body?.productId | | url | String | true | request.body?.url | | size | Integer | true | request.body?.size | **mimeType** : MIME type of the uploaded media (e.g., image/jpeg) **productId** : ID of product associated with this media asset **url** : Secure, validated URL for the media asset (S3 or equivalent) **size** : Media size in bytes (for validation and quota) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/productlistingmedias** ```js axios({ method: 'POST', url: '/v1/productlistingmedias', data: { mimeType:"String", productId:"ID", url:"String", size:"Integer", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## OrderManagement Service Handles all marketplace orders, manual checkout flows for fixed-price/offer/auction settlements, Stripe payment processing and webhook reconciliation, explicit status updates (shipping, delivery, cancellation), and feedback eligibility via orderItems. ### OrderManagement Service Data Objects **OrderManagementOrder** Marketplace order record. Stores buyer, shipping, status, items, Stripe payment data, and manual shipment/delivery events. Only accessible to admins or the buyer/seller of order items. **OrderManagementOrderItem** Order line item representing purchase of a single product from a specific seller as part of an order. Enables feedback, delivery, and per-seller analytics. Immutable after order creation. **Sys_orderManagementOrderPayment** A payment storage object to store the payment life cyle of orders based on orderManagementOrder object. It is autocreated based on the source object's checkout config **Sys_paymentCustomer** A payment storage object to store the customer values of the payment platform **Sys_paymentMethod** A payment storage object to store the payment methods of the platform customers ### OrderManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/ordermanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/ordermanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/ordermanagement-api` ### `List Ordermanagementorders` API List orders, filtered for buyer and/or seller, or by admin. Includes select orderItems. **Rest Route** The `listOrderManagementOrders` API REST controller can be triggered via the following route: `/v1/ordermanagementorders` **Rest Request Parameters** The `listOrderManagementOrders` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ordermanagementorders', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Ordermanagementorderitem` API Get a specific order item (for feedback/business logic). **Rest Route** The `getOrderManagementOrderItem` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems/:orderManagementOrderItemId` **Rest Request Parameters** The `getOrderManagementOrderItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderItemId | ID | true | request.params?.orderManagementOrderItemId | **orderManagementOrderItemId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems/:orderManagementOrderItemId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderitems/${orderManagementOrderItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Ordermanagementorder` API Soft-delete/cancel order by admin or eligible actor prior to shipment. Sets status to CANCELLED and cancels active payment intent if pending. Irreversible and blocks feedback. **Rest Route** The `deleteOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` **Rest Request Parameters** The `deleteOrderManagementOrder` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorder` API Get single order by ID. Only accessible to admin, buyer, or relevant sellers of items within this order. Includes all orderItems. **Rest Route** The `getOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` **Rest Request Parameters** The `getOrderManagementOrder` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | **orderManagementOrderId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Ordermanagementorderstatus` API Update order status (manual shipment, delivery, cancellation/refund). Restricted: only seller of all items can mark as shipped, only buyer can confirm delivery, only admin can set refund/cancelled. Timestamps updated as per business rule. **Rest Route** The `updateOrderManagementOrderStatus` API REST controller can be triggered via the following route: `/v1/ordermanagementorderstatus/:orderManagementOrderId` **Rest Request Parameters** The `updateOrderManagementOrderStatus` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **status** : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderstatus/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderstatus/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Complete Orderstripewebhook` API Webhook endpoint called by Stripe to reconcile payment state and update order status based on paymentIntentId and event data. No authentication required (Stripe IPs only). **Rest Route** The `completeOrderStripeWebhook` API REST controller can be triggered via the following route: `/v1/completeorderstripewebhook/:orderManagementOrderId` **Rest Request Parameters** The `completeOrderStripeWebhook` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **status** : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/completeorderstripewebhook/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/completeorderstripewebhook/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderbyproductid` API get orders by productId **Rest Route** The `getOrderManagementOrderByProductId` API REST controller can be triggered via the following route: `/v1/ordermanagementorderbyproductid/:items` **Rest Request Parameters** The `getOrderManagementOrderByProductId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | items | String | true | request.params?.items | **orderManagementOrderId** : This id paremeter is used to query the required data object. **items** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderbyproductid/:items** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderbyproductid/${items}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Ordermanagementorder` API Creates an order and initiates Stripe payment. Validates that all products in the order are fixed-price, populates orderItems, saves Stripe customer/paymentMethod/paymentIntentId for reconciliation. Only accessible to buyers for own checkouts and only allows fixed-price product checkout (no auction). **Rest Route** The `createOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders` **Rest Request Parameters** The `createOrderManagementOrder` api has got 14 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderNumber | String | true | request.body?.orderNumber | | items | ID | false | request.body?.items | | paymentMethodId | String | true | request.body?.paymentMethodId | | stripeCustomerId | String | true | request.body?.stripeCustomerId | | paymentIntentId | String | false | request.body?.paymentIntentId | | shippingAddress | Object | true | request.body?.shippingAddress | | summary | Object | true | request.body?.summary | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderNumber** : Unique, human-friendly order number (displayed to users); enforced unique. **items** : Array of orderManagementOrderItem ids representing items in this order. **paymentMethodId** : Stripe paymentMethodId used for payment. Not stored if cash or other payment (future). **stripeCustomerId** : Stripe customerId of buyer; enables saved/paymentMethodId flows. **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **shippingAddress** : Shipping address for the order (copy of buyer address at purchase time). **summary** : Object with total, subtotal, currency, shipping, discount breakdown as snapshot of order at time of purchase. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorders** ```js axios({ method: 'POST', url: '/v1/ordermanagementorders', data: { orderNumber:"String", items:"ID", paymentMethodId:"String", stripeCustomerId:"String", paymentIntentId:"String", shippingAddress:"Object", summary:"Object", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderitems` API List order items for a given order or for buyer/seller analytics. Used for feedback management. **Rest Route** The `listOrderManagementOrderItems` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems` **Rest Request Parameters** The `listOrderManagementOrderItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Ownordermanagementorders` API list the loggedin user orders **Rest Route** The `listOwnOrderManagementOrders` API REST controller can be triggered via the following route: `/v1/ownordermanagementorders` **Rest Request Parameters** The `listOwnOrderManagementOrders` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ownordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ownordermanagementorders', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Lis Ordermanagementownorderitem` API list the loggedin user's order items **Rest Route** The `lisOrderManagementOwnOrderItem` API REST controller can be triggered via the following route: `/v1/lisordermanagementownorderitem` **Rest Request Parameters** The `lisOrderManagementOwnOrderItem` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/lisordermanagementownorderitem** ```js axios({ method: 'GET', url: '/v1/lisordermanagementownorderitem', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Ordermanagementorderitem` API create order item **Rest Route** The `createOrderManagementOrderItem` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems` **Rest Request Parameters** The `createOrderManagementOrderItem` api has got 8 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | shipping | Double | true | request.body?.shipping | | orderId | ID | true | request.body?.orderId | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | | price | Double | true | request.body?.price | | sellerId | ID | true | request.body?.sellerId | | title | String | true | request.body?.title | | currency | String | true | request.body?.currency | **shipping** : Shipping cost for this product (may be 0 for free shipping). **orderId** : Parent order this item belongs to; enables join and lifecycle tracking. **quantity** : Number of units purchased for this product. **productId** : ID of product purchased in this line item. **price** : Unit price for this product at purchase time. **sellerId** : UserId of seller (owner of product at purchase time). **title** : Product title at purchase time (copied for convenience/audit). **currency** : Currency code for price/shipping (ISO 4217). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderitems** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderitems', data: { shipping:"Double", orderId:"ID", quantity:"Integer", productId:"ID", price:"Double", sellerId:"ID", title:"String", currency:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpayment2` API This route is used to get the payment information by ID. **Rest Route** The `getOrderManagementOrderPayment2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `getOrderManagementOrderPayment2` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderpayments2` API This route is used to list all payments. **Rest Route** The `listOrderManagementOrderPayments2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayments2` **Rest Request Parameters** The `listOrderManagementOrderPayments2` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Ordermanagementorderpayment` API This route is used to create a new payment. **Rest Route** The `createOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment` **Rest Request Parameters** The `createOrderManagementOrderPayment` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderId | ID | true | request.body?.orderId | | paymentId | String | true | request.body?.paymentId | | paymentStatus | String | true | request.body?.paymentStatus | | statusLiteral | String | true | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | **orderId** : an ID value to represent the orderId which is the ID parameter of the source orderManagementOrder object **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderpayment', data: { orderId:"ID", paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Ordermanagementorderpayment` API This route is used to update an existing payment. **Rest Route** The `updateOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `updateOrderManagementOrderPayment` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | false | request.body?.paymentId | | paymentStatus | String | false | request.body?.paymentStatus | | statusLiteral | String | false | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | **sys_orderManagementOrderPaymentId** : This id paremeter is used to select the required data object that will be updated **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Ordermanagementorderpayment` API This route is used to delete a payment. **Rest Route** The `deleteOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `deleteOrderManagementOrderPayment` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderpayments2` API This route is used to list all payments. **Rest Route** The `listOrderManagementOrderPayments2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayments2` **Rest Request Parameters** The `listOrderManagementOrderPayments2` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Ordermanagementorderpaymentbyorderid` API This route is used to get the payment information by order id. **Rest Route** The `getOrderManagementOrderPaymentByOrderId` API REST controller can be triggered via the following route: `/v1/orderManagementOrderpaymentbyorderid/:orderId` **Rest Request Parameters** The `getOrderManagementOrderPaymentByOrderId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | orderId | String | true | request.params?.orderId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **orderId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbyorderid/:orderId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbyorderid/${orderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpaymentbypaymentid` API This route is used to get the payment information by payment id. **Rest Route** The `getOrderManagementOrderPaymentByPaymentId` API REST controller can be triggered via the following route: `/v1/orderManagementOrderpaymentbypaymentid/:paymentId` **Rest Request Parameters** The `getOrderManagementOrderPaymentByPaymentId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | true | request.params?.paymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **paymentId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbypaymentid/:paymentId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbypaymentid/${paymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpayment2` API This route is used to get the payment information by ID. **Rest Route** The `getOrderManagementOrderPayment2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `getOrderManagementOrderPayment2` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Start Ordermanagementorderpayment` API Start payment for orderManagementOrder **Rest Route** The `startOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/startordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `startOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to start a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/startordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/startordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Refresh Ordermanagementorderpayment` API Refresh payment info for orderManagementOrder from Stripe **Rest Route** The `refreshOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/refreshordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `refreshOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to refresh a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/refreshordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/refreshordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Callback Ordermanagementorderpayment` API Refresh payment values by gateway webhook call for orderManagementOrder **Rest Route** The `callbackOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/callbackordermanagementorderpayment` **Rest Request Parameters** The `callbackOrderManagementOrderPayment` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.body?.orderManagementOrderId | **orderManagementOrderId** : The order id parameter that will be read from webhook callback params **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/callbackordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/callbackordermanagementorderpayment', data: { orderManagementOrderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Get Paymentcustomerbyuserid` API This route is used to get the payment customer information by user id. **Rest Route** The `getPaymentCustomerByUserId` API REST controller can be triggered via the following route: `/v1/paymentcustomers/:userId` **Rest Request Parameters** The `getPaymentCustomerByUserId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_paymentCustomerId | ID | true | request.params?.sys_paymentCustomerId | | userId | String | true | request.params?.userId | **sys_paymentCustomerId** : This id paremeter is used to query the required data object. **userId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomers/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_paymentCustomer": { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Paymentcustomers` API This route is used to list all payment customers. **Rest Route** The `listPaymentCustomers` API REST controller can be triggered via the following route: `/v1/paymentcustomers` **Rest Request Parameters** The `listPaymentCustomers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers** ```js axios({ method: 'GET', url: '/v1/paymentcustomers', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentCustomers": [ { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Paymentcustomermethods` API This route is used to list all payment customer methods. **Rest Route** The `listPaymentCustomerMethods` API REST controller can be triggered via the following route: `/v1/paymentcustomermethods/:userId` **Rest Request Parameters** The `listPaymentCustomerMethods` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | String | true | request.params?.userId | **userId** : This parameter will be used to select the data objects that want to be listed **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomermethods/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomermethods/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentMethods", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentMethods": [ { "id": "ID", "paymentMethodId": "String", "userId": "ID", "customerId": "String", "cardHolderName": "String", "cardHolderZip": "String", "platform": "String", "cardInfo": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ## Feedback Service Handles feedback for order items: one feedback per buyer/orderItem, attached to sellerId for analytical feedback/rating aggregation and reputation tracking. Enables querying feedbacks received/given for sellers and buyers. test ### Feedback Service Data Objects **Feedback** One feedback per (buyer, orderItem). Stores rating (1-5), comment, ties to seller for analytics. Created only after delivery confirmed on order item. ### Feedback Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/feedback-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/feedback-api` * **Production:** `https://ebaycclone.mindbricks.co/feedback-api` ### `List Feedbacks` API List feedback with filtering by buyerId (given), sellerId (received), productId, or orderItemId. Used for showing seller profile, buyer profile, or order analytics. **Rest Route** The `listFeedbacks` API REST controller can be triggered via the following route: `/v1/feedbacks` **Rest Request Parameters** The `listFeedbacks` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/feedbacks** ```js axios({ method: 'GET', url: '/v1/feedbacks', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedbacks", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "feedbacks": [ { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Feedback` API Get a single feedback by id. Accessible to public (for seller profile, product, or audit views). **Rest Route** The `getFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `getFeedback` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | **feedbackId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/feedbacks/:feedbackId** ```js axios({ method: 'GET', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Feedback` API Update feedback (comment/rating) for existing feedback record (buyer only). Admin can update as override. **Rest Route** The `updateFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `updateFeedback` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | | rating | Integer | false | request.body?.rating | | comment | String | false | request.body?.comment | **feedbackId** : This id paremeter is used to select the required data object that will be updated **rating** : Rating (1-5 stars) submitted by buyer. Required. **comment** : Optional textual feedback comment, max ~500 chars. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/feedbacks/:feedbackId** ```js axios({ method: 'PATCH', url: `/v1/feedbacks/${feedbackId}`, data: { rating:"Integer", comment:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Feedback` API Delete (soft-delete) feedback (by buyer or admin). Only feedback owner or admin. **Rest Route** The `deleteFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `deleteFeedback` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | **feedbackId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/feedbacks/:feedbackId** ```js axios({ method: 'DELETE', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Feedback` API Buyer creates feedback for a delivered order item. Only allowed once per (buyer, orderItemId). Allowed only once order item is delivered. **Rest Route** The `createFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks` **Rest Request Parameters** The `createFeedback` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | rating | Integer | true | request.body?.rating | | orderId | ID | true | request.body?.orderId | | orderItemId | ID | true | request.body?.orderItemId | | sellerId | ID | true | request.body?.sellerId | | comment | String | false | request.body?.comment | | productId | ID | true | request.body?.productId | **rating** : Rating (1-5 stars) submitted by buyer. Required. **orderId** : Order containing this purchased item. Used for aggregation and validation. **orderItemId** : Purchased item (line item) in order. Feedback is per (buyer, orderItem). **sellerId** : Seller of product for analytics/aggregation. Not author; used for querying feedback about sellers. **comment** : Optional textual feedback comment, max ~500 chars. **productId** : The product listing being reviewed (snapshot at order time). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/feedbacks** ```js axios({ method: 'POST', url: '/v1/feedbacks', data: { rating:"Integer", orderId:"ID", orderItemId:"ID", sellerId:"ID", comment:"String", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # REST API GUIDE ## ebaycclone-notificationmanagement-service Handles storage, management, and event-driven delivery of in-app and email notifications for user-impacting system events (bids, offers, orders, feedback, messaging, etc.). Supports marking notifications as read/unread, structured filtering by event type/channel, and always returns in-app notifications ordered by recency. ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to: Email: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. ## Documentation Scope Welcome to the official documentation for the NotificationManagement Service's REST API. This document is designed to provide a comprehensive guide to interfacing with our NotificationManagement Service exclusively through RESTful API endpoints. **Intended Audience** This documentation is intended for developers and integrators who are looking to interact with the NotificationManagement Service via HTTP requests for purposes such as creating, updating, deleting and querying NotificationManagement objects. **Overview** Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases. Beyond REST It's important to note that the NotificationManagement Service also supports alternative methods of interaction, such as gRPC and messaging via a Message Broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation. ## Authentication And Authorization To ensure secure access to the NotificationManagement service's protected endpoints, a project-wide access token is required. This token serves as the primary method for authenticating requests to our service. However, it's important to note that access control varies across different routes: **Protected API**: Certain API (routes) require specific authorization levels. Access to these routes is contingent upon the possession of a valid access token that meets the route-specific authorization criteria. Unauthorized requests to these routes will be rejected. **Public API **: The service also includes public API (routes) that are accessible without authentication. These public endpoints are designed for open access and do not require an access token. ### Token Locations When including your access token in a request, ensure it is placed in one of the following specified locations. The service will sequentially search these locations for the token, utilizing the first one it encounters. | Location | Token Name / Param Name | | ---------------------- | ---------------------------- | | Query | access_token | | Authorization Header | Bearer | | Header | ebaycclone-access-token| | Cookie | ebaycclone-access-token| Please ensure the token is correctly placed in one of these locations, using the appropriate label as indicated. The service prioritizes these locations in the order listed, processing the first token it successfully identifies. ## Api Definitions This section outlines the API endpoints available within the NotificationManagement service. Each endpoint can receive parameters through various methods, meticulously described in the following definitions. It's important to understand the flexibility in how parameters can be included in requests to effectively interact with the NotificationManagement service. This service is configured to listen for HTTP requests on port `3000`, serving both the main API interface and default administrative endpoints. The following routes are available by default: * **API Test Interface (API Face):** `/` * **Swagger Documentation:** `/swagger` * **Postman Collection Download:** `/getPostmanCollection` * **Health Checks:** `/health` and `/admin/health` * **Current Session Info:** `/currentuser` * **Favicon:** `/favicon.ico` This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/notificationmanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/notificationmanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/notificationmanagement-api` **Parameter Inclusion Methods:** Parameters can be incorporated into API requests in several ways, each with its designated location. Understanding these methods is crucial for correctly constructing your requests: **Query Parameters:** Included directly in the URL's query string. **Path Parameters:** Embedded within the URL's path. **Body Parameters:** Sent within the JSON body of the request. **Session Parameters:** Automatically read from the session object. This method is used for parameters that are intrinsic to the user's session, such as userId. When using an API that involves session parameters, you can omit these from your request. The service will automatically bind them to the API layer, provided that a session is associated with your request. **Note on Session Parameters:** Session parameters represent a unique method of parameter inclusion, relying on the context of the user's session. A common example of a session parameter is userId, which the service automatically associates with your request when a session exists. This feature ensures seamless integration of user-specific data without manual input for each request. By adhering to the specified parameter inclusion methods, you can effectively utilize the NotificationManagement service's API endpoints. For detailed information on each endpoint, including required parameters and their accepted locations, refer to the individual API definitions below. ### Common Parameters The `NotificationManagement` service's business API support several common parameters designed to modify and enhance the behavior of API requests. These parameters are not individually listed in the API route definitions to avoid repetition. Instead, refer to this section to understand how to leverage these common behaviors across different routes. Note that all common parameters should be included in the query part of the URL. ### Supported Common Parameters: - **getJoins (BOOLEAN)**: Controls whether to retrieve associated objects along with the main object. By default, `getJoins` is assumed to be `true`. Set it to `false` if you prefer to receive only the main fields of an object, excluding its associations. - **excludeCQRS (BOOLEAN)**: Applicable only when `getJoins` is `true`. By default, `excludeCQRS` is set to `false`. Enabling this parameter (`true`) omits non-local associations, which are typically more resource-intensive as they require querying external services like ElasticSearch for additional information. Use this to optimize response times and resource usage. - **requestId (String)**: Identifies a request to enable tracking through the service's log chain. A random hex string of 32 characters is assigned by default. If you wish to use a custom `requestId`, simply include it in your query parameters. - **caching (BOOLEAN)**: Determines the use of caching for query API. By default, caching is enabled (`true`). To ensure the freshest data directly from the database, set this parameter to `false`, bypassing the cache. - **cacheTTL (Integer)**: Specifies the Time-To-Live (TTL) for query caching, in seconds. This is particularly useful for adjusting the default caching duration (5 minutes) for `get list` queries. Setting a custom `cacheTTL` allows you to fine-tune the cache lifespan to meet your needs. - **pageNumber (Integer)**: For paginated `get list` API's, this parameter selects which page of results to retrieve. The default is `1`, indicating the first page. To disable pagination and retrieve all results, set `pageNumber` to `0`. - **pageRowCount (Integer)**: In conjunction with paginated API's, this parameter defines the number of records per page. The default value is `25`. Adjusting `pageRowCount` allows you to control the volume of data returned in a single request. By utilizing these common parameters, you can tailor the behavior of API requests to suit your specific requirements, ensuring optimal performance and usability of the `NotificationManagement` service. ### Error Response If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity: - **400 Bad Request**: The request was improperly formatted or contained invalid parameters, preventing the server from processing it. - **401 Unauthorized**: The request lacked valid authentication credentials or the credentials provided do not grant access to the requested resource. - **404 Not Found**: The requested resource was not found on the server. - **500 Internal Server Error**: The server encountered an unexpected condition that prevented it from fulfilling the request. Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ### Object Structure of a Successfull Response When the `NotificationManagement` service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client. **Key Characteristics of the Response Envelope:** - **Data Presentation**: Depending on the nature of the request, the service returns either a single data object or an array of objects encapsulated within the JSON envelope. - **Creation and Update API**: These API routes return the unmodified (pure) form of the data object(s), without any associations to other data objects. - **Delete API**: Even though the data is removed from the database, the last known state of the data object(s) is returned in its pure form. - **Get Requests**: A single data object is returned in JSON format. - **Get List Requests**: An array of data objects is provided, reflecting a collection of resources. - **Data Structure and Joins**: The complexity of the data structure in the response can vary based on the API's architectural design and the join options specified in the request. The architecture might inherently limit join operations, or they might be dynamically controlled through query parameters. - **Pure Data Forms**: In some cases, the response mirrors the exact structure found in the primary data table, without extensions. - **Extended Data Forms**: Alternatively, responses might include data extended through joins with tables within the same service or aggregated from external sources, such as ElasticSearch indices related to other services. - **Join Varieties**: The extensions might involve one-to-one joins, resulting in single object associations, or one-to-many joins, leading to an array of objects. In certain instances, the data might even feature nested inclusions from other data objects. **Design Considerations**: The structure of a API's response data is meticulously crafted during the service's architectural planning. This design ensures that responses adequately reflect the intended data relationships and service logic, providing clients with rich and meaningful information. **Brief Data**: Certain API's return a condensed version of the object data, intentionally selecting only specific fields deemed useful for that request. In such instances, the API documentation will detail the properties included in the response, guiding developers on what to expect. ### API Response Structure The API utilizes a standardized JSON envelope to encapsulate responses. This envelope is designed to consistently deliver both the requested data and essential metadata, ensuring that clients can efficiently interpret and utilize the response. **HTTP Status Codes:** - **200 OK**: This status code is returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request has been processed successfully. - **201 Created**: This status code is specific to CREATE operations, signifying that the requested resource has been successfully created. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling the successful execution of the request. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3 "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` - **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation performed. **Handling Errors:** For details on handling error scenarios and understanding the structure of error responses, please refer to the "Error Response" section provided earlier in this documentation. It outlines how error conditions are communicated, including the use of HTTP status codes and standardized JSON structures for error messages. ## Resources NotificationManagement service provides the following resources which are stored in its own database as a data object. Note that a resource for an api access is a data object for the service. ### Notification resource *Resource Definition* : Stores and manages in-app and email notifications tied to user-facing events like bids, offers, orders, messaging, shipment, and feedback. Includes event type (notificationType) for filter/search, arbitrary event payload, and delivery channel. Soft-delete enforced. In-app notifications always sorted by createdAt DESC on retrieval. *Notification Resource Properties* | Name | Type | Required | Default | Definition | | ---- | ---- | -------- | ------- | ---------- | | **notificationType** | Enum | | | *Type of event triggering notification (e.g., BID_UPDATED, ORDER_SHIPPED, MESSAGE_RECEIVED, etc.). Used for display/icon and query filter.* | | **userId** | ID | | | *User receiving the notification (recipient).* | | **channel** | Enum | | | *Channel by which notification is delivered: IN_APP or EMAIL.* | | **payload** | Object | | | *Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType.* | | **isRead** | Boolean | | | *Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel)* | #### Enum Properties Enum properties are represented as strings in the database. The values are mapped to their corresponding names in the application layer. ##### notificationType Enum Property *Property Definition* : Type of event triggering notification (e.g., BID_UPDATED, ORDER_SHIPPED, MESSAGE_RECEIVED, etc.). Used for display/icon and query filter.*Enum Options* | Name | Value | Index | | ---- | ----- | ----- | | **BID_UPDATED** | `"BID_UPDATED""` | 0 | | **BID_OUTBID** | `"BID_OUTBID""` | 1 | | **BID_WON** | `"BID_WON""` | 2 | | **OFFER_PLACED** | `"OFFER_PLACED""` | 3 | | **OFFER_ACCEPTED** | `"OFFER_ACCEPTED""` | 4 | | **OFFER_DECLINED** | `"OFFER_DECLINED""` | 5 | | **OFFER_COUNTERED** | `"OFFER_COUNTERED""` | 6 | | **ORDER_PLACED** | `"ORDER_PLACED""` | 7 | | **ORDER_PAID** | `"ORDER_PAID""` | 8 | | **ORDER_SHIPPED** | `"ORDER_SHIPPED""` | 9 | | **ORDER_DELIVERED** | `"ORDER_DELIVERED""` | 10 | | **ORDER_CANCELLED** | `"ORDER_CANCELLED""` | 11 | | **FEEDBACK_RECEIVED** | `"FEEDBACK_RECEIVED""` | 12 | | **FEEDBACK_REQUESTED** | `"FEEDBACK_REQUESTED""` | 13 | | **MESSAGE_RECEIVED** | `"MESSAGE_RECEIVED""` | 14 | | **MESSAGE_SENT** | `"MESSAGE_SENT""` | 15 | | **SYSTEM_ALERT** | `"SYSTEM_ALERT""` | 16 | ##### channel Enum Property *Property Definition* : Channel by which notification is delivered: IN_APP or EMAIL.*Enum Options* | Name | Value | Index | | ---- | ----- | ----- | | **IN_APP** | `"IN_APP""` | 0 | | **EMAIL** | `"EMAIL""` | 1 | ## Business Api ### Create Notification API *API Definition* : Creates a notification entry in response to a system/business event. Only allowed for system/event processes and admins (not standard user/action). Typically event-driven, receives userId, notificationType, payload, and channel. *API Crud Type* : create *Default access route* : *POST* `/v1/notifications` #### Parameters The createNotification api has got 5 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationType | Enum | true | request.body?.notificationType | | userId | ID | true | request.body?.userId | | channel | Enum | true | request.body?.channel | | payload | Object | true | request.body?.payload | | isRead | Boolean | true | request.body?.isRead | To access the api you can use the **REST** controller with the path **POST /v1/notifications** ```js axios({ method: 'POST', url: '/v1/notifications', data: { notificationType:"Enum", userId:"ID", channel:"Enum", payload:"Object", isRead:"Boolean", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`notification`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"notification","method":"POST","action":"create","appVersion":"Version","rowCount":1,"notification":{"id":"ID","notificationType":"Enum","notificationType_idx":"Integer","userId":"ID","channel":"Enum","channel_idx":"Integer","payload":"Object","isRead":"Boolean","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Create Notification](businessApi/createNotification). ### Update Notification API *API Definition* : Updates a notification (mark as read/unread, payload patch for e.g. admin fix). Only receiver (userId) or admins may update. isRead is primary update scenario; others very limited. *API Crud Type* : update *Default access route* : *PATCH* `/v1/notifications/:notificationId` #### Parameters The updateNotification api has got 3 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | | payload | Object | false | request.body?.payload | | isRead | Boolean | false | request.body?.isRead | To access the api you can use the **REST** controller with the path **PATCH /v1/notifications/:notificationId** ```js axios({ method: 'PATCH', url: `/v1/notifications/${notificationId}`, data: { payload:"Object", isRead:"Boolean", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`notification`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"notification","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"notification":{"id":"ID","notificationType":"Enum","notificationType_idx":"Integer","userId":"ID","channel":"Enum","channel_idx":"Integer","payload":"Object","isRead":"Boolean","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Update Notification](businessApi/updateNotification). ### List Notifications API *API Definition* : Returns filtered list of notifications for a user, with optional filters: notificationType, isRead, channel. Always sorted by createdAt (descending) for in-app notifications. Only retrieval allowed for owner/admin. *API Crud Type* : list *Default access route* : *GET* `/v1/notifications` The listNotifications api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/notifications** ```js axios({ method: 'GET', url: '/v1/notifications', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`notifications`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"notifications","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","notifications":[{"id":"ID","notificationType":"Enum","notificationType_idx":"Integer","userId":"ID","channel":"Enum","channel_idx":"Integer","payload":"Object","isRead":"Boolean","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For List Notifications](businessApi/listNotifications). ### Delete Notification API *API Definition* : Soft-delete a notification record. Only receiver or admin may delete. *API Crud Type* : delete *Default access route* : *DELETE* `/v1/notifications/:notificationId` #### Parameters The deleteNotification api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | To access the api you can use the **REST** controller with the path **DELETE /v1/notifications/:notificationId** ```js axios({ method: 'DELETE', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`notification`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"notification","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"notification":{"id":"ID","notificationType":"Enum","notificationType_idx":"Integer","userId":"ID","channel":"Enum","channel_idx":"Integer","payload":"Object","isRead":"Boolean","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Delete Notification](businessApi/deleteNotification). ### Get Notification API *API Definition* : Retrieves a notification for the receiver or admin. Used to populate content on detail/expanded view. *API Crud Type* : get *Default access route* : *GET* `/v1/notifications/:notificationId` #### Parameters The getNotification api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | To access the api you can use the **REST** controller with the path **GET /v1/notifications/:notificationId** ```js axios({ method: 'GET', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`notification`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"notification","method":"GET","action":"get","appVersion":"Version","rowCount":1,"notification":{"id":"ID","notificationType":"Enum","notificationType_idx":"Integer","userId":"ID","channel":"Enum","channel_idx":"Integer","payload":"Object","isRead":"Boolean","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Get Notification](businessApi/getNotification). ### Authentication Specific Routes ### Common Routes ### Route: currentuser *Route Definition*: Retrieves the currently authenticated user's session information. *Route Type*: sessionInfo *Access Route*: `GET /currentuser` #### Parameters This route does **not** require any request parameters. #### Behavior - Returns the authenticated session object associated with the current access token. - If no valid session exists, responds with a 401 Unauthorized. ```js // Sample GET /currentuser call axios.get("/currentuser", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** Returns the session object, including user-related data and token information. ``` { "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", "roleId": "user", "tenantId": "abc123", "accessToken": "jwt-token-string", ... } ``` **Error Response** **401 Unauthorized:** No active session found. ``` { "status": "ERR", "message": "No login found" } ``` **Notes** * This route is typically used by frontend or mobile applications to fetch the current session state after login. * The returned session includes key user identity fields, tenant information (if applicable), and the access token for further authenticated requests. * Always ensure a valid access token is provided in the request to retrieve the session. ### Route: permissions `*Route Definition*`: Retrieves all effective permission records assigned to the currently authenticated user. `*Route Type*`: permissionFetch *Access Route*: `GET /permissions` #### Parameters This route does **not** require any request parameters. #### Behavior - Fetches all active permission records (`givenPermissions` entries) associated with the current user session. - Returns a full array of permission objects. - Requires a valid session (`access token`) to be available. ```js // Sample GET /permissions call axios.get("/permissions", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** Returns an array of permission objects. ```json [ { "id": "perm1", "permissionName": "adminPanel.access", "roleId": "admin", "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" }, { "id": "perm2", "permissionName": "orders.manage", "roleId": null, "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" } ] ``` Each object reflects a single permission grant, aligned with the givenPermissions model: - `**permissionName**`: The permission the user has. - `**roleId**`: If the permission was granted through a role. -` **subjectUserId**`: If directly granted to the user. - `**subjectUserGroupId**`: If granted through a group. - `**objectId**`: If tied to a specific object (OBAC). - `**canDo**`: True or false flag to represent if permission is active or restricted. **Error Responses** * **401 Unauthorized**: No active session found. ```json { "status": "ERR", "message": "No login found" } ``` * **500 Internal Server Error**: Unexpected error fetching permissions. **Notes** * The /permissions route is available across all backend services generated by Mindbricks, not just the auth service. * Auth service: Fetches permissions freshly from the live database (givenPermissions table). * Other services: Typically use a cached or projected view of permissions stored in a common ElasticSearch store, optimized for faster authorization checks. > **Tip**: > Applications can cache permission results client-side or server-side, but should occasionally refresh by calling this endpoint, especially after login or permission-changing operations. ### Route: permissions/:permissionName *Route Definition*: Checks whether the current user has access to a specific permission, and provides a list of scoped object exceptions or inclusions. *Route Type*: permissionScopeCheck *Access Route*: `GET /permissions/:permissionName` #### Parameters | Parameter | Type | Required | Population | |------------------|--------|----------|------------------------| | permissionName | String | Yes | `request.params.permissionName` | #### Behavior - Evaluates whether the current user **has access** to the given `permissionName`. - Returns a structured object indicating: - Whether the permission is generally granted (`canDo`) - Which object IDs are explicitly included or excluded from access (`exceptions`) - Requires a valid session (`access token`). ```js // Sample GET /permissions/orders.manage axios.get("/permissions/orders.manage", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** ```json { "canDo": true, "exceptions": [ "a1f2e3d4-xxxx-yyyy-zzzz-object1", "b2c3d4e5-xxxx-yyyy-zzzz-object2" ] } ``` * If `canDo` is `true`, the user generally has the permission, but not for the objects listed in `exceptions` (i.e., restrictions). * If `canDo` is `false`, the user does not have the permission by default — but only for the objects in `exceptions`, they do have permission (i.e., selective overrides). * The exceptions array contains valid **UUID strings**, each corresponding to an object ID (typically from the data model targeted by the permission). ## Copyright All sources, documents and other digital materials are copyright of . ## About Us For more information please visit our website: . . . # Service Design Specification **ebaycclone-notificationmanagement-service** documentation -Version:**`1.0.0`** ## Scope This document provides a structured architectural overview of the `notificationManagement` microservice, detailing its configuration, data model, authorization logic, business rules, and API design. It has been automatically generated based on the service definition within Mindbricks, ensuring that the information reflects the source of truth used during code generation and deployment. The document is intended to serve multiple audiences: * **Service architects** can use it to validate design decisions and ensure alignment with broader architectural goals. * **Developers and maintainers** will find it useful for understanding the structure and behavior of the service, facilitating easier debugging, feature extension, and integration with other systems. * **Stakeholders and reviewers** can use it to gain a clear understanding of the service's capabilities and domain logic. > **Note for Frontend Developers**: While this document is valuable for understanding business logic and data interactions, please refer to the [Service API Documentation](#) for endpoint-level specifications and integration details. > **Note for Backend Developers**: Since the code for this service is automatically generated by Mindbricks, you typically won't need to implement or modify it manually. However, this document is especially valuable when you're building other services—whether within Mindbricks or externally—that need to interact with or depend on this service. It provides a clear reference to the service's data contracts, business rules, and API structure, helping ensure compatibility and correct integration. ## `NotificationManagement` Service Settings [**Edit**](notificationmanagement/serviceSettings) Handles storage, management, and event-driven delivery of in-app and email notifications for user-impacting system events (bids, offers, orders, feedback, messaging, etc.). Supports marking notifications as read/unread, structured filtering by event type/channel, and always returns in-app notifications ordered by recency. ### Service Overview This service is configured to listen for HTTP requests on port `3000`, serving both the main API interface and default administrative endpoints. The following routes are available by default: * **API Test Interface (API Face):** `/` * **Swagger Documentation:** `/swagger` * **Postman Collection Download:** `/getPostmanCollection` * **Health Checks:** `/health` and `/admin/health` * **Current Session Info:** `/currentuser` * **Favicon:** `/favicon.ico` The service uses a **PostgreSQL** database for data storage, with the database name set to `ebaycclone-notificationmanagement-service`. This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/notificationmanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/notificationmanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/notificationmanagement-api` ### Authentication & Security - **Login Required**: Yes This service requires user authentication for access. It supports both JWT and RSA-based authentication mechanisms, ensuring secure user sessions and data integrity. If a crud route also is configured to require login, it will check a valid JWT token in the request query/header/bearer/cookie. If the token is valid, it will extract the user information from the token and make the fetched session data available in the request context. ### Service Data Objects The service uses a **PostgreSQL** database for data storage, with the database name set to `ebaycclone-notificationmanagement-service`. Data deletion is managed using a **soft delete** strategy. Instead of removing records from the database, they are flagged as inactive by setting the `isActive` field to `false`. | Object Name | Description | Public Access | |-------------|-------------|---------------| | `notification` | Stores and manages in-app and email notifications tied to user-facing events like bids, offers, orders, messaging, shipment, and feedback. Includes event type (notificationType) for filter/search, arbitrary event payload, and delivery channel. Soft-delete enforced. In-app notifications always sorted by createdAt DESC on retrieval. | accessPrivate | ## notification Data Object ### Object Overview **Description:** Stores and manages in-app and email notifications tied to user-facing events like bids, offers, orders, messaging, shipment, and feedback. Includes event type (notificationType) for filter/search, arbitrary event payload, and delivery channel. Soft-delete enforced. In-app notifications always sorted by createdAt DESC on retrieval. This object represents a core data structure within the service and acts as the blueprint for database interaction, API generation, and business logic enforcement. It is defined using the `ObjectSettings` pattern, which governs its behavior, access control, caching strategy, and integration points with other systems such as Stripe and Redis. ### Core Configuration - **Soft Delete:** Enabled — Determines whether records are marked inactive (`isActive = false`) instead of being physically deleted. - **Public Access:** accessPrivate — If enabled, anonymous users may access this object’s data depending on API-level rules. ### Composite Indexes - **userTypeIsReadIndex**: [userId, notificationType, isRead] This composite index is defined to optimize query performance for complex queries involving multiple fields. The index also defines a conflict resolution strategy for duplicate key violations. When a new record would violate this composite index, the following action will be taken: **On Duplicate**: `` ### Properties Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `notificationType` | Enum | Yes | Type of event triggering notification (e.g., BID_UPDATED, ORDER_SHIPPED, MESSAGE_RECEIVED, etc.). Used for display/icon and query filter. | | `userId` | ID | Yes | User receiving the notification (recipient). | | `channel` | Enum | Yes | Channel by which notification is delivered: IN_APP or EMAIL. | | `payload` | Object | Yes | Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. | | `isRead` | Boolean | Yes | Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) | * Required properties are mandatory for creating objects and must be provided in the request body if no default value is set. ### Default Values Default values are automatically assigned to properties when a new object is created, if no value is provided in the request body. Since default values are applied on db level, they should be literal values, not expressions.If you want to use expressions, you can use transposed parameters in any business API to set default values dynamically. - **notificationType**: "BID_UPDATED" - **userId**: '00000000-0000-0000-0000-000000000000' - **channel**: "IN_APP" - **payload**: {} - **isRead**: false ### Constant Properties `notificationType` `userId` `channel` Constant properties are defined to be immutable after creation, meaning they cannot be updated or changed once set. They are typically used for properties that should remain constant throughout the object's lifecycle. A property is set to be constant if the `Allow Update` option is set to `false`. ### Auto Update Properties `payload` `isRead` An update crud API created with the option `Auto Params` enabled will automatically update these properties with the provided values in the request body. If you want to update any property in your own business logic not by user input, you can set the `Allow Auto Update` option to false. These properties will be added to the update API's body parameters and can be updated by the user if any value is provided in the request body. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an addtional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the index property to sort by the enum value or when your enum options represent a sequence of values. - **notificationType**: [BID_UPDATED, BID_OUTBID, BID_WON, OFFER_PLACED, OFFER_ACCEPTED, OFFER_DECLINED, OFFER_COUNTERED, ORDER_PLACED, ORDER_PAID, ORDER_SHIPPED, ORDER_DELIVERED, ORDER_CANCELLED, FEEDBACK_RECEIVED, FEEDBACK_REQUESTED, MESSAGE_RECEIVED, MESSAGE_SENT, SYSTEM_ALERT] - **channel**: [IN_APP, EMAIL] ### Elastic Search Indexing `notificationType` `userId` `channel` `isRead` Properties that are indexed in Elastic Search will be searchable via the Elastic Search API. While all properties are stored in the elastic search index of the data object, only those marked for Elastic Search indexing will be available for search queries. ### Database Indexing `notificationType` `userId` `channel` `isRead` Properties that are indexed in the database will be optimized for query performance, allowing for faster data retrieval. Make a property indexed in the database if you want to use it frequently in query filters or sorting. ### Secondary Key Properties `userId` Secondary key properties are used to create an additional indexed identifiers for the data object, allowing for alternative access patterns. Different than normal indexed properties, secondary keys will act as primary keys and Mindbricks will provide automatic secondary key db utility functions to access the data object by the secondary key. ### Relation Properties `userId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. You can define relations in the data object properties, which will be used to create foreign key constraints in the database. For complex joins operations, Mindbricks supportsa BFF pattern, where you can view dynamic and static views based on Elastic Search Indexes. Use db level relations for simple one-to-one or one-to-many relationships, and use BFF views for complex joins that require multiple data objects to be joined together. - **userId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes ### Filter Properties `notificationType` `userId` `channel` `isRead` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's that have "Auto Params" enabled. - **notificationType**: Enum has a filter named `notificationType` - **userId**: ID has a filter named `userId` - **channel**: Enum has a filter named `channel` - **isRead**: Boolean has a filter named `isRead` ## Business Logic notificationManagement has got 5 Business APIs to manage its internal and crud logic. For the details of each business API refer to its chapter. * [Create Notification](/businessLogic/createnotification) * [Update Notification](/businessLogic/updatenotification) * [List Notifications](/businessLogic/listnotifications) * [Delete Notification](/businessLogic/deletenotification) * [Get Notification](/businessLogic/getnotification) ## Edge Controllers No edge controllers defined for this service. --- ## Service Library ### Functions No general functions defined. ### Hook Functions No hook functions defined. ### Edge Functions No edge functions defined. ### Templates No templates defined. ### Assets No assets defined. ### Public Assets No public assets defined. --- ### Event Emission --- ## Integration Patterns ## Deployment Considerations ### Environment Configuration - **HTTP Port**: `3000` - **Database Type**: MongoDB - **Global Soft Delete**: Enabled ## Implementation Guidelines ### Development Workflow 1. **Data Model Implementation**: Generate database schema from data object definitions 2. **CRUD Route Generation**: Implement auto-generated routes with custom logic 3. **Custom Logic Integration**: Implement hook functions and edge functions 4. **Authentication Integration**: Configure with project-level authentication 5. **Testing**: Unit and integration testing for all components ### Code Generation Expectations - **Database Schema**: Auto-generated from data objects and relationships - **API Routes**: REST endpoints with customizable behavior - **Validation Logic**: Input validation from property definitions - **Access Control**: Authentication and authorization middleware ### Custom Code Integration Points - **Hook Functions**: Lifecycle-specific custom logic - **Edge Functions**: Full request/response control - **Library Functions**: Reusable business logic - **Templates**: Dynamic content rendering ### Testing Strategy #### Unit Testing - Test all custom library functions - Test validation logic and business rules - Test hook function implementations #### Integration Testing - Test API endpoints with authentication scenarios - Test database operations and transactions - Test external integrations - Test event emission and Kafka integration #### Performance Testing - Load test high-traffic endpoints - Test caching effectiveness - Monitor database query performance - Test scalability under load --- ## Appendices ### Data Type Reference | Type | Description | Storage | |------|-------------|---------| | ID | Unique identifier | UUID (SQL) / ObjectID (NoSQL) | | String | Short text (≤255 chars) | VARCHAR | | Text | Long-form text | TEXT | | Integer | 32-bit whole numbers | INT | | Boolean | True/false values | BOOLEAN | | Double | 64-bit floating point | DOUBLE | | Float | 32-bit floating point | FLOAT | | Short | 16-bit integers | SMALLINT | | Object | JSON object | JSONB (PostgreSQL) / Object (MongoDB) | | Date | ISO 8601 timestamp | TIMESTAMP | | Enum | Fixed numeric values | SMALLINT with lookup | ### Enum Value Mappings #### Request Locations - `0`: Bearer token in Authorization header - `1`: Cookie value - `2`: Custom HTTP header - `3`: Query parameter - `4`: Request body property - `5`: URL path parameter - `6`: Session data - `7`: Root request object #### HTTP Methods - `0`: GET - `1`: POST - `2`: PUT - `3`: PATCH - `4`: DELETE ### Edge Function Signature ```javascript async function edgeFunction(request) { // Custom request processing // Return response object or throw error return { data: {}, status: 200, message: "Success" }; } ``` --- *This document was generated from the service architecture definition and should be kept in sync with implementation changes.* # EVENT GUIDE ## ebaycclone-ordermanagement-service Handles all marketplace orders, manual checkout flows for fixed-price/offer/auction settlements, Stripe payment processing and webhook reconciliation, explicit status updates (shipping, delivery, cancellation), and feedback eligibility via orderItems. ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to: Email: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. # Documentation Scope Welcome to the official documentation for the `OrderManagement` Service Event descriptions. This guide is dedicated to detailing how to subscribe to and listen for state changes within the `OrderManagement` Service, offering an exclusive focus on event subscription mechanisms. **Intended Audience** This documentation is aimed at developers and integrators looking to monitor `OrderManagement` Service state changes. It is especially relevant for those wishing to implement or enhance business logic based on interactions with `OrderManagement` objects. **Overview** This section provides detailed instructions on monitoring service events, covering payload structures and demonstrating typical use cases through examples. # Authentication and Authorization Access to the `OrderManagement` service's events is facilitated through the project's Kafka server, which is not accessible to the public. Subscription to a Kafka topic requires being on the same network and possessing valid Kafka user credentials. This document presupposes that readers have existing access to the Kafka server. Additionally, the service offers a public subscription option via REST for real-time data management in frontend applications, secured through REST API authentication and authorization mechanisms. To subscribe to service events via the REST API, please consult the Realtime REST API Guide. # Database Events Database events are triggered at the database layer, automatically and atomically, in response to any modifications at the data level. These events serve to notify subscribers about the creation, update, or deletion of objects within the database, distinct from any overarching business logic. Listening to database events is particularly beneficial for those focused on tracking changes at the database level. A typical use case for subscribing to database events is to replicate the data store of one service within another service's scope, ensuring data consistency and syncronization across services. For example, while a business operation such as "approve membership" might generate a high-level business event like `membership-approved`, the underlying database changes could involve multiple state updates to different entities. These might be published as separate events, such as `dbevent-member-updated` and `dbevent-user-updated`, reflecting the granular changes at the database level. Such detailed eventing provides a robust foundation for building responsive, data-driven applications, enabling fine-grained observability and reaction to the dynamics of the data landscape. It also facilitates the architectural pattern of event sourcing, where state changes are captured as a sequence of events, allowing for high-fidelity data replication and history replay for analytical or auditing purposes. ## DbEvent orderManagementOrder-created **Event topic**: `ebaycclone-ordermanagement-service-dbevent-ordermanagementorder-created` This event is triggered upon the creation of a `orderManagementOrder` data object in the database. The event payload encompasses the newly created data, encapsulated within the root of the paylod. **Event payload**: ```json {"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent orderManagementOrder-updated **Event topic**: `ebaycclone-ordermanagement-service-dbevent-ordermanagementorder-updated` Activation of this event follows the update of a `orderManagementOrder` data object. The payload contains the updated information under the `orderManagementOrder` attribute, along with the original data prior to update, labeled as `old_orderManagementOrder` and also you can find the old and new versions of updated-only portion of the data.. **Event payload**: ```json { old_orderManagementOrder:{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, orderManagementOrder:{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, oldDataValues, newDataValues } ``` ## DbEvent orderManagementOrder-deleted **Event topic**: `ebaycclone-ordermanagement-service-dbevent-ordermanagementorder-deleted` This event announces the deletion of a `orderManagementOrder` data object, covering both hard deletions (permanent removal) and soft deletions (where the `isActive` attribute is set to false). Regardless of the deletion type, the event payload will present the data as it was immediately before deletion, highlighting an `isActive` status of false for soft deletions. **Event payload**: ```json {"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent orderManagementOrderItem-created **Event topic**: `ebaycclone-ordermanagement-service-dbevent-ordermanagementorderitem-created` This event is triggered upon the creation of a `orderManagementOrderItem` data object in the database. The event payload encompasses the newly created data, encapsulated within the root of the paylod. **Event payload**: ```json {"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent orderManagementOrderItem-updated **Event topic**: `ebaycclone-ordermanagement-service-dbevent-ordermanagementorderitem-updated` Activation of this event follows the update of a `orderManagementOrderItem` data object. The payload contains the updated information under the `orderManagementOrderItem` attribute, along with the original data prior to update, labeled as `old_orderManagementOrderItem` and also you can find the old and new versions of updated-only portion of the data.. **Event payload**: ```json { old_orderManagementOrderItem:{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, orderManagementOrderItem:{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, oldDataValues, newDataValues } ``` ## DbEvent orderManagementOrderItem-deleted **Event topic**: `ebaycclone-ordermanagement-service-dbevent-ordermanagementorderitem-deleted` This event announces the deletion of a `orderManagementOrderItem` data object, covering both hard deletions (permanent removal) and soft deletions (where the `isActive` attribute is set to false). Regardless of the deletion type, the event payload will present the data as it was immediately before deletion, highlighting an `isActive` status of false for soft deletions. **Event payload**: ```json {"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent sys_orderManagementOrderPayment-created **Event topic**: `ebaycclone-ordermanagement-service-dbevent-sys_ordermanagementorderpayment-created` This event is triggered upon the creation of a `sys_orderManagementOrderPayment` data object in the database. The event payload encompasses the newly created data, encapsulated within the root of the paylod. **Event payload**: ```json {"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent sys_orderManagementOrderPayment-updated **Event topic**: `ebaycclone-ordermanagement-service-dbevent-sys_ordermanagementorderpayment-updated` Activation of this event follows the update of a `sys_orderManagementOrderPayment` data object. The payload contains the updated information under the `sys_orderManagementOrderPayment` attribute, along with the original data prior to update, labeled as `old_sys_orderManagementOrderPayment` and also you can find the old and new versions of updated-only portion of the data.. **Event payload**: ```json { old_sys_orderManagementOrderPayment:{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, sys_orderManagementOrderPayment:{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, oldDataValues, newDataValues } ``` ## DbEvent sys_orderManagementOrderPayment-deleted **Event topic**: `ebaycclone-ordermanagement-service-dbevent-sys_ordermanagementorderpayment-deleted` This event announces the deletion of a `sys_orderManagementOrderPayment` data object, covering both hard deletions (permanent removal) and soft deletions (where the `isActive` attribute is set to false). Regardless of the deletion type, the event payload will present the data as it was immediately before deletion, highlighting an `isActive` status of false for soft deletions. **Event payload**: ```json {"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent sys_paymentCustomer-created **Event topic**: `ebaycclone-ordermanagement-service-dbevent-sys_paymentcustomer-created` This event is triggered upon the creation of a `sys_paymentCustomer` data object in the database. The event payload encompasses the newly created data, encapsulated within the root of the paylod. **Event payload**: ```json {"id":"ID","userId":"ID","customerId":"String","platform":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent sys_paymentCustomer-updated **Event topic**: `ebaycclone-ordermanagement-service-dbevent-sys_paymentcustomer-updated` Activation of this event follows the update of a `sys_paymentCustomer` data object. The payload contains the updated information under the `sys_paymentCustomer` attribute, along with the original data prior to update, labeled as `old_sys_paymentCustomer` and also you can find the old and new versions of updated-only portion of the data.. **Event payload**: ```json { old_sys_paymentCustomer:{"id":"ID","userId":"ID","customerId":"String","platform":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, sys_paymentCustomer:{"id":"ID","userId":"ID","customerId":"String","platform":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, oldDataValues, newDataValues } ``` ## DbEvent sys_paymentCustomer-deleted **Event topic**: `ebaycclone-ordermanagement-service-dbevent-sys_paymentcustomer-deleted` This event announces the deletion of a `sys_paymentCustomer` data object, covering both hard deletions (permanent removal) and soft deletions (where the `isActive` attribute is set to false). Regardless of the deletion type, the event payload will present the data as it was immediately before deletion, highlighting an `isActive` status of false for soft deletions. **Event payload**: ```json {"id":"ID","userId":"ID","customerId":"String","platform":"String","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent sys_paymentMethod-created **Event topic**: `ebaycclone-ordermanagement-service-dbevent-sys_paymentmethod-created` This event is triggered upon the creation of a `sys_paymentMethod` data object in the database. The event payload encompasses the newly created data, encapsulated within the root of the paylod. **Event payload**: ```json {"id":"ID","paymentMethodId":"String","userId":"ID","customerId":"String","cardHolderName":"String","cardHolderZip":"String","platform":"String","cardInfo":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent sys_paymentMethod-updated **Event topic**: `ebaycclone-ordermanagement-service-dbevent-sys_paymentmethod-updated` Activation of this event follows the update of a `sys_paymentMethod` data object. The payload contains the updated information under the `sys_paymentMethod` attribute, along with the original data prior to update, labeled as `old_sys_paymentMethod` and also you can find the old and new versions of updated-only portion of the data.. **Event payload**: ```json { old_sys_paymentMethod:{"id":"ID","paymentMethodId":"String","userId":"ID","customerId":"String","cardHolderName":"String","cardHolderZip":"String","platform":"String","cardInfo":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, sys_paymentMethod:{"id":"ID","paymentMethodId":"String","userId":"ID","customerId":"String","cardHolderName":"String","cardHolderZip":"String","platform":"String","cardInfo":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, oldDataValues, newDataValues } ``` ## DbEvent sys_paymentMethod-deleted **Event topic**: `ebaycclone-ordermanagement-service-dbevent-sys_paymentmethod-deleted` This event announces the deletion of a `sys_paymentMethod` data object, covering both hard deletions (permanent removal) and soft deletions (where the `isActive` attribute is set to false). Regardless of the deletion type, the event payload will present the data as it was immediately before deletion, highlighting an `isActive` status of false for soft deletions. **Event payload**: ```json {"id":"ID","paymentMethodId":"String","userId":"ID","customerId":"String","cardHolderName":"String","cardHolderZip":"String","platform":"String","cardInfo":"Object","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` # ElasticSearch Index Events Within the `OrderManagement` service, most data objects are mirrored in ElasticSearch indices, ensuring these indices remain syncronized with their database counterparts through creation, updates, and deletions. These indices serve dual purposes: they act as a data source for external services and furnish aggregated data tailored to enhance frontend user experiences. Consequently, an ElasticSearch index might encapsulate data in its original form or aggregate additional information from other data objects. These aggregations can include both one-to-one and one-to-many relationships not only with database objects within the same service but also across different services. This capability allows developers to access comprehensive, aggregated data efficiently. By subscribing to ElasticSearch index events, developers are notified when an index is updated and can directly obtain the aggregated entity within the event payload, bypassing the need for separate ElasticSearch queries. It's noteworthy that some services may augment another service's index by appending to the entity’s `extends` object. In such scenarios, an `*-extended` event will contain only the newly added data. Should you require the complete dataset, you would need to retrieve the full ElasticSearch index entity using the provided ID. This approach to indexing and event handling facilitates a modular, interconnected architecture where services can seamlessly integrate and react to changes, enriching the overall data ecosystem and enabling more dynamic, responsive applications. ## Index Event ordermanagementorder-created **Event topic**: `elastic-index-ebaycclone_ordermanagementorder-created` **Event payload**: ```json {"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event ordermanagementorder-updated **Event topic**: `elastic-index-ebaycclone_ordermanagementorder-created` **Event payload**: ```json {"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event ordermanagementorder-deleted **Event topic**: `elastic-index-ebaycclone_ordermanagementorder-deleted` **Event payload**: ```json {"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event ordermanagementorder-extended **Event topic**: `elastic-index-ebaycclone_ordermanagementorder-extended` **Event payload**: ```js { id: id, extends: { [extendName]: "Object", [extendName + "_count"]: "Number", }, } ``` # Route Events Route events are emitted following the successful execution of a route. While most routes perform CRUD (Create, Read, Update, Delete) operations on data objects, resulting in route events that closely resemble database events, there are distinctions worth noting. A single route execution might trigger multiple CRUD actions and ElasticSearch indexing operations. However, for those primarily concerned with the overarching business logic and its outcomes, listening to the consolidated route event, published once at the conclusion of the route's execution, is more pertinent. Moreover, routes often deliver aggregated data beyond the primary database object, catering to specific client needs. For instance, creating a data object via a route might not only return the entity's data but also route-specific metrics, such as the executing user's permissions related to the entity. Alternatively, a route might automatically generate default child entities following the creation of a parent object. Consequently, the route event encapsulates a unified dataset encompassing both the parent and its children, in contrast to individual events triggered for each entity created. Therefore, subscribing to route events can offer a richer, more contextually relevant set of information aligned with business logic. The payload of a route event mirrors the REST response JSON of the route, providing a direct and comprehensive reflection of the data and metadata communicated to the client. This ensures that subscribers to route events receive a payload that encapsulates both the primary data involved and any additional information deemed significant at the business level, facilitating a deeper understanding and integration of the service's functional outcomes. ## Route Event ordermanagementorders-listed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorders-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrders` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrders`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrders","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","orderManagementOrders":[{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementorderitem-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderitem-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrderItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrderItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrderItem","method":"GET","action":"get","appVersion":"Version","rowCount":1,"orderManagementOrderItem":{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorder-deleted **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorder-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorder-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorder-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"GET","action":"get","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderstatus-updated **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderstatus-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event orderstripewebhook-completed **Event topic** : `ebaycclone-ordermanagement-service-orderstripewebhook-completed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderbyproductid-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderbyproductid-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"GET","action":"get","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorder-created **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorder-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"POST","action":"create","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderitems-listed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderitems-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrderItems` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrderItems`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrderItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","orderManagementOrderItems":[{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ownordermanagementorders-listed **Event topic** : `ebaycclone-ordermanagement-service-ownordermanagementorders-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrders` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrders`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrders","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","orderManagementOrders":[{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementownorderitem-lissed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementownorderitem-lissed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrderItems` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrderItems`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrderItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","orderManagementOrderItems":[{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementorderitem-created **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderitem-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrderItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrderItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrderItem","method":"POST","action":"create","appVersion":"Version","rowCount":1,"orderManagementOrderItem":{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment2-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment2-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayments2-listed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayments2-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayments` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayments`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayments","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","sys_orderManagementOrderPayments":[{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementorderpayment-created **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"POST","action":"create","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment-updated **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment-deleted **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayments2-listed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayments2-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayments` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayments`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayments","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","sys_orderManagementOrderPayments":[{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementorderpaymentbyorderid-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpaymentbyorderid-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpaymentbypaymentid-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpaymentbypaymentid-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment2-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment2-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment-started **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-started` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},"paymentResult":{"paymentTicketId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"Enum","paymentIntentInfo":"Object","statusLiteral":"String","amount":"Double","currency":"String","success":true,"description":"String","metadata":"Object","paymentUserParams":"Object"}} ``` ## Route Event ordermanagementorderpayment-refreshed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-refreshed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},"paymentResult":{"paymentTicketId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"Enum","paymentIntentInfo":"Object","statusLiteral":"String","amount":"Double","currency":"String","success":true,"description":"String","metadata":"Object","paymentUserParams":"Object"}} ``` ## Route Event ordermanagementorderpayment-calledback **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-calledback` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"POST","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},"paymentResult":{"paymentTicketId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"Enum","paymentIntentInfo":"Object","statusLiteral":"String","amount":"Double","currency":"String","success":true,"description":"String","metadata":"Object","paymentUserParams":"Object"}} ``` ## Route Event paymentcustomerbyuserid-retrived **Event topic** : `ebaycclone-ordermanagement-service-paymentcustomerbyuserid-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_paymentCustomer` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_paymentCustomer`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_paymentCustomer","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_paymentCustomer":{"id":"ID","userId":"ID","customerId":"String","platform":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event paymentcustomers-listed **Event topic** : `ebaycclone-ordermanagement-service-paymentcustomers-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_paymentCustomers` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_paymentCustomers`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_paymentCustomers","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","sys_paymentCustomers":[{"id":"ID","userId":"ID","customerId":"String","platform":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event paymentcustomermethods-listed **Event topic** : `ebaycclone-ordermanagement-service-paymentcustomermethods-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_paymentMethods` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_paymentMethods`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_paymentMethods","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","sys_paymentMethods":[{"id":"ID","paymentMethodId":"String","userId":"ID","customerId":"String","cardHolderName":"String","cardHolderZip":"String","platform":"String","cardInfo":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Index Event ordermanagementorderitem-created **Event topic**: `elastic-index-ebaycclone_ordermanagementorderitem-created` **Event payload**: ```json {"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event ordermanagementorderitem-updated **Event topic**: `elastic-index-ebaycclone_ordermanagementorderitem-created` **Event payload**: ```json {"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event ordermanagementorderitem-deleted **Event topic**: `elastic-index-ebaycclone_ordermanagementorderitem-deleted` **Event payload**: ```json {"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event ordermanagementorderitem-extended **Event topic**: `elastic-index-ebaycclone_ordermanagementorderitem-extended` **Event payload**: ```js { id: id, extends: { [extendName]: "Object", [extendName + "_count"]: "Number", }, } ``` # Route Events Route events are emitted following the successful execution of a route. While most routes perform CRUD (Create, Read, Update, Delete) operations on data objects, resulting in route events that closely resemble database events, there are distinctions worth noting. A single route execution might trigger multiple CRUD actions and ElasticSearch indexing operations. However, for those primarily concerned with the overarching business logic and its outcomes, listening to the consolidated route event, published once at the conclusion of the route's execution, is more pertinent. Moreover, routes often deliver aggregated data beyond the primary database object, catering to specific client needs. For instance, creating a data object via a route might not only return the entity's data but also route-specific metrics, such as the executing user's permissions related to the entity. Alternatively, a route might automatically generate default child entities following the creation of a parent object. Consequently, the route event encapsulates a unified dataset encompassing both the parent and its children, in contrast to individual events triggered for each entity created. Therefore, subscribing to route events can offer a richer, more contextually relevant set of information aligned with business logic. The payload of a route event mirrors the REST response JSON of the route, providing a direct and comprehensive reflection of the data and metadata communicated to the client. This ensures that subscribers to route events receive a payload that encapsulates both the primary data involved and any additional information deemed significant at the business level, facilitating a deeper understanding and integration of the service's functional outcomes. ## Route Event ordermanagementorders-listed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorders-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrders` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrders`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrders","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","orderManagementOrders":[{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementorderitem-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderitem-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrderItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrderItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrderItem","method":"GET","action":"get","appVersion":"Version","rowCount":1,"orderManagementOrderItem":{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorder-deleted **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorder-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorder-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorder-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"GET","action":"get","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderstatus-updated **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderstatus-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event orderstripewebhook-completed **Event topic** : `ebaycclone-ordermanagement-service-orderstripewebhook-completed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderbyproductid-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderbyproductid-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"GET","action":"get","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorder-created **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorder-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"POST","action":"create","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderitems-listed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderitems-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrderItems` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrderItems`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrderItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","orderManagementOrderItems":[{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ownordermanagementorders-listed **Event topic** : `ebaycclone-ordermanagement-service-ownordermanagementorders-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrders` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrders`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrders","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","orderManagementOrders":[{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementownorderitem-lissed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementownorderitem-lissed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrderItems` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrderItems`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrderItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","orderManagementOrderItems":[{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementorderitem-created **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderitem-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrderItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrderItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrderItem","method":"POST","action":"create","appVersion":"Version","rowCount":1,"orderManagementOrderItem":{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment2-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment2-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayments2-listed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayments2-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayments` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayments`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayments","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","sys_orderManagementOrderPayments":[{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementorderpayment-created **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"POST","action":"create","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment-updated **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment-deleted **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayments2-listed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayments2-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayments` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayments`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayments","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","sys_orderManagementOrderPayments":[{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementorderpaymentbyorderid-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpaymentbyorderid-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpaymentbypaymentid-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpaymentbypaymentid-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment2-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment2-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment-started **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-started` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},"paymentResult":{"paymentTicketId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"Enum","paymentIntentInfo":"Object","statusLiteral":"String","amount":"Double","currency":"String","success":true,"description":"String","metadata":"Object","paymentUserParams":"Object"}} ``` ## Route Event ordermanagementorderpayment-refreshed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-refreshed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},"paymentResult":{"paymentTicketId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"Enum","paymentIntentInfo":"Object","statusLiteral":"String","amount":"Double","currency":"String","success":true,"description":"String","metadata":"Object","paymentUserParams":"Object"}} ``` ## Route Event ordermanagementorderpayment-calledback **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-calledback` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"POST","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},"paymentResult":{"paymentTicketId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"Enum","paymentIntentInfo":"Object","statusLiteral":"String","amount":"Double","currency":"String","success":true,"description":"String","metadata":"Object","paymentUserParams":"Object"}} ``` ## Route Event paymentcustomerbyuserid-retrived **Event topic** : `ebaycclone-ordermanagement-service-paymentcustomerbyuserid-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_paymentCustomer` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_paymentCustomer`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_paymentCustomer","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_paymentCustomer":{"id":"ID","userId":"ID","customerId":"String","platform":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event paymentcustomers-listed **Event topic** : `ebaycclone-ordermanagement-service-paymentcustomers-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_paymentCustomers` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_paymentCustomers`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_paymentCustomers","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","sys_paymentCustomers":[{"id":"ID","userId":"ID","customerId":"String","platform":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event paymentcustomermethods-listed **Event topic** : `ebaycclone-ordermanagement-service-paymentcustomermethods-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_paymentMethods` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_paymentMethods`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_paymentMethods","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","sys_paymentMethods":[{"id":"ID","paymentMethodId":"String","userId":"ID","customerId":"String","cardHolderName":"String","cardHolderZip":"String","platform":"String","cardInfo":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Index Event sys_ordermanagementorderpayment-created **Event topic**: `elastic-index-ebaycclone_sys_ordermanagementorderpayment-created` **Event payload**: ```json {"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event sys_ordermanagementorderpayment-updated **Event topic**: `elastic-index-ebaycclone_sys_ordermanagementorderpayment-created` **Event payload**: ```json {"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event sys_ordermanagementorderpayment-deleted **Event topic**: `elastic-index-ebaycclone_sys_ordermanagementorderpayment-deleted` **Event payload**: ```json {"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event sys_ordermanagementorderpayment-extended **Event topic**: `elastic-index-ebaycclone_sys_ordermanagementorderpayment-extended` **Event payload**: ```js { id: id, extends: { [extendName]: "Object", [extendName + "_count"]: "Number", }, } ``` # Route Events Route events are emitted following the successful execution of a route. While most routes perform CRUD (Create, Read, Update, Delete) operations on data objects, resulting in route events that closely resemble database events, there are distinctions worth noting. A single route execution might trigger multiple CRUD actions and ElasticSearch indexing operations. However, for those primarily concerned with the overarching business logic and its outcomes, listening to the consolidated route event, published once at the conclusion of the route's execution, is more pertinent. Moreover, routes often deliver aggregated data beyond the primary database object, catering to specific client needs. For instance, creating a data object via a route might not only return the entity's data but also route-specific metrics, such as the executing user's permissions related to the entity. Alternatively, a route might automatically generate default child entities following the creation of a parent object. Consequently, the route event encapsulates a unified dataset encompassing both the parent and its children, in contrast to individual events triggered for each entity created. Therefore, subscribing to route events can offer a richer, more contextually relevant set of information aligned with business logic. The payload of a route event mirrors the REST response JSON of the route, providing a direct and comprehensive reflection of the data and metadata communicated to the client. This ensures that subscribers to route events receive a payload that encapsulates both the primary data involved and any additional information deemed significant at the business level, facilitating a deeper understanding and integration of the service's functional outcomes. ## Route Event ordermanagementorders-listed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorders-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrders` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrders`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrders","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","orderManagementOrders":[{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementorderitem-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderitem-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrderItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrderItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrderItem","method":"GET","action":"get","appVersion":"Version","rowCount":1,"orderManagementOrderItem":{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorder-deleted **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorder-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorder-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorder-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"GET","action":"get","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderstatus-updated **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderstatus-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event orderstripewebhook-completed **Event topic** : `ebaycclone-ordermanagement-service-orderstripewebhook-completed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderbyproductid-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderbyproductid-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"GET","action":"get","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorder-created **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorder-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"POST","action":"create","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderitems-listed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderitems-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrderItems` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrderItems`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrderItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","orderManagementOrderItems":[{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ownordermanagementorders-listed **Event topic** : `ebaycclone-ordermanagement-service-ownordermanagementorders-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrders` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrders`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrders","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","orderManagementOrders":[{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementownorderitem-lissed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementownorderitem-lissed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrderItems` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrderItems`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrderItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","orderManagementOrderItems":[{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementorderitem-created **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderitem-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrderItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrderItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrderItem","method":"POST","action":"create","appVersion":"Version","rowCount":1,"orderManagementOrderItem":{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment2-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment2-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayments2-listed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayments2-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayments` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayments`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayments","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","sys_orderManagementOrderPayments":[{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementorderpayment-created **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"POST","action":"create","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment-updated **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment-deleted **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayments2-listed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayments2-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayments` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayments`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayments","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","sys_orderManagementOrderPayments":[{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementorderpaymentbyorderid-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpaymentbyorderid-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpaymentbypaymentid-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpaymentbypaymentid-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment2-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment2-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment-started **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-started` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},"paymentResult":{"paymentTicketId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"Enum","paymentIntentInfo":"Object","statusLiteral":"String","amount":"Double","currency":"String","success":true,"description":"String","metadata":"Object","paymentUserParams":"Object"}} ``` ## Route Event ordermanagementorderpayment-refreshed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-refreshed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},"paymentResult":{"paymentTicketId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"Enum","paymentIntentInfo":"Object","statusLiteral":"String","amount":"Double","currency":"String","success":true,"description":"String","metadata":"Object","paymentUserParams":"Object"}} ``` ## Route Event ordermanagementorderpayment-calledback **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-calledback` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"POST","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},"paymentResult":{"paymentTicketId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"Enum","paymentIntentInfo":"Object","statusLiteral":"String","amount":"Double","currency":"String","success":true,"description":"String","metadata":"Object","paymentUserParams":"Object"}} ``` ## Route Event paymentcustomerbyuserid-retrived **Event topic** : `ebaycclone-ordermanagement-service-paymentcustomerbyuserid-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_paymentCustomer` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_paymentCustomer`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_paymentCustomer","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_paymentCustomer":{"id":"ID","userId":"ID","customerId":"String","platform":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event paymentcustomers-listed **Event topic** : `ebaycclone-ordermanagement-service-paymentcustomers-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_paymentCustomers` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_paymentCustomers`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_paymentCustomers","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","sys_paymentCustomers":[{"id":"ID","userId":"ID","customerId":"String","platform":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event paymentcustomermethods-listed **Event topic** : `ebaycclone-ordermanagement-service-paymentcustomermethods-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_paymentMethods` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_paymentMethods`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_paymentMethods","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","sys_paymentMethods":[{"id":"ID","paymentMethodId":"String","userId":"ID","customerId":"String","cardHolderName":"String","cardHolderZip":"String","platform":"String","cardInfo":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Index Event sys_paymentcustomer-created **Event topic**: `elastic-index-ebaycclone_sys_paymentcustomer-created` **Event payload**: ```json {"id":"ID","userId":"ID","customerId":"String","platform":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event sys_paymentcustomer-updated **Event topic**: `elastic-index-ebaycclone_sys_paymentcustomer-created` **Event payload**: ```json {"id":"ID","userId":"ID","customerId":"String","platform":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event sys_paymentcustomer-deleted **Event topic**: `elastic-index-ebaycclone_sys_paymentcustomer-deleted` **Event payload**: ```json {"id":"ID","userId":"ID","customerId":"String","platform":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event sys_paymentcustomer-extended **Event topic**: `elastic-index-ebaycclone_sys_paymentcustomer-extended` **Event payload**: ```js { id: id, extends: { [extendName]: "Object", [extendName + "_count"]: "Number", }, } ``` # Route Events Route events are emitted following the successful execution of a route. While most routes perform CRUD (Create, Read, Update, Delete) operations on data objects, resulting in route events that closely resemble database events, there are distinctions worth noting. A single route execution might trigger multiple CRUD actions and ElasticSearch indexing operations. However, for those primarily concerned with the overarching business logic and its outcomes, listening to the consolidated route event, published once at the conclusion of the route's execution, is more pertinent. Moreover, routes often deliver aggregated data beyond the primary database object, catering to specific client needs. For instance, creating a data object via a route might not only return the entity's data but also route-specific metrics, such as the executing user's permissions related to the entity. Alternatively, a route might automatically generate default child entities following the creation of a parent object. Consequently, the route event encapsulates a unified dataset encompassing both the parent and its children, in contrast to individual events triggered for each entity created. Therefore, subscribing to route events can offer a richer, more contextually relevant set of information aligned with business logic. The payload of a route event mirrors the REST response JSON of the route, providing a direct and comprehensive reflection of the data and metadata communicated to the client. This ensures that subscribers to route events receive a payload that encapsulates both the primary data involved and any additional information deemed significant at the business level, facilitating a deeper understanding and integration of the service's functional outcomes. ## Route Event ordermanagementorders-listed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorders-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrders` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrders`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrders","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","orderManagementOrders":[{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementorderitem-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderitem-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrderItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrderItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrderItem","method":"GET","action":"get","appVersion":"Version","rowCount":1,"orderManagementOrderItem":{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorder-deleted **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorder-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorder-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorder-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"GET","action":"get","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderstatus-updated **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderstatus-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event orderstripewebhook-completed **Event topic** : `ebaycclone-ordermanagement-service-orderstripewebhook-completed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderbyproductid-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderbyproductid-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"GET","action":"get","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorder-created **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorder-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"POST","action":"create","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderitems-listed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderitems-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrderItems` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrderItems`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrderItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","orderManagementOrderItems":[{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ownordermanagementorders-listed **Event topic** : `ebaycclone-ordermanagement-service-ownordermanagementorders-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrders` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrders`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrders","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","orderManagementOrders":[{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementownorderitem-lissed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementownorderitem-lissed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrderItems` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrderItems`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrderItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","orderManagementOrderItems":[{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementorderitem-created **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderitem-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrderItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrderItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrderItem","method":"POST","action":"create","appVersion":"Version","rowCount":1,"orderManagementOrderItem":{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment2-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment2-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayments2-listed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayments2-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayments` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayments`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayments","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","sys_orderManagementOrderPayments":[{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementorderpayment-created **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"POST","action":"create","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment-updated **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment-deleted **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayments2-listed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayments2-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayments` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayments`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayments","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","sys_orderManagementOrderPayments":[{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementorderpaymentbyorderid-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpaymentbyorderid-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpaymentbypaymentid-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpaymentbypaymentid-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment2-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment2-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment-started **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-started` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},"paymentResult":{"paymentTicketId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"Enum","paymentIntentInfo":"Object","statusLiteral":"String","amount":"Double","currency":"String","success":true,"description":"String","metadata":"Object","paymentUserParams":"Object"}} ``` ## Route Event ordermanagementorderpayment-refreshed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-refreshed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},"paymentResult":{"paymentTicketId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"Enum","paymentIntentInfo":"Object","statusLiteral":"String","amount":"Double","currency":"String","success":true,"description":"String","metadata":"Object","paymentUserParams":"Object"}} ``` ## Route Event ordermanagementorderpayment-calledback **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-calledback` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"POST","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},"paymentResult":{"paymentTicketId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"Enum","paymentIntentInfo":"Object","statusLiteral":"String","amount":"Double","currency":"String","success":true,"description":"String","metadata":"Object","paymentUserParams":"Object"}} ``` ## Route Event paymentcustomerbyuserid-retrived **Event topic** : `ebaycclone-ordermanagement-service-paymentcustomerbyuserid-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_paymentCustomer` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_paymentCustomer`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_paymentCustomer","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_paymentCustomer":{"id":"ID","userId":"ID","customerId":"String","platform":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event paymentcustomers-listed **Event topic** : `ebaycclone-ordermanagement-service-paymentcustomers-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_paymentCustomers` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_paymentCustomers`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_paymentCustomers","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","sys_paymentCustomers":[{"id":"ID","userId":"ID","customerId":"String","platform":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event paymentcustomermethods-listed **Event topic** : `ebaycclone-ordermanagement-service-paymentcustomermethods-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_paymentMethods` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_paymentMethods`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_paymentMethods","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","sys_paymentMethods":[{"id":"ID","paymentMethodId":"String","userId":"ID","customerId":"String","cardHolderName":"String","cardHolderZip":"String","platform":"String","cardInfo":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Index Event sys_paymentmethod-created **Event topic**: `elastic-index-ebaycclone_sys_paymentmethod-created` **Event payload**: ```json {"id":"ID","paymentMethodId":"String","userId":"ID","customerId":"String","cardHolderName":"String","cardHolderZip":"String","platform":"String","cardInfo":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event sys_paymentmethod-updated **Event topic**: `elastic-index-ebaycclone_sys_paymentmethod-created` **Event payload**: ```json {"id":"ID","paymentMethodId":"String","userId":"ID","customerId":"String","cardHolderName":"String","cardHolderZip":"String","platform":"String","cardInfo":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event sys_paymentmethod-deleted **Event topic**: `elastic-index-ebaycclone_sys_paymentmethod-deleted` **Event payload**: ```json {"id":"ID","paymentMethodId":"String","userId":"ID","customerId":"String","cardHolderName":"String","cardHolderZip":"String","platform":"String","cardInfo":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event sys_paymentmethod-extended **Event topic**: `elastic-index-ebaycclone_sys_paymentmethod-extended` **Event payload**: ```js { id: id, extends: { [extendName]: "Object", [extendName + "_count"]: "Number", }, } ``` # Route Events Route events are emitted following the successful execution of a route. While most routes perform CRUD (Create, Read, Update, Delete) operations on data objects, resulting in route events that closely resemble database events, there are distinctions worth noting. A single route execution might trigger multiple CRUD actions and ElasticSearch indexing operations. However, for those primarily concerned with the overarching business logic and its outcomes, listening to the consolidated route event, published once at the conclusion of the route's execution, is more pertinent. Moreover, routes often deliver aggregated data beyond the primary database object, catering to specific client needs. For instance, creating a data object via a route might not only return the entity's data but also route-specific metrics, such as the executing user's permissions related to the entity. Alternatively, a route might automatically generate default child entities following the creation of a parent object. Consequently, the route event encapsulates a unified dataset encompassing both the parent and its children, in contrast to individual events triggered for each entity created. Therefore, subscribing to route events can offer a richer, more contextually relevant set of information aligned with business logic. The payload of a route event mirrors the REST response JSON of the route, providing a direct and comprehensive reflection of the data and metadata communicated to the client. This ensures that subscribers to route events receive a payload that encapsulates both the primary data involved and any additional information deemed significant at the business level, facilitating a deeper understanding and integration of the service's functional outcomes. ## Route Event ordermanagementorders-listed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorders-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrders` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrders`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrders","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","orderManagementOrders":[{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementorderitem-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderitem-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrderItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrderItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrderItem","method":"GET","action":"get","appVersion":"Version","rowCount":1,"orderManagementOrderItem":{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorder-deleted **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorder-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorder-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorder-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"GET","action":"get","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderstatus-updated **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderstatus-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event orderstripewebhook-completed **Event topic** : `ebaycclone-ordermanagement-service-orderstripewebhook-completed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderbyproductid-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderbyproductid-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"GET","action":"get","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorder-created **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorder-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"POST","action":"create","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderitems-listed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderitems-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrderItems` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrderItems`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrderItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","orderManagementOrderItems":[{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ownordermanagementorders-listed **Event topic** : `ebaycclone-ordermanagement-service-ownordermanagementorders-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrders` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrders`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrders","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","orderManagementOrders":[{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementownorderitem-lissed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementownorderitem-lissed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrderItems` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrderItems`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrderItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","orderManagementOrderItems":[{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementorderitem-created **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderitem-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrderItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrderItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrderItem","method":"POST","action":"create","appVersion":"Version","rowCount":1,"orderManagementOrderItem":{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment2-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment2-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayments2-listed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayments2-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayments` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayments`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayments","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","sys_orderManagementOrderPayments":[{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementorderpayment-created **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"POST","action":"create","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment-updated **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment-deleted **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayments2-listed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayments2-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayments` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayments`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayments","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","sys_orderManagementOrderPayments":[{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event ordermanagementorderpaymentbyorderid-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpaymentbyorderid-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpaymentbypaymentid-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpaymentbypaymentid-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment2-retrived **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment2-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_orderManagementOrderPayment` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_orderManagementOrderPayment`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event ordermanagementorderpayment-started **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-started` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},"paymentResult":{"paymentTicketId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"Enum","paymentIntentInfo":"Object","statusLiteral":"String","amount":"Double","currency":"String","success":true,"description":"String","metadata":"Object","paymentUserParams":"Object"}} ``` ## Route Event ordermanagementorderpayment-refreshed **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-refreshed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},"paymentResult":{"paymentTicketId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"Enum","paymentIntentInfo":"Object","statusLiteral":"String","amount":"Double","currency":"String","success":true,"description":"String","metadata":"Object","paymentUserParams":"Object"}} ``` ## Route Event ordermanagementorderpayment-calledback **Event topic** : `ebaycclone-ordermanagement-service-ordermanagementorderpayment-calledback` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `orderManagementOrder` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`orderManagementOrder`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"POST","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},"paymentResult":{"paymentTicketId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"Enum","paymentIntentInfo":"Object","statusLiteral":"String","amount":"Double","currency":"String","success":true,"description":"String","metadata":"Object","paymentUserParams":"Object"}} ``` ## Route Event paymentcustomerbyuserid-retrived **Event topic** : `ebaycclone-ordermanagement-service-paymentcustomerbyuserid-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_paymentCustomer` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_paymentCustomer`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_paymentCustomer","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_paymentCustomer":{"id":"ID","userId":"ID","customerId":"String","platform":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event paymentcustomers-listed **Event topic** : `ebaycclone-ordermanagement-service-paymentcustomers-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_paymentCustomers` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_paymentCustomers`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_paymentCustomers","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","sys_paymentCustomers":[{"id":"ID","userId":"ID","customerId":"String","platform":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event paymentcustomermethods-listed **Event topic** : `ebaycclone-ordermanagement-service-paymentcustomermethods-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `sys_paymentMethods` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`sys_paymentMethods`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_paymentMethods","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","sys_paymentMethods":[{"id":"ID","paymentMethodId":"String","userId":"ID","customerId":"String","cardHolderName":"String","cardHolderZip":"String","platform":"String","cardInfo":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` # Copyright All sources, documents and other digital materials are copyright of . # About Us For more information please visit our website: . . . # **EBAYCCLONE** FRONTEND GUIDE FOR AI CODING AGENTS This document is a rest api guide for the ebaycclone project. The document is designed for AI agents who will generate frontend code that will consume the project backend. The project has got 1 auth service, 1 notification service, 1 bff service and business services. Each service is a separate microservice application and listens the HTTP request from different service urls. The services may be in preview server, staging server or real production server. So each service have got 3 acess urls. Frontend application should support all deployemnt servers in the development phase, and user should be able to select the target api server in the login page. ## Project Introduction ebaycClone is a comprehensive backend for an online marketplace supporting auctions and fixed-price sales of physical goods, with role-based access, public user registration, Stripe payments, notifications, and robust ownership enforcement. ## API Structure ### Object Structure of a Successfull Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client. **HTTP Status Codes:** - **200 OK**: This status code is returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request has been processed successfully. - **201 Created**: This status code is specific to CREATE operations, signifying that the requested resource has been successfully created. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling the successful execution of the request. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` - **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation performed. ### Additional Data Each api may have include addtional data other than the main data object according to the business logic of the API. They will be given in each API's response signature. ### Error Response If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity: - **400 Bad Request**: The request was improperly formatted or contained invalid parameters, preventing the server from processing it. - **401 Unauthorized**: The request lacked valid authentication token , login required - **403 Forbidden Error** Curent token provided do not grant access to the requested resource. - **404 Not Found**: The requested resource was not found on the server. - **500 Internal Server Error**: The server encountered an unexpected condition that prevented it from fulfilling the request. Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Accessing the backend Each service of the backend has got its own url according to the deployment environement. User may want to test the frontend in one of the 3 deployments of the application, preview, staging and production. Please ensure that register and login pages do have a deployemnt server selection option, so as the frontned coding agent you can arrange the base url path of all services. The base url of the application in each environment is as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com` * **Staging:** `https://ebaycclone-stage.mindbricks.co` * **Production:** `https://ebaycclone.mindbricks.co` For the auth service the base url is as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` For each other service, the service base url will be given in service sections. Any login requied request to the backend should have a valid token, when a user makes a successfull login, the ressponse JSON includes a JWT access token in the `accessToken`fields. In normal conditions, this token is also set to the cookie and then consumed automatically, but since AI coding agents preview options may fail to use cookies, please ensure that in each request include the access token in the bearer auth header. ## Registration Management First of all please ensure that register and login pages do have a deployemnt server selection option, so as the frontned coding agent you can arrange the base url path of all services. Start with a landing page and arranging register, verification and login flow. So at the first step, you need a general knowledge of the application to make a good landing page and the authetication flow. ### How To Register Using `registeruser` route of auth api, send the required fields to the backend in your registration page. The registerUser api in in `auth` service, is described with request and response structure below. Note that since `registerUser` api is a business api, it has a version control, so please call it with the given version like `/v1/registeruser` ### `Register User` API This api is used by public users to register themselves **Rest Route** The `registerUser` API REST controller can be triggered via the following route: `/v1/registeruser` **Rest Request Parameters** The `registerUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **password** : The password defined by the the user that is being registered. **fullname** : The fullname defined by the the user that is being registered. **email** : The email defined by the the user that is being registered. **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` After a successful registration, frontend code should handle the verification needs. The registration response will have a `user` object in the root envelope, this object will have user information with an `id` parameter. ### Email Verification In the registration response, you should check the property `emailVerificationNeeded` in the reponse root, and if this property is true you should start the email verification flow. After login process, if you get an HTTP error status, and if there is an `errCode` property in the response with `EmailVerificationNeeded` value, you should start the email verification flow. 1. Call the email verification `start` route of the backend (described below) with the user email, backend will send a secret code to the given email adresss. **Backend can send the email message if the architect defined a real mail service or smtp server, so during the development time backend will send the secret code also to the frontend. You can get this secret code from the response within the `secretCode` property**. 2. The secret code in the sent email message will be a 6 digits code , and you should arrange an input page so that the user can paste this code to the frontend application. Please navigate to this input page after you start the verification process. **If the secretCode is sent to the frontend for test purposes, then you should show it as info in the input page, so that user can copy and paste it**. 3. There is a `codeIndex` property in the start response, please show it's value on the input page, so that user can match the index in the message with the one on the screen. 4. When the user submits the code, please complete the email verification using the `complete` route of the backend (described below) with the user email and the secret code. 5. After you get a successful response from email verification, you can navigate to the login page. Here is the `start`and `complete` routes of email verification. These are system routes , so they dont have a version control. #### `POST /verification-services/email-verification/start` **Purpose:** Starts the email verification by generating and sending a secret code. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `email` | String | Yes | User’s email address to verify | **Example Request** ```json { "email": "user@example.com" } ``` **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ In production, `secretCode` is **not** returned — only sent via email. **Error Responses** * `400 Bad Request`: Already verified * `403 Forbidden`: Too many attempts (rate limit) --- #### `POST /verification-services/email-verification/complete` **Purpose:** Completes the verification using the received code. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `email` | String | Yes | User’s email | | `secretCode` | String | Yes | Verification code | **Success Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` **Error Responses** * `403 Forbidden`: Code expired or mismatched * `404 Not Found`: No verification in progress --- ## Login Management After a successfull login and completing required verifications, user can now login. Please make a fancy minimal login page where user can enter his email and password. ## Bucket Management This application has a bucket service and is used to store user or other objects related files. Bucket service is login agnostic, so when accessing for write or private read, you should insert a bucket token (given by services) to your request authorization header as bearer token. **User Bucket** This bucket is used to store public user files for each user. When a user logs in, or in /currentuser response there is `userBucketToken` to be used when sending user related public files to the bucket service. To upload `POST {baseUrl}/bucket/upload` Request body is form data which includes the bucketId and the file as binary in `files` property. ```js { bucketId: "{userId}-public-user-bucket", files: {binary} } ``` Response status is 200 on succesfull result, eg body: ```json { "success": true, "data": [ { "fileId": "9da03f6d-0409-41ad-bb06-225a244ae408", "originalName": "test (10).png", "mimeType": "image/png", "size": 604063, "status": "uploaded", "bucketName": "f7103b85-fcda-4dec-92c6-c336f71fd3a2-public-user-bucket", "isPublic": true, "downloadUrl": "https://babilcom.mindbricks.co/bucket/download/9da03f6d-0409-41ad-bb06-225a244ae408" } ] } ``` To download a file from the bucket, you should know its fileId, so if youupload an avatar or something else, be sure that the download url or the fileId is stored in backend. Bucket is mostly used, in object creations where alos demands an addtional file like a product image or user avatar. So after you upload your image to the bucket, insert the returned download url to the related property in the related object creation. **Application Bucket** This Ebaycclone application alos has common public bucket which everybody has a read access, but only users who have `superAdmin`, `admin` or `saasAdmin` roles can write (upload) to the bucket. The common public project bucket id is `"ebaycclone-public-common-bucket"` and in certain areas like product image uploads, since the user will already have the admin bucket token, he will be able to upload realted object images. Please make your UI arrangements as able to upload files to the bucket using these bucket tokens. **Object Buckets** Some objects may return also a bucket token, to upload or access related files with object. For example, when you get a project's data in a project management application, if there is a public or private bucket token, this is provided mostly for uploading project related files or downloading them with the token. These buckets will be used according to the descriptions given along with the object definitions. ## Role Management This Ebaycclone may have different role names defined fro different business logic. But unless another case is asked by the user, respect to the admin roles which may be `superAdmin`, `admin` or `saasAdmin` in the currentuser or login response given with the `roleId`property. ```json { // ... "roleId":"superAdmin", // ... } ``` If the application needs an admin panel, or any admin related page, please use these roleId's to decide if the user can access those pages or not. ## 1. Authentication Routes ### 1.1 `POST /login` — User Login **Purpose:** Verifies user credentials and creates an authenticated session with a JWT access token. **Access Routes:** * `GET /login`: Returns a minimal HTML login page (for browser-based testing). * `POST /login`: Authenticates user credentials and returns an access token and session. #### Request Parameters | Parameter | Type | Required | Source | | ---------- | ------ | -------- | ----------------------- | | `username` | String | Yes | `request.body.username` | | `password` | String | Yes | `request.body.password` | #### Behavior * Authenticates credentials and returns a session object. * Sets cookie: `projectname-access-token[-tenantCodename]` * Adds the same token in response headers. * Accepts either `username` or `email` fields (if both exist, `username` is prioritized). #### Example ```js axios.post("/login", { username: "user@example.com", password: "securePassword" }); ``` #### Success Response ```json { "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", //... } ``` #### Error Responses * `401 Unauthorized`: Invalid credentials * `403 Forbidden`: Email/mobile verification or 2FA pending * `400 Bad Request`: Missing parameters --- ### 1.2 `POST /logout` — User Logout **Purpose:** Terminates the current session and clears associated authentication tokens. #### Behavior * Invalidates session (if exists). * Clears cookie `projectname-access-token[-tenantCodename]`. * Returns a confirmation response (always `200 OK`). #### Example ```js axios.post("/logout", {}, { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` #### Notes * Can be called without a session (idempotent behavior). * Works for both cookie-based and token-based sessions. #### Success Response ```json { "status": "OK", "message": "User logged out successfully" } ``` --- ## 2. Verification Services Overview All verification routes are grouped under the `/verification-services` base path. They follow a **two-step verification pattern**: `start` → `complete`. --- ## 3. Email Verification ### 3.1 Trigger Scenarios * After registration (`emailVerificationRequiredForLogin` = true) * When updating email address * When login fails due to unverified email ### 3.2 Flow Summary 1. `/start` → Generate & send code via email. 2. `/complete` → Verify code and mark email as verified. ** PLEASE NOTE ** Email verification is a frontend triiggered process. After user registers, the frontend should start the email verification process and navigate to its code input page. --- ### 3.3 `POST /verification-services/email-verification/start` **Purpose:** Starts the email verification by generating and sending a secret code. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `email` | String | Yes | User’s email address to verify | **Example Request** ```json { "email": "user@example.com" } ``` **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ In production, `secretCode` is **not** returned — only sent via email. **Error Responses** * `400 Bad Request`: Already verified * `403 Forbidden`: Too many attempts (rate limit) --- ### 3.4 `POST /verification-services/email-verification/complete` **Purpose:** Completes the verification using the received code. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `email` | String | Yes | User’s email | | `secretCode` | String | Yes | Verification code | **Success Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` **Error Responses** * `403 Forbidden`: Code expired or mismatched * `404 Not Found`: No verification in progress --- ### 3.5 Behavioral Notes * **Resend Cooldown:** `resendTimeWindow` (e.g. 60s) * **Expiration:** Codes expire after `expireTimeWindow` (e.g. 1 day) * **Single Active Session:** One verification per user --- ## 4. Mobile Verification ### 4.1 Trigger Scenarios * After registration (`mobileVerificationRequiredForLogin` = true) * When updating phone number * On login requiring mobile verification ### 4.2 Flow 1. `/start` → Sends verification code via SMS 2. `/complete` → Validates code and confirms number --- ### 4.3 `POST /verification-services/mobile-verification/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------ | | `email` | String | Yes | User’s email to locate mobile record | **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 180, "verificationType": "byCode", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ `secretCode` returned only in development. **Errors** * `400 Bad Request`: Already verified * `403 Forbidden`: Rate-limited --- ### 4.4 `POST /verification-services/mobile-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------------- | | `email` | String | Yes | Associated email | | `secretCode` | String | Yes | Code received via SMS | **Success Response** ```json { "status": "OK", "isVerified": true, "mobile": "+1 333 ...", // in testMode "userId": "user-uuid", } ``` --- ### 4.5 Behavioral Notes * **Cooldown:** One code per minute * **Expiration:** Codes valid for 1 day * **One Session Per User** --- ## 5. Two-Factor Authentication (2FA) ### 5.1 Email 2FA **Flow** 1. `/start` → Generates and sends email code 2. `/complete` → Verifies code and updates session --- #### `POST /verification-services/email-2factor-verification/start` | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ---------------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Current session | | `client` | String | No | Optional context | | `reason` | String | No | Reason for 2FA | **Response** ```json { "status": "OK", "sessionId": "user session id UUID", "userId": "user-uuid", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", } ``` --- #### `POST /verification-services/email-2factor-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `secretCode` | String | Yes | Code from email | **Response** ```json { // user session data "sessionId": "session-uuid", // ... } ``` --- ### 5.2 Mobile 2FA **Flow** 1. `/start` → Sends SMS code 2. `/complete` → Validates and finalizes session --- #### `POST /verification-services/mobile-2factor-verification/start` | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ----------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `client` | String | No | Context | | `reason` | String | No | Reason | **Response** ```json { "status": "OK", "sessionId": "user session id UUID", "userId": "user-uuid", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", } ``` --- #### `POST /verification-services/mobile-2factor-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------ | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `secretCode` | String | Yes | Code via SMS | **Response** ```json { // user session data "sessionId": "session-uuid", // ... } ``` --- ### 5.3 2FA Behavioral Notes * One active code per session * Cooldown: `resendTimeWindow` (e.g., 60s) * Expiration: `expireTimeWindow` (e.g., 5m) --- ## 6. Password Reset ### 6.1 By Email **Flow** 1. `/start` → Sends verification code via email 2. `/complete` → Validates and resets password --- #### `POST /verification-services/password-reset-by-email/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------- | | `email` | String | Yes | User email | **Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` #### `POST /verification-services/password-reset-by-email/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------- | | `email` | String | Yes | User email | | `secretCode` | String | Yes | Code received | | `password` | String | Yes | New password | **Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` --- ### 6.2 By Mobile **Flow** 1. `/start` → Sends SMS code 2. `/complete` → Validates and resets password --- #### `POST /verification-services/password-reset-by-mobile/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------- | | `mobile` | String | Yes | Mobile number | **Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` #### `POST /verification-services/password-reset-by-mobile/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ---------------- | | `email` | String | Yes | Associated email | | `secretCode` | String | Yes | Code via SMS | | `password` | String | Yes | New password | **Response** ```json { "status": "OK", "isVerified": true, "mobile": "+1 444 ....", // in testMode "userId": "user-uuid", } ``` --- ### 6.3 Behavioral Notes * Cooldown: 60s resend * Expiration: 24h * One session per user * Works without an active login session --- ## 7. Verification Method Types ### 7.1 `byCode` User manually enters the 6-digit code in frontend. ### 7.2 `byLink` Frontend handles a one-click verification via email/SMS link containing code parameters. ## 8) `GET /currentuser` — Current Session **Purpose** Return the currently authenticated user’s session. **Route Type** `sessionInfo` **Authentication** Requires a valid access token (header or cookie). ### Request *No parameters.* ### Example ```js axios.get("/currentuser", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) Returns the session object (identity, tenancy, token metadata): ```json { "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", "roleId": "user", "tenantId": "abc123", "accessToken": "jwt-token-string", "...": "..." } ``` ### Errors * **401 Unauthorized** — No active session/token ```json { "status": "ERR", "message": "No login found" } ``` **Notes** * Commonly called by web/mobile clients after login to hydrate session state. * Includes key identity/tenant fields and a token reference (if applicable). * Ensure a valid token is supplied to receive a 200 response. --- ## 9) `GET /permissions` — List Effective Permissions **Purpose** Return all effective permission grants for the current user. **Route Type** `permissionFetch` **Authentication** Requires a valid access token. ### Request *No parameters.* ### Example ```js axios.get("/permissions", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) Array of permission grants (aligned with `givenPermissions`): ```json [ { "id": "perm1", "permissionName": "adminPanel.access", "roleId": "admin", "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" }, { "id": "perm2", "permissionName": "orders.manage", "roleId": null, "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" } ] ``` **Field meanings (per item):** * `permissionName`: Granted permission key. * `roleId`: Present if granted via role. * `subjectUserId`: Present if granted directly to the user. * `subjectUserGroupId`: Present if granted via group. * `objectId`: Present if scoped to a specific object (OBAC). * `canDo`: `true` if enabled, `false` if restricted. ### Errors * **401 Unauthorized** — No active session ```json { "status": "ERR", "message": "No login found" } ``` * **500 Internal Server Error** — Unexpected failure **Notes** * Available on all Mindbricks-generated services (not only Auth). * **Auth service:** Reads live `givenPermissions` from DB. * **Other services:** Typically respond from a cached/projected view (e.g., ElasticSearch) for faster checks. > **Tip:** Cache permission results client-side/server-side and refresh after login or permission updates. --- ## 10) `GET /permissions/:permissionName` — Check Permission Scope **Purpose** Check whether the current user has a specific permission and return any scoped object exceptions/inclusions. **Route Type** `permissionScopeCheck` **Authentication** Requires a valid access token. ### Path Parameters | Name | Type | Required | Source | | ---------------- | ------ | -------- | ------------------------------- | | `permissionName` | String | Yes | `request.params.permissionName` | ### Example ```js axios.get("/permissions/orders.manage", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) ```json { "canDo": true, "exceptions": [ "a1f2e3d4-xxxx-yyyy-zzzz-object1", "b2c3d4e5-xxxx-yyyy-zzzz-object2" ] } ``` **Interpretation** * If `canDo: true`: permission is generally granted **except** the listed `exceptions` (restrictions). * If `canDo: false`: permission is generally **not** granted, **only** allowed for the listed `exceptions` (selective overrides). * `exceptions` contains object IDs (UUID strings) from the relevant domain model. ### Errors * **401 Unauthorized** — No active session/token. ## Services And Data Object ## Auth Service Authentication service for the project ### Auth Service Data Objects **User** A data object that stores the user information and handles login settings. ### Auth Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` ### `Get User` API This api is used by admin roles or the users themselves to get the user profile information. **Rest Route** The `getUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `getUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users/:userId** ```js axios({ method: 'GET', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update User` API This route is used by admins to update user profiles. **Rest Route** The `updateUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `updateUser` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/users/:userId** ```js axios({ method: 'PATCH', url: `/v1/users/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Profile` API This route is used by users to update their profiles. **Rest Route** The `updateProfile` API REST controller can be triggered via the following route: `/v1/profile/:userId` **Rest Request Parameters** The `updateProfile` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/profile/:userId** ```js axios({ method: 'PATCH', url: `/v1/profile/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create User` API This api is used by admin roles to create a new user manually from admin panels **Rest Route** The `createUser` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `createUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | email | String | true | request.body?.email | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **email** : A string value to represent the user's email. **password** : A string value to represent the user's password. It will be stored as hashed. **fullname** : A string value to represent the fullname of the user **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/users** ```js axios({ method: 'POST', url: '/v1/users', data: { avatar:"String", email:"String", password:"String", fullname:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete User` API This api is used by admins to delete user profiles. **Rest Route** The `deleteUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `deleteUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/users/:userId** ```js axios({ method: 'DELETE', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Archive Profile` API This api is used by users to archive their profiles. **Rest Route** The `archiveProfile` API REST controller can be triggered via the following route: `/v1/archiveprofile/:userId` **Rest Request Parameters** The `archiveProfile` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/archiveprofile/:userId** ```js axios({ method: 'DELETE', url: `/v1/archiveprofile/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Users` API The list of users is filtered by the tenantId. **Rest Route** The `listUsers` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `listUsers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users** ```js axios({ method: 'GET', url: '/v1/users', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Search Users` API The list of users is filtered by the tenantId. **Rest Route** The `searchUsers` API REST controller can be triggered via the following route: `/v1/searchusers` **Rest Request Parameters** The `searchUsers` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | keyword | String | true | request.query?.keyword | **keyword** : **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchusers** ```js axios({ method: 'GET', url: '/v1/searchusers', data: { }, params: { keyword:'"String"', } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Userrole` API This route is used by admin roles to update the user role.The default role is user when a user is registered. A user's role can be updated by superAdmin or admin **Rest Route** The `updateUserRole` API REST controller can be triggered via the following route: `/v1/userrole/:userId` **Rest Request Parameters** The `updateUserRole` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | roleId | String | true | request.body?.roleId | **userId** : This id paremeter is used to select the required data object that will be updated **roleId** : The new roleId of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userrole/:userId** ```js axios({ method: 'PATCH', url: `/v1/userrole/${userId}`, data: { roleId:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpassword` API This route is used to update the password of users in the profile page by users themselves **Rest Route** The `updateUserPassword` API REST controller can be triggered via the following route: `/v1/userpassword/:userId` **Rest Request Parameters** The `updateUserPassword` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | oldPassword | String | true | request.body?.oldPassword | | newPassword | String | true | request.body?.newPassword | **userId** : This id paremeter is used to select the required data object that will be updated **oldPassword** : The old password of the user that will be overridden bu the new one. Send for double check. **newPassword** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpassword/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpassword/${userId}`, data: { oldPassword:"String", newPassword:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpasswordbyadmin` API This route is used to change any user password by admins only. Superadmin can chnage all passwords, admins can change only nonadmin passwords **Rest Route** The `updateUserPasswordByAdmin` API REST controller can be triggered via the following route: `/v1/userpasswordbyadmin/:userId` **Rest Request Parameters** The `updateUserPasswordByAdmin` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | password | String | true | request.body?.password | **userId** : This id paremeter is used to select the required data object that will be updated **password** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpasswordbyadmin/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpasswordbyadmin/${userId}`, data: { password:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Briefuser` API This route is used by public to get simple user profile information. **Rest Route** The `getBriefUser` API REST controller can be triggered via the following route: `/v1/briefuser/:userId` **Rest Request Parameters** The `getBriefUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/briefuser/:userId** ```js axios({ method: 'GET', url: `/v1/briefuser/${userId}`, data: { }, params: { } }); ``` **REST Response** This route's response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "fullname": "String", "avatar": "String", "isActive": true } } ``` ### `Register User` API This api is used by public users to register themselves **Rest Route** The `registerUser` API REST controller can be triggered via the following route: `/v1/registeruser` **Rest Request Parameters** The `registerUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **password** : The password defined by the the user that is being registered. **fullname** : The fullname defined by the the user that is being registered. **email** : The email defined by the the user that is being registered. **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## AuctionOffer Service Handles auction bids and fixed-price offers for product listings, enforces real-time auction state, handles strict offer workflows including counter-offers, and triggers domain events for bid/offer notifications. No payment or frontend aggregation logic included. ### AuctionOffer Service Data Objects **AuctionOfferOffer** Represents an offer (best offer/counter-offer) made on a fixed-price product. Tracks buyer, seller, amounts, currency, state transitions, counter-offers, and expiry. **AuctionOfferBid** Represents an individual bid placed on an auction-type product. Linked to product and user, tracks bid amount, currency, status (ACTIVE, WON, LOST, CANCELLED), and time placed. ### AuctionOffer Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auctionoffer-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auctionoffer-api` * **Production:** `https://ebaycclone.mindbricks.co/auctionoffer-api` ### `Update Auctionofferoffer` API Updates offer: accepts/declines/counters by seller, withdraws by buyer before response. Enforces status transition rules, sets respondedAt. Triggers event. **Rest Route** The `updateAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `updateAuctionOfferOffer` api has got 8 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | message | String | false | request.body?.message | | status | Enum | false | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | **auctionOfferOfferId** : This id paremeter is used to select the required data object that will be updated **counterOfferId** : References another offer (counter-offer chain). **counterMessage** : Message accompanying seller's counter-offer (optional). **counterAmount** : Counter-offer amount (when offer is COUNTERED). **message** : Message/special notes from buyer (optional). **status** : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). **expiresAt** : When this offer expires (optional). **respondedAt** : When the seller (or buyer, for counter-offer) responded/updated the offer status. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Auctionofferbid` API Creates a new bid for an auction product. Validates auction status, not seller, product type, bid window, and ensures min. increment. Updates product.currentBid and product.highestBidderId atomically. Triggers notification event. **Rest Route** The `createAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids` **Rest Request Parameters** The `createAuctionOfferBid` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | bidAmount | Double | true | request.body?.bidAmount | | currency | String | true | request.body?.currency | | status | Enum | true | request.body?.status | | productId | ID | true | request.body?.productId | **bidAmount** : Bid amount placed by the user. **currency** : ISO currency for the bid (e.g., USD, EUR). **status** : Bid status: ACTIVE, WON, LOST, CANCELLED. **productId** : Product being bid on (must be AUCTION type). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/auctionofferbids** ```js axios({ method: 'POST', url: '/v1/auctionofferbids', data: { bidAmount:"Double", currency:"String", status:"Enum", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Auctionofferbid` API Gets a single bid (only visible to owner/admin or for auction history). **Rest Route** The `getAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `getAuctionOfferBid` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | **auctionOfferBidId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'GET', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Auctionofferoffer` API Gets a single offer (shown to buyer/seller or admin). **Rest Route** The `getAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `getAuctionOfferOffer` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | **auctionOfferOfferId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'GET', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Auctionofferoffers` API Lists offers by product, user, status, or counterOffer chain. **Rest Route** The `listAuctionOfferOffers` API REST controller can be triggered via the following route: `/v1/auctionofferoffers` **Rest Request Parameters** The `listAuctionOfferOffers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers** ```js axios({ method: 'GET', url: '/v1/auctionofferoffers', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferOffers": [ { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Auctionofferbid` API Updates a bid’s status (allow only status update, e.g. CANCELLED, WIN/LOSE on admin settlement). Only owner/admin, and only if auction not ended or not settled. Triggers notification event. **Rest Route** The `updateAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `updateAuctionOfferBid` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | | status | Enum | false | request.body?.status | **auctionOfferBidId** : This id paremeter is used to select the required data object that will be updated **status** : Bid status: ACTIVE, WON, LOST, CANCELLED. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { status:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Auctionofferoffer` API Creates a new offer for a fixed-price product, validating acceptOffers, type, eligibility, and product/seller/buyer active. Defaults to PENDING state. Triggers notification event. **Rest Route** The `createAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers` **Rest Request Parameters** The `createAuctionOfferOffer` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | productId | ID | true | request.body?.productId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | offerAmount | Double | true | request.body?.offerAmount | | message | String | false | request.body?.message | | status | Enum | true | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | **currency** : ISO currency (e.g., USD, EUR) for the offer. **productId** : Product the offer applies to (must be fixed-price, acceptOffers true). **counterOfferId** : References another offer (counter-offer chain). **counterMessage** : Message accompanying seller's counter-offer (optional). **counterAmount** : Counter-offer amount (when offer is COUNTERED). **offerAmount** : Primary offer amount from buyer. **message** : Message/special notes from buyer (optional). **status** : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). **expiresAt** : When this offer expires (optional). **respondedAt** : When the seller (or buyer, for counter-offer) responded/updated the offer status. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/auctionofferoffers** ```js axios({ method: 'POST', url: '/v1/auctionofferoffers', data: { currency:"String", productId:"ID", counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", offerAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Auctionofferbids` API Lists bids by product, user, or auction, supports history/analytics. **Rest Route** The `listAuctionOfferBids` API REST controller can be triggered via the following route: `/v1/auctionofferbids` **Rest Request Parameters** The `listAuctionOfferBids` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids** ```js axios({ method: 'GET', url: '/v1/auctionofferbids', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBids", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferBids": [ { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Auctionofferbid` API Soft-deletes a bid (for admin or self before auction ends). **Rest Route** The `deleteAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `deleteAuctionOfferBid` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | **auctionOfferBidId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Auctionofferoffer` API Soft-deletes an offer (allowed only in non-accepted/expired state). **Rest Route** The `deleteAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `deleteAuctionOfferOffer` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | **auctionOfferOfferId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## CategoryManagement Service Handles product categories and subcategories for marketplace browsing and classification, supporting public discovery plus admin-only management. ### CategoryManagement Service Data Objects **Category** Represents a product category in the marketplace (e.g., Electronics, Clothing, Toys), used for browsing, filtering, and discovery. Admins manage categories. **Subcategory** Represents a subcategory within a parent category (e.g., 'Smartphones' under 'Electronics'). Used for more granular product discovery and navigation. 'group' categorizes special display logic. ### CategoryManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/categorymanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/categorymanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/categorymanagement-api` ### `Delete Category` API Soft-delete a category (admin-only). **Rest Route** The `deleteCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `deleteCategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | **categoryId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/categories/:categoryId** ```js axios({ method: 'DELETE', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Subcategory` API Get a subcategory by ID. Public - only active subcategories returned except for admin. **Rest Route** The `getSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `getSubcategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | **subcategoryId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/subcategories/:subcategoryId** ```js axios({ method: 'GET', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Category` API Get a single category by ID. Public - only active categories returned (for non-admins). **Rest Route** The `getCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `getCategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | **categoryId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/categories/:categoryId** ```js axios({ method: 'GET', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Subcategory` API Update subcategory (admin-only), including group enum change. **Rest Route** The `updateSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `updateSubcategory` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | name | String | false | request.body?.name | | group | Enum | false | request.body?.group | **subcategoryId** : This id paremeter is used to select the required data object that will be updated **categoryId** : Reference to the parent category (category.id). **name** : Display name of the subcategory. **group** : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/subcategories/:subcategoryId** ```js axios({ method: 'PATCH', url: `/v1/subcategories/${subcategoryId}`, data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Subcategories` API List all subcategories for browsing/filtering, with support for group enum and parent category queries. Only active subcategories shown to public/non-admin users. **Rest Route** The `listSubcategories` API REST controller can be triggered via the following route: `/v1/subcategories` **Rest Request Parameters** The `listSubcategories` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/subcategories** ```js axios({ method: 'GET', url: '/v1/subcategories', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "subcategories": [ { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Subcategory` API Soft-delete a subcategory (admin-only). **Rest Route** The `deleteSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `deleteSubcategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | **subcategoryId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/subcategories/:subcategoryId** ```js axios({ method: 'DELETE', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Categories` API List all categories for browsing and filtering. Only active categories shown to public/non-admin users. **Rest Route** The `listCategories` API REST controller can be triggered via the following route: `/v1/categories` **Rest Request Parameters** The `listCategories` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/categories** ```js axios({ method: 'GET', url: '/v1/categories', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "categories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "categories": [ { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Category` API Update category details (admin-only). **Rest Route** The `updateCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `updateCategory` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | false | request.body?.title | **categoryId** : This id paremeter is used to select the required data object that will be updated **imageUrl** : URL for category image/avatar (optional, used for homepage visuals). **subtitle** : Optional short description for UI/tooltips. **title** : Display name of the category. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/categories/:categoryId** ```js axios({ method: 'PATCH', url: `/v1/categories/${categoryId}`, data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Subcategory` API Create a new subcategory under a given category (admin-only), with enum group constraint. **Rest Route** The `createSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories` **Rest Request Parameters** The `createSubcategory` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.body?.categoryId | | name | String | true | request.body?.name | | group | Enum | true | request.body?.group | **categoryId** : Reference to the parent category (category.id). **name** : Display name of the subcategory. **group** : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/subcategories** ```js axios({ method: 'POST', url: '/v1/subcategories', data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Category` API Create a new category (admin-only) for product classification. **Rest Route** The `createCategory` API REST controller can be triggered via the following route: `/v1/categories` **Rest Request Parameters** The `createCategory` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | true | request.body?.title | **imageUrl** : URL for category image/avatar (optional, used for homepage visuals). **subtitle** : Optional short description for UI/tooltips. **title** : Display name of the category. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/categories** ```js axios({ method: 'POST', url: '/v1/categories', data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## Messaging Service In-app messaging service for direct user-to-user text messages (buyers/sellers). Stores, retrieves, and manages user conversations. Launch version: text-only. ### Messaging Service Data Objects **MessagingMessage** A direct, text-only in-app message between two users (buyer/seller); stores sender, recipient, content, read status, and timestamp. ### Messaging Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/messaging-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/messaging-api` * **Production:** `https://ebaycclone.mindbricks.co/messaging-api` ### `List Messagingmessages` API List all messages in the conversation between the logged-in user and another party, ordered by sentAt descending. Can filter unread with isRead. Returns only messages visible to user (isActive). **Rest Route** The `listMessagingMessages` API REST controller can be triggered via the following route: `/v1/messagingmessages` **Rest Request Parameters** The `listMessagingMessages` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages** ```js axios({ method: 'GET', url: '/v1/messagingmessages', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessages", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "messagingMessages": [ { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Messagingmessage` API Send a new text message from the logged-in user to a recipient. Sender is set from session. Launch version supports only text content. **Rest Route** The `createMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages` **Rest Request Parameters** The `createMessagingMessage` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | toUserId | ID | true | request.body?.toUserId | | content | String | true | request.body?.content | | isRead | Boolean | true | request.body?.isRead | **toUserId** : Recipient (user) of this message. **content** : Text content of the message. No files or attachments for launch. **isRead** : If true, recipient has marked this message as read. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/messagingmessages** ```js axios({ method: 'POST', url: '/v1/messagingmessages', data: { toUserId:"ID", content:"String", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Messagingmessage` API Update a message (mark as read/unread). Only the recipient or admin can change isRead. No content edits. Sender, content, sentAt are immutable. **Rest Route** The `updateMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `updateMessagingMessage` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | | isRead | Boolean | false | request.body?.isRead | **messagingMessageId** : This id paremeter is used to select the required data object that will be updated **isRead** : If true, recipient has marked this message as read. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'PATCH', url: `/v1/messagingmessages/${messagingMessageId}`, data: { isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Messagingmessage` API Get a message by ID. Only accessible to the sender, the recipient, or an admin. Used for message detail view or reading a single message in a thread. **Rest Route** The `getMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `getMessagingMessage` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | **messagingMessageId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'GET', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Messagingmessage` API Delete a message (soft-delete). Only sender, recipient, or admin may delete a message. Deletion only hides it for the user; not a full erase unless both delete. **Rest Route** The `deleteMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `deleteMessagingMessage` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | **messagingMessageId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'DELETE', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## NotificationManagement Service Handles storage, management, and event-driven delivery of in-app and email notifications for user-impacting system events (bids, offers, orders, feedback, messaging, etc.). Supports marking notifications as read/unread, structured filtering by event type/channel, and always returns in-app notifications ordered by recency. ### NotificationManagement Service Data Objects **Notification** Stores and manages in-app and email notifications tied to user-facing events like bids, offers, orders, messaging, shipment, and feedback. Includes event type (notificationType) for filter/search, arbitrary event payload, and delivery channel. Soft-delete enforced. In-app notifications always sorted by createdAt DESC on retrieval. ### NotificationManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/notificationmanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/notificationmanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/notificationmanagement-api` ### `Create Notification` API Creates a notification entry in response to a system/business event. Only allowed for system/event processes and admins (not standard user/action). Typically event-driven, receives userId, notificationType, payload, and channel. **Rest Route** The `createNotification` API REST controller can be triggered via the following route: `/v1/notifications` **Rest Request Parameters** The `createNotification` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationType | Enum | true | request.body?.notificationType | | userId | ID | true | request.body?.userId | | channel | Enum | true | request.body?.channel | | payload | Object | true | request.body?.payload | | isRead | Boolean | true | request.body?.isRead | **notificationType** : Type of event triggering notification (e.g., BID_UPDATED, ORDER_SHIPPED, MESSAGE_RECEIVED, etc.). Used for display/icon and query filter. **userId** : User receiving the notification (recipient). **channel** : Channel by which notification is delivered: IN_APP or EMAIL. **payload** : Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. **isRead** : Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/notifications** ```js axios({ method: 'POST', url: '/v1/notifications', data: { notificationType:"Enum", userId:"ID", channel:"Enum", payload:"Object", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Notification` API Updates a notification (mark as read/unread, payload patch for e.g. admin fix). Only receiver (userId) or admins may update. isRead is primary update scenario; others very limited. **Rest Route** The `updateNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `updateNotification` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | | payload | Object | false | request.body?.payload | | isRead | Boolean | false | request.body?.isRead | **notificationId** : This id paremeter is used to select the required data object that will be updated **payload** : Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. **isRead** : Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/notifications/:notificationId** ```js axios({ method: 'PATCH', url: `/v1/notifications/${notificationId}`, data: { payload:"Object", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Notifications` API Returns filtered list of notifications for a user, with optional filters: notificationType, isRead, channel. Always sorted by createdAt (descending) for in-app notifications. Only retrieval allowed for owner/admin. **Rest Route** The `listNotifications` API REST controller can be triggered via the following route: `/v1/notifications` **Rest Request Parameters** The `listNotifications` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/notifications** ```js axios({ method: 'GET', url: '/v1/notifications', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notifications", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "notifications": [ { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Notification` API Soft-delete a notification record. Only receiver or admin may delete. **Rest Route** The `deleteNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `deleteNotification` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | **notificationId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/notifications/:notificationId** ```js axios({ method: 'DELETE', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Notification` API Retrieves a notification for the receiver or admin. Used to populate content on detail/expanded view. **Rest Route** The `getNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `getNotification` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | **notificationId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/notifications/:notificationId** ```js axios({ method: 'GET', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## SearchIndexing Service Maintains the denormalized search index (materialized view) for global, public search across products, sellers, categories, and subcategories. Handles indexing in response to entity events and exposes optimized query endpoints for BFF/aggregator. ### SearchIndexing Service Data Objects **SearchIndex** Materialized/denormalized search index record for a marketplace entity (product, seller, category, subcategory). Used exclusively for high-speed querying in BFF global/public search. ### SearchIndexing Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/searchindexing-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/searchindexing-api` * **Production:** `https://ebaycclone.mindbricks.co/searchindexing-api` ### `List Searchindexes` API List/search search index entries by type or referenceId (used by BFF/global search). Always excludes inactive (soft-deleted) records. Supports filtering and full-text search filters by documentType/referenceId for admin/maintenance use. **Rest Route** The `listSearchIndexes` API REST controller can be triggered via the following route: `/v1/searchindexes` **Rest Request Parameters** The `listSearchIndexes` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchindexes** ```js axios({ method: 'GET', url: '/v1/searchindexes', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndices", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "searchIndices": [ { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Searchindex` API Update an existing searchIndex record (by (documentType, referenceId) or id). Used in response to events (entity edit, data change); internal/automation/admin only. **Rest Route** The `updateSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `updateSearchIndex` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | | documentType | Enum | false | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | false | request.body?.indexedAt | **searchIndexId** : This id paremeter is used to select the required data object that will be updated **documentType** : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY **document** : Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. **referenceId** : ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. **indexedAt** : Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/searchindexs/:searchIndexId** ```js axios({ method: 'PATCH', url: `/v1/searchindexs/${searchIndexId}`, data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Searchindex` API Soft-delete a searchIndex record (by id or by (documentType, referenceId)). Typical use: in response to entity soft-delete; internal/automation/admin only. **Rest Route** The `deleteSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `deleteSearchIndex` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | **searchIndexId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/searchindexs/:searchIndexId** ```js axios({ method: 'DELETE', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Searchindex` API Create a new searchIndex record (internal, used by event triggers and admin tools only). Typically called when a new product/seller/category/subcategory is created. **Rest Route** The `createSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs` **Rest Request Parameters** The `createSearchIndex` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | documentType | Enum | true | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | true | request.body?.indexedAt | **documentType** : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY **document** : Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. **referenceId** : ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. **indexedAt** : Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/searchindexs** ```js axios({ method: 'POST', url: '/v1/searchindexs', data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Searchindex` API Get a single denormalized index record (by id, or documentType+referenceId). Used by BFF for full entity search. Always excludes inactive records unless forced (admin only path). **Rest Route** The `getSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `getSearchIndex` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | **searchIndexId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchindexs/:searchIndexId** ```js axios({ method: 'GET', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## AdminModeration Service Administrative backend service for moderation and manual override actions. Responsible for logging all admin interventions (user/product/feedback/media/category/order/notification/searchindex moderation), triggering corrections via interservice calls, and providing comprehensive audit trails for compliance. ### AdminModeration Service Data Objects **ModerationAction** Audit record for all admin moderation/override actions affecting core business entities. Links to admin, timestamp, entity type/ID, action performed, and reason. ### AdminModeration Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/adminmoderation-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/adminmoderation-api` * **Production:** `https://ebaycclone.mindbricks.co/adminmoderation-api` ### `Get Moderationaction` API Get a single moderation action log by ID. Used to review admin audit trails; accessible only to platform admins. **Rest Route** The `getModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `getModerationAction` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | **moderationActionId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/moderationactions/:moderationActionId** ```js axios({ method: 'GET', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Moderationaction` API Soft-deletes a moderation action log record (dangerous; allowed only to superadmins or strict manual correction), primarily for audit correction or internal error cleanup. Usually, moderation logs are immutable. **Rest Route** The `deleteModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `deleteModerationAction` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | **moderationActionId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/moderationactions/:moderationActionId** ```js axios({ method: 'DELETE', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Moderationaction` API Logs an admin moderation or override action in the system for audit and traceability. Requires admin login, takes context from session, and creates an audit entry for any admin operation over any entity type. **Rest Route** The `createModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions` **Rest Request Parameters** The `createModerationAction` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | entityId | ID | true | request.body?.entityId | | entityType | Enum | true | request.body?.entityType | | reason | String | true | request.body?.reason | | actionType | Enum | true | request.body?.actionType | **entityId** : ID of target entity affected by moderation (user/product/etc). **entityType** : Type of entity affected (USER, PRODUCT, FEEDBACK, MEDIA, CATEGORY, NOTIFICATION, ORDER, SEARCHINDEX). **reason** : Explanation or justification for the moderation action performed. **actionType** : Type of moderation action (e.g., SOFT_DELETE, RESTORE, UPDATE_ROLE, MANUAL_CORRECTION, MEDIA_FLAG, INDEX_REBUILD, PAYMENT_FIX, FEEDBACK_OVERRIDE, ADMIN_NOTE). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/moderationactions** ```js axios({ method: 'POST', url: '/v1/moderationactions', data: { entityId:"ID", entityType:"Enum", reason:"String", actionType:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Moderationactions` API List moderation actions for admin dashboard/audit search. Supports filtering by admin, entityType, entityId, actionType, and date. Always sorted by most recent action. **Rest Route** The `listModerationActions` API REST controller can be triggered via the following route: `/v1/moderationactions` **Rest Request Parameters** The `listModerationActions` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/moderationactions** ```js axios({ method: 'GET', url: '/v1/moderationactions', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationActions", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "moderationActions": [ { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Moderationaction` API Allows update of explanation/note on a moderation action for correction (typically by admin or superadmin only). No entity/type/admin may be changed after creation; only 'reason' is editable for audit consistency. **Rest Route** The `updateModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `updateModerationAction` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | | reason | String | false | request.body?.reason | **moderationActionId** : This id paremeter is used to select the required data object that will be updated **reason** : Explanation or justification for the moderation action performed. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/moderationactions/:moderationActionId** ```js axios({ method: 'PATCH', url: `/v1/moderationactions/${moderationActionId}`, data: { reason:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## WatchlistCart Service Handles user watchlists (with custom folders) and shopping cart preparation for checkout, strictly enforcing only fixed-price products in carts, supporting item moves/bulk operations, and robust default/folder logic.. ### WatchlistCart Service Data Objects **WatchlistItem** Item in a user’s watchlist, optionally in a named folder; references product and user. **CartItem** Single product pending checkout in a user’s cart. Only fixed-price products permitted; quantity supported for multi-unit purchases (if allowed). **WatchlistList** A named folder/list in a user’s watchlist. Default list exists for all users. Custom lists may be created and deleted. ### WatchlistCart Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/watchlistcart-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/watchlistcart-api` * **Production:** `https://ebaycclone.mindbricks.co/watchlistcart-api` ### `List Watchlistlist` API List all lists in user’s watchlists. Supports listing by listId for folders. **Rest Route** The `listWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists` **Rest Request Parameters** The `listWatchlistList` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/watchlistlists** ```js axios({ method: 'GET', url: '/v1/watchlistlists', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Cartitems` API List all cart items for a user (pending checkout). **Rest Route** The `listCartItems` API REST controller can be triggered via the following route: `/v1/cartitems` **Rest Request Parameters** The `listCartItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/cartitems** ```js axios({ method: 'GET', url: '/v1/cartitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "price": "Double", "title": "String", "type": "Enum", "type_idx": "Integer", "mediaAssetIds": "ID" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Cartitem` API Remove an item from the user’s cart. **Rest Route** The `deleteCartItem` API REST controller can be triggered via the following route: `/v1/cartitems/:cartItemId` **Rest Request Parameters** The `deleteCartItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | **cartItemId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/cartitems/:cartItemId** ```js axios({ method: 'DELETE', url: `/v1/cartitems/${cartItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Watchlistitem` API Add product to user’s watchlist (default or target list/folder). One (user, product, list) per item enforced. Block duplicates. **Rest Route** The `createWatchlistItem` API REST controller can be triggered via the following route: `/v1/watchlistitems` **Rest Request Parameters** The `createWatchlistItem` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | productId | ID | true | request.body?.productId | | listId | ID | false | request.body?.listId | **addedAt** : Timestamp watchlist item created. **productId** : Referenced product in the watchlist. **listId** : Owning watchlistList; null if in default watchlist. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/watchlistitems** ```js axios({ method: 'POST', url: '/v1/watchlistitems', data: { addedAt:"Date", productId:"ID", listId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Watchlistitems` API List all products in user’s watchlists. Supports listing by listId for folders. **Rest Route** The `listWatchlistItems` API REST controller can be triggered via the following route: `/v1/watchlistitems` **Rest Request Parameters** The `listWatchlistItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/watchlistitems** ```js axios({ method: 'GET', url: '/v1/watchlistitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Cartitemquantity` API Change the quantity for a cart item. User must own the item. **Rest Route** The `updateCartItemQuantity` API REST controller can be triggered via the following route: `/v1/cartitemquantity/:cartItemId` **Rest Request Parameters** The `updateCartItemQuantity` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | | quantity | Integer | false | request.body?.quantity | **cartItemId** : This id paremeter is used to select the required data object that will be updated **quantity** : How many units (if product allows). **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/cartitemquantity/:cartItemId** ```js axios({ method: 'PATCH', url: `/v1/cartitemquantity/${cartItemId}`, data: { quantity:"Integer", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Watchlistlist` API Create a new custom watchlist folder. Name must be unique per user; ‘Default’ is reserved for system. **Rest Route** The `createWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists` **Rest Request Parameters** The `createWatchlistList` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | name | String | true | request.body?.name | **name** : Custom folder or list name. 'Default' is reserved (non-deletable for each user). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/watchlistlists** ```js axios({ method: 'POST', url: '/v1/watchlistlists', data: { name:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Watchlistlist` API Delete a custom watchlist (folder). Items are reassigned to user’s default list. Cannot delete default list. **Rest Route** The `deleteWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists/:watchlistListId` **Rest Request Parameters** The `deleteWatchlistList` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistListId | ID | true | request.params?.watchlistListId | **watchlistListId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistlists/:watchlistListId** ```js axios({ method: 'DELETE', url: `/v1/watchlistlists/${watchlistListId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Watchlistitem` API Remove a product from a user’s watchlist. **Rest Route** The `deleteWatchlistItem` API REST controller can be triggered via the following route: `/v1/watchlistitems/:watchlistItemId` **Rest Request Parameters** The `deleteWatchlistItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistItemId | ID | true | request.params?.watchlistItemId | **watchlistItemId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistitems/:watchlistItemId** ```js axios({ method: 'DELETE', url: `/v1/watchlistitems/${watchlistItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Cartitem` API Add an item to the user’s cart. Only fixed-price products allowed. Duplicates not permitted. **Rest Route** The `createCartItem` API REST controller can be triggered via the following route: `/v1/cartitems` **Rest Request Parameters** The `createCartItem` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | **addedAt** : Timestamp added to cart. **quantity** : How many units (if product allows). **productId** : Product being checked out. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/cartitems** ```js axios({ method: 'POST', url: '/v1/cartitems', data: { addedAt:"Date", quantity:"Integer", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Do Userwatchlist` API userwatchlist **Rest Route** The `userwatchlist` API REST controller can be triggered via the following route: `/v1/userwatchlist` **Rest Request Parameters** The `userwatchlist` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userwatchlist** ```js axios({ method: 'GET', url: '/v1/userwatchlist', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Usercartitems` API list all cart items adde by user **Rest Route** The `listUserCartItems` API REST controller can be triggered via the following route: `/v1/usercartitems` **Rest Request Parameters** The `listUserCartItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/usercartitems** ```js axios({ method: 'GET', url: '/v1/usercartitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "shipping": "Double" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Do Userwatchlistlists` API list all watch lists created by user **Rest Route** The `userwatchlistlists` API REST controller can be triggered via the following route: `/v1/userwatchlistlists` **Rest Request Parameters** The `userwatchlistlists` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userwatchlistlists** ```js axios({ method: 'GET', url: '/v1/userwatchlistlists', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ## ProductListing Service Handles product listings (both auction and fixed-price), image/media storage with validations, enforces immutable type, soft-delete, and public product discovery. ### ProductListing Service Data Objects **ProductListingMedia** Stores and manages images/media associated with products, including secure URL, MIME type, and size validation. Each asset can be used by multiple products. **ProductListingProduct** Represents a single product listing (fixed-price or auction) in the marketplace, with seller, category, type, price information, shipping details, media references, and dynamic auction fields. ### ProductListing Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/productlisting-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/productlisting-api` * **Production:** `https://ebaycclone.mindbricks.co/productlisting-api` ### `List Productlistingmedia` API List all media assets (admin or for media management/bulk preview). **Rest Route** The `listProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias` **Rest Request Parameters** The `listProductListingMedia` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias** ```js axios({ method: 'GET', url: '/v1/productlistingmedias', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedias", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingMedias": [ { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Productlistingproduct` API Get a single product listing. Checks isActive and public status. Includes media, category, subcategory, and seller info via joins. **Rest Route** The `getProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `getProductListingProduct` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | **productListingProductId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'GET', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Productlistingownproducts` API listing the loggedin user's products **Rest Route** The `listProductListingOwnProducts` API REST controller can be triggered via the following route: `/v1/productlistingownproducts` **Rest Request Parameters** The `listProductListingOwnProducts` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingownproducts** ```js axios({ method: 'GET', url: '/v1/productlistingownproducts', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Productlistingmedia` API Get a single media asset by ID (for admin or to display in product UI). **Rest Route** The `getProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` **Rest Request Parameters** The `getProductListingMedia` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | **productListingMediaId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'GET', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Productlistingproducts` API List public product listings. Only isActive=true records are returned. Includes category, subcategory, seller, media joins. Supports filtering. **Rest Route** The `listProductListingProducts` API REST controller can be triggered via the following route: `/v1/productlistingproducts` **Rest Request Parameters** The `listProductListingProducts` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts** ```js axios({ method: 'GET', url: '/v1/productlistingproducts', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Productlistingproduct` API Soft-delete a product listing. Only owner or admin can delete. **Rest Route** The `deleteProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `deleteProductListingProduct` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | **productListingProductId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'DELETE', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Productlistingproduct` API Update a product listing. Product type cannot be changed (immutable). **Rest Route** The `updateProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `updateProductListingProduct` api has got 21 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | | currency | String | false | request.body?.currency | | description | Text | false | request.body?.description | | condition | Enum | false | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | false | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | false | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | false | request.body?.shippingMethod | | shipping | Double | false | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | false | request.body?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | **productListingProductId** : This id paremeter is used to select the required data object that will be updated **currency** : ISO currency code (e.g. USD, EUR) **description** : Product detailed description **condition** : Condition of product: BRAND_NEW, NEW, or USED **startBid** : The opening bid value (for auction type products) **endPrice** : Optional immediate sale/upper end price for auction (if AUCTION type) **price** : Product price (required if fixed price type) **title** : Product title **startPrice** : Minimum starting price for auction (required if AUCTION type) **endBid** : The upper (max) bid value for auction products (if any) **estimatedDelivery** : Estimated delivery date for this product **shippingCurrency** : Currency code for shipping cost **mediaAssetIds** : References to associated product/media assets **shippingMethod** : Shipping option for product: STANDARD, EXPRESS, or FREE **shipping** : Shipping cost for this product **startBidDate** : Date/time when auction bidding begins **subcategoryId** : Reference to subcategory **categoryId** : Reference to parent category **endBidDate** : Date/time when auction bidding ends **currentBid** : Current highest bid for auction-type product (updated atomically on bid placement) **highestBidderId** : User ID of current highest bidder (auction-only, updated by auction microservice) **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'PATCH', url: `/v1/productlistingproducts/${productListingProductId}`, data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Productlistingproduct` API Create a new product listing (fixed or auction), conditioned on product type. Type is immutable after creation. **Rest Route** The `createProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts` **Rest Request Parameters** The `createProductListingProduct` api has got 21 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | description | Text | true | request.body?.description | | condition | Enum | true | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | true | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | type | Enum | true | request.body?.type | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | true | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | true | request.body?.shippingMethod | | shipping | Double | true | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | true | request.body?.subcategoryId | | categoryId | ID | true | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | **currency** : ISO currency code (e.g. USD, EUR) **description** : Product detailed description **condition** : Condition of product: BRAND_NEW, NEW, or USED **startBid** : The opening bid value (for auction type products) **endPrice** : Optional immediate sale/upper end price for auction (if AUCTION type) **price** : Product price (required if fixed price type) **title** : Product title **startPrice** : Minimum starting price for auction (required if AUCTION type) **type** : Product listing type, either FIXED or AUCTION (immutable after creation) **endBid** : The upper (max) bid value for auction products (if any) **estimatedDelivery** : Estimated delivery date for this product **shippingCurrency** : Currency code for shipping cost **mediaAssetIds** : References to associated product/media assets **shippingMethod** : Shipping option for product: STANDARD, EXPRESS, or FREE **shipping** : Shipping cost for this product **startBidDate** : Date/time when auction bidding begins **subcategoryId** : Reference to subcategory **categoryId** : Reference to parent category **endBidDate** : Date/time when auction bidding ends **currentBid** : Current highest bid for auction-type product (updated atomically on bid placement) **highestBidderId** : User ID of current highest bidder (auction-only, updated by auction microservice) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/productlistingproducts** ```js axios({ method: 'POST', url: '/v1/productlistingproducts', data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", type:"Enum", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Productlistingmedia` API Soft-delete a media asset (typically by admin or media owner for flagged/invalid content). **Rest Route** The `deleteProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` **Rest Request Parameters** The `deleteProductListingMedia` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | **productListingMediaId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'DELETE', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Productlistingmedia` API Create a new media asset record after validation. Used mainly by edge controller after upload. **Rest Route** The `createProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias` **Rest Request Parameters** The `createProductListingMedia` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | mimeType | String | true | request.body?.mimeType | | productId | ID | false | request.body?.productId | | url | String | true | request.body?.url | | size | Integer | true | request.body?.size | **mimeType** : MIME type of the uploaded media (e.g., image/jpeg) **productId** : ID of product associated with this media asset **url** : Secure, validated URL for the media asset (S3 or equivalent) **size** : Media size in bytes (for validation and quota) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/productlistingmedias** ```js axios({ method: 'POST', url: '/v1/productlistingmedias', data: { mimeType:"String", productId:"ID", url:"String", size:"Integer", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## OrderManagement Service Handles all marketplace orders, manual checkout flows for fixed-price/offer/auction settlements, Stripe payment processing and webhook reconciliation, explicit status updates (shipping, delivery, cancellation), and feedback eligibility via orderItems. ### OrderManagement Service Data Objects **OrderManagementOrder** Marketplace order record. Stores buyer, shipping, status, items, Stripe payment data, and manual shipment/delivery events. Only accessible to admins or the buyer/seller of order items. **OrderManagementOrderItem** Order line item representing purchase of a single product from a specific seller as part of an order. Enables feedback, delivery, and per-seller analytics. Immutable after order creation. **Sys_orderManagementOrderPayment** A payment storage object to store the payment life cyle of orders based on orderManagementOrder object. It is autocreated based on the source object's checkout config **Sys_paymentCustomer** A payment storage object to store the customer values of the payment platform **Sys_paymentMethod** A payment storage object to store the payment methods of the platform customers ### OrderManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/ordermanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/ordermanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/ordermanagement-api` ### `List Ordermanagementorders` API List orders, filtered for buyer and/or seller, or by admin. Includes select orderItems. **Rest Route** The `listOrderManagementOrders` API REST controller can be triggered via the following route: `/v1/ordermanagementorders` **Rest Request Parameters** The `listOrderManagementOrders` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ordermanagementorders', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Ordermanagementorderitem` API Get a specific order item (for feedback/business logic). **Rest Route** The `getOrderManagementOrderItem` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems/:orderManagementOrderItemId` **Rest Request Parameters** The `getOrderManagementOrderItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderItemId | ID | true | request.params?.orderManagementOrderItemId | **orderManagementOrderItemId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems/:orderManagementOrderItemId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderitems/${orderManagementOrderItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Ordermanagementorder` API Soft-delete/cancel order by admin or eligible actor prior to shipment. Sets status to CANCELLED and cancels active payment intent if pending. Irreversible and blocks feedback. **Rest Route** The `deleteOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` **Rest Request Parameters** The `deleteOrderManagementOrder` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorder` API Get single order by ID. Only accessible to admin, buyer, or relevant sellers of items within this order. Includes all orderItems. **Rest Route** The `getOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` **Rest Request Parameters** The `getOrderManagementOrder` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | **orderManagementOrderId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Ordermanagementorderstatus` API Update order status (manual shipment, delivery, cancellation/refund). Restricted: only seller of all items can mark as shipped, only buyer can confirm delivery, only admin can set refund/cancelled. Timestamps updated as per business rule. **Rest Route** The `updateOrderManagementOrderStatus` API REST controller can be triggered via the following route: `/v1/ordermanagementorderstatus/:orderManagementOrderId` **Rest Request Parameters** The `updateOrderManagementOrderStatus` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **status** : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderstatus/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderstatus/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Complete Orderstripewebhook` API Webhook endpoint called by Stripe to reconcile payment state and update order status based on paymentIntentId and event data. No authentication required (Stripe IPs only). **Rest Route** The `completeOrderStripeWebhook` API REST controller can be triggered via the following route: `/v1/completeorderstripewebhook/:orderManagementOrderId` **Rest Request Parameters** The `completeOrderStripeWebhook` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **status** : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/completeorderstripewebhook/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/completeorderstripewebhook/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderbyproductid` API get orders by productId **Rest Route** The `getOrderManagementOrderByProductId` API REST controller can be triggered via the following route: `/v1/ordermanagementorderbyproductid/:items` **Rest Request Parameters** The `getOrderManagementOrderByProductId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | items | String | true | request.params?.items | **orderManagementOrderId** : This id paremeter is used to query the required data object. **items** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderbyproductid/:items** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderbyproductid/${items}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Ordermanagementorder` API Creates an order and initiates Stripe payment. Validates that all products in the order are fixed-price, populates orderItems, saves Stripe customer/paymentMethod/paymentIntentId for reconciliation. Only accessible to buyers for own checkouts and only allows fixed-price product checkout (no auction). **Rest Route** The `createOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders` **Rest Request Parameters** The `createOrderManagementOrder` api has got 14 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderNumber | String | true | request.body?.orderNumber | | items | ID | false | request.body?.items | | paymentMethodId | String | true | request.body?.paymentMethodId | | stripeCustomerId | String | true | request.body?.stripeCustomerId | | paymentIntentId | String | false | request.body?.paymentIntentId | | shippingAddress | Object | true | request.body?.shippingAddress | | summary | Object | true | request.body?.summary | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderNumber** : Unique, human-friendly order number (displayed to users); enforced unique. **items** : Array of orderManagementOrderItem ids representing items in this order. **paymentMethodId** : Stripe paymentMethodId used for payment. Not stored if cash or other payment (future). **stripeCustomerId** : Stripe customerId of buyer; enables saved/paymentMethodId flows. **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **shippingAddress** : Shipping address for the order (copy of buyer address at purchase time). **summary** : Object with total, subtotal, currency, shipping, discount breakdown as snapshot of order at time of purchase. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorders** ```js axios({ method: 'POST', url: '/v1/ordermanagementorders', data: { orderNumber:"String", items:"ID", paymentMethodId:"String", stripeCustomerId:"String", paymentIntentId:"String", shippingAddress:"Object", summary:"Object", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderitems` API List order items for a given order or for buyer/seller analytics. Used for feedback management. **Rest Route** The `listOrderManagementOrderItems` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems` **Rest Request Parameters** The `listOrderManagementOrderItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Ownordermanagementorders` API list the loggedin user orders **Rest Route** The `listOwnOrderManagementOrders` API REST controller can be triggered via the following route: `/v1/ownordermanagementorders` **Rest Request Parameters** The `listOwnOrderManagementOrders` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ownordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ownordermanagementorders', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Lis Ordermanagementownorderitem` API list the loggedin user's order items **Rest Route** The `lisOrderManagementOwnOrderItem` API REST controller can be triggered via the following route: `/v1/lisordermanagementownorderitem` **Rest Request Parameters** The `lisOrderManagementOwnOrderItem` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/lisordermanagementownorderitem** ```js axios({ method: 'GET', url: '/v1/lisordermanagementownorderitem', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Ordermanagementorderitem` API create order item **Rest Route** The `createOrderManagementOrderItem` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems` **Rest Request Parameters** The `createOrderManagementOrderItem` api has got 8 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | shipping | Double | true | request.body?.shipping | | orderId | ID | true | request.body?.orderId | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | | price | Double | true | request.body?.price | | sellerId | ID | true | request.body?.sellerId | | title | String | true | request.body?.title | | currency | String | true | request.body?.currency | **shipping** : Shipping cost for this product (may be 0 for free shipping). **orderId** : Parent order this item belongs to; enables join and lifecycle tracking. **quantity** : Number of units purchased for this product. **productId** : ID of product purchased in this line item. **price** : Unit price for this product at purchase time. **sellerId** : UserId of seller (owner of product at purchase time). **title** : Product title at purchase time (copied for convenience/audit). **currency** : Currency code for price/shipping (ISO 4217). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderitems** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderitems', data: { shipping:"Double", orderId:"ID", quantity:"Integer", productId:"ID", price:"Double", sellerId:"ID", title:"String", currency:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpayment2` API This route is used to get the payment information by ID. **Rest Route** The `getOrderManagementOrderPayment2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `getOrderManagementOrderPayment2` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderpayments2` API This route is used to list all payments. **Rest Route** The `listOrderManagementOrderPayments2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayments2` **Rest Request Parameters** The `listOrderManagementOrderPayments2` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Ordermanagementorderpayment` API This route is used to create a new payment. **Rest Route** The `createOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment` **Rest Request Parameters** The `createOrderManagementOrderPayment` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderId | ID | true | request.body?.orderId | | paymentId | String | true | request.body?.paymentId | | paymentStatus | String | true | request.body?.paymentStatus | | statusLiteral | String | true | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | **orderId** : an ID value to represent the orderId which is the ID parameter of the source orderManagementOrder object **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderpayment', data: { orderId:"ID", paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Ordermanagementorderpayment` API This route is used to update an existing payment. **Rest Route** The `updateOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `updateOrderManagementOrderPayment` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | false | request.body?.paymentId | | paymentStatus | String | false | request.body?.paymentStatus | | statusLiteral | String | false | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | **sys_orderManagementOrderPaymentId** : This id paremeter is used to select the required data object that will be updated **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Ordermanagementorderpayment` API This route is used to delete a payment. **Rest Route** The `deleteOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `deleteOrderManagementOrderPayment` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderpayments2` API This route is used to list all payments. **Rest Route** The `listOrderManagementOrderPayments2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayments2` **Rest Request Parameters** The `listOrderManagementOrderPayments2` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Ordermanagementorderpaymentbyorderid` API This route is used to get the payment information by order id. **Rest Route** The `getOrderManagementOrderPaymentByOrderId` API REST controller can be triggered via the following route: `/v1/orderManagementOrderpaymentbyorderid/:orderId` **Rest Request Parameters** The `getOrderManagementOrderPaymentByOrderId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | orderId | String | true | request.params?.orderId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **orderId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbyorderid/:orderId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbyorderid/${orderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpaymentbypaymentid` API This route is used to get the payment information by payment id. **Rest Route** The `getOrderManagementOrderPaymentByPaymentId` API REST controller can be triggered via the following route: `/v1/orderManagementOrderpaymentbypaymentid/:paymentId` **Rest Request Parameters** The `getOrderManagementOrderPaymentByPaymentId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | true | request.params?.paymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **paymentId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbypaymentid/:paymentId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbypaymentid/${paymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpayment2` API This route is used to get the payment information by ID. **Rest Route** The `getOrderManagementOrderPayment2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `getOrderManagementOrderPayment2` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Start Ordermanagementorderpayment` API Start payment for orderManagementOrder **Rest Route** The `startOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/startordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `startOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to start a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/startordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/startordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Refresh Ordermanagementorderpayment` API Refresh payment info for orderManagementOrder from Stripe **Rest Route** The `refreshOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/refreshordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `refreshOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to refresh a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/refreshordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/refreshordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Callback Ordermanagementorderpayment` API Refresh payment values by gateway webhook call for orderManagementOrder **Rest Route** The `callbackOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/callbackordermanagementorderpayment` **Rest Request Parameters** The `callbackOrderManagementOrderPayment` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.body?.orderManagementOrderId | **orderManagementOrderId** : The order id parameter that will be read from webhook callback params **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/callbackordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/callbackordermanagementorderpayment', data: { orderManagementOrderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Get Paymentcustomerbyuserid` API This route is used to get the payment customer information by user id. **Rest Route** The `getPaymentCustomerByUserId` API REST controller can be triggered via the following route: `/v1/paymentcustomers/:userId` **Rest Request Parameters** The `getPaymentCustomerByUserId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_paymentCustomerId | ID | true | request.params?.sys_paymentCustomerId | | userId | String | true | request.params?.userId | **sys_paymentCustomerId** : This id paremeter is used to query the required data object. **userId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomers/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_paymentCustomer": { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Paymentcustomers` API This route is used to list all payment customers. **Rest Route** The `listPaymentCustomers` API REST controller can be triggered via the following route: `/v1/paymentcustomers` **Rest Request Parameters** The `listPaymentCustomers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers** ```js axios({ method: 'GET', url: '/v1/paymentcustomers', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentCustomers": [ { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Paymentcustomermethods` API This route is used to list all payment customer methods. **Rest Route** The `listPaymentCustomerMethods` API REST controller can be triggered via the following route: `/v1/paymentcustomermethods/:userId` **Rest Request Parameters** The `listPaymentCustomerMethods` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | String | true | request.params?.userId | **userId** : This parameter will be used to select the data objects that want to be listed **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomermethods/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomermethods/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentMethods", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentMethods": [ { "id": "ID", "paymentMethodId": "String", "userId": "ID", "customerId": "String", "cardHolderName": "String", "cardHolderZip": "String", "platform": "String", "cardInfo": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ## Feedback Service Handles feedback for order items: one feedback per buyer/orderItem, attached to sellerId for analytical feedback/rating aggregation and reputation tracking. Enables querying feedbacks received/given for sellers and buyers. test ### Feedback Service Data Objects **Feedback** One feedback per (buyer, orderItem). Stores rating (1-5), comment, ties to seller for analytics. Created only after delivery confirmed on order item. ### Feedback Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/feedback-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/feedback-api` * **Production:** `https://ebaycclone.mindbricks.co/feedback-api` ### `List Feedbacks` API List feedback with filtering by buyerId (given), sellerId (received), productId, or orderItemId. Used for showing seller profile, buyer profile, or order analytics. **Rest Route** The `listFeedbacks` API REST controller can be triggered via the following route: `/v1/feedbacks` **Rest Request Parameters** The `listFeedbacks` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/feedbacks** ```js axios({ method: 'GET', url: '/v1/feedbacks', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedbacks", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "feedbacks": [ { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Feedback` API Get a single feedback by id. Accessible to public (for seller profile, product, or audit views). **Rest Route** The `getFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `getFeedback` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | **feedbackId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/feedbacks/:feedbackId** ```js axios({ method: 'GET', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Feedback` API Update feedback (comment/rating) for existing feedback record (buyer only). Admin can update as override. **Rest Route** The `updateFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `updateFeedback` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | | rating | Integer | false | request.body?.rating | | comment | String | false | request.body?.comment | **feedbackId** : This id paremeter is used to select the required data object that will be updated **rating** : Rating (1-5 stars) submitted by buyer. Required. **comment** : Optional textual feedback comment, max ~500 chars. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/feedbacks/:feedbackId** ```js axios({ method: 'PATCH', url: `/v1/feedbacks/${feedbackId}`, data: { rating:"Integer", comment:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Feedback` API Delete (soft-delete) feedback (by buyer or admin). Only feedback owner or admin. **Rest Route** The `deleteFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `deleteFeedback` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | **feedbackId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/feedbacks/:feedbackId** ```js axios({ method: 'DELETE', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Feedback` API Buyer creates feedback for a delivered order item. Only allowed once per (buyer, orderItemId). Allowed only once order item is delivered. **Rest Route** The `createFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks` **Rest Request Parameters** The `createFeedback` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | rating | Integer | true | request.body?.rating | | orderId | ID | true | request.body?.orderId | | orderItemId | ID | true | request.body?.orderItemId | | sellerId | ID | true | request.body?.sellerId | | comment | String | false | request.body?.comment | | productId | ID | true | request.body?.productId | **rating** : Rating (1-5 stars) submitted by buyer. Required. **orderId** : Order containing this purchased item. Used for aggregation and validation. **orderItemId** : Purchased item (line item) in order. Feedback is per (buyer, orderItem). **sellerId** : Seller of product for analytics/aggregation. Not author; used for querying feedback about sellers. **comment** : Optional textual feedback comment, max ~500 chars. **productId** : The product listing being reviewed (snapshot at order time). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/feedbacks** ```js axios({ method: 'POST', url: '/v1/feedbacks', data: { rating:"Integer", orderId:"ID", orderItemId:"ID", sellerId:"ID", comment:"String", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # REST API GUIDE ## ebaycclone-ordermanagement-service Handles all marketplace orders, manual checkout flows for fixed-price/offer/auction settlements, Stripe payment processing and webhook reconciliation, explicit status updates (shipping, delivery, cancellation), and feedback eligibility via orderItems. ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to: Email: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. ## Documentation Scope Welcome to the official documentation for the OrderManagement Service's REST API. This document is designed to provide a comprehensive guide to interfacing with our OrderManagement Service exclusively through RESTful API endpoints. **Intended Audience** This documentation is intended for developers and integrators who are looking to interact with the OrderManagement Service via HTTP requests for purposes such as creating, updating, deleting and querying OrderManagement objects. **Overview** Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases. Beyond REST It's important to note that the OrderManagement Service also supports alternative methods of interaction, such as gRPC and messaging via a Message Broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation. ## Authentication And Authorization To ensure secure access to the OrderManagement service's protected endpoints, a project-wide access token is required. This token serves as the primary method for authenticating requests to our service. However, it's important to note that access control varies across different routes: **Protected API**: Certain API (routes) require specific authorization levels. Access to these routes is contingent upon the possession of a valid access token that meets the route-specific authorization criteria. Unauthorized requests to these routes will be rejected. **Public API **: The service also includes public API (routes) that are accessible without authentication. These public endpoints are designed for open access and do not require an access token. ### Token Locations When including your access token in a request, ensure it is placed in one of the following specified locations. The service will sequentially search these locations for the token, utilizing the first one it encounters. | Location | Token Name / Param Name | | ---------------------- | ---------------------------- | | Query | access_token | | Authorization Header | Bearer | | Header | ebaycclone-access-token| | Cookie | ebaycclone-access-token| Please ensure the token is correctly placed in one of these locations, using the appropriate label as indicated. The service prioritizes these locations in the order listed, processing the first token it successfully identifies. ## Api Definitions This section outlines the API endpoints available within the OrderManagement service. Each endpoint can receive parameters through various methods, meticulously described in the following definitions. It's important to understand the flexibility in how parameters can be included in requests to effectively interact with the OrderManagement service. This service is configured to listen for HTTP requests on port `3004`, serving both the main API interface and default administrative endpoints. The following routes are available by default: * **API Test Interface (API Face):** `/` * **Swagger Documentation:** `/swagger` * **Postman Collection Download:** `/getPostmanCollection` * **Health Checks:** `/health` and `/admin/health` * **Current Session Info:** `/currentuser` * **Favicon:** `/favicon.ico` This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/ordermanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/ordermanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/ordermanagement-api` **Parameter Inclusion Methods:** Parameters can be incorporated into API requests in several ways, each with its designated location. Understanding these methods is crucial for correctly constructing your requests: **Query Parameters:** Included directly in the URL's query string. **Path Parameters:** Embedded within the URL's path. **Body Parameters:** Sent within the JSON body of the request. **Session Parameters:** Automatically read from the session object. This method is used for parameters that are intrinsic to the user's session, such as userId. When using an API that involves session parameters, you can omit these from your request. The service will automatically bind them to the API layer, provided that a session is associated with your request. **Note on Session Parameters:** Session parameters represent a unique method of parameter inclusion, relying on the context of the user's session. A common example of a session parameter is userId, which the service automatically associates with your request when a session exists. This feature ensures seamless integration of user-specific data without manual input for each request. By adhering to the specified parameter inclusion methods, you can effectively utilize the OrderManagement service's API endpoints. For detailed information on each endpoint, including required parameters and their accepted locations, refer to the individual API definitions below. ### Common Parameters The `OrderManagement` service's business API support several common parameters designed to modify and enhance the behavior of API requests. These parameters are not individually listed in the API route definitions to avoid repetition. Instead, refer to this section to understand how to leverage these common behaviors across different routes. Note that all common parameters should be included in the query part of the URL. ### Supported Common Parameters: - **getJoins (BOOLEAN)**: Controls whether to retrieve associated objects along with the main object. By default, `getJoins` is assumed to be `true`. Set it to `false` if you prefer to receive only the main fields of an object, excluding its associations. - **excludeCQRS (BOOLEAN)**: Applicable only when `getJoins` is `true`. By default, `excludeCQRS` is set to `false`. Enabling this parameter (`true`) omits non-local associations, which are typically more resource-intensive as they require querying external services like ElasticSearch for additional information. Use this to optimize response times and resource usage. - **requestId (String)**: Identifies a request to enable tracking through the service's log chain. A random hex string of 32 characters is assigned by default. If you wish to use a custom `requestId`, simply include it in your query parameters. - **caching (BOOLEAN)**: Determines the use of caching for query API. By default, caching is enabled (`true`). To ensure the freshest data directly from the database, set this parameter to `false`, bypassing the cache. - **cacheTTL (Integer)**: Specifies the Time-To-Live (TTL) for query caching, in seconds. This is particularly useful for adjusting the default caching duration (5 minutes) for `get list` queries. Setting a custom `cacheTTL` allows you to fine-tune the cache lifespan to meet your needs. - **pageNumber (Integer)**: For paginated `get list` API's, this parameter selects which page of results to retrieve. The default is `1`, indicating the first page. To disable pagination and retrieve all results, set `pageNumber` to `0`. - **pageRowCount (Integer)**: In conjunction with paginated API's, this parameter defines the number of records per page. The default value is `25`. Adjusting `pageRowCount` allows you to control the volume of data returned in a single request. By utilizing these common parameters, you can tailor the behavior of API requests to suit your specific requirements, ensuring optimal performance and usability of the `OrderManagement` service. ### Error Response If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity: - **400 Bad Request**: The request was improperly formatted or contained invalid parameters, preventing the server from processing it. - **401 Unauthorized**: The request lacked valid authentication credentials or the credentials provided do not grant access to the requested resource. - **404 Not Found**: The requested resource was not found on the server. - **500 Internal Server Error**: The server encountered an unexpected condition that prevented it from fulfilling the request. Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ### Object Structure of a Successfull Response When the `OrderManagement` service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client. **Key Characteristics of the Response Envelope:** - **Data Presentation**: Depending on the nature of the request, the service returns either a single data object or an array of objects encapsulated within the JSON envelope. - **Creation and Update API**: These API routes return the unmodified (pure) form of the data object(s), without any associations to other data objects. - **Delete API**: Even though the data is removed from the database, the last known state of the data object(s) is returned in its pure form. - **Get Requests**: A single data object is returned in JSON format. - **Get List Requests**: An array of data objects is provided, reflecting a collection of resources. - **Data Structure and Joins**: The complexity of the data structure in the response can vary based on the API's architectural design and the join options specified in the request. The architecture might inherently limit join operations, or they might be dynamically controlled through query parameters. - **Pure Data Forms**: In some cases, the response mirrors the exact structure found in the primary data table, without extensions. - **Extended Data Forms**: Alternatively, responses might include data extended through joins with tables within the same service or aggregated from external sources, such as ElasticSearch indices related to other services. - **Join Varieties**: The extensions might involve one-to-one joins, resulting in single object associations, or one-to-many joins, leading to an array of objects. In certain instances, the data might even feature nested inclusions from other data objects. **Design Considerations**: The structure of a API's response data is meticulously crafted during the service's architectural planning. This design ensures that responses adequately reflect the intended data relationships and service logic, providing clients with rich and meaningful information. **Brief Data**: Certain API's return a condensed version of the object data, intentionally selecting only specific fields deemed useful for that request. In such instances, the API documentation will detail the properties included in the response, guiding developers on what to expect. ### API Response Structure The API utilizes a standardized JSON envelope to encapsulate responses. This envelope is designed to consistently deliver both the requested data and essential metadata, ensuring that clients can efficiently interpret and utilize the response. **HTTP Status Codes:** - **200 OK**: This status code is returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request has been processed successfully. - **201 Created**: This status code is specific to CREATE operations, signifying that the requested resource has been successfully created. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling the successful execution of the request. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3 "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` - **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation performed. **Handling Errors:** For details on handling error scenarios and understanding the structure of error responses, please refer to the "Error Response" section provided earlier in this documentation. It outlines how error conditions are communicated, including the use of HTTP status codes and standardized JSON structures for error messages. ## Resources OrderManagement service provides the following resources which are stored in its own database as a data object. Note that a resource for an api access is a data object for the service. ### OrderManagementOrder resource *Resource Definition* : Marketplace order record. Stores buyer, shipping, status, items, Stripe payment data, and manual shipment/delivery events. Only accessible to admins or the buyer/seller of order items. *OrderManagementOrder Resource Properties* | Name | Type | Required | Default | Definition | | ---- | ---- | -------- | ------- | ---------- | | **orderNumber** | String | | | *Unique, human-friendly order number (displayed to users); enforced unique.* | | **items** | ID | | | *Array of orderManagementOrderItem ids representing items in this order.* | | **buyerId** | ID | | | *User ID of the buyer placing the order.* | | **status** | Enum | | | *Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED* | | **paymentMethodId** | String | | | *Stripe paymentMethodId used for payment. Not stored if cash or other payment (future).* | | **stripeCustomerId** | String | | | *Stripe customerId of buyer; enables saved/paymentMethodId flows.* | | **paymentIntentId** | String | | | *Stripe paymentIntentId; enables webhook correlation and status sync.* | | **shippingAddress** | Object | | | *Shipping address for the order (copy of buyer address at purchase time).* | | **summary** | Object | | | *Object with total, subtotal, currency, shipping, discount breakdown as snapshot of order at time of purchase.* | | **trackingNumber** | String | | | *Optional tracking number entered by seller when marking as shipped.* | | **estimatedDelivery** | Date | | | *Estimated delivery date for order; copied from fastest estimated item or seller input.* | | **cancelledAt** | Date | | | *Timestamp when cancelled by buyer, seller, or admin before shipment.* | | **paidAt** | Date | | | *Timestamp when payment confirmed via Stripe or manual admin update.* | | **deliveredAt** | Date | | | *Timestamp when buyer confirms delivery.* | | **shippedAt** | Date | | | *Timestamp when seller marks as shipped.* | | **carrier** | String | | | *Optional carrier name entered by seller when marking as shipped.* | | **_paymentConfirmation** | Enum | | | *An automatic property that is used to check the confirmed status of the payment set by webhooks.* | #### Enum Properties Enum properties are represented as strings in the database. The values are mapped to their corresponding names in the application layer. ##### status Enum Property *Property Definition* : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED*Enum Options* | Name | Value | Index | | ---- | ----- | ----- | | **PENDING_PAYMENT** | `"PENDING_PAYMENT""` | 0 | | **PAID** | `"PAID""` | 1 | | **PROCESSING** | `"PROCESSING""` | 2 | | **SHIPPED** | `"SHIPPED""` | 3 | | **DELIVERED** | `"DELIVERED""` | 4 | | **CANCELLED** | `"CANCELLED""` | 5 | | **REFUNDED** | `"REFUNDED""` | 6 | ##### _paymentConfirmation Enum Property *Property Definition* : An automatic property that is used to check the confirmed status of the payment set by webhooks.*Enum Options* | Name | Value | Index | | ---- | ----- | ----- | | **pending** | `"pending""` | 0 | | **processing** | `"processing""` | 1 | | **paid** | `"paid""` | 2 | | **canceled** | `"canceled""` | 3 | ### OrderManagementOrderItem resource *Resource Definition* : Order line item representing purchase of a single product from a specific seller as part of an order. Enables feedback, delivery, and per-seller analytics. Immutable after order creation. *OrderManagementOrderItem Resource Properties* | Name | Type | Required | Default | Definition | | ---- | ---- | -------- | ------- | ---------- | | **shipping** | Double | | | *Shipping cost for this product (may be 0 for free shipping).* | | **orderId** | ID | | | *Parent order this item belongs to; enables join and lifecycle tracking.* | | **quantity** | Integer | | | *Number of units purchased for this product.* | | **productId** | ID | | | *ID of product purchased in this line item.* | | **price** | Double | | | *Unit price for this product at purchase time.* | | **sellerId** | ID | | | *UserId of seller (owner of product at purchase time).* | | **title** | String | | | *Product title at purchase time (copied for convenience/audit).* | | **currency** | String | | | *Currency code for price/shipping (ISO 4217).* | ### Sys_orderManagementOrderPayment resource *Resource Definition* : A payment storage object to store the payment life cyle of orders based on orderManagementOrder object. It is autocreated based on the source object's checkout config *Sys_orderManagementOrderPayment Resource Properties* | Name | Type | Required | Default | Definition | | ---- | ---- | -------- | ------- | ---------- | | **ownerId** | ID | | | * An ID value to represent owner user who created the order* | | **orderId** | ID | | | *an ID value to represent the orderId which is the ID parameter of the source orderManagementOrder object* | | **paymentId** | String | | | *A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type* | | **paymentStatus** | String | | | *A string value to represent the payment status which belongs to the lifecyle of a Stripe payment.* | | **statusLiteral** | String | | | *A string value to represent the logical payment status which belongs to the application lifecycle itself.* | | **redirectUrl** | String | | | *A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client.* | ### Sys_paymentCustomer resource *Resource Definition* : A payment storage object to store the customer values of the payment platform *Sys_paymentCustomer Resource Properties* | Name | Type | Required | Default | Definition | | ---- | ---- | -------- | ------- | ---------- | | **userId** | ID | | | * An ID value to represent the user who is created as a stripe customer* | | **customerId** | String | | | *A string value to represent the customer id which is generated on the Stripe gateway. This id is used to represent the customer in the Stripe gateway* | | **platform** | String | | | *A String value to represent payment platform which is used to make the payment. It is stripe as default. It will be used to distinguesh the payment gateways in the future.* | ### Sys_paymentMethod resource *Resource Definition* : A payment storage object to store the payment methods of the platform customers *Sys_paymentMethod Resource Properties* | Name | Type | Required | Default | Definition | | ---- | ---- | -------- | ------- | ---------- | | **paymentMethodId** | String | | | *A string value to represent the id of the payment method on the payment platform.* | | **userId** | ID | | | * An ID value to represent the user who owns the payment method* | | **customerId** | String | | | *A string value to represent the customer id which is generated on the payment gateway.* | | **cardHolderName** | String | | | *A string value to represent the name of the card holder. It can be different than the registered customer.* | | **cardHolderZip** | String | | | *A string value to represent the zip code of the card holder. It is used for address verification in specific countries.* | | **platform** | String | | | *A String value to represent payment platform which teh paymentMethod belongs. It is stripe as default. It will be used to distinguesh the payment gateways in the future.* | | **cardInfo** | Object | | | *A Json value to store the card details of the payment method.* | ## Business Api ### List Ordermanagementorders API *API Definition* : List orders, filtered for buyer and/or seller, or by admin. Includes select orderItems. *API Crud Type* : list *Default access route* : *GET* `/v1/ordermanagementorders` The listOrderManagementOrders api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ordermanagementorders', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrders`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrders","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","orderManagementOrders":[{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For List Ordermanagementorders](businessApi/listOrderManagementOrders). ### Get Ordermanagementorderitem API *API Definition* : Get a specific order item (for feedback/business logic). *API Crud Type* : get *Default access route* : *GET* `/v1/ordermanagementorderitems/:orderManagementOrderItemId` #### Parameters The getOrderManagementOrderItem api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderItemId | ID | true | request.params?.orderManagementOrderItemId | To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems/:orderManagementOrderItemId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderitems/${orderManagementOrderItemId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrderItem`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrderItem","method":"GET","action":"get","appVersion":"Version","rowCount":1,"orderManagementOrderItem":{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Get Ordermanagementorderitem](businessApi/getOrderManagementOrderItem). ### Delete Ordermanagementorder API *API Definition* : Soft-delete/cancel order by admin or eligible actor prior to shipment. Sets status to CANCELLED and cancels active payment intent if pending. Irreversible and blocks feedback. *API Crud Type* : delete *Default access route* : *DELETE* `/v1/ordermanagementorders/:orderManagementOrderId` #### Parameters The deleteOrderManagementOrder api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrder`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Delete Ordermanagementorder](businessApi/deleteOrderManagementOrder). ### Get Ordermanagementorder API *API Definition* : Get single order by ID. Only accessible to admin, buyer, or relevant sellers of items within this order. Includes all orderItems. *API Crud Type* : get *Default access route* : *GET* `/v1/ordermanagementorders/:orderManagementOrderId` #### Parameters The getOrderManagementOrder api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrder`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"GET","action":"get","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Get Ordermanagementorder](businessApi/getOrderManagementOrder). ### Update Ordermanagementorderstatus API *API Definition* : Update order status (manual shipment, delivery, cancellation/refund). Restricted: only seller of all items can mark as shipped, only buyer can confirm delivery, only admin can set refund/cancelled. Timestamps updated as per business rule. *API Crud Type* : update *Default access route* : *PATCH* `/v1/ordermanagementorderstatus/:orderManagementOrderId` #### Parameters The updateOrderManagementOrderStatus api has got 10 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderstatus/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderstatus/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrder`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Update Ordermanagementorderstatus](businessApi/updateOrderManagementOrderStatus). ### Complete Orderstripewebhook API *API Definition* : Webhook endpoint called by Stripe to reconcile payment state and update order status based on paymentIntentId and event data. No authentication required (Stripe IPs only). *API Crud Type* : update *Default access route* : *PATCH* `/v1/completeorderstripewebhook/:orderManagementOrderId` #### Parameters The completeOrderStripeWebhook api has got 10 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | To access the api you can use the **REST** controller with the path **PATCH /v1/completeorderstripewebhook/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/completeorderstripewebhook/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrder`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Complete Orderstripewebhook](businessApi/completeOrderStripeWebhook). ### Get Ordermanagementorderbyproductid API *API Definition* : get orders by productId *API Crud Type* : get *Default access route* : *GET* `/v1/ordermanagementorderbyproductid/:items` #### Parameters The getOrderManagementOrderByProductId api has got 2 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | items | String | true | request.params?.items | To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderbyproductid/:items** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderbyproductid/${items}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrder`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"GET","action":"get","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Get Ordermanagementorderbyproductid](businessApi/getOrderManagementOrderByProductId). ### Create Ordermanagementorder API *API Definition* : Creates an order and initiates Stripe payment. Validates that all products in the order are fixed-price, populates orderItems, saves Stripe customer/paymentMethod/paymentIntentId for reconciliation. Only accessible to buyers for own checkouts and only allows fixed-price product checkout (no auction). *API Crud Type* : create *Default access route* : *POST* `/v1/ordermanagementorders` #### Parameters The createOrderManagementOrder api has got 14 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderNumber | String | true | request.body?.orderNumber | | items | ID | false | request.body?.items | | paymentMethodId | String | true | request.body?.paymentMethodId | | stripeCustomerId | String | true | request.body?.stripeCustomerId | | paymentIntentId | String | false | request.body?.paymentIntentId | | shippingAddress | Object | true | request.body?.shippingAddress | | summary | Object | true | request.body?.summary | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorders** ```js axios({ method: 'POST', url: '/v1/ordermanagementorders', data: { orderNumber:"String", items:"ID", paymentMethodId:"String", stripeCustomerId:"String", paymentIntentId:"String", shippingAddress:"Object", summary:"Object", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrder`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"POST","action":"create","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Create Ordermanagementorder](businessApi/createOrderManagementOrder). ### List Ordermanagementorderitems API *API Definition* : List order items for a given order or for buyer/seller analytics. Used for feedback management. *API Crud Type* : list *Default access route* : *GET* `/v1/ordermanagementorderitems` The listOrderManagementOrderItems api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderitems', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrderItems`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrderItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","orderManagementOrderItems":[{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For List Ordermanagementorderitems](businessApi/listOrderManagementOrderItems). ### List Ownordermanagementorders API *API Definition* : list the loggedin user orders *API Crud Type* : list *Default access route* : *GET* `/v1/ownordermanagementorders` The listOwnOrderManagementOrders api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/ownordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ownordermanagementorders', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrders`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrders","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","orderManagementOrders":[{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For List Ownordermanagementorders](businessApi/listOwnOrderManagementOrders). ### Lis Ordermanagementownorderitem API *API Definition* : list the loggedin user's order items *API Crud Type* : list *Default access route* : *GET* `/v1/lisordermanagementownorderitem` The lisOrderManagementOwnOrderItem api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/lisordermanagementownorderitem** ```js axios({ method: 'GET', url: '/v1/lisordermanagementownorderitem', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrderItems`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrderItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","orderManagementOrderItems":[{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Lis Ordermanagementownorderitem](businessApi/lisOrderManagementOwnOrderItem). ### Create Ordermanagementorderitem API *API Definition* : create order item *API Crud Type* : create *Default access route* : *POST* `/v1/ordermanagementorderitems` #### Parameters The createOrderManagementOrderItem api has got 8 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | shipping | Double | true | request.body?.shipping | | orderId | ID | true | request.body?.orderId | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | | price | Double | true | request.body?.price | | sellerId | ID | true | request.body?.sellerId | | title | String | true | request.body?.title | | currency | String | true | request.body?.currency | To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderitems** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderitems', data: { shipping:"Double", orderId:"ID", quantity:"Integer", productId:"ID", price:"Double", sellerId:"ID", title:"String", currency:"String", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrderItem`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrderItem","method":"POST","action":"create","appVersion":"Version","rowCount":1,"orderManagementOrderItem":{"id":"ID","shipping":"Double","orderId":"ID","quantity":"Integer","productId":"ID","price":"Double","sellerId":"ID","title":"String","currency":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Create Ordermanagementorderitem](businessApi/createOrderManagementOrderItem). ### Get Ordermanagementorderpayment2 API *API Definition* : This route is used to get the payment information by ID. *API Crud Type* : get *Default access route* : *GET* `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` #### Parameters The getOrderManagementOrderPayment2 api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`sys_orderManagementOrderPayment`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Get Ordermanagementorderpayment2](businessApi/getOrderManagementOrderPayment2). ### List Ordermanagementorderpayments2 API *API Definition* : This route is used to list all payments. *API Crud Type* : list *Default access route* : *GET* `/v1/ordermanagementorderpayments2` The listOrderManagementOrderPayments2 api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`sys_orderManagementOrderPayments`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayments","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","sys_orderManagementOrderPayments":[{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For List Ordermanagementorderpayments2](businessApi/listOrderManagementOrderPayments2). ### Create Ordermanagementorderpayment API *API Definition* : This route is used to create a new payment. *API Crud Type* : create *Default access route* : *POST* `/v1/ordermanagementorderpayment` #### Parameters The createOrderManagementOrderPayment api has got 5 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderId | ID | true | request.body?.orderId | | paymentId | String | true | request.body?.paymentId | | paymentStatus | String | true | request.body?.paymentStatus | | statusLiteral | String | true | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderpayment', data: { orderId:"ID", paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`sys_orderManagementOrderPayment`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"POST","action":"create","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Create Ordermanagementorderpayment](businessApi/createOrderManagementOrderPayment). ### Update Ordermanagementorderpayment API *API Definition* : This route is used to update an existing payment. *API Crud Type* : update *Default access route* : *PATCH* `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` #### Parameters The updateOrderManagementOrderPayment api has got 5 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | false | request.body?.paymentId | | paymentStatus | String | false | request.body?.paymentStatus | | statusLiteral | String | false | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`sys_orderManagementOrderPayment`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Update Ordermanagementorderpayment](businessApi/updateOrderManagementOrderPayment). ### Delete Ordermanagementorderpayment API *API Definition* : This route is used to delete a payment. *API Crud Type* : delete *Default access route* : *DELETE* `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` #### Parameters The deleteOrderManagementOrderPayment api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`sys_orderManagementOrderPayment`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Delete Ordermanagementorderpayment](businessApi/deleteOrderManagementOrderPayment). ### List Ordermanagementorderpayments2 API *API Definition* : This route is used to list all payments. *API Crud Type* : list *Default access route* : *GET* `/v1/ordermanagementorderpayments2` The listOrderManagementOrderPayments2 api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`sys_orderManagementOrderPayments`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayments","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","sys_orderManagementOrderPayments":[{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For List Ordermanagementorderpayments2](businessApi/listOrderManagementOrderPayments2). ### Get Ordermanagementorderpaymentbyorderid API *API Definition* : This route is used to get the payment information by order id. *API Crud Type* : get *Default access route* : *GET* `/v1/orderManagementOrderpaymentbyorderid/:orderId` #### Parameters The getOrderManagementOrderPaymentByOrderId api has got 2 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | orderId | String | true | request.params?.orderId | To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbyorderid/:orderId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbyorderid/${orderId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`sys_orderManagementOrderPayment`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Get Ordermanagementorderpaymentbyorderid](businessApi/getOrderManagementOrderPaymentByOrderId). ### Get Ordermanagementorderpaymentbypaymentid API *API Definition* : This route is used to get the payment information by payment id. *API Crud Type* : get *Default access route* : *GET* `/v1/orderManagementOrderpaymentbypaymentid/:paymentId` #### Parameters The getOrderManagementOrderPaymentByPaymentId api has got 2 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | true | request.params?.paymentId | To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbypaymentid/:paymentId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbypaymentid/${paymentId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`sys_orderManagementOrderPayment`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Get Ordermanagementorderpaymentbypaymentid](businessApi/getOrderManagementOrderPaymentByPaymentId). ### Get Ordermanagementorderpayment2 API *API Definition* : This route is used to get the payment information by ID. *API Crud Type* : get *Default access route* : *GET* `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` #### Parameters The getOrderManagementOrderPayment2 api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`sys_orderManagementOrderPayment`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_orderManagementOrderPayment","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_orderManagementOrderPayment":{"id":"ID","ownerId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"String","statusLiteral":"String","redirectUrl":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Get Ordermanagementorderpayment2](businessApi/getOrderManagementOrderPayment2). ### Start Ordermanagementorderpayment API *API Definition* : Start payment for orderManagementOrder *API Crud Type* : update *Default access route* : *PATCH* `/v1/startordermanagementorderpayment/:orderManagementOrderId` #### Parameters The startOrderManagementOrderPayment api has got 2 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | To access the api you can use the **REST** controller with the path **PATCH /v1/startordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/startordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrder`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},"paymentResult":{"paymentTicketId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"Enum","paymentIntentInfo":"Object","statusLiteral":"String","amount":"Double","currency":"String","success":true,"description":"String","metadata":"Object","paymentUserParams":"Object"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Start Ordermanagementorderpayment](businessApi/startOrderManagementOrderPayment). ### Refresh Ordermanagementorderpayment API *API Definition* : Refresh payment info for orderManagementOrder from Stripe *API Crud Type* : update *Default access route* : *PATCH* `/v1/refreshordermanagementorderpayment/:orderManagementOrderId` #### Parameters The refreshOrderManagementOrderPayment api has got 2 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | To access the api you can use the **REST** controller with the path **PATCH /v1/refreshordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/refreshordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrder`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},"paymentResult":{"paymentTicketId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"Enum","paymentIntentInfo":"Object","statusLiteral":"String","amount":"Double","currency":"String","success":true,"description":"String","metadata":"Object","paymentUserParams":"Object"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Refresh Ordermanagementorderpayment](businessApi/refreshOrderManagementOrderPayment). ### Callback Ordermanagementorderpayment API *API Definition* : Refresh payment values by gateway webhook call for orderManagementOrder *API Crud Type* : update *Default access route* : *POST* `/v1/callbackordermanagementorderpayment` #### Parameters The callbackOrderManagementOrderPayment api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.body?.orderManagementOrderId | To access the api you can use the **REST** controller with the path **POST /v1/callbackordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/callbackordermanagementorderpayment', data: { orderManagementOrderId:"ID", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrder`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"orderManagementOrder","method":"POST","action":"update","appVersion":"Version","rowCount":1,"orderManagementOrder":{"id":"ID","orderNumber":"String","items":"ID","buyerId":"ID","status":"Enum","status_idx":"Integer","paymentMethodId":"String","stripeCustomerId":"String","paymentIntentId":"String","shippingAddress":"Object","summary":"Object","trackingNumber":"String","estimatedDelivery":"Date","cancelledAt":"Date","paidAt":"Date","deliveredAt":"Date","shippedAt":"Date","carrier":"String","_paymentConfirmation":"Enum","_paymentConfirmation_idx":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},"paymentResult":{"paymentTicketId":"ID","orderId":"ID","paymentId":"String","paymentStatus":"Enum","paymentIntentInfo":"Object","statusLiteral":"String","amount":"Double","currency":"String","success":true,"description":"String","metadata":"Object","paymentUserParams":"Object"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Callback Ordermanagementorderpayment](businessApi/callbackOrderManagementOrderPayment). ### Get Paymentcustomerbyuserid API *API Definition* : This route is used to get the payment customer information by user id. *API Crud Type* : get *Default access route* : *GET* `/v1/paymentcustomers/:userId` #### Parameters The getPaymentCustomerByUserId api has got 2 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_paymentCustomerId | ID | true | request.params?.sys_paymentCustomerId | | userId | String | true | request.params?.userId | To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomers/${userId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`sys_paymentCustomer`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_paymentCustomer","method":"GET","action":"get","appVersion":"Version","rowCount":1,"sys_paymentCustomer":{"id":"ID","userId":"ID","customerId":"String","platform":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Get Paymentcustomerbyuserid](businessApi/getPaymentCustomerByUserId). ### List Paymentcustomers API *API Definition* : This route is used to list all payment customers. *API Crud Type* : list *Default access route* : *GET* `/v1/paymentcustomers` The listPaymentCustomers api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers** ```js axios({ method: 'GET', url: '/v1/paymentcustomers', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`sys_paymentCustomers`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_paymentCustomers","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","sys_paymentCustomers":[{"id":"ID","userId":"ID","customerId":"String","platform":"String","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For List Paymentcustomers](businessApi/listPaymentCustomers). ### List Paymentcustomermethods API *API Definition* : This route is used to list all payment customer methods. *API Crud Type* : list *Default access route* : *GET* `/v1/paymentcustomermethods/:userId` #### Parameters The listPaymentCustomerMethods api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | String | true | request.params?.userId | To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomermethods/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomermethods/${userId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`sys_paymentMethods`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"sys_paymentMethods","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","sys_paymentMethods":[{"id":"ID","paymentMethodId":"String","userId":"ID","customerId":"String","cardHolderName":"String","cardHolderZip":"String","platform":"String","cardInfo":"Object","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For List Paymentcustomermethods](businessApi/listPaymentCustomerMethods). ### Authentication Specific Routes ### Common Routes ### Route: currentuser *Route Definition*: Retrieves the currently authenticated user's session information. *Route Type*: sessionInfo *Access Route*: `GET /currentuser` #### Parameters This route does **not** require any request parameters. #### Behavior - Returns the authenticated session object associated with the current access token. - If no valid session exists, responds with a 401 Unauthorized. ```js // Sample GET /currentuser call axios.get("/currentuser", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** Returns the session object, including user-related data and token information. ``` { "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", "roleId": "user", "tenantId": "abc123", "accessToken": "jwt-token-string", ... } ``` **Error Response** **401 Unauthorized:** No active session found. ``` { "status": "ERR", "message": "No login found" } ``` **Notes** * This route is typically used by frontend or mobile applications to fetch the current session state after login. * The returned session includes key user identity fields, tenant information (if applicable), and the access token for further authenticated requests. * Always ensure a valid access token is provided in the request to retrieve the session. ### Route: permissions `*Route Definition*`: Retrieves all effective permission records assigned to the currently authenticated user. `*Route Type*`: permissionFetch *Access Route*: `GET /permissions` #### Parameters This route does **not** require any request parameters. #### Behavior - Fetches all active permission records (`givenPermissions` entries) associated with the current user session. - Returns a full array of permission objects. - Requires a valid session (`access token`) to be available. ```js // Sample GET /permissions call axios.get("/permissions", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** Returns an array of permission objects. ```json [ { "id": "perm1", "permissionName": "adminPanel.access", "roleId": "admin", "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" }, { "id": "perm2", "permissionName": "orders.manage", "roleId": null, "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" } ] ``` Each object reflects a single permission grant, aligned with the givenPermissions model: - `**permissionName**`: The permission the user has. - `**roleId**`: If the permission was granted through a role. -` **subjectUserId**`: If directly granted to the user. - `**subjectUserGroupId**`: If granted through a group. - `**objectId**`: If tied to a specific object (OBAC). - `**canDo**`: True or false flag to represent if permission is active or restricted. **Error Responses** * **401 Unauthorized**: No active session found. ```json { "status": "ERR", "message": "No login found" } ``` * **500 Internal Server Error**: Unexpected error fetching permissions. **Notes** * The /permissions route is available across all backend services generated by Mindbricks, not just the auth service. * Auth service: Fetches permissions freshly from the live database (givenPermissions table). * Other services: Typically use a cached or projected view of permissions stored in a common ElasticSearch store, optimized for faster authorization checks. > **Tip**: > Applications can cache permission results client-side or server-side, but should occasionally refresh by calling this endpoint, especially after login or permission-changing operations. ### Route: permissions/:permissionName *Route Definition*: Checks whether the current user has access to a specific permission, and provides a list of scoped object exceptions or inclusions. *Route Type*: permissionScopeCheck *Access Route*: `GET /permissions/:permissionName` #### Parameters | Parameter | Type | Required | Population | |------------------|--------|----------|------------------------| | permissionName | String | Yes | `request.params.permissionName` | #### Behavior - Evaluates whether the current user **has access** to the given `permissionName`. - Returns a structured object indicating: - Whether the permission is generally granted (`canDo`) - Which object IDs are explicitly included or excluded from access (`exceptions`) - Requires a valid session (`access token`). ```js // Sample GET /permissions/orders.manage axios.get("/permissions/orders.manage", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** ```json { "canDo": true, "exceptions": [ "a1f2e3d4-xxxx-yyyy-zzzz-object1", "b2c3d4e5-xxxx-yyyy-zzzz-object2" ] } ``` * If `canDo` is `true`, the user generally has the permission, but not for the objects listed in `exceptions` (i.e., restrictions). * If `canDo` is `false`, the user does not have the permission by default — but only for the objects in `exceptions`, they do have permission (i.e., selective overrides). * The exceptions array contains valid **UUID strings**, each corresponding to an object ID (typically from the data model targeted by the permission). ## Copyright All sources, documents and other digital materials are copyright of . ## About Us For more information please visit our website: . . . # Service Design Specification **ebaycclone-ordermanagement-service** documentation -Version:**`1.0.16`** ## Scope This document provides a structured architectural overview of the `orderManagement` microservice, detailing its configuration, data model, authorization logic, business rules, and API design. It has been automatically generated based on the service definition within Mindbricks, ensuring that the information reflects the source of truth used during code generation and deployment. The document is intended to serve multiple audiences: * **Service architects** can use it to validate design decisions and ensure alignment with broader architectural goals. * **Developers and maintainers** will find it useful for understanding the structure and behavior of the service, facilitating easier debugging, feature extension, and integration with other systems. * **Stakeholders and reviewers** can use it to gain a clear understanding of the service's capabilities and domain logic. > **Note for Frontend Developers**: While this document is valuable for understanding business logic and data interactions, please refer to the [Service API Documentation](#) for endpoint-level specifications and integration details. > **Note for Backend Developers**: Since the code for this service is automatically generated by Mindbricks, you typically won't need to implement or modify it manually. However, this document is especially valuable when you're building other services—whether within Mindbricks or externally—that need to interact with or depend on this service. It provides a clear reference to the service's data contracts, business rules, and API structure, helping ensure compatibility and correct integration. ## `OrderManagement` Service Settings [**Edit**](ordermanagement/serviceSettings) Handles all marketplace orders, manual checkout flows for fixed-price/offer/auction settlements, Stripe payment processing and webhook reconciliation, explicit status updates (shipping, delivery, cancellation), and feedback eligibility via orderItems. ### Service Overview This service is configured to listen for HTTP requests on port `3004`, serving both the main API interface and default administrative endpoints. The following routes are available by default: * **API Test Interface (API Face):** `/` * **Swagger Documentation:** `/swagger` * **Postman Collection Download:** `/getPostmanCollection` * **Health Checks:** `/health` and `/admin/health` * **Current Session Info:** `/currentuser` * **Favicon:** `/favicon.ico` The service uses a **PostgreSQL** database for data storage, with the database name set to `ebaycclone-ordermanagement-service`. This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/ordermanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/ordermanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/ordermanagement-api` ### Authentication & Security - **Login Required**: Yes This service requires user authentication for access. It supports both JWT and RSA-based authentication mechanisms, ensuring secure user sessions and data integrity. If a crud route also is configured to require login, it will check a valid JWT token in the request query/header/bearer/cookie. If the token is valid, it will extract the user information from the token and make the fetched session data available in the request context. ### Service Data Objects The service uses a **PostgreSQL** database for data storage, with the database name set to `ebaycclone-ordermanagement-service`. Data deletion is managed using a **soft delete** strategy. Instead of removing records from the database, they are flagged as inactive by setting the `isActive` field to `false`. | Object Name | Description | Public Access | |-------------|-------------|---------------| | `orderManagementOrder` | Marketplace order record. Stores buyer, shipping, status, items, Stripe payment data, and manual shipment/delivery events. Only accessible to admins or the buyer/seller of order items. | accessPrivate | | `orderManagementOrderItem` | Order line item representing purchase of a single product from a specific seller as part of an order. Enables feedback, delivery, and per-seller analytics. Immutable after order creation. | accessPrivate | | `sys_orderManagementOrderPayment` | A payment storage object to store the payment life cyle of orders based on orderManagementOrder object. It is autocreated based on the source object's checkout config | accessPrivate | | `sys_paymentCustomer` | A payment storage object to store the customer values of the payment platform | accessPrivate | | `sys_paymentMethod` | A payment storage object to store the payment methods of the platform customers | accessPrivate | ## orderManagementOrder Data Object ### Object Overview **Description:** Marketplace order record. Stores buyer, shipping, status, items, Stripe payment data, and manual shipment/delivery events. Only accessible to admins or the buyer/seller of order items. This object represents a core data structure within the service and acts as the blueprint for database interaction, API generation, and business logic enforcement. It is defined using the `ObjectSettings` pattern, which governs its behavior, access control, caching strategy, and integration points with other systems such as Stripe and Redis. ### Core Configuration - **Soft Delete:** Enabled — Determines whether records are marked inactive (`isActive = false`) instead of being physically deleted. - **Public Access:** accessPrivate — If enabled, anonymous users may access this object’s data depending on API-level rules. ### Composite Indexes - **orderNumberUniqueIdx**: [orderNumber] This composite index is defined to optimize query performance for complex queries involving multiple fields. The index also defines a conflict resolution strategy for duplicate key violations. When a new record would violate this composite index, the following action will be taken: **On Duplicate**: `throwError` An error will be thrown, preventing the insertion of conflicting data. ### Stripe Integration This data object is configured to integrate with Stripe for order management of `orderManagementOrder`. It is designed to handle payment processing and order tracking. To manage payments, Mindbricks will design additional Business API routes arround this data object, which will be used checkout orders and charge customers. - **Order Name**: `orderManagementOrder` - **Order Id Property**: this.orderManagementOrder.id This MScript expression is used to extract the order's unique identifier from the data object. - **Order Amount Property**: this.orderManagementOrder.summary.total This MScript expression is used to determine the order amount for payment. It should return a numeric value representing the total amount to be charged. - **Order Currency Property**: this.orderManagementOrder.summary.currency This MScript expression is used to determine the currency for the order. It should return a string representing the currency code (e.g., "USD", "EUR"). - **Order Description Property**: `Order #${this.orderManagementOrder.orderNumber} for buyerId ${this.orderManagementOrder.buyerId}` This MScript expression is used to provide a description for the order, which will be shown in Stripe and on customer receipts. It should return a string that describes the order. - **Order Status Property**: status This property is selected as the order status property, which will be used to track the current status of the order. It will be automatically updated based on payment results from Stripe. - **Order Status Update Date Property**: updatedAt This property is selected to record the timestamp of the last order status update. It will be automatically managed during payment events to reflect when the status was last changed. - **Order Owner Id Property**: buyerId This property is selected as the order owner property, which will be used to track the user who owns the order. It will be used to ensure correct access control in payment flows, allowing only the owner to manage their orders. - **Map Payment Result to Order Status**: This configuration defines how Stripe's payment results (e.g., started, success, failed, canceled) map to internal order statuses., `paymentResultStarted` status will be mapped to a local value using `"PENDING_PAYMENT"` and will be set to `status`property. `paymentResultCanceled` status will be mapped to a local value using `"CANCELLED"` and will be set to `status` property. `paymentResultFailed` status will be mapped to a local value using `"CANCELLED"` and will be set to `status` property. `paymentResultSuccess` status will be mapped to a local value using `"PAID"` and will be set to `status` property. - **On Checkout Error**: continueRoute if an error occurs during the checkout process, the API will continue to execute, allowing for custom error handling. In this case, the payment error will ve recorded as a status update. To make a retry a new checkout, a new order will be created with the same data as the original order. ### Properties Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `orderNumber` | String | Yes | Unique, human-friendly order number (displayed to users); enforced unique. | | `items` | ID | No | Array of orderManagementOrderItem ids representing items in this order. | | `buyerId` | ID | Yes | User ID of the buyer placing the order. | | `status` | Enum | Yes | Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED | | `paymentMethodId` | String | Yes | Stripe paymentMethodId used for payment. Not stored if cash or other payment (future). | | `stripeCustomerId` | String | Yes | Stripe customerId of buyer; enables saved/paymentMethodId flows. | | `paymentIntentId` | String | No | Stripe paymentIntentId; enables webhook correlation and status sync. | | `shippingAddress` | Object | Yes | Shipping address for the order (copy of buyer address at purchase time). | | `summary` | Object | Yes | Object with total, subtotal, currency, shipping, discount breakdown as snapshot of order at time of purchase. | | `trackingNumber` | String | No | Optional tracking number entered by seller when marking as shipped. | | `estimatedDelivery` | Date | No | Estimated delivery date for order; copied from fastest estimated item or seller input. | | `cancelledAt` | Date | No | Timestamp when cancelled by buyer, seller, or admin before shipment. | | `paidAt` | Date | No | Timestamp when payment confirmed via Stripe or manual admin update. | | `deliveredAt` | Date | No | Timestamp when buyer confirms delivery. | | `shippedAt` | Date | No | Timestamp when seller marks as shipped. | | `carrier` | String | No | Optional carrier name entered by seller when marking as shipped. | | `_paymentConfirmation` | Enum | Yes | An automatic property that is used to check the confirmed status of the payment set by webhooks. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value is set. ### Array Properties `items` Array properties can hold multiple values and are indicated by the `[]` suffix in their type. Avoid using arrays in properties that are used for relations, as they will not work correctly. Note that using connection objects instead of arrays is recommended for relations, as they provide better performance and flexibility. ### Default Values Default values are automatically assigned to properties when a new object is created, if no value is provided in the request body. Since default values are applied on db level, they should be literal values, not expressions.If you want to use expressions, you can use transposed parameters in any business API to set default values dynamically. - **orderNumber**: 'default' - **buyerId**: '00000000-0000-0000-0000-000000000000' - **status**: PENDING_PAYMENT - **paymentMethodId**: 'default' - **stripeCustomerId**: 'default' - **shippingAddress**: {} - **summary**: {} - **_paymentConfirmation**: pending ### Always Create with Default Values Some of the default values are set to be always used when creating a new object, even if the property value is provided in the request body. It ensures that the property is always initialized with a default value when the object is created. - **status**: Will be created with value `PENDING_PAYMENT` - **_paymentConfirmation**: Will be created with value `pending` ### Constant Properties `orderNumber` `items` `buyerId` `paymentMethodId` `stripeCustomerId` `shippingAddress` `summary` Constant properties are defined to be immutable after creation, meaning they cannot be updated or changed once set. They are typically used for properties that should remain constant throughout the object's lifecycle. A property is set to be constant if the `Allow Update` option is set to `false`. ### Auto Update Properties `status` `paymentIntentId` `trackingNumber` `estimatedDelivery` `cancelledAt` `paidAt` `deliveredAt` `shippedAt` `carrier` An update crud API created with the option `Auto Params` enabled will automatically update these properties with the provided values in the request body. If you want to update any property in your own business logic not by user input, you can set the `Allow Auto Update` option to false. These properties will be added to the update API's body parameters and can be updated by the user if any value is provided in the request body. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an addtional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the index property to sort by the enum value or when your enum options represent a sequence of values. - **status**: [PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED] - **_paymentConfirmation**: [pending, processing, paid, canceled] ### Elastic Search Indexing `orderNumber` `buyerId` `status` `cancelledAt` `paidAt` `deliveredAt` `shippedAt` `_paymentConfirmation` Properties that are indexed in Elastic Search will be searchable via the Elastic Search API. While all properties are stored in the elastic search index of the data object, only those marked for Elastic Search indexing will be available for search queries. ### Database Indexing `orderNumber` `buyerId` `status` `paymentIntentId` `cancelledAt` `paidAt` `deliveredAt` `shippedAt` `_paymentConfirmation` Properties that are indexed in the database will be optimized for query performance, allowing for faster data retrieval. Make a property indexed in the database if you want to use it frequently in query filters or sorting. ### Unique Properties `orderNumber` Unique properties are enforced to have distinct values across all instances of the data object, preventing duplicate entries. Note that a unique property is automatically indexed in the database so you will not need to set the `Indexed in DB` option. ### Redis Cluster Properties `orderNumber` Cluster properties are used to group related data in Redis, and used to invalidate the query cache more precisely. If no cluster property is set, the data object query cache will be invalidated for all instances of the data object when any instance is created, updated or deleted. For example, if you have a `userId` property that is used to cluster a task data query in Redis, when a new task is created, the query caches which have different userId filters will be reserved, and only the queries that have the same userId filter or have no filter at all will be invalidated. ### Secondary Key Properties `orderNumber` `paymentIntentId` `_paymentConfirmation` Secondary key properties are used to create an additional indexed identifiers for the data object, allowing for alternative access patterns. Different than normal indexed properties, secondary keys will act as primary keys and Mindbricks will provide automatic secondary key db utility functions to access the data object by the secondary key. ### Relation Properties `items` `buyerId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. You can define relations in the data object properties, which will be used to create foreign key constraints in the database. For complex joins operations, Mindbricks supportsa BFF pattern, where you can view dynamic and static views based on Elastic Search Indexes. Use db level relations for simple one-to-one or one-to-many relationships, and use BFF views for complex joins that require multiple data objects to be joined together. - **items**: ID Relation to `orderManagementOrderItem`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: No - **buyerId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes ### Session Data Properties `buyerId` Session data properties are used to store data that is specific to the user session, allowing for personalized experiences and temporary data storage. If a property is configured as session data, it will be automatically mapped to the related field in the user session during CRUD operations. Note that session data properties can not be mutated by the user, but only by the system. - **buyerId**: ID property will be mapped to the session parameter `userId`. This property is also used to store the owner of the session data, allowing for ownership checks and access control. ### Filter Properties `orderNumber` `status` `_paymentConfirmation` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's that have "Auto Params" enabled. - **orderNumber**: String has a filter named `orderNumber` - **status**: Enum has a filter named `status` - **_paymentConfirmation**: Enum has a filter named `_paymentConfirmation` ## orderManagementOrderItem Data Object ### Object Overview **Description:** Order line item representing purchase of a single product from a specific seller as part of an order. Enables feedback, delivery, and per-seller analytics. Immutable after order creation. This object represents a core data structure within the service and acts as the blueprint for database interaction, API generation, and business logic enforcement. It is defined using the `ObjectSettings` pattern, which governs its behavior, access control, caching strategy, and integration points with other systems such as Stripe and Redis. ### Core Configuration - **Soft Delete:** Enabled — Determines whether records are marked inactive (`isActive = false`) instead of being physically deleted. - **Public Access:** accessPrivate — If enabled, anonymous users may access this object’s data depending on API-level rules. ### Composite Indexes - **uniqueOrderItemInOrder**: [orderId, productId] This composite index is defined to optimize query performance for complex queries involving multiple fields. The index also defines a conflict resolution strategy for duplicate key violations. When a new record would violate this composite index, the following action will be taken: **On Duplicate**: `throwError` An error will be thrown, preventing the insertion of conflicting data. ### Properties Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `shipping` | Double | Yes | Shipping cost for this product (may be 0 for free shipping). | | `orderId` | ID | Yes | Parent order this item belongs to; enables join and lifecycle tracking. | | `quantity` | Integer | Yes | Number of units purchased for this product. | | `productId` | ID | Yes | ID of product purchased in this line item. | | `price` | Double | Yes | Unit price for this product at purchase time. | | `sellerId` | ID | Yes | UserId of seller (owner of product at purchase time). | | `title` | String | Yes | Product title at purchase time (copied for convenience/audit). | | `currency` | String | Yes | Currency code for price/shipping (ISO 4217). | * Required properties are mandatory for creating objects and must be provided in the request body if no default value is set. ### Default Values Default values are automatically assigned to properties when a new object is created, if no value is provided in the request body. Since default values are applied on db level, they should be literal values, not expressions.If you want to use expressions, you can use transposed parameters in any business API to set default values dynamically. - **shipping**: 0.0 - **orderId**: '00000000-0000-0000-0000-000000000000' - **quantity**: 1 - **productId**: '00000000-0000-0000-0000-000000000000' - **price**: 0.0 - **sellerId**: '00000000-0000-0000-0000-000000000000' - **title**: 'default' - **currency**: 'default' ### Constant Properties `shipping` `orderId` `quantity` `productId` `price` `sellerId` `title` `currency` Constant properties are defined to be immutable after creation, meaning they cannot be updated or changed once set. They are typically used for properties that should remain constant throughout the object's lifecycle. A property is set to be constant if the `Allow Update` option is set to `false`. ### Elastic Search Indexing `orderId` `productId` `sellerId` `title` Properties that are indexed in Elastic Search will be searchable via the Elastic Search API. While all properties are stored in the elastic search index of the data object, only those marked for Elastic Search indexing will be available for search queries. ### Database Indexing `orderId` `productId` `sellerId` Properties that are indexed in the database will be optimized for query performance, allowing for faster data retrieval. Make a property indexed in the database if you want to use it frequently in query filters or sorting. ### Relation Properties `orderId` `productId` `sellerId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. You can define relations in the data object properties, which will be used to create foreign key constraints in the database. For complex joins operations, Mindbricks supportsa BFF pattern, where you can view dynamic and static views based on Elastic Search Indexes. Use db level relations for simple one-to-one or one-to-many relationships, and use BFF views for complex joins that require multiple data objects to be joined together. - **orderId**: ID Relation to `orderManagementOrder`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes - **productId**: ID Relation to `productListingProduct`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes - **sellerId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes ## sys_orderManagementOrderPayment Data Object ### Object Overview **Description:** A payment storage object to store the payment life cyle of orders based on orderManagementOrder object. It is autocreated based on the source object's checkout config This object represents a core data structure within the service and acts as the blueprint for database interaction, API generation, and business logic enforcement. It is defined using the `ObjectSettings` pattern, which governs its behavior, access control, caching strategy, and integration points with other systems such as Stripe and Redis. ### Core Configuration - **Soft Delete:** Enabled — Determines whether records are marked inactive (`isActive = false`) instead of being physically deleted. - **Public Access:** accessPrivate — If enabled, anonymous users may access this object’s data depending on API-level rules. ### Properties Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `ownerId` | ID | No | An ID value to represent owner user who created the order | | `orderId` | ID | Yes | an ID value to represent the orderId which is the ID parameter of the source orderManagementOrder object | | `paymentId` | String | Yes | A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type | | `paymentStatus` | String | Yes | A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. | | `statusLiteral` | String | Yes | A string value to represent the logical payment status which belongs to the application lifecycle itself. | | `redirectUrl` | String | No | A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value is set. ### Default Values Default values are automatically assigned to properties when a new object is created, if no value is provided in the request body. Since default values are applied on db level, they should be literal values, not expressions.If you want to use expressions, you can use transposed parameters in any business API to set default values dynamically. - **orderId**: '00000000-0000-0000-0000-000000000000' - **paymentId**: 'default' - **paymentStatus**: 'default' - **statusLiteral**: started ### Constant Properties `orderId` Constant properties are defined to be immutable after creation, meaning they cannot be updated or changed once set. They are typically used for properties that should remain constant throughout the object's lifecycle. A property is set to be constant if the `Allow Update` option is set to `false`. ### Auto Update Properties `ownerId` `orderId` `paymentId` `paymentStatus` `statusLiteral` `redirectUrl` An update crud API created with the option `Auto Params` enabled will automatically update these properties with the provided values in the request body. If you want to update any property in your own business logic not by user input, you can set the `Allow Auto Update` option to false. These properties will be added to the update API's body parameters and can be updated by the user if any value is provided in the request body. ### Elastic Search Indexing `ownerId` `orderId` `paymentId` `paymentStatus` `statusLiteral` `redirectUrl` Properties that are indexed in Elastic Search will be searchable via the Elastic Search API. While all properties are stored in the elastic search index of the data object, only those marked for Elastic Search indexing will be available for search queries. ### Database Indexing `ownerId` `orderId` `paymentId` `paymentStatus` `statusLiteral` `redirectUrl` Properties that are indexed in the database will be optimized for query performance, allowing for faster data retrieval. Make a property indexed in the database if you want to use it frequently in query filters or sorting. ### Unique Properties `orderId` Unique properties are enforced to have distinct values across all instances of the data object, preventing duplicate entries. Note that a unique property is automatically indexed in the database so you will not need to set the `Indexed in DB` option. ### Secondary Key Properties `orderId` Secondary key properties are used to create an additional indexed identifiers for the data object, allowing for alternative access patterns. Different than normal indexed properties, secondary keys will act as primary keys and Mindbricks will provide automatic secondary key db utility functions to access the data object by the secondary key. ### Session Data Properties `ownerId` Session data properties are used to store data that is specific to the user session, allowing for personalized experiences and temporary data storage. If a property is configured as session data, it will be automatically mapped to the related field in the user session during CRUD operations. Note that session data properties can not be mutated by the user, but only by the system. - **ownerId**: ID property will be mapped to the session parameter `userId`. This property is also used to store the owner of the session data, allowing for ownership checks and access control. ### Filter Properties `ownerId` `orderId` `paymentId` `paymentStatus` `statusLiteral` `redirectUrl` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's that have "Auto Params" enabled. - **ownerId**: ID has a filter named `ownerId` - **orderId**: ID has a filter named `orderId` - **paymentId**: String has a filter named `paymentId` - **paymentStatus**: String has a filter named `paymentStatus` - **statusLiteral**: String has a filter named `statusLiteral` - **redirectUrl**: String has a filter named `redirectUrl` ## sys_paymentCustomer Data Object ### Object Overview **Description:** A payment storage object to store the customer values of the payment platform This object represents a core data structure within the service and acts as the blueprint for database interaction, API generation, and business logic enforcement. It is defined using the `ObjectSettings` pattern, which governs its behavior, access control, caching strategy, and integration points with other systems such as Stripe and Redis. ### Core Configuration - **Soft Delete:** Enabled — Determines whether records are marked inactive (`isActive = false`) instead of being physically deleted. - **Public Access:** accessPrivate — If enabled, anonymous users may access this object’s data depending on API-level rules. ### Properties Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `userId` | ID | No | An ID value to represent the user who is created as a stripe customer | | `customerId` | String | Yes | A string value to represent the customer id which is generated on the Stripe gateway. This id is used to represent the customer in the Stripe gateway | | `platform` | String | Yes | A String value to represent payment platform which is used to make the payment. It is stripe as default. It will be used to distinguesh the payment gateways in the future. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value is set. ### Default Values Default values are automatically assigned to properties when a new object is created, if no value is provided in the request body. Since default values are applied on db level, they should be literal values, not expressions.If you want to use expressions, you can use transposed parameters in any business API to set default values dynamically. - **customerId**: 'default' - **platform**: stripe ### Constant Properties `customerId` `platform` Constant properties are defined to be immutable after creation, meaning they cannot be updated or changed once set. They are typically used for properties that should remain constant throughout the object's lifecycle. A property is set to be constant if the `Allow Update` option is set to `false`. ### Auto Update Properties `userId` `customerId` `platform` An update crud API created with the option `Auto Params` enabled will automatically update these properties with the provided values in the request body. If you want to update any property in your own business logic not by user input, you can set the `Allow Auto Update` option to false. These properties will be added to the update API's body parameters and can be updated by the user if any value is provided in the request body. ### Elastic Search Indexing `userId` `customerId` `platform` Properties that are indexed in Elastic Search will be searchable via the Elastic Search API. While all properties are stored in the elastic search index of the data object, only those marked for Elastic Search indexing will be available for search queries. ### Database Indexing `userId` `customerId` `platform` Properties that are indexed in the database will be optimized for query performance, allowing for faster data retrieval. Make a property indexed in the database if you want to use it frequently in query filters or sorting. ### Unique Properties `userId` `customerId` Unique properties are enforced to have distinct values across all instances of the data object, preventing duplicate entries. Note that a unique property is automatically indexed in the database so you will not need to set the `Indexed in DB` option. ### Secondary Key Properties `userId` `customerId` Secondary key properties are used to create an additional indexed identifiers for the data object, allowing for alternative access patterns. Different than normal indexed properties, secondary keys will act as primary keys and Mindbricks will provide automatic secondary key db utility functions to access the data object by the secondary key. ### Session Data Properties `userId` Session data properties are used to store data that is specific to the user session, allowing for personalized experiences and temporary data storage. If a property is configured as session data, it will be automatically mapped to the related field in the user session during CRUD operations. Note that session data properties can not be mutated by the user, but only by the system. - **userId**: ID property will be mapped to the session parameter `userId`. This property is also used to store the owner of the session data, allowing for ownership checks and access control. ### Filter Properties `userId` `customerId` `platform` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's that have "Auto Params" enabled. - **userId**: ID has a filter named `userId` - **customerId**: String has a filter named `customerId` - **platform**: String has a filter named `platform` ## sys_paymentMethod Data Object ### Object Overview **Description:** A payment storage object to store the payment methods of the platform customers This object represents a core data structure within the service and acts as the blueprint for database interaction, API generation, and business logic enforcement. It is defined using the `ObjectSettings` pattern, which governs its behavior, access control, caching strategy, and integration points with other systems such as Stripe and Redis. ### Core Configuration - **Soft Delete:** Enabled — Determines whether records are marked inactive (`isActive = false`) instead of being physically deleted. - **Public Access:** accessPrivate — If enabled, anonymous users may access this object’s data depending on API-level rules. ### Properties Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `paymentMethodId` | String | Yes | A string value to represent the id of the payment method on the payment platform. | | `userId` | ID | Yes | An ID value to represent the user who owns the payment method | | `customerId` | String | Yes | A string value to represent the customer id which is generated on the payment gateway. | | `cardHolderName` | String | No | A string value to represent the name of the card holder. It can be different than the registered customer. | | `cardHolderZip` | String | No | A string value to represent the zip code of the card holder. It is used for address verification in specific countries. | | `platform` | String | Yes | A String value to represent payment platform which teh paymentMethod belongs. It is stripe as default. It will be used to distinguesh the payment gateways in the future. | | `cardInfo` | Object | Yes | A Json value to store the card details of the payment method. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value is set. ### Default Values Default values are automatically assigned to properties when a new object is created, if no value is provided in the request body. Since default values are applied on db level, they should be literal values, not expressions.If you want to use expressions, you can use transposed parameters in any business API to set default values dynamically. - **paymentMethodId**: 'default' - **userId**: '00000000-0000-0000-0000-000000000000' - **customerId**: 'default' - **platform**: stripe - **cardInfo**: {} ### Constant Properties `paymentMethodId` `userId` `customerId` `cardHolderName` `cardHolderZip` `platform` Constant properties are defined to be immutable after creation, meaning they cannot be updated or changed once set. They are typically used for properties that should remain constant throughout the object's lifecycle. A property is set to be constant if the `Allow Update` option is set to `false`. ### Auto Update Properties `paymentMethodId` `userId` `customerId` `cardHolderName` `cardHolderZip` `platform` `cardInfo` An update crud API created with the option `Auto Params` enabled will automatically update these properties with the provided values in the request body. If you want to update any property in your own business logic not by user input, you can set the `Allow Auto Update` option to false. These properties will be added to the update API's body parameters and can be updated by the user if any value is provided in the request body. ### Elastic Search Indexing `paymentMethodId` `userId` `customerId` `cardHolderName` `cardHolderZip` `platform` `cardInfo` Properties that are indexed in Elastic Search will be searchable via the Elastic Search API. While all properties are stored in the elastic search index of the data object, only those marked for Elastic Search indexing will be available for search queries. ### Database Indexing `paymentMethodId` `userId` `customerId` `platform` `cardInfo` Properties that are indexed in the database will be optimized for query performance, allowing for faster data retrieval. Make a property indexed in the database if you want to use it frequently in query filters or sorting. ### Unique Properties `paymentMethodId` Unique properties are enforced to have distinct values across all instances of the data object, preventing duplicate entries. Note that a unique property is automatically indexed in the database so you will not need to set the `Indexed in DB` option. ### Secondary Key Properties `paymentMethodId` `userId` `customerId` Secondary key properties are used to create an additional indexed identifiers for the data object, allowing for alternative access patterns. Different than normal indexed properties, secondary keys will act as primary keys and Mindbricks will provide automatic secondary key db utility functions to access the data object by the secondary key. ### Session Data Properties `userId` Session data properties are used to store data that is specific to the user session, allowing for personalized experiences and temporary data storage. If a property is configured as session data, it will be automatically mapped to the related field in the user session during CRUD operations. Note that session data properties can not be mutated by the user, but only by the system. - **userId**: ID property will be mapped to the session parameter `userId`. This property is also used to store the owner of the session data, allowing for ownership checks and access control. ### Filter Properties `paymentMethodId` `userId` `customerId` `cardHolderName` `cardHolderZip` `platform` `cardInfo` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's that have "Auto Params" enabled. - **paymentMethodId**: String has a filter named `paymentMethodId` - **userId**: ID has a filter named `userId` - **customerId**: String has a filter named `customerId` - **cardHolderName**: String has a filter named `cardHolderName` - **cardHolderZip**: String has a filter named `cardHolderZip` - **platform**: String has a filter named `platform` - **cardInfo**: Object has a filter named `cardInfo` ## Business Logic orderManagement has got 27 Business APIs to manage its internal and crud logic. For the details of each business API refer to its chapter. * [List Ordermanagementorders](/businessLogic/listordermanagementorders) * [Get Ordermanagementorderitem](/businessLogic/getordermanagementorderitem) * [Delete Ordermanagementorder](/businessLogic/deleteordermanagementorder) * [Get Ordermanagementorder](/businessLogic/getordermanagementorder) * [Update Ordermanagementorderstatus](/businessLogic/updateordermanagementorderstatus) * [Complete Orderstripewebhook](/businessLogic/completeorderstripewebhook) * [Get Ordermanagementorderbyproductid](/businessLogic/getordermanagementorderbyproductid) * [Create Ordermanagementorder](/businessLogic/createordermanagementorder) * [List Ordermanagementorderitems](/businessLogic/listordermanagementorderitems) * [List Ownordermanagementorders](/businessLogic/listownordermanagementorders) * [Lis Ordermanagementownorderitem](/businessLogic/lisordermanagementownorderitem) * [Create Ordermanagementorderitem](/businessLogic/createordermanagementorderitem) * [Get Ordermanagementorderpayment2](/businessLogic/getordermanagementorderpayment2) * [List Ordermanagementorderpayments2](/businessLogic/listordermanagementorderpayments2) * [Create Ordermanagementorderpayment](/businessLogic/createordermanagementorderpayment) * [Update Ordermanagementorderpayment](/businessLogic/updateordermanagementorderpayment) * [Delete Ordermanagementorderpayment](/businessLogic/deleteordermanagementorderpayment) * [List Ordermanagementorderpayments2](/businessLogic/listordermanagementorderpayments2) * [Get Ordermanagementorderpaymentbyorderid](/businessLogic/getordermanagementorderpaymentbyorderid) * [Get Ordermanagementorderpaymentbypaymentid](/businessLogic/getordermanagementorderpaymentbypaymentid) * [Get Ordermanagementorderpayment2](/businessLogic/getordermanagementorderpayment2) * [Start Ordermanagementorderpayment](/businessLogic/startordermanagementorderpayment) * [Refresh Ordermanagementorderpayment](/businessLogic/refreshordermanagementorderpayment) * [Callback Ordermanagementorderpayment](/businessLogic/callbackordermanagementorderpayment) * [Get Paymentcustomerbyuserid](/businessLogic/getpaymentcustomerbyuserid) * [List Paymentcustomers](/businessLogic/listpaymentcustomers) * [List Paymentcustomermethods](/businessLogic/listpaymentcustomermethods) ## Edge Controllers No edge controllers defined for this service. --- ## Service Library ### Functions #### generateOrderId.js ```js module.exports=function(){return 'ORD-' + Date.now().toString(36) + Math.floor(Math.random()*1000).toString(36);} ``` #### calculateOrderSummary.js ```js module.exports=function(products,quantities){ let subtotal=0; let shipping=0; let currency='USD'; products.forEach(p => { let qty=quantities[p.id]||1; subtotal+=p.price*qty; shipping+=p.shipping*qty; if(p.currency) currency=p.currency; }); return {subtotal,shipping,total:subtotal+shipping,currency}; }; ``` ### Hook Functions No hook functions defined. ### Edge Functions No edge functions defined. ### Templates No templates defined. ### Assets No assets defined. ### Public Assets No public assets defined. --- ### Event Emission --- ## Integration Patterns ## Deployment Considerations ### Environment Configuration - **HTTP Port**: `3004` - **Database Type**: MongoDB - **Global Soft Delete**: Enabled ## Implementation Guidelines ### Development Workflow 1. **Data Model Implementation**: Generate database schema from data object definitions 2. **CRUD Route Generation**: Implement auto-generated routes with custom logic 3. **Custom Logic Integration**: Implement hook functions and edge functions 4. **Authentication Integration**: Configure with project-level authentication 5. **Testing**: Unit and integration testing for all components ### Code Generation Expectations - **Database Schema**: Auto-generated from data objects and relationships - **API Routes**: REST endpoints with customizable behavior - **Validation Logic**: Input validation from property definitions - **Access Control**: Authentication and authorization middleware ### Custom Code Integration Points - **Hook Functions**: Lifecycle-specific custom logic - **Edge Functions**: Full request/response control - **Library Functions**: Reusable business logic - **Templates**: Dynamic content rendering ### Testing Strategy #### Unit Testing - Test all custom library functions - Test validation logic and business rules - Test hook function implementations #### Integration Testing - Test API endpoints with authentication scenarios - Test database operations and transactions - Test external integrations - Test event emission and Kafka integration #### Performance Testing - Load test high-traffic endpoints - Test caching effectiveness - Monitor database query performance - Test scalability under load --- ## Appendices ### Data Type Reference | Type | Description | Storage | |------|-------------|---------| | ID | Unique identifier | UUID (SQL) / ObjectID (NoSQL) | | String | Short text (≤255 chars) | VARCHAR | | Text | Long-form text | TEXT | | Integer | 32-bit whole numbers | INT | | Boolean | True/false values | BOOLEAN | | Double | 64-bit floating point | DOUBLE | | Float | 32-bit floating point | FLOAT | | Short | 16-bit integers | SMALLINT | | Object | JSON object | JSONB (PostgreSQL) / Object (MongoDB) | | Date | ISO 8601 timestamp | TIMESTAMP | | Enum | Fixed numeric values | SMALLINT with lookup | ### Enum Value Mappings #### Request Locations - `0`: Bearer token in Authorization header - `1`: Cookie value - `2`: Custom HTTP header - `3`: Query parameter - `4`: Request body property - `5`: URL path parameter - `6`: Session data - `7`: Root request object #### HTTP Methods - `0`: GET - `1`: POST - `2`: PUT - `3`: PATCH - `4`: DELETE ### Edge Function Signature ```javascript async function edgeFunction(request) { // Custom request processing // Return response object or throw error return { data: {}, status: 200, message: "Success" }; } ``` --- *This document was generated from the service architecture definition and should be kept in sync with implementation changes.* # API INTEGRATION PATTERNS ## Ebaycclone Admin Panel This document provides comprehensive information about API integration patterns used in the Ebaycclone Admin Panel, including HTTP client configuration, request/response handling, error management, and performance optimization strategies. ## Architectural Design Credit and Contact Information The architectural design of this API integration system is credited to Mindbricks Genesis Engine. We encourage open communication and welcome any questions or discussions related to the architectural aspects of this API integration system. ## Documentation Scope This guide covers the complete API integration patterns within the Ebaycclone Admin Panel. It includes HTTP client configuration, request/response handling, error management, caching strategies, and performance optimization techniques. **Intended Audience** This documentation is intended for frontend developers, API integrators, and system architects who need to understand, implement, or maintain API integration patterns within the admin panel. ## HTTP Client Architecture ### Service-Specific Axios Instances **AuctionOffer Axios Configuration** ```javascript import axios from 'axios'; import { CONFIG } from 'src/global-config'; const auctionOfferAxiosInstance = axios.create({ baseURL: CONFIG.auctionOfferServiceUrl }); auctionOfferAxiosInstance.interceptors.response.use( (response) => response, (error) => Promise.reject((error.response && error.response.data) || 'Something went wrong!') ); export default auctionOfferAxiosInstance; ``` **Fetcher Utility** ```javascript export const fetcher = async (args) => { try { const [url, config] = Array.isArray(args) ? args : [args]; const res = await auctionOfferAxiosInstance.get(url, { ...config }); return res.data; } catch (error) { console.error('Failed to fetch:', error); throw error; } }; ``` **Service Endpoints** ```javascript export const auctionOfferEndpoints = { auctionOfferOffer: { updateAuctionOfferOffer: '/v1/auctionofferoffers/:auctionOfferOfferId' , getAuctionOfferOffer: '/v1/auctionofferoffers/:auctionOfferOfferId' , listAuctionOfferOffers: '/v1/auctionofferoffers' , createAuctionOfferOffer: '/v1/auctionofferoffers' , deleteAuctionOfferOffer: '/v1/auctionofferoffers/:auctionOfferOfferId' }, auctionOfferBid: { createAuctionOfferBid: '/v1/auctionofferbids' , getAuctionOfferBid: '/v1/auctionofferbids/:auctionOfferBidId' , updateAuctionOfferBid: '/v1/auctionofferbids/:auctionOfferBidId' , listAuctionOfferBids: '/v1/auctionofferbids' , deleteAuctionOfferBid: '/v1/auctionofferbids/:auctionOfferBidId' } }; ``` **CategoryManagement Axios Configuration** ```javascript import axios from 'axios'; import { CONFIG } from 'src/global-config'; const categoryManagementAxiosInstance = axios.create({ baseURL: CONFIG.categoryManagementServiceUrl }); categoryManagementAxiosInstance.interceptors.response.use( (response) => response, (error) => Promise.reject((error.response && error.response.data) || 'Something went wrong!') ); export default categoryManagementAxiosInstance; ``` **Fetcher Utility** ```javascript export const fetcher = async (args) => { try { const [url, config] = Array.isArray(args) ? args : [args]; const res = await categoryManagementAxiosInstance.get(url, { ...config }); return res.data; } catch (error) { console.error('Failed to fetch:', error); throw error; } }; ``` **Service Endpoints** ```javascript export const categoryManagementEndpoints = { category: { deleteCategory: '/v1/categories/:categoryId' , getCategory: '/v1/categories/:categoryId' , listCategories: '/v1/categories' , updateCategory: '/v1/categories/:categoryId' , createCategory: '/v1/categories' }, subcategory: { getSubcategory: '/v1/subcategories/:subcategoryId' , updateSubcategory: '/v1/subcategories/:subcategoryId' , listSubcategories: '/v1/subcategories' , deleteSubcategory: '/v1/subcategories/:subcategoryId' , createSubcategory: '/v1/subcategories' } }; ``` **Messaging Axios Configuration** ```javascript import axios from 'axios'; import { CONFIG } from 'src/global-config'; const messagingAxiosInstance = axios.create({ baseURL: CONFIG.messagingServiceUrl }); messagingAxiosInstance.interceptors.response.use( (response) => response, (error) => Promise.reject((error.response && error.response.data) || 'Something went wrong!') ); export default messagingAxiosInstance; ``` **Fetcher Utility** ```javascript export const fetcher = async (args) => { try { const [url, config] = Array.isArray(args) ? args : [args]; const res = await messagingAxiosInstance.get(url, { ...config }); return res.data; } catch (error) { console.error('Failed to fetch:', error); throw error; } }; ``` **Service Endpoints** ```javascript export const messagingEndpoints = { messagingMessage: { listMessagingMessages: '/v1/messagingmessages' , createMessagingMessage: '/v1/messagingmessages' , updateMessagingMessage: '/v1/messagingmessages/:messagingMessageId' , getMessagingMessage: '/v1/messagingmessages/:messagingMessageId' , deleteMessagingMessage: '/v1/messagingmessages/:messagingMessageId' } }; ``` **NotificationManagement Axios Configuration** ```javascript import axios from 'axios'; import { CONFIG } from 'src/global-config'; const notificationManagementAxiosInstance = axios.create({ baseURL: CONFIG.notificationManagementServiceUrl }); notificationManagementAxiosInstance.interceptors.response.use( (response) => response, (error) => Promise.reject((error.response && error.response.data) || 'Something went wrong!') ); export default notificationManagementAxiosInstance; ``` **Fetcher Utility** ```javascript export const fetcher = async (args) => { try { const [url, config] = Array.isArray(args) ? args : [args]; const res = await notificationManagementAxiosInstance.get(url, { ...config }); return res.data; } catch (error) { console.error('Failed to fetch:', error); throw error; } }; ``` **Service Endpoints** ```javascript export const notificationManagementEndpoints = { notification: { createNotification: '/v1/notifications' , updateNotification: '/v1/notifications/:notificationId' , listNotifications: '/v1/notifications' , deleteNotification: '/v1/notifications/:notificationId' , getNotification: '/v1/notifications/:notificationId' } }; ``` **SearchIndexing Axios Configuration** ```javascript import axios from 'axios'; import { CONFIG } from 'src/global-config'; const searchIndexingAxiosInstance = axios.create({ baseURL: CONFIG.searchIndexingServiceUrl }); searchIndexingAxiosInstance.interceptors.response.use( (response) => response, (error) => Promise.reject((error.response && error.response.data) || 'Something went wrong!') ); export default searchIndexingAxiosInstance; ``` **Fetcher Utility** ```javascript export const fetcher = async (args) => { try { const [url, config] = Array.isArray(args) ? args : [args]; const res = await searchIndexingAxiosInstance.get(url, { ...config }); return res.data; } catch (error) { console.error('Failed to fetch:', error); throw error; } }; ``` **Service Endpoints** ```javascript export const searchIndexingEndpoints = { searchIndex: { listSearchIndexes: '/v1/searchindexes' , updateSearchIndex: '/v1/searchindexs/:searchIndexId' , deleteSearchIndex: '/v1/searchindexs/:searchIndexId' , createSearchIndex: '/v1/searchindexs' , getSearchIndex: '/v1/searchindexs/:searchIndexId' } }; ``` **AdminModeration Axios Configuration** ```javascript import axios from 'axios'; import { CONFIG } from 'src/global-config'; const adminModerationAxiosInstance = axios.create({ baseURL: CONFIG.adminModerationServiceUrl }); adminModerationAxiosInstance.interceptors.response.use( (response) => response, (error) => Promise.reject((error.response && error.response.data) || 'Something went wrong!') ); export default adminModerationAxiosInstance; ``` **Fetcher Utility** ```javascript export const fetcher = async (args) => { try { const [url, config] = Array.isArray(args) ? args : [args]; const res = await adminModerationAxiosInstance.get(url, { ...config }); return res.data; } catch (error) { console.error('Failed to fetch:', error); throw error; } }; ``` **Service Endpoints** ```javascript export const adminModerationEndpoints = { moderationAction: { getModerationAction: '/v1/moderationactions/:moderationActionId' , deleteModerationAction: '/v1/moderationactions/:moderationActionId' , createModerationAction: '/v1/moderationactions' , listModerationActions: '/v1/moderationactions' , updateModerationAction: '/v1/moderationactions/:moderationActionId' } }; ``` **WatchlistCart Axios Configuration** ```javascript import axios from 'axios'; import { CONFIG } from 'src/global-config'; const watchlistCartAxiosInstance = axios.create({ baseURL: CONFIG.watchlistCartServiceUrl }); watchlistCartAxiosInstance.interceptors.response.use( (response) => response, (error) => Promise.reject((error.response && error.response.data) || 'Something went wrong!') ); export default watchlistCartAxiosInstance; ``` **Fetcher Utility** ```javascript export const fetcher = async (args) => { try { const [url, config] = Array.isArray(args) ? args : [args]; const res = await watchlistCartAxiosInstance.get(url, { ...config }); return res.data; } catch (error) { console.error('Failed to fetch:', error); throw error; } }; ``` **Service Endpoints** ```javascript export const watchlistCartEndpoints = { watchlistItem: { createWatchlistItem: '/v1/watchlistitems' , listWatchlistItems: '/v1/watchlistitems' , deleteWatchlistItem: '/v1/watchlistitems/:watchlistItemId' }, cartItem: { listCartItems: '/v1/cartitems' , deleteCartItem: '/v1/cartitems/:cartItemId' , updateCartItemQuantity: '/v1/cartitemquantity/:cartItemId' , createCartItem: '/v1/cartitems' }, watchlistList: { createWatchlistList: '/v1/watchlistlists' , deleteWatchlistList: '/v1/watchlistlists/:watchlistListId' } }; ``` **ProductListing Axios Configuration** ```javascript import axios from 'axios'; import { CONFIG } from 'src/global-config'; const productListingAxiosInstance = axios.create({ baseURL: CONFIG.productListingServiceUrl }); productListingAxiosInstance.interceptors.response.use( (response) => response, (error) => Promise.reject((error.response && error.response.data) || 'Something went wrong!') ); export default productListingAxiosInstance; ``` **Fetcher Utility** ```javascript export const fetcher = async (args) => { try { const [url, config] = Array.isArray(args) ? args : [args]; const res = await productListingAxiosInstance.get(url, { ...config }); return res.data; } catch (error) { console.error('Failed to fetch:', error); throw error; } }; ``` **Service Endpoints** ```javascript export const productListingEndpoints = { productListingMedia: { listProductListingMedia: '/v1/productlistingmedias' , getProductListingMedia: '/v1/productlistingmedias/:productListingMediaId' , deleteProductListingMedia: '/v1/productlistingmedias/:productListingMediaId' , createProductListingMedia: '/v1/productlistingmedias' }, productListingProduct: { getProductListingProduct: '/v1/productlistingproducts/:productListingProductId' , listProductListingProducts: '/v1/productlistingproducts' , deleteProductListingProduct: '/v1/productlistingproducts/:productListingProductId' , updateProductListingProduct: '/v1/productlistingproducts/:productListingProductId' , createProductListingProduct: '/v1/productlistingproducts' } }; ``` **OrderManagement Axios Configuration** ```javascript import axios from 'axios'; import { CONFIG } from 'src/global-config'; const orderManagementAxiosInstance = axios.create({ baseURL: CONFIG.orderManagementServiceUrl }); orderManagementAxiosInstance.interceptors.response.use( (response) => response, (error) => Promise.reject((error.response && error.response.data) || 'Something went wrong!') ); export default orderManagementAxiosInstance; ``` **Fetcher Utility** ```javascript export const fetcher = async (args) => { try { const [url, config] = Array.isArray(args) ? args : [args]; const res = await orderManagementAxiosInstance.get(url, { ...config }); return res.data; } catch (error) { console.error('Failed to fetch:', error); throw error; } }; ``` **Service Endpoints** ```javascript export const orderManagementEndpoints = { orderManagementOrder: { listOrderManagementOrders: '/v1/ordermanagementorders' , deleteOrderManagementOrder: '/v1/ordermanagementorders/:orderManagementOrderId' , getOrderManagementOrder: '/v1/ordermanagementorders/:orderManagementOrderId' , updateOrderManagementOrderStatus: '/v1/ordermanagementorderstatus/:orderManagementOrderId' , completeOrderStripeWebhook: '/v1/completeorderstripewebhook/:orderManagementOrderId' , createOrderManagementOrder: '/v1/ordermanagementorders' , startOrderManagementOrderPayment: '/v1/startordermanagementorderpayment/:orderManagementOrderId' , refreshOrderManagementOrderPayment: '/v1/refreshordermanagementorderpayment/:orderManagementOrderId' , callbackOrderManagementOrderPayment: '/v1/callbackordermanagementorderpayment' }, orderManagementOrderItem: { getOrderManagementOrderItem: '/v1/ordermanagementorderitems/:orderManagementOrderItemId' , listOrderManagementOrderItems: '/v1/ordermanagementorderitems' }, sys_orderManagementOrderPayment: { getOrderManagementOrderPayment2: '/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId' , listOrderManagementOrderPayments2: '/v1/ordermanagementorderpayments2' , createOrderManagementOrderPayment: '/v1/ordermanagementorderpayment' , updateOrderManagementOrderPayment: '/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId' , deleteOrderManagementOrderPayment: '/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId' , listOrderManagementOrderPayments2: '/v1/ordermanagementorderpayments2' , getOrderManagementOrderPaymentByOrderId: '/v1/orderManagementOrderpaymentbyorderid/:orderId' , getOrderManagementOrderPaymentByPaymentId: '/v1/orderManagementOrderpaymentbypaymentid/:paymentId' , getOrderManagementOrderPayment2: '/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId' }, sys_paymentCustomer: { getPaymentCustomerByUserId: '/v1/paymentcustomers/:userId' , listPaymentCustomers: '/v1/paymentcustomers' }, sys_paymentMethod: { listPaymentCustomerMethods: '/v1/paymentcustomermethods/:userId' } }; ``` **Feedback Axios Configuration** ```javascript import axios from 'axios'; import { CONFIG } from 'src/global-config'; const feedbackAxiosInstance = axios.create({ baseURL: CONFIG.feedbackServiceUrl }); feedbackAxiosInstance.interceptors.response.use( (response) => response, (error) => Promise.reject((error.response && error.response.data) || 'Something went wrong!') ); export default feedbackAxiosInstance; ``` **Fetcher Utility** ```javascript export const fetcher = async (args) => { try { const [url, config] = Array.isArray(args) ? args : [args]; const res = await feedbackAxiosInstance.get(url, { ...config }); return res.data; } catch (error) { console.error('Failed to fetch:', error); throw error; } }; ``` **Service Endpoints** ```javascript export const feedbackEndpoints = { feedback: { listFeedbacks: '/v1/feedbacks' , getFeedback: '/v1/feedbacks/:feedbackId' , updateFeedback: '/v1/feedbacks/:feedbackId' , deleteFeedback: '/v1/feedbacks/:feedbackId' , createFeedback: '/v1/feedbacks' } }; ``` **Auth Axios Configuration** ```javascript import axios from 'axios'; import { CONFIG } from 'src/global-config'; const authAxiosInstance = axios.create({ baseURL: CONFIG.authServiceUrl }); authAxiosInstance.interceptors.response.use( (response) => response, (error) => Promise.reject((error.response && error.response.data) || 'Something went wrong!') ); export default authAxiosInstance; ``` **Fetcher Utility** ```javascript export const fetcher = async (args) => { try { const [url, config] = Array.isArray(args) ? args : [args]; const res = await authAxiosInstance.get(url, { ...config }); return res.data; } catch (error) { console.error('Failed to fetch:', error); throw error; } }; ``` **Service Endpoints** ```javascript export const authEndpoints = { login: "/login", me: "/v1/users/:userId", logout: "/logout", user: { getUser: '/v1/users/:userId' , updateUser: '/v1/users/:userId' , updateProfile: '/v1/profile/:userId' , createUser: '/v1/users' , deleteUser: '/v1/users/:userId' , archiveProfile: '/v1/archiveprofile/:userId' , listUsers: '/v1/users' , searchUsers: '/v1/searchusers' , updateUserRole: '/v1/userrole/:userId' , updateUserPassword: '/v1/userpassword/:userId' , updateUserPasswordByAdmin: '/v1/userpasswordbyadmin/:userId' , getBriefUser: '/v1/briefuser/:userId' , registerUser: '/v1/registeruser' } }; ``` ### Service Integration **AuctionOffer Service Integration** The AuctionOffer service is integrated using: - Service-specific Axios instance with base URL configuration - Dynamic endpoint generation based on business logic - Error handling through response interceptors - Fetcher utility for data retrieval **Available Endpoints:** - `AuctionOfferOffer` data object management - `AuctionOfferBid` data object management **CategoryManagement Service Integration** The CategoryManagement service is integrated using: - Service-specific Axios instance with base URL configuration - Dynamic endpoint generation based on business logic - Error handling through response interceptors - Fetcher utility for data retrieval **Available Endpoints:** - `Category` data object management - `Subcategory` data object management **Messaging Service Integration** The Messaging service is integrated using: - Service-specific Axios instance with base URL configuration - Dynamic endpoint generation based on business logic - Error handling through response interceptors - Fetcher utility for data retrieval **Available Endpoints:** - `MessagingMessage` data object management **NotificationManagement Service Integration** The NotificationManagement service is integrated using: - Service-specific Axios instance with base URL configuration - Dynamic endpoint generation based on business logic - Error handling through response interceptors - Fetcher utility for data retrieval **Available Endpoints:** - `Notification` data object management **SearchIndexing Service Integration** The SearchIndexing service is integrated using: - Service-specific Axios instance with base URL configuration - Dynamic endpoint generation based on business logic - Error handling through response interceptors - Fetcher utility for data retrieval **Available Endpoints:** - `SearchIndex` data object management **AdminModeration Service Integration** The AdminModeration service is integrated using: - Service-specific Axios instance with base URL configuration - Dynamic endpoint generation based on business logic - Error handling through response interceptors - Fetcher utility for data retrieval **Available Endpoints:** - `ModerationAction` data object management **WatchlistCart Service Integration** The WatchlistCart service is integrated using: - Service-specific Axios instance with base URL configuration - Dynamic endpoint generation based on business logic - Error handling through response interceptors - Fetcher utility for data retrieval **Available Endpoints:** - `WatchlistItem` data object management - `CartItem` data object management - `WatchlistList` data object management **ProductListing Service Integration** The ProductListing service is integrated using: - Service-specific Axios instance with base URL configuration - Dynamic endpoint generation based on business logic - Error handling through response interceptors - Fetcher utility for data retrieval **Available Endpoints:** - `ProductListingMedia` data object management - `ProductListingProduct` data object management **OrderManagement Service Integration** The OrderManagement service is integrated using: - Service-specific Axios instance with base URL configuration - Dynamic endpoint generation based on business logic - Error handling through response interceptors - Fetcher utility for data retrieval **Available Endpoints:** - `OrderManagementOrder` data object management - `OrderManagementOrderItem` data object management - `Sys_orderManagementOrderPayment` data object management - `Sys_paymentCustomer` data object management - `Sys_paymentMethod` data object management **Feedback Service Integration** The Feedback service is integrated using: - Service-specific Axios instance with base URL configuration - Dynamic endpoint generation based on business logic - Error handling through response interceptors - Fetcher utility for data retrieval **Available Endpoints:** - `Feedback` data object management **Auth Service Integration** The Auth service is integrated using: - Service-specific Axios instance with base URL configuration - Dynamic endpoint generation based on business logic - Error handling through response interceptors - Fetcher utility for data retrieval **Available Endpoints:** - `User` data object management ## Request/Response Patterns ### Standard Request Format **Request Structure** ```javascript // Simple GET request const response = await fetcher('/endpoint'); // GET request with parameters const response = await fetcher(['/endpoint', { params: { id: 1 } }]); // POST request const response = await auctionOfferAxiosInstance.post('/endpoint', data); ``` ```javascript // Simple GET request const response = await fetcher('/endpoint'); // GET request with parameters const response = await fetcher(['/endpoint', { params: { id: 1 } }]); // POST request const response = await categoryManagementAxiosInstance.post('/endpoint', data); ``` ```javascript // Simple GET request const response = await fetcher('/endpoint'); // GET request with parameters const response = await fetcher(['/endpoint', { params: { id: 1 } }]); // POST request const response = await messagingAxiosInstance.post('/endpoint', data); ``` ```javascript // Simple GET request const response = await fetcher('/endpoint'); // GET request with parameters const response = await fetcher(['/endpoint', { params: { id: 1 } }]); // POST request const response = await notificationManagementAxiosInstance.post('/endpoint', data); ``` ```javascript // Simple GET request const response = await fetcher('/endpoint'); // GET request with parameters const response = await fetcher(['/endpoint', { params: { id: 1 } }]); // POST request const response = await searchIndexingAxiosInstance.post('/endpoint', data); ``` ```javascript // Simple GET request const response = await fetcher('/endpoint'); // GET request with parameters const response = await fetcher(['/endpoint', { params: { id: 1 } }]); // POST request const response = await adminModerationAxiosInstance.post('/endpoint', data); ``` ```javascript // Simple GET request const response = await fetcher('/endpoint'); // GET request with parameters const response = await fetcher(['/endpoint', { params: { id: 1 } }]); // POST request const response = await watchlistCartAxiosInstance.post('/endpoint', data); ``` ```javascript // Simple GET request const response = await fetcher('/endpoint'); // GET request with parameters const response = await fetcher(['/endpoint', { params: { id: 1 } }]); // POST request const response = await productListingAxiosInstance.post('/endpoint', data); ``` ```javascript // Simple GET request const response = await fetcher('/endpoint'); // GET request with parameters const response = await fetcher(['/endpoint', { params: { id: 1 } }]); // POST request const response = await orderManagementAxiosInstance.post('/endpoint', data); ``` ```javascript // Simple GET request const response = await fetcher('/endpoint'); // GET request with parameters const response = await fetcher(['/endpoint', { params: { id: 1 } }]); // POST request const response = await feedbackAxiosInstance.post('/endpoint', data); ``` ```javascript // Simple GET request const response = await fetcher('/endpoint'); // GET request with parameters const response = await fetcher(['/endpoint', { params: { id: 1 } }]); // POST request const response = await authAxiosInstance.post('/endpoint', data); ``` ### Response Handling **Standard Response Format** ```javascript // Success response const response = await fetcher('/endpoint'); // response contains the data directly // Error handling try { const response = await fetcher('/endpoint'); } catch (error) { console.error('API Error:', error); // Error is already processed by the interceptor } ``` ### Pagination Handling **Pagination Implementation** ```javascript // Pagination is handled by the data grid component // The MUI DataGrid handles pagination automatically ``` ## Error Handling Patterns ### Error Classification **Error Types** ```javascript // Basic error handling through Axios interceptors // Errors are processed and simplified before reaching components ``` ### Error Handler **Centralized Error Handling** ```javascript class APIErrorHandler { handleError(error) { if (error.response) { // Server responded with error status return this.handleServerError(error); } else if (error.request) { // Network error return this.handleNetworkError(error); } else { // Other error return this.handleUnknownError(error); } } handleServerError(error) { const { status, data } = error.response; switch (status) { case 400: return new ValidationError( data.message || 'Validation failed', data.errors || [] ); case 401: return new AuthenticationError( data.message || 'Authentication required' ); case 403: return new AuthorizationError( data.message || 'Access denied' ); case 404: return new APIError( data.message || 'Resource not found', 404, 'NOT_FOUND' ); case 429: return new APIError( data.message || 'Rate limit exceeded', 429, 'RATE_LIMIT' ); case 500: return new APIError( data.message || 'Internal server error', 500, 'SERVER_ERROR' ); default: return new APIError( data.message || 'Unknown server error', status, 'UNKNOWN_ERROR' ); } } handleNetworkError(error) { return new NetworkError( 'Network error occurred', error ); } handleUnknownError(error) { return new APIError( error.message || 'Unknown error occurred', 0, 'UNKNOWN_ERROR' ); } } ``` ### Retry Mechanisms **Exponential Backoff Retry** ```javascript class RetryManager { constructor(options = {}) { this.maxRetries = options.maxRetries || 3; this.baseDelay = options.baseDelay || 1000; this.maxDelay = options.maxDelay || 10000; this.retryableStatusCodes = options.retryableStatusCodes || [408, 429, 500, 502, 503, 504]; } async executeWithRetry(operation, context = {}) { let lastError; for (let attempt = 0; attempt <= this.maxRetries; attempt++) { try { return await operation(); } catch (error) { lastError = error; if (attempt === this.maxRetries || !this.shouldRetry(error)) { break; } const delay = this.calculateDelay(attempt); await this.sleep(delay); } } throw lastError; } shouldRetry(error) { return false; } calculateDelay(attempt) { return 0; } sleep(ms) { return Promise.resolve(); } } ``` ## Performance Optimization ### Request Batching **Batch Request Manager** ```javascript class BatchRequestManager { constructor(apiClient) { this.apiClient = apiClient; this.pendingRequests = new Map(); this.batchTimeout = 100; // 100ms } async batchRequest(endpoint, data, options = {}) { const batchKey = this.generateBatchKey(endpoint, options); if (!this.pendingRequests.has(batchKey)) { this.pendingRequests.set(batchKey, []); } const request = { data: data, resolve: null, reject: null, timestamp: Date.now() }; const promise = new Promise((resolve, reject) => { request.resolve = resolve; request.reject = reject; }); this.pendingRequests.get(batchKey).push(request); // Process batch after timeout setTimeout(() => this.processBatch(batchKey), this.batchTimeout); return promise; } async processBatch(batchKey) { const requests = this.pendingRequests.get(batchKey); if (!requests || requests.length === 0) return; this.pendingRequests.delete(batchKey); try { const [serviceName, endpoint] = batchKey.split(':'); const batchData = requests.map(req => req.data); const response = await this.apiClient.post(`/${endpoint}/batch`, { requests: batchData }); requests.forEach((request, index) => { if (response.data.results[index].success) { request.resolve(response.data.results[index].data); } else { request.reject(new Error(response.data.results[index].error)); } }); } catch (error) { requests.forEach(request => { request.reject(error); }); } } } ``` # AUTHENTICATION FLOW ## Ebaycclone Admin Panel This document provides comprehensive information about the authentication system implemented in the Ebaycclone Admin Panel, including login flows, token management, session handling, and security considerations. ## Architectural Design Credit and Contact Information The architectural design of this authentication system is credited to Mindbricks Genesis Engine. We encourage open communication and welcome any questions or discussions related to the architectural aspects of this authentication system. ## Documentation Scope This guide covers the complete authentication flow within the Ebaycclone Admin Panel. It includes login processes, token management, session handling, multi-tenant support, and security best practices. **Intended Audience** This documentation is intended for frontend developers, security engineers, and system administrators who need to understand, implement, or maintain the authentication system within the admin panel. ## Authentication Architecture ### Overview The admin panel implements a comprehensive authentication system that integrates with the project's authentication service. It supports JWT-based authentication, session management, and cross-domain authentication. ### Authentication Components **Core Components** - **Auth Service Integration**: Communication with backend authentication service - **Token Management**: JWT token storage and validation - **Session Management**: User session state and persistence - **Route Protection**: Authentication guards for protected routes - **Cross-Domain Authentication**: Support for cross-domain cookie authentication ## Login Flow ### Standard Login Process **Step 1: Login Form Display** The login form uses React Hook Form with Zod validation for username and password fields. **Step 2: Credential Submission** ```javascript const onSubmit = handleSubmit(async (data) => { try { await signInWithPassword({ username: data.username, password: data.password }); await checkUserSession?.(); router.push("/panel"); } catch (error) { const feedbackMessage = getErrorMessage(error); setErrorMessage(feedbackMessage); } }); ``` **Step 3: Session Establishment** The session is established through the `setSession` utility which stores the JWT token in sessionStorage and sets up cross-tab communication. ### Cross-Domain Authentication The admin panel supports cross-domain authentication through cookie-based token sharing: **Cross-Domain Token Detection** ```javascript export function getCrossDomainAuthToken() { const projectCodename = 'ebaycclone'; const cookieName = `${projectCodename}-access-token`; return getCookie(cookieName); } ``` **Cross-Domain Session Validation** ```javascript export async function validateCrossDomainSession(accessToken) { try { if (!accessToken || !isValidToken(accessToken)) { return null; } const decodedToken = jwtDecode(accessToken); if (!decodedToken?.userId) { return null; } const res = await authAxios.get(`/v1/users/${decodedToken.userId}`, { headers: { 'Authorization': `Bearer ${accessToken}` } }); return res.data?.user || null; } catch (error) { console.error('Error validating cross-domain session:', error); return null; } } ``` ## Token Management ### JWT Token Handling **Token Storage** ```javascript export async function setSession(accessToken) { try { if (accessToken) { sessionStorage.setItem(JWT_STORAGE_KEY, accessToken); // Trigger custom event for cross-tab communication window.dispatchEvent(new CustomEvent('auth-session-changed', { detail: { action: 'login', token: accessToken } })); // Set authorization headers for all service clients auctionOfferAxios.defaults.headers.common.Authorization = `Bearer ${accessToken}`; categoryManagementAxios.defaults.headers.common.Authorization = `Bearer ${accessToken}`; messagingAxios.defaults.headers.common.Authorization = `Bearer ${accessToken}`; notificationManagementAxios.defaults.headers.common.Authorization = `Bearer ${accessToken}`; searchIndexingAxios.defaults.headers.common.Authorization = `Bearer ${accessToken}`; adminModerationAxios.defaults.headers.common.Authorization = `Bearer ${accessToken}`; watchlistCartAxios.defaults.headers.common.Authorization = `Bearer ${accessToken}`; productListingAxios.defaults.headers.common.Authorization = `Bearer ${accessToken}`; orderManagementAxios.defaults.headers.common.Authorization = `Bearer ${accessToken}`; feedbackAxios.defaults.headers.common.Authorization = `Bearer ${accessToken}`; authAxios.defaults.headers.common.Authorization = `Bearer ${accessToken}`; const decodedToken = jwtDecode(accessToken); if (!decodedToken) { throw new Error("Invalid access token!"); } return decodedToken; } else { // Clear session sessionStorage.removeItem(JWT_STORAGE_KEY); window.dispatchEvent(new CustomEvent('auth-session-changed', { detail: { action: 'logout', token: null } })); delete auctionOfferAxios.defaults.headers.common.Authorization; delete categoryManagementAxios.defaults.headers.common.Authorization; delete messagingAxios.defaults.headers.common.Authorization; delete notificationManagementAxios.defaults.headers.common.Authorization; delete searchIndexingAxios.defaults.headers.common.Authorization; delete adminModerationAxios.defaults.headers.common.Authorization; delete watchlistCartAxios.defaults.headers.common.Authorization; delete productListingAxios.defaults.headers.common.Authorization; delete orderManagementAxios.defaults.headers.common.Authorization; delete feedbackAxios.defaults.headers.common.Authorization; delete authAxios.defaults.headers.common.Authorization; return null; } } catch (error) { console.error('Error during set session:', error); throw error; } } ``` **Token Validation** ```javascript export function isValidToken(accessToken) { if (!accessToken) { return false; } try { return jwtDecode(accessToken); } catch (error) { console.error('Error during token validation:', error); return false; } } ``` ### Session Management **AuthProvider Implementation** ```javascript export function AuthProvider({ children }) { const { state, setState } = useSetState({ user: null, loading: true }); const checkUserSession = useCallback(async () => { try { // First, check for existing session in sessionStorage let accessToken = sessionStorage.getItem(JWT_STORAGE_KEY); let user = null; if (accessToken && isValidToken(accessToken)) { // Validate existing session const decodedToken = await setSession(accessToken); const res = await authAxios.get(`${authEndpoints.me.replace(":userId",decodedToken?.userId)}`); user = res.data?.user; } else if (canAccessCrossDomainCookies()) { // Check for cross-domain authentication cookie const crossDomainToken = getCrossDomainAuthToken(); if (crossDomainToken) { user = await validateCrossDomainSession(crossDomainToken); if (user) { await setSession(crossDomainToken); accessToken = crossDomainToken; } } } if (user && accessToken) { setState({ user: { ...user, accessToken }, loading: false }); } else { setState({ user: null, loading: false }); } } catch (error) { console.error('Error checking user session:', error); setState({ user: null, loading: false }); } }, []); // ... rest of implementation } ``` ### Role-Based Access Control **RoleBasedGuard Implementation** ```javascript export function RoleBasedGuard({ sx, children, hasContent, currentRole, acceptRoles }) { if (typeof acceptRoles !== 'undefined' && !acceptRoles.includes(currentRole)) { return hasContent ? ( Permission denied You do not have permission to access this page. ) : null; } return <> {children} ; } ``` ## Logout Flow ### Logout Process **Logout Implementation** ```javascript export const signOut = async () => { try { await authAxios.post(authEndpoints.logout); await setSession(null); } catch (error) { console.error("Error during sign out:", error); throw error; } }; ``` **Session Cleanup** The `setSession(null)` function handles all cleanup: - Removes JWT token from sessionStorage - Triggers cross-tab logout event - Clears authorization headers from all service clients - Returns null to indicate no active session ## Security Considerations ### Token Security **JWT Token Validation** ```javascript export function jwtDecode(token) { try { if (!token) return null; const parts = token.split('.'); if (parts.length < 2) { throw new Error('Invalid token!'); } const base64Url = parts[1]; const base64 = base64Url.replace(/-/g, '+').replace(/_/g, '/'); const decoded = JSON.parse(atob(base64)); return decoded; } catch (error) { console.error('Error decoding token:', error); throw error; } } ``` ### Input Validation **Login Form Validation** The login form uses Zod schema validation: ```javascript export const LoginSchema = zod.object({ username: zod.string().min(1, { message: 'User name is required!' }), password: zod.string().min(1, { message: 'Password is required!' }), }); ``` ## Error Handling ### Authentication Errors **Error Message Handling** ```javascript // Error messages are displayed to users // Basic error handling is implemented ``` The admin panel uses a centralized error message utility (`getErrorMessage`) to handle authentication errors and display user-friendly messages. # DATA OBJECT MANAGEMENT ## Ebaycclone Admin Panel This document provides comprehensive information about how the Ebaycclone Admin Panel manages data objects, including CRUD operations, validation, relationships, and user interface generation. ## Architectural Design Credit and Contact Information The architectural design of this data object management system is credited to Mindbricks Genesis Engine. We encourage open communication and welcome any questions or discussions related to the architectural aspects of this data object management system. ## Documentation Scope This guide covers the complete data object management system within the Ebaycclone Admin Panel. It includes dynamic UI generation, CRUD operations, data validation, relationship management, and user experience patterns. **Intended Audience** This documentation is intended for frontend developers, UI/UX designers, and system administrators who need to understand how data objects are managed, displayed, and manipulated within the admin panel. ## Data Object Architecture ### Overview The admin panel implements a basic data object management system that generates simple CRUD interfaces for data objects defined in the backend services. Each data object is represented by a data grid for listing and basic modal components for create/update/delete operations. ### Data Object Structure **Core Data Object Properties** - **Name**: Unique identifier for the data object - **Display Name**: Human-readable name for UI display - **Component Name**: React component name for rendering - **Properties**: Array of data object properties with types ### Dynamic UI Generation **Component Generation Pattern** ```javascript // Data object component structure AuctionOffer auctionOfferOffer const DataObjectComponentAuctionOfferAuctionOfferOffer = { // List view for displaying multiple records ListView: { component: 'AuctionOfferAuctionOfferOfferAppPage', features: ['data-grid', 'export', 'filtering', 'search'] }, // Modal components for data manipulation CreateModal: { component: 'AuctionOfferAuctionOfferOfferAppPageCreateModal', lazy: true }, UpdateModal: { component: 'AuctionOfferAuctionOfferOfferAppPageUpdateModal', lazy: true }, // Action components DeleteModal: { component: 'AuctionOfferAuctionOfferOfferAppPageDeleteModal', lazy: true } }; // Data object component structure AuctionOffer auctionOfferBid const DataObjectComponentAuctionOfferAuctionOfferBid = { // List view for displaying multiple records ListView: { component: 'AuctionOfferAuctionOfferBidAppPage', features: ['data-grid', 'export', 'filtering', 'search'] }, // Modal components for data manipulation CreateModal: { component: 'AuctionOfferAuctionOfferBidAppPageCreateModal', lazy: true }, UpdateModal: { component: 'AuctionOfferAuctionOfferBidAppPageUpdateModal', lazy: true }, // Action components DeleteModal: { component: 'AuctionOfferAuctionOfferBidAppPageDeleteModal', lazy: true } }; // Data object component structure CategoryManagement category const DataObjectComponentCategoryManagementCategory = { // List view for displaying multiple records ListView: { component: 'CategoryManagementCategoryAppPage', features: ['data-grid', 'export', 'filtering', 'search'] }, // Modal components for data manipulation CreateModal: { component: 'CategoryManagementCategoryAppPageCreateModal', lazy: true }, UpdateModal: { component: 'CategoryManagementCategoryAppPageUpdateModal', lazy: true }, // Action components DeleteModal: { component: 'CategoryManagementCategoryAppPageDeleteModal', lazy: true } }; // Data object component structure CategoryManagement subcategory const DataObjectComponentCategoryManagementSubcategory = { // List view for displaying multiple records ListView: { component: 'CategoryManagementSubcategoryAppPage', features: ['data-grid', 'export', 'filtering', 'search'] }, // Modal components for data manipulation CreateModal: { component: 'CategoryManagementSubcategoryAppPageCreateModal', lazy: true }, UpdateModal: { component: 'CategoryManagementSubcategoryAppPageUpdateModal', lazy: true }, // Action components DeleteModal: { component: 'CategoryManagementSubcategoryAppPageDeleteModal', lazy: true } }; // Data object component structure Messaging messagingMessage const DataObjectComponentMessagingMessagingMessage = { // List view for displaying multiple records ListView: { component: 'MessagingMessagingMessageAppPage', features: ['data-grid', 'export', 'filtering', 'search'] }, // Modal components for data manipulation CreateModal: { component: 'MessagingMessagingMessageAppPageCreateModal', lazy: true }, UpdateModal: { component: 'MessagingMessagingMessageAppPageUpdateModal', lazy: true }, // Action components DeleteModal: { component: 'MessagingMessagingMessageAppPageDeleteModal', lazy: true } }; // Data object component structure NotificationManagement notification const DataObjectComponentNotificationManagementNotification = { // List view for displaying multiple records ListView: { component: 'NotificationManagementNotificationAppPage', features: ['data-grid', 'export', 'filtering', 'search'] }, // Modal components for data manipulation CreateModal: { component: 'NotificationManagementNotificationAppPageCreateModal', lazy: true }, UpdateModal: { component: 'NotificationManagementNotificationAppPageUpdateModal', lazy: true }, // Action components DeleteModal: { component: 'NotificationManagementNotificationAppPageDeleteModal', lazy: true } }; // Data object component structure SearchIndexing searchIndex const DataObjectComponentSearchIndexingSearchIndex = { // List view for displaying multiple records ListView: { component: 'SearchIndexingSearchIndexAppPage', features: ['data-grid', 'export', 'filtering', 'search'] }, // Modal components for data manipulation CreateModal: { component: 'SearchIndexingSearchIndexAppPageCreateModal', lazy: true }, UpdateModal: { component: 'SearchIndexingSearchIndexAppPageUpdateModal', lazy: true }, // Action components DeleteModal: { component: 'SearchIndexingSearchIndexAppPageDeleteModal', lazy: true } }; // Data object component structure AdminModeration moderationAction const DataObjectComponentAdminModerationModerationAction = { // List view for displaying multiple records ListView: { component: 'AdminModerationModerationActionAppPage', features: ['data-grid', 'export', 'filtering', 'search'] }, // Modal components for data manipulation CreateModal: { component: 'AdminModerationModerationActionAppPageCreateModal', lazy: true }, UpdateModal: { component: 'AdminModerationModerationActionAppPageUpdateModal', lazy: true }, // Action components DeleteModal: { component: 'AdminModerationModerationActionAppPageDeleteModal', lazy: true } }; // Data object component structure WatchlistCart watchlistItem const DataObjectComponentWatchlistCartWatchlistItem = { // List view for displaying multiple records ListView: { component: 'WatchlistCartWatchlistItemAppPage', features: ['data-grid', 'export', 'filtering', 'search'] }, // Modal components for data manipulation CreateModal: { component: 'WatchlistCartWatchlistItemAppPageCreateModal', lazy: true }, UpdateModal: { component: 'WatchlistCartWatchlistItemAppPageUpdateModal', lazy: true }, // Action components DeleteModal: { component: 'WatchlistCartWatchlistItemAppPageDeleteModal', lazy: true } }; // Data object component structure WatchlistCart cartItem const DataObjectComponentWatchlistCartCartItem = { // List view for displaying multiple records ListView: { component: 'WatchlistCartCartItemAppPage', features: ['data-grid', 'export', 'filtering', 'search'] }, // Modal components for data manipulation CreateModal: { component: 'WatchlistCartCartItemAppPageCreateModal', lazy: true }, UpdateModal: { component: 'WatchlistCartCartItemAppPageUpdateModal', lazy: true }, // Action components DeleteModal: { component: 'WatchlistCartCartItemAppPageDeleteModal', lazy: true } }; // Data object component structure WatchlistCart watchlistList const DataObjectComponentWatchlistCartWatchlistList = { // List view for displaying multiple records ListView: { component: 'WatchlistCartWatchlistListAppPage', features: ['data-grid', 'export', 'filtering', 'search'] }, // Modal components for data manipulation CreateModal: { component: 'WatchlistCartWatchlistListAppPageCreateModal', lazy: true }, UpdateModal: { component: 'WatchlistCartWatchlistListAppPageUpdateModal', lazy: true }, // Action components DeleteModal: { component: 'WatchlistCartWatchlistListAppPageDeleteModal', lazy: true } }; // Data object component structure ProductListing productListingMedia const DataObjectComponentProductListingProductListingMedia = { // List view for displaying multiple records ListView: { component: 'ProductListingProductListingMediaAppPage', features: ['data-grid', 'export', 'filtering', 'search'] }, // Modal components for data manipulation CreateModal: { component: 'ProductListingProductListingMediaAppPageCreateModal', lazy: true }, UpdateModal: { component: 'ProductListingProductListingMediaAppPageUpdateModal', lazy: true }, // Action components DeleteModal: { component: 'ProductListingProductListingMediaAppPageDeleteModal', lazy: true } }; // Data object component structure ProductListing productListingProduct const DataObjectComponentProductListingProductListingProduct = { // List view for displaying multiple records ListView: { component: 'ProductListingProductListingProductAppPage', features: ['data-grid', 'export', 'filtering', 'search'] }, // Modal components for data manipulation CreateModal: { component: 'ProductListingProductListingProductAppPageCreateModal', lazy: true }, UpdateModal: { component: 'ProductListingProductListingProductAppPageUpdateModal', lazy: true }, // Action components DeleteModal: { component: 'ProductListingProductListingProductAppPageDeleteModal', lazy: true } }; // Data object component structure OrderManagement orderManagementOrder const DataObjectComponentOrderManagementOrderManagementOrder = { // List view for displaying multiple records ListView: { component: 'OrderManagementOrderManagementOrderAppPage', features: ['data-grid', 'export', 'filtering', 'search'] }, // Modal components for data manipulation CreateModal: { component: 'OrderManagementOrderManagementOrderAppPageCreateModal', lazy: true }, UpdateModal: { component: 'OrderManagementOrderManagementOrderAppPageUpdateModal', lazy: true }, // Action components DeleteModal: { component: 'OrderManagementOrderManagementOrderAppPageDeleteModal', lazy: true } }; // Data object component structure OrderManagement orderManagementOrderItem const DataObjectComponentOrderManagementOrderManagementOrderItem = { // List view for displaying multiple records ListView: { component: 'OrderManagementOrderManagementOrderItemAppPage', features: ['data-grid', 'export', 'filtering', 'search'] }, // Modal components for data manipulation CreateModal: { component: 'OrderManagementOrderManagementOrderItemAppPageCreateModal', lazy: true }, UpdateModal: { component: 'OrderManagementOrderManagementOrderItemAppPageUpdateModal', lazy: true }, // Action components DeleteModal: { component: 'OrderManagementOrderManagementOrderItemAppPageDeleteModal', lazy: true } }; // Data object component structure OrderManagement sys_orderManagementOrderPayment const DataObjectComponentOrderManagementSys_orderManagementOrderPayment = { // List view for displaying multiple records ListView: { component: 'OrderManagementSys_orderManagementOrderPaymentAppPage', features: ['data-grid', 'export', 'filtering', 'search'] }, // Modal components for data manipulation CreateModal: { component: 'OrderManagementSys_orderManagementOrderPaymentAppPageCreateModal', lazy: true }, UpdateModal: { component: 'OrderManagementSys_orderManagementOrderPaymentAppPageUpdateModal', lazy: true }, // Action components DeleteModal: { component: 'OrderManagementSys_orderManagementOrderPaymentAppPageDeleteModal', lazy: true } }; // Data object component structure OrderManagement sys_paymentCustomer const DataObjectComponentOrderManagementSys_paymentCustomer = { // List view for displaying multiple records ListView: { component: 'OrderManagementSys_paymentCustomerAppPage', features: ['data-grid', 'export', 'filtering', 'search'] }, // Modal components for data manipulation CreateModal: { component: 'OrderManagementSys_paymentCustomerAppPageCreateModal', lazy: true }, UpdateModal: { component: 'OrderManagementSys_paymentCustomerAppPageUpdateModal', lazy: true }, // Action components DeleteModal: { component: 'OrderManagementSys_paymentCustomerAppPageDeleteModal', lazy: true } }; // Data object component structure OrderManagement sys_paymentMethod const DataObjectComponentOrderManagementSys_paymentMethod = { // List view for displaying multiple records ListView: { component: 'OrderManagementSys_paymentMethodAppPage', features: ['data-grid', 'export', 'filtering', 'search'] }, // Modal components for data manipulation CreateModal: { component: 'OrderManagementSys_paymentMethodAppPageCreateModal', lazy: true }, UpdateModal: { component: 'OrderManagementSys_paymentMethodAppPageUpdateModal', lazy: true }, // Action components DeleteModal: { component: 'OrderManagementSys_paymentMethodAppPageDeleteModal', lazy: true } }; // Data object component structure Feedback feedback const DataObjectComponentFeedbackFeedback = { // List view for displaying multiple records ListView: { component: 'FeedbackFeedbackAppPage', features: ['data-grid', 'export', 'filtering', 'search'] }, // Modal components for data manipulation CreateModal: { component: 'FeedbackFeedbackAppPageCreateModal', lazy: true }, UpdateModal: { component: 'FeedbackFeedbackAppPageUpdateModal', lazy: true }, // Action components DeleteModal: { component: 'FeedbackFeedbackAppPageDeleteModal', lazy: true } }; // Data object component structure Auth user const DataObjectComponentAuthUser = { // List view for displaying multiple records ListView: { component: 'AuthUserAppPage', features: ['data-grid', 'export', 'filtering', 'search'] }, // Modal components for data manipulation CreateModal: { component: 'AuthUserAppPageCreateModal', lazy: true }, UpdateModal: { component: 'AuthUserAppPageUpdateModal', lazy: true }, // Action components DeleteModal: { component: 'AuthUserAppPageDeleteModal', lazy: true } }; ``` ## Service Data Objects ### AuctionOffer Service Data Objects **Service Overview** - **Service Name**: `auctionOffer` - **Service Display Name**: `AuctionOffer` - **Total Data Objects**: 2 **Data Objects** #### AuctionOfferOffer Data Object **Basic Information** - **Object Name**: `auctionOfferOffer` - **Display Name**: `AuctionOfferOffer` - **Component Name**: `AuctionOfferAuctionOfferOfferAppPage` - **Description**: Represents an offer (best offer/counter-offer) made on a fixed-price product. Tracks buyer, seller, amounts, currency, state transitions, counter-offers, and expiry. **Object Properties** | Property Name | Type | Required | Default | Definition | |---------------|------|----------|---------|------------| | **buyerId** | ID | | N/A | *Buyer making the offer.* | | **currency** | String | | N/A | *ISO currency (e.g., USD, EUR) for the offer.* | | **productId** | ID | | N/A | *Product the offer applies to (must be fixed-price, acceptOffers true).* | | **counterOfferId** | ID | | N/A | *References another offer (counter-offer chain).* | | **counterMessage** | String | | N/A | *Message accompanying seller's counter-offer (optional).* | | **counterAmount** | Double | | N/A | *Counter-offer amount (when offer is COUNTERED).* | | **offerAmount** | Double | | N/A | *Primary offer amount from buyer.* | | **message** | String | | N/A | *Message/special notes from buyer (optional).* | | **sellerId** | ID | | N/A | *Seller of the product (recipient of offer; auto-fetched from product).* | | **status** | Enum | | N/A | *Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED).* | | **expiresAt** | Date | | N/A | *When this offer expires (optional).* | | **respondedAt** | Date | | N/A | *When the seller (or buyer, for counter-offer) responded/updated the offer status.* | **Enum Properties** ##### status Enum Property *Property Definition*: Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). *Enum Options* | Name | Value | Index | |------|-------|-------| | **PENDING** | `"PENDING"` | 0 | | **ACCEPTED** | `"ACCEPTED"` | 1 | | **DECLINED** | `"DECLINED"` | 2 | | **COUNTERED** | `"COUNTERED"` | 3 | | **EXPIRED** | `"EXPIRED"` | 4 | | **CANCELLED** | `"CANCELLED"` | 5 | **Generated UI Components** - **List Component**: `AuctionOfferAuctionOfferOfferAppPageList` - Displays paginated data with filtering and sorting - **Create Modal**: `AuctionOfferAuctionOfferOfferAppPageCreateModal` - Form for creating new records - **Update Modal**: `AuctionOfferAuctionOfferOfferAppPageUpdateModal` - Form for editing existing records - **Delete Modal**: `AuctionOfferAuctionOfferOfferAppPageDeleteModal` - Confirmation dialog for deletion **API Endpoints** - **List**: `GET /auctionOfferOffer/list` - Retrieve paginated list of records - **Get**: `GET /auctionOfferOffer/get` - Retrieve single record by ID - **Create**: `POST /auctionOfferOffer/create` - Create new record - **Update**: `PUT /auctionOfferOffer/update` - Update existing record - **Delete**: `DELETE /auctionOfferOffer/delete` - Delete record by ID **Route Configuration** - **List Route**: `/dashboard/auctionOffer/auctionOfferOffer` - **Create Route**: `/dashboard/auctionOffer/auctionOfferOffer/create` - **Update Route**: `/dashboard/auctionOffer/auctionOfferOffer/update/:id` - **Delete Route**: `/dashboard/auctionOffer/auctionOfferOffer/delete/:id` #### AuctionOfferBid Data Object **Basic Information** - **Object Name**: `auctionOfferBid` - **Display Name**: `AuctionOfferBid` - **Component Name**: `AuctionOfferAuctionOfferBidAppPage` - **Description**: Represents an individual bid placed on an auction-type product. Linked to product and user, tracks bid amount, currency, status (ACTIVE, WON, LOST, CANCELLED), and time placed. **Object Properties** | Property Name | Type | Required | Default | Definition | |---------------|------|----------|---------|------------| | **userId** | ID | | N/A | *User placing the bid.* | | **bidAmount** | Double | | N/A | *Bid amount placed by the user.* | | **placedAt** | Date | | N/A | *When the bid was placed.* | | **currency** | String | | N/A | *ISO currency for the bid (e.g., USD, EUR).* | | **status** | Enum | | N/A | *Bid status: ACTIVE, WON, LOST, CANCELLED.* | | **productId** | ID | | N/A | *Product being bid on (must be AUCTION type).* | **Enum Properties** ##### status Enum Property *Property Definition*: Bid status: ACTIVE, WON, LOST, CANCELLED. *Enum Options* | Name | Value | Index | |------|-------|-------| | **ACTIVE** | `"ACTIVE"` | 0 | | **WON** | `"WON"` | 1 | | **LOST** | `"LOST"` | 2 | | **CANCELLED** | `"CANCELLED"` | 3 | **Generated UI Components** - **List Component**: `AuctionOfferAuctionOfferBidAppPageList` - Displays paginated data with filtering and sorting - **Create Modal**: `AuctionOfferAuctionOfferBidAppPageCreateModal` - Form for creating new records - **Update Modal**: `AuctionOfferAuctionOfferBidAppPageUpdateModal` - Form for editing existing records - **Delete Modal**: `AuctionOfferAuctionOfferBidAppPageDeleteModal` - Confirmation dialog for deletion **API Endpoints** - **List**: `GET /auctionOfferBid/list` - Retrieve paginated list of records - **Get**: `GET /auctionOfferBid/get` - Retrieve single record by ID - **Create**: `POST /auctionOfferBid/create` - Create new record - **Update**: `PUT /auctionOfferBid/update` - Update existing record - **Delete**: `DELETE /auctionOfferBid/delete` - Delete record by ID **Route Configuration** - **List Route**: `/dashboard/auctionOffer/auctionOfferBid` - **Create Route**: `/dashboard/auctionOffer/auctionOfferBid/create` - **Update Route**: `/dashboard/auctionOffer/auctionOfferBid/update/:id` - **Delete Route**: `/dashboard/auctionOffer/auctionOfferBid/delete/:id` ### CategoryManagement Service Data Objects **Service Overview** - **Service Name**: `categoryManagement` - **Service Display Name**: `CategoryManagement` - **Total Data Objects**: 2 **Data Objects** #### Category Data Object **Basic Information** - **Object Name**: `category` - **Display Name**: `Category` - **Component Name**: `CategoryManagementCategoryAppPage` - **Description**: Represents a product category in the marketplace (e.g., Electronics, Clothing, Toys), used for browsing, filtering, and discovery. Admins manage categories. **Object Properties** | Property Name | Type | Required | Default | Definition | |---------------|------|----------|---------|------------| | **imageUrl** | String | | N/A | *URL for category image/avatar (optional, used for homepage visuals).* | | **subtitle** | String | | N/A | *Optional short description for UI/tooltips.* | | **title** | String | | N/A | *Display name of the category.* | **Generated UI Components** - **List Component**: `CategoryManagementCategoryAppPageList` - Displays paginated data with filtering and sorting - **Create Modal**: `CategoryManagementCategoryAppPageCreateModal` - Form for creating new records - **Update Modal**: `CategoryManagementCategoryAppPageUpdateModal` - Form for editing existing records - **Delete Modal**: `CategoryManagementCategoryAppPageDeleteModal` - Confirmation dialog for deletion **API Endpoints** - **List**: `GET /category/list` - Retrieve paginated list of records - **Get**: `GET /category/get` - Retrieve single record by ID - **Create**: `POST /category/create` - Create new record - **Update**: `PUT /category/update` - Update existing record - **Delete**: `DELETE /category/delete` - Delete record by ID **Route Configuration** - **List Route**: `/dashboard/categoryManagement/category` - **Create Route**: `/dashboard/categoryManagement/category/create` - **Update Route**: `/dashboard/categoryManagement/category/update/:id` - **Delete Route**: `/dashboard/categoryManagement/category/delete/:id` #### Subcategory Data Object **Basic Information** - **Object Name**: `subcategory` - **Display Name**: `Subcategory` - **Component Name**: `CategoryManagementSubcategoryAppPage` - **Description**: Represents a subcategory within a parent category (e.g., 'Smartphones' under 'Electronics'). Used for more granular product discovery and navigation. 'group' categorizes special display logic. **Object Properties** | Property Name | Type | Required | Default | Definition | |---------------|------|----------|---------|------------| | **categoryId** | ID | | N/A | *Reference to the parent category (category.id).* | | **name** | String | | N/A | *Display name of the subcategory.* | | **group** | Enum | | N/A | *Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE.* | **Enum Properties** ##### group Enum Property *Property Definition*: Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. *Enum Options* | Name | Value | Index | |------|-------|-------| | **MOST_POPULAR** | `"MOST_POPULAR"` | 0 | | **MORE** | `"MORE"` | 1 | **Generated UI Components** - **List Component**: `CategoryManagementSubcategoryAppPageList` - Displays paginated data with filtering and sorting - **Create Modal**: `CategoryManagementSubcategoryAppPageCreateModal` - Form for creating new records - **Update Modal**: `CategoryManagementSubcategoryAppPageUpdateModal` - Form for editing existing records - **Delete Modal**: `CategoryManagementSubcategoryAppPageDeleteModal` - Confirmation dialog for deletion **API Endpoints** - **List**: `GET /subcategory/list` - Retrieve paginated list of records - **Get**: `GET /subcategory/get` - Retrieve single record by ID - **Create**: `POST /subcategory/create` - Create new record - **Update**: `PUT /subcategory/update` - Update existing record - **Delete**: `DELETE /subcategory/delete` - Delete record by ID **Route Configuration** - **List Route**: `/dashboard/categoryManagement/subcategory` - **Create Route**: `/dashboard/categoryManagement/subcategory/create` - **Update Route**: `/dashboard/categoryManagement/subcategory/update/:id` - **Delete Route**: `/dashboard/categoryManagement/subcategory/delete/:id` ### Messaging Service Data Objects **Service Overview** - **Service Name**: `messaging` - **Service Display Name**: `Messaging` - **Total Data Objects**: 1 **Data Objects** #### MessagingMessage Data Object **Basic Information** - **Object Name**: `messagingMessage` - **Display Name**: `MessagingMessage` - **Component Name**: `MessagingMessagingMessageAppPage` - **Description**: A direct, text-only in-app message between two users (buyer/seller); stores sender, recipient, content, read status, and timestamp. **Object Properties** | Property Name | Type | Required | Default | Definition | |---------------|------|----------|---------|------------| | **fromUserId** | ID | | N/A | *Sender (user) of this message.* | | **toUserId** | ID | | N/A | *Recipient (user) of this message.* | | **content** | String | | N/A | *Text content of the message. No files or attachments for launch.* | | **isRead** | Boolean | | N/A | *If true, recipient has marked this message as read.* | | **sentAt** | Date | | N/A | *Time the message was sent. If not set, will be createdAt. Used for ordering.* | **Generated UI Components** - **List Component**: `MessagingMessagingMessageAppPageList` - Displays paginated data with filtering and sorting - **Create Modal**: `MessagingMessagingMessageAppPageCreateModal` - Form for creating new records - **Update Modal**: `MessagingMessagingMessageAppPageUpdateModal` - Form for editing existing records - **Delete Modal**: `MessagingMessagingMessageAppPageDeleteModal` - Confirmation dialog for deletion **API Endpoints** - **List**: `GET /messagingMessage/list` - Retrieve paginated list of records - **Get**: `GET /messagingMessage/get` - Retrieve single record by ID - **Create**: `POST /messagingMessage/create` - Create new record - **Update**: `PUT /messagingMessage/update` - Update existing record - **Delete**: `DELETE /messagingMessage/delete` - Delete record by ID **Route Configuration** - **List Route**: `/dashboard/messaging/messagingMessage` - **Create Route**: `/dashboard/messaging/messagingMessage/create` - **Update Route**: `/dashboard/messaging/messagingMessage/update/:id` - **Delete Route**: `/dashboard/messaging/messagingMessage/delete/:id` ### NotificationManagement Service Data Objects **Service Overview** - **Service Name**: `notificationManagement` - **Service Display Name**: `NotificationManagement` - **Total Data Objects**: 1 **Data Objects** #### Notification Data Object **Basic Information** - **Object Name**: `notification` - **Display Name**: `Notification` - **Component Name**: `NotificationManagementNotificationAppPage` - **Description**: Stores and manages in-app and email notifications tied to user-facing events like bids, offers, orders, messaging, shipment, and feedback. Includes event type (notificationType) for filter/search, arbitrary event payload, and delivery channel. Soft-delete enforced. In-app notifications always sorted by createdAt DESC on retrieval. **Object Properties** | Property Name | Type | Required | Default | Definition | |---------------|------|----------|---------|------------| | **notificationType** | Enum | | N/A | *Type of event triggering notification (e.g., BID_UPDATED, ORDER_SHIPPED, MESSAGE_RECEIVED, etc.). Used for display/icon and query filter.* | | **userId** | ID | | N/A | *User receiving the notification (recipient).* | | **channel** | Enum | | N/A | *Channel by which notification is delivered: IN_APP or EMAIL.* | | **payload** | Object | | N/A | *Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType.* | | **isRead** | Boolean | | N/A | *Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel)* | **Enum Properties** ##### notificationType Enum Property *Property Definition*: Type of event triggering notification (e.g., BID_UPDATED, ORDER_SHIPPED, MESSAGE_RECEIVED, etc.). Used for display/icon and query filter. *Enum Options* | Name | Value | Index | |------|-------|-------| | **BID_UPDATED** | `"BID_UPDATED"` | 0 | | **BID_OUTBID** | `"BID_OUTBID"` | 1 | | **BID_WON** | `"BID_WON"` | 2 | | **OFFER_PLACED** | `"OFFER_PLACED"` | 3 | | **OFFER_ACCEPTED** | `"OFFER_ACCEPTED"` | 4 | | **OFFER_DECLINED** | `"OFFER_DECLINED"` | 5 | | **OFFER_COUNTERED** | `"OFFER_COUNTERED"` | 6 | | **ORDER_PLACED** | `"ORDER_PLACED"` | 7 | | **ORDER_PAID** | `"ORDER_PAID"` | 8 | | **ORDER_SHIPPED** | `"ORDER_SHIPPED"` | 9 | | **ORDER_DELIVERED** | `"ORDER_DELIVERED"` | 10 | | **ORDER_CANCELLED** | `"ORDER_CANCELLED"` | 11 | | **FEEDBACK_RECEIVED** | `"FEEDBACK_RECEIVED"` | 12 | | **FEEDBACK_REQUESTED** | `"FEEDBACK_REQUESTED"` | 13 | | **MESSAGE_RECEIVED** | `"MESSAGE_RECEIVED"` | 14 | | **MESSAGE_SENT** | `"MESSAGE_SENT"` | 15 | | **SYSTEM_ALERT** | `"SYSTEM_ALERT"` | 16 | ##### channel Enum Property *Property Definition*: Channel by which notification is delivered: IN_APP or EMAIL. *Enum Options* | Name | Value | Index | |------|-------|-------| | **IN_APP** | `"IN_APP"` | 0 | | **EMAIL** | `"EMAIL"` | 1 | **Generated UI Components** - **List Component**: `NotificationManagementNotificationAppPageList` - Displays paginated data with filtering and sorting - **Create Modal**: `NotificationManagementNotificationAppPageCreateModal` - Form for creating new records - **Update Modal**: `NotificationManagementNotificationAppPageUpdateModal` - Form for editing existing records - **Delete Modal**: `NotificationManagementNotificationAppPageDeleteModal` - Confirmation dialog for deletion **API Endpoints** - **List**: `GET /notification/list` - Retrieve paginated list of records - **Get**: `GET /notification/get` - Retrieve single record by ID - **Create**: `POST /notification/create` - Create new record - **Update**: `PUT /notification/update` - Update existing record - **Delete**: `DELETE /notification/delete` - Delete record by ID **Route Configuration** - **List Route**: `/dashboard/notificationManagement/notification` - **Create Route**: `/dashboard/notificationManagement/notification/create` - **Update Route**: `/dashboard/notificationManagement/notification/update/:id` - **Delete Route**: `/dashboard/notificationManagement/notification/delete/:id` ### SearchIndexing Service Data Objects **Service Overview** - **Service Name**: `searchIndexing` - **Service Display Name**: `SearchIndexing` - **Total Data Objects**: 1 **Data Objects** #### SearchIndex Data Object **Basic Information** - **Object Name**: `searchIndex` - **Display Name**: `SearchIndex` - **Component Name**: `SearchIndexingSearchIndexAppPage` - **Description**: Materialized/denormalized search index record for a marketplace entity (product, seller, category, subcategory). Used exclusively for high-speed querying in BFF global/public search. **Object Properties** | Property Name | Type | Required | Default | Definition | |---------------|------|----------|---------|------------| | **documentType** | Enum | | N/A | *Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY* | | **document** | Object | | N/A | *Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType.* | | **referenceId** | ID | | N/A | *ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers.* | | **indexedAt** | Date | | N/A | *Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing.* | **Enum Properties** ##### documentType Enum Property *Property Definition*: Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY *Enum Options* | Name | Value | Index | |------|-------|-------| | **PRODUCT** | `"PRODUCT"` | 0 | | **SELLER** | `"SELLER"` | 1 | | **CATEGORY** | `"CATEGORY"` | 2 | | **SUBCATEGORY** | `"SUBCATEGORY"` | 3 | **Generated UI Components** - **List Component**: `SearchIndexingSearchIndexAppPageList` - Displays paginated data with filtering and sorting - **Create Modal**: `SearchIndexingSearchIndexAppPageCreateModal` - Form for creating new records - **Update Modal**: `SearchIndexingSearchIndexAppPageUpdateModal` - Form for editing existing records - **Delete Modal**: `SearchIndexingSearchIndexAppPageDeleteModal` - Confirmation dialog for deletion **API Endpoints** - **List**: `GET /searchIndex/list` - Retrieve paginated list of records - **Get**: `GET /searchIndex/get` - Retrieve single record by ID - **Create**: `POST /searchIndex/create` - Create new record - **Update**: `PUT /searchIndex/update` - Update existing record - **Delete**: `DELETE /searchIndex/delete` - Delete record by ID **Route Configuration** - **List Route**: `/dashboard/searchIndexing/searchIndex` - **Create Route**: `/dashboard/searchIndexing/searchIndex/create` - **Update Route**: `/dashboard/searchIndexing/searchIndex/update/:id` - **Delete Route**: `/dashboard/searchIndexing/searchIndex/delete/:id` ### AdminModeration Service Data Objects **Service Overview** - **Service Name**: `adminModeration` - **Service Display Name**: `AdminModeration` - **Total Data Objects**: 1 **Data Objects** #### ModerationAction Data Object **Basic Information** - **Object Name**: `moderationAction` - **Display Name**: `ModerationAction` - **Component Name**: `AdminModerationModerationActionAppPage` - **Description**: Audit record for all admin moderation/override actions affecting core business entities. Links to admin, timestamp, entity type/ID, action performed, and reason. **Object Properties** | Property Name | Type | Required | Default | Definition | |---------------|------|----------|---------|------------| | **adminId** | ID | | N/A | *ID of admin performing moderation action.* | | **entityId** | ID | | N/A | *ID of target entity affected by moderation (user/product/etc).* | | **actionTimestamp** | Date | | N/A | *Timestamp moderation action was performed/logged.* | | **entityType** | Enum | | N/A | *Type of entity affected (USER, PRODUCT, FEEDBACK, MEDIA, CATEGORY, NOTIFICATION, ORDER, SEARCHINDEX).* | | **reason** | String | | N/A | *Explanation or justification for the moderation action performed.* | | **actionType** | Enum | | N/A | *Type of moderation action (e.g., SOFT_DELETE, RESTORE, UPDATE_ROLE, MANUAL_CORRECTION, MEDIA_FLAG, INDEX_REBUILD, PAYMENT_FIX, FEEDBACK_OVERRIDE, ADMIN_NOTE).* | **Enum Properties** ##### entityType Enum Property *Property Definition*: Type of entity affected (USER, PRODUCT, FEEDBACK, MEDIA, CATEGORY, NOTIFICATION, ORDER, SEARCHINDEX). *Enum Options* | Name | Value | Index | |------|-------|-------| | **USER** | `"USER"` | 0 | | **PRODUCT** | `"PRODUCT"` | 1 | | **FEEDBACK** | `"FEEDBACK"` | 2 | | **MEDIA** | `"MEDIA"` | 3 | | **CATEGORY** | `"CATEGORY"` | 4 | | **NOTIFICATION** | `"NOTIFICATION"` | 5 | | **ORDER** | `"ORDER"` | 6 | | **SEARCHINDEX** | `"SEARCHINDEX"` | 7 | ##### actionType Enum Property *Property Definition*: Type of moderation action (e.g., SOFT_DELETE, RESTORE, UPDATE_ROLE, MANUAL_CORRECTION, MEDIA_FLAG, INDEX_REBUILD, PAYMENT_FIX, FEEDBACK_OVERRIDE, ADMIN_NOTE). *Enum Options* | Name | Value | Index | |------|-------|-------| | **SOFT_DELETE** | `"SOFT_DELETE"` | 0 | | **RESTORE** | `"RESTORE"` | 1 | | **UPDATE_ROLE** | `"UPDATE_ROLE"` | 2 | | **MANUAL_CORRECTION** | `"MANUAL_CORRECTION"` | 3 | | **MEDIA_FLAG** | `"MEDIA_FLAG"` | 4 | | **INDEX_REBUILD** | `"INDEX_REBUILD"` | 5 | | **PAYMENT_FIX** | `"PAYMENT_FIX"` | 6 | | **FEEDBACK_OVERRIDE** | `"FEEDBACK_OVERRIDE"` | 7 | | **ADMIN_NOTE** | `"ADMIN_NOTE"` | 8 | **Generated UI Components** - **List Component**: `AdminModerationModerationActionAppPageList` - Displays paginated data with filtering and sorting - **Create Modal**: `AdminModerationModerationActionAppPageCreateModal` - Form for creating new records - **Update Modal**: `AdminModerationModerationActionAppPageUpdateModal` - Form for editing existing records - **Delete Modal**: `AdminModerationModerationActionAppPageDeleteModal` - Confirmation dialog for deletion **API Endpoints** - **List**: `GET /moderationAction/list` - Retrieve paginated list of records - **Get**: `GET /moderationAction/get` - Retrieve single record by ID - **Create**: `POST /moderationAction/create` - Create new record - **Update**: `PUT /moderationAction/update` - Update existing record - **Delete**: `DELETE /moderationAction/delete` - Delete record by ID **Route Configuration** - **List Route**: `/dashboard/adminModeration/moderationAction` - **Create Route**: `/dashboard/adminModeration/moderationAction/create` - **Update Route**: `/dashboard/adminModeration/moderationAction/update/:id` - **Delete Route**: `/dashboard/adminModeration/moderationAction/delete/:id` ### WatchlistCart Service Data Objects **Service Overview** - **Service Name**: `watchlistCart` - **Service Display Name**: `WatchlistCart` - **Total Data Objects**: 3 **Data Objects** #### WatchlistItem Data Object **Basic Information** - **Object Name**: `watchlistItem` - **Display Name**: `WatchlistItem` - **Component Name**: `WatchlistCartWatchlistItemAppPage` - **Description**: Item in a user’s watchlist, optionally in a named folder; references product and user. **Object Properties** | Property Name | Type | Required | Default | Definition | |---------------|------|----------|---------|------------| | **userId** | ID | | N/A | *Owner of the watchlist item.* | | **addedAt** | Date | | N/A | *Timestamp watchlist item created.* | | **productId** | ID | | N/A | *Referenced product in the watchlist.* | | **listId** | ID | | N/A | *Owning watchlistList; null if in default watchlist.* | **Generated UI Components** - **List Component**: `WatchlistCartWatchlistItemAppPageList` - Displays paginated data with filtering and sorting - **Create Modal**: `WatchlistCartWatchlistItemAppPageCreateModal` - Form for creating new records - **Update Modal**: `WatchlistCartWatchlistItemAppPageUpdateModal` - Form for editing existing records - **Delete Modal**: `WatchlistCartWatchlistItemAppPageDeleteModal` - Confirmation dialog for deletion **API Endpoints** - **List**: `GET /watchlistItem/list` - Retrieve paginated list of records - **Get**: `GET /watchlistItem/get` - Retrieve single record by ID - **Create**: `POST /watchlistItem/create` - Create new record - **Update**: `PUT /watchlistItem/update` - Update existing record - **Delete**: `DELETE /watchlistItem/delete` - Delete record by ID **Route Configuration** - **List Route**: `/dashboard/watchlistCart/watchlistItem` - **Create Route**: `/dashboard/watchlistCart/watchlistItem/create` - **Update Route**: `/dashboard/watchlistCart/watchlistItem/update/:id` - **Delete Route**: `/dashboard/watchlistCart/watchlistItem/delete/:id` #### CartItem Data Object **Basic Information** - **Object Name**: `cartItem` - **Display Name**: `CartItem` - **Component Name**: `WatchlistCartCartItemAppPage` - **Description**: Single product pending checkout in a user’s cart. Only fixed-price products permitted; quantity supported for multi-unit purchases (if allowed). **Object Properties** | Property Name | Type | Required | Default | Definition | |---------------|------|----------|---------|------------| | **addedAt** | Date | | N/A | *Timestamp added to cart.* | | **userId** | ID | | N/A | *Cart owner.* | | **quantity** | Integer | | N/A | *How many units (if product allows).* | | **productId** | ID | | N/A | *Product being checked out.* | **Generated UI Components** - **List Component**: `WatchlistCartCartItemAppPageList` - Displays paginated data with filtering and sorting - **Create Modal**: `WatchlistCartCartItemAppPageCreateModal` - Form for creating new records - **Update Modal**: `WatchlistCartCartItemAppPageUpdateModal` - Form for editing existing records - **Delete Modal**: `WatchlistCartCartItemAppPageDeleteModal` - Confirmation dialog for deletion **API Endpoints** - **List**: `GET /cartItem/list` - Retrieve paginated list of records - **Get**: `GET /cartItem/get` - Retrieve single record by ID - **Create**: `POST /cartItem/create` - Create new record - **Update**: `PUT /cartItem/update` - Update existing record - **Delete**: `DELETE /cartItem/delete` - Delete record by ID **Route Configuration** - **List Route**: `/dashboard/watchlistCart/cartItem` - **Create Route**: `/dashboard/watchlistCart/cartItem/create` - **Update Route**: `/dashboard/watchlistCart/cartItem/update/:id` - **Delete Route**: `/dashboard/watchlistCart/cartItem/delete/:id` #### WatchlistList Data Object **Basic Information** - **Object Name**: `watchlistList` - **Display Name**: `WatchlistList` - **Component Name**: `WatchlistCartWatchlistListAppPage` - **Description**: A named folder/list in a user’s watchlist. Default list exists for all users. Custom lists may be created and deleted. **Object Properties** | Property Name | Type | Required | Default | Definition | |---------------|------|----------|---------|------------| | **name** | String | | N/A | *Custom folder or list name. 'Default' is reserved (non-deletable for each user).* | | **itemCount** | Integer | | N/A | *Number of (non-deleted) items in the list/folder.* | | **userId** | ID | | N/A | *Owner of the watchlist list/folder.* | **Generated UI Components** - **List Component**: `WatchlistCartWatchlistListAppPageList` - Displays paginated data with filtering and sorting - **Create Modal**: `WatchlistCartWatchlistListAppPageCreateModal` - Form for creating new records - **Update Modal**: `WatchlistCartWatchlistListAppPageUpdateModal` - Form for editing existing records - **Delete Modal**: `WatchlistCartWatchlistListAppPageDeleteModal` - Confirmation dialog for deletion **API Endpoints** - **List**: `GET /watchlistList/list` - Retrieve paginated list of records - **Get**: `GET /watchlistList/get` - Retrieve single record by ID - **Create**: `POST /watchlistList/create` - Create new record - **Update**: `PUT /watchlistList/update` - Update existing record - **Delete**: `DELETE /watchlistList/delete` - Delete record by ID **Route Configuration** - **List Route**: `/dashboard/watchlistCart/watchlistList` - **Create Route**: `/dashboard/watchlistCart/watchlistList/create` - **Update Route**: `/dashboard/watchlistCart/watchlistList/update/:id` - **Delete Route**: `/dashboard/watchlistCart/watchlistList/delete/:id` ### ProductListing Service Data Objects **Service Overview** - **Service Name**: `productListing` - **Service Display Name**: `ProductListing` - **Total Data Objects**: 2 **Data Objects** #### ProductListingMedia Data Object **Basic Information** - **Object Name**: `productListingMedia` - **Display Name**: `ProductListingMedia` - **Component Name**: `ProductListingProductListingMediaAppPage` - **Description**: Stores and manages images/media associated with products, including secure URL, MIME type, and size validation. Each asset can be used by multiple products. **Object Properties** | Property Name | Type | Required | Default | Definition | |---------------|------|----------|---------|------------| | **mimeType** | String | | N/A | *MIME type of the uploaded media (e.g., image/jpeg)* | | **productId** | ID | | N/A | *ID of product associated with this media asset* | | **url** | String | | N/A | *Secure, validated URL for the media asset (S3 or equivalent)* | | **size** | Integer | | N/A | *Media size in bytes (for validation and quota)* | **Generated UI Components** - **List Component**: `ProductListingProductListingMediaAppPageList` - Displays paginated data with filtering and sorting - **Create Modal**: `ProductListingProductListingMediaAppPageCreateModal` - Form for creating new records - **Update Modal**: `ProductListingProductListingMediaAppPageUpdateModal` - Form for editing existing records - **Delete Modal**: `ProductListingProductListingMediaAppPageDeleteModal` - Confirmation dialog for deletion **API Endpoints** - **List**: `GET /productListingMedia/list` - Retrieve paginated list of records - **Get**: `GET /productListingMedia/get` - Retrieve single record by ID - **Create**: `POST /productListingMedia/create` - Create new record - **Update**: `PUT /productListingMedia/update` - Update existing record - **Delete**: `DELETE /productListingMedia/delete` - Delete record by ID **Route Configuration** - **List Route**: `/dashboard/productListing/productListingMedia` - **Create Route**: `/dashboard/productListing/productListingMedia/create` - **Update Route**: `/dashboard/productListing/productListingMedia/update/:id` - **Delete Route**: `/dashboard/productListing/productListingMedia/delete/:id` #### ProductListingProduct Data Object **Basic Information** - **Object Name**: `productListingProduct` - **Display Name**: `ProductListingProduct` - **Component Name**: `ProductListingProductListingProductAppPage` - **Description**: Represents a single product listing (fixed-price or auction) in the marketplace, with seller, category, type, price information, shipping details, media references, and dynamic auction fields. **Object Properties** | Property Name | Type | Required | Default | Definition | |---------------|------|----------|---------|------------| | **currency** | String | | N/A | *ISO currency code (e.g. USD, EUR)* | | **description** | Text | | N/A | *Product detailed description* | | **condition** | Enum | | N/A | *Condition of product: BRAND_NEW, NEW, or USED* | | **startBid** | Double | | N/A | *The opening bid value (for auction type products)* | | **endPrice** | Double | | N/A | *Optional immediate sale/upper end price for auction (if AUCTION type)* | | **price** | Double | | N/A | *Product price (required if fixed price type)* | | **title** | String | | N/A | *Product title* | | **startPrice** | Double | | N/A | *Minimum starting price for auction (required if AUCTION type)* | | **type** | Enum | | N/A | *Product listing type, either FIXED or AUCTION (immutable after creation)* | | **endBid** | Double | | N/A | *The upper (max) bid value for auction products (if any)* | | **estimatedDelivery** | Date | | N/A | *Estimated delivery date for this product* | | **shippingCurrency** | String | | N/A | *Currency code for shipping cost* | | **sellerId** | ID | | N/A | *Reference to user who listed the product* | | **mediaAssetIds** | ID | | N/A | *References to associated product/media assets* | | **shippingMethod** | Enum | | N/A | *Shipping option for product: STANDARD, EXPRESS, or FREE* | | **shipping** | Double | | N/A | *Shipping cost for this product* | | **startBidDate** | Date | | N/A | *Date/time when auction bidding begins* | | **subcategoryId** | ID | | N/A | *Reference to subcategory* | | **categoryId** | ID | | N/A | *Reference to parent category* | | **endBidDate** | Date | | N/A | *Date/time when auction bidding ends* | | **currentBid** | Double | | N/A | *Current highest bid for auction-type product (updated atomically on bid placement)* | | **highestBidderId** | ID | | N/A | *User ID of current highest bidder (auction-only, updated by auction microservice)* | **Enum Properties** ##### condition Enum Property *Property Definition*: Condition of product: BRAND_NEW, NEW, or USED *Enum Options* | Name | Value | Index | |------|-------|-------| | **BRAND_NEW** | `"BRAND_NEW"` | 0 | | **NEW** | `"NEW"` | 1 | | **USED** | `"USED"` | 2 | ##### type Enum Property *Property Definition*: Product listing type, either FIXED or AUCTION (immutable after creation) *Enum Options* | Name | Value | Index | |------|-------|-------| | **FIXED** | `"FIXED"` | 0 | | **AUCTION** | `"AUCTION"` | 1 | ##### shippingMethod Enum Property *Property Definition*: Shipping option for product: STANDARD, EXPRESS, or FREE *Enum Options* | Name | Value | Index | |------|-------|-------| | **STANDARD** | `"STANDARD"` | 0 | | **EXPRESS** | `"EXPRESS"` | 1 | | **FREE** | `"FREE"` | 2 | **Generated UI Components** - **List Component**: `ProductListingProductListingProductAppPageList` - Displays paginated data with filtering and sorting - **Create Modal**: `ProductListingProductListingProductAppPageCreateModal` - Form for creating new records - **Update Modal**: `ProductListingProductListingProductAppPageUpdateModal` - Form for editing existing records - **Delete Modal**: `ProductListingProductListingProductAppPageDeleteModal` - Confirmation dialog for deletion **API Endpoints** - **List**: `GET /productListingProduct/list` - Retrieve paginated list of records - **Get**: `GET /productListingProduct/get` - Retrieve single record by ID - **Create**: `POST /productListingProduct/create` - Create new record - **Update**: `PUT /productListingProduct/update` - Update existing record - **Delete**: `DELETE /productListingProduct/delete` - Delete record by ID **Route Configuration** - **List Route**: `/dashboard/productListing/productListingProduct` - **Create Route**: `/dashboard/productListing/productListingProduct/create` - **Update Route**: `/dashboard/productListing/productListingProduct/update/:id` - **Delete Route**: `/dashboard/productListing/productListingProduct/delete/:id` ### OrderManagement Service Data Objects **Service Overview** - **Service Name**: `orderManagement` - **Service Display Name**: `OrderManagement` - **Total Data Objects**: 5 **Data Objects** #### OrderManagementOrder Data Object **Basic Information** - **Object Name**: `orderManagementOrder` - **Display Name**: `OrderManagementOrder` - **Component Name**: `OrderManagementOrderManagementOrderAppPage` - **Description**: Marketplace order record. Stores buyer, shipping, status, items, Stripe payment data, and manual shipment/delivery events. Only accessible to admins or the buyer/seller of order items. **Object Properties** | Property Name | Type | Required | Default | Definition | |---------------|------|----------|---------|------------| | **orderNumber** | String | | N/A | *Unique, human-friendly order number (displayed to users); enforced unique.* | | **items** | ID | | N/A | *Array of orderManagementOrderItem ids representing items in this order.* | | **buyerId** | ID | | N/A | *User ID of the buyer placing the order.* | | **status** | Enum | | N/A | *Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED* | | **paymentMethodId** | String | | N/A | *Stripe paymentMethodId used for payment. Not stored if cash or other payment (future).* | | **stripeCustomerId** | String | | N/A | *Stripe customerId of buyer; enables saved/paymentMethodId flows.* | | **paymentIntentId** | String | | N/A | *Stripe paymentIntentId; enables webhook correlation and status sync.* | | **shippingAddress** | Object | | N/A | *Shipping address for the order (copy of buyer address at purchase time).* | | **summary** | Object | | N/A | *Object with total, subtotal, currency, shipping, discount breakdown as snapshot of order at time of purchase.* | | **trackingNumber** | String | | N/A | *Optional tracking number entered by seller when marking as shipped.* | | **estimatedDelivery** | Date | | N/A | *Estimated delivery date for order; copied from fastest estimated item or seller input.* | | **cancelledAt** | Date | | N/A | *Timestamp when cancelled by buyer, seller, or admin before shipment.* | | **paidAt** | Date | | N/A | *Timestamp when payment confirmed via Stripe or manual admin update.* | | **deliveredAt** | Date | | N/A | *Timestamp when buyer confirms delivery.* | | **shippedAt** | Date | | N/A | *Timestamp when seller marks as shipped.* | | **carrier** | String | | N/A | *Optional carrier name entered by seller when marking as shipped.* | | **_paymentConfirmation** | Enum | | N/A | *An automatic property that is used to check the confirmed status of the payment set by webhooks.* | **Enum Properties** ##### status Enum Property *Property Definition*: Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED *Enum Options* | Name | Value | Index | |------|-------|-------| | **PENDING_PAYMENT** | `"PENDING_PAYMENT"` | 0 | | **PAID** | `"PAID"` | 1 | | **PROCESSING** | `"PROCESSING"` | 2 | | **SHIPPED** | `"SHIPPED"` | 3 | | **DELIVERED** | `"DELIVERED"` | 4 | | **CANCELLED** | `"CANCELLED"` | 5 | | **REFUNDED** | `"REFUNDED"` | 6 | ##### _paymentConfirmation Enum Property *Property Definition*: An automatic property that is used to check the confirmed status of the payment set by webhooks. *Enum Options* | Name | Value | Index | |------|-------|-------| | **pending** | `"pending"` | 0 | | **processing** | `"processing"` | 1 | | **paid** | `"paid"` | 2 | | **canceled** | `"canceled"` | 3 | **Generated UI Components** - **List Component**: `OrderManagementOrderManagementOrderAppPageList` - Displays paginated data with filtering and sorting - **Create Modal**: `OrderManagementOrderManagementOrderAppPageCreateModal` - Form for creating new records - **Update Modal**: `OrderManagementOrderManagementOrderAppPageUpdateModal` - Form for editing existing records - **Delete Modal**: `OrderManagementOrderManagementOrderAppPageDeleteModal` - Confirmation dialog for deletion **API Endpoints** - **List**: `GET /orderManagementOrder/list` - Retrieve paginated list of records - **Get**: `GET /orderManagementOrder/get` - Retrieve single record by ID - **Create**: `POST /orderManagementOrder/create` - Create new record - **Update**: `PUT /orderManagementOrder/update` - Update existing record - **Delete**: `DELETE /orderManagementOrder/delete` - Delete record by ID **Route Configuration** - **List Route**: `/dashboard/orderManagement/orderManagementOrder` - **Create Route**: `/dashboard/orderManagement/orderManagementOrder/create` - **Update Route**: `/dashboard/orderManagement/orderManagementOrder/update/:id` - **Delete Route**: `/dashboard/orderManagement/orderManagementOrder/delete/:id` #### OrderManagementOrderItem Data Object **Basic Information** - **Object Name**: `orderManagementOrderItem` - **Display Name**: `OrderManagementOrderItem` - **Component Name**: `OrderManagementOrderManagementOrderItemAppPage` - **Description**: Order line item representing purchase of a single product from a specific seller as part of an order. Enables feedback, delivery, and per-seller analytics. Immutable after order creation. **Object Properties** | Property Name | Type | Required | Default | Definition | |---------------|------|----------|---------|------------| | **shipping** | Double | | N/A | *Shipping cost for this product (may be 0 for free shipping).* | | **orderId** | ID | | N/A | *Parent order this item belongs to; enables join and lifecycle tracking.* | | **quantity** | Integer | | N/A | *Number of units purchased for this product.* | | **productId** | ID | | N/A | *ID of product purchased in this line item.* | | **price** | Double | | N/A | *Unit price for this product at purchase time.* | | **sellerId** | ID | | N/A | *UserId of seller (owner of product at purchase time).* | | **title** | String | | N/A | *Product title at purchase time (copied for convenience/audit).* | | **currency** | String | | N/A | *Currency code for price/shipping (ISO 4217).* | **Generated UI Components** - **List Component**: `OrderManagementOrderManagementOrderItemAppPageList` - Displays paginated data with filtering and sorting - **Create Modal**: `OrderManagementOrderManagementOrderItemAppPageCreateModal` - Form for creating new records - **Update Modal**: `OrderManagementOrderManagementOrderItemAppPageUpdateModal` - Form for editing existing records - **Delete Modal**: `OrderManagementOrderManagementOrderItemAppPageDeleteModal` - Confirmation dialog for deletion **API Endpoints** - **List**: `GET /orderManagementOrderItem/list` - Retrieve paginated list of records - **Get**: `GET /orderManagementOrderItem/get` - Retrieve single record by ID - **Create**: `POST /orderManagementOrderItem/create` - Create new record - **Update**: `PUT /orderManagementOrderItem/update` - Update existing record - **Delete**: `DELETE /orderManagementOrderItem/delete` - Delete record by ID **Route Configuration** - **List Route**: `/dashboard/orderManagement/orderManagementOrderItem` - **Create Route**: `/dashboard/orderManagement/orderManagementOrderItem/create` - **Update Route**: `/dashboard/orderManagement/orderManagementOrderItem/update/:id` - **Delete Route**: `/dashboard/orderManagement/orderManagementOrderItem/delete/:id` #### Sys_orderManagementOrderPayment Data Object **Basic Information** - **Object Name**: `sys_orderManagementOrderPayment` - **Display Name**: `Sys_orderManagementOrderPayment` - **Component Name**: `OrderManagementSys_orderManagementOrderPaymentAppPage` - **Description**: A payment storage object to store the payment life cyle of orders based on orderManagementOrder object. It is autocreated based on the source object's checkout config **Object Properties** | Property Name | Type | Required | Default | Definition | |---------------|------|----------|---------|------------| | **ownerId** | ID | | N/A | * An ID value to represent owner user who created the order* | | **orderId** | ID | | N/A | *an ID value to represent the orderId which is the ID parameter of the source orderManagementOrder object* | | **paymentId** | String | | N/A | *A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type* | | **paymentStatus** | String | | N/A | *A string value to represent the payment status which belongs to the lifecyle of a Stripe payment.* | | **statusLiteral** | String | | N/A | *A string value to represent the logical payment status which belongs to the application lifecycle itself.* | | **redirectUrl** | String | | N/A | *A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client.* | **Generated UI Components** - **List Component**: `OrderManagementSys_orderManagementOrderPaymentAppPageList` - Displays paginated data with filtering and sorting - **Create Modal**: `OrderManagementSys_orderManagementOrderPaymentAppPageCreateModal` - Form for creating new records - **Update Modal**: `OrderManagementSys_orderManagementOrderPaymentAppPageUpdateModal` - Form for editing existing records - **Delete Modal**: `OrderManagementSys_orderManagementOrderPaymentAppPageDeleteModal` - Confirmation dialog for deletion **API Endpoints** - **List**: `GET /sys_orderManagementOrderPayment/list` - Retrieve paginated list of records - **Get**: `GET /sys_orderManagementOrderPayment/get` - Retrieve single record by ID - **Create**: `POST /sys_orderManagementOrderPayment/create` - Create new record - **Update**: `PUT /sys_orderManagementOrderPayment/update` - Update existing record - **Delete**: `DELETE /sys_orderManagementOrderPayment/delete` - Delete record by ID **Route Configuration** - **List Route**: `/dashboard/orderManagement/sys_orderManagementOrderPayment` - **Create Route**: `/dashboard/orderManagement/sys_orderManagementOrderPayment/create` - **Update Route**: `/dashboard/orderManagement/sys_orderManagementOrderPayment/update/:id` - **Delete Route**: `/dashboard/orderManagement/sys_orderManagementOrderPayment/delete/:id` #### Sys_paymentCustomer Data Object **Basic Information** - **Object Name**: `sys_paymentCustomer` - **Display Name**: `Sys_paymentCustomer` - **Component Name**: `OrderManagementSys_paymentCustomerAppPage` - **Description**: A payment storage object to store the customer values of the payment platform **Object Properties** | Property Name | Type | Required | Default | Definition | |---------------|------|----------|---------|------------| | **userId** | ID | | N/A | * An ID value to represent the user who is created as a stripe customer* | | **customerId** | String | | N/A | *A string value to represent the customer id which is generated on the Stripe gateway. This id is used to represent the customer in the Stripe gateway* | | **platform** | String | | N/A | *A String value to represent payment platform which is used to make the payment. It is stripe as default. It will be used to distinguesh the payment gateways in the future.* | **Generated UI Components** - **List Component**: `OrderManagementSys_paymentCustomerAppPageList` - Displays paginated data with filtering and sorting - **Create Modal**: `OrderManagementSys_paymentCustomerAppPageCreateModal` - Form for creating new records - **Update Modal**: `OrderManagementSys_paymentCustomerAppPageUpdateModal` - Form for editing existing records - **Delete Modal**: `OrderManagementSys_paymentCustomerAppPageDeleteModal` - Confirmation dialog for deletion **API Endpoints** - **List**: `GET /sys_paymentCustomer/list` - Retrieve paginated list of records - **Get**: `GET /sys_paymentCustomer/get` - Retrieve single record by ID - **Create**: `POST /sys_paymentCustomer/create` - Create new record - **Update**: `PUT /sys_paymentCustomer/update` - Update existing record - **Delete**: `DELETE /sys_paymentCustomer/delete` - Delete record by ID **Route Configuration** - **List Route**: `/dashboard/orderManagement/sys_paymentCustomer` - **Create Route**: `/dashboard/orderManagement/sys_paymentCustomer/create` - **Update Route**: `/dashboard/orderManagement/sys_paymentCustomer/update/:id` - **Delete Route**: `/dashboard/orderManagement/sys_paymentCustomer/delete/:id` #### Sys_paymentMethod Data Object **Basic Information** - **Object Name**: `sys_paymentMethod` - **Display Name**: `Sys_paymentMethod` - **Component Name**: `OrderManagementSys_paymentMethodAppPage` - **Description**: A payment storage object to store the payment methods of the platform customers **Object Properties** | Property Name | Type | Required | Default | Definition | |---------------|------|----------|---------|------------| | **paymentMethodId** | String | | N/A | *A string value to represent the id of the payment method on the payment platform.* | | **userId** | ID | | N/A | * An ID value to represent the user who owns the payment method* | | **customerId** | String | | N/A | *A string value to represent the customer id which is generated on the payment gateway.* | | **cardHolderName** | String | | N/A | *A string value to represent the name of the card holder. It can be different than the registered customer.* | | **cardHolderZip** | String | | N/A | *A string value to represent the zip code of the card holder. It is used for address verification in specific countries.* | | **platform** | String | | N/A | *A String value to represent payment platform which teh paymentMethod belongs. It is stripe as default. It will be used to distinguesh the payment gateways in the future.* | | **cardInfo** | Object | | N/A | *A Json value to store the card details of the payment method.* | **Generated UI Components** - **List Component**: `OrderManagementSys_paymentMethodAppPageList` - Displays paginated data with filtering and sorting - **Create Modal**: `OrderManagementSys_paymentMethodAppPageCreateModal` - Form for creating new records - **Update Modal**: `OrderManagementSys_paymentMethodAppPageUpdateModal` - Form for editing existing records - **Delete Modal**: `OrderManagementSys_paymentMethodAppPageDeleteModal` - Confirmation dialog for deletion **API Endpoints** - **List**: `GET /sys_paymentMethod/list` - Retrieve paginated list of records - **Get**: `GET /sys_paymentMethod/get` - Retrieve single record by ID - **Create**: `POST /sys_paymentMethod/create` - Create new record - **Update**: `PUT /sys_paymentMethod/update` - Update existing record - **Delete**: `DELETE /sys_paymentMethod/delete` - Delete record by ID **Route Configuration** - **List Route**: `/dashboard/orderManagement/sys_paymentMethod` - **Create Route**: `/dashboard/orderManagement/sys_paymentMethod/create` - **Update Route**: `/dashboard/orderManagement/sys_paymentMethod/update/:id` - **Delete Route**: `/dashboard/orderManagement/sys_paymentMethod/delete/:id` ### Feedback Service Data Objects **Service Overview** - **Service Name**: `feedback` - **Service Display Name**: `Feedback` - **Total Data Objects**: 1 **Data Objects** #### Feedback Data Object **Basic Information** - **Object Name**: `feedback` - **Display Name**: `Feedback` - **Component Name**: `FeedbackFeedbackAppPage` - **Description**: One feedback per (buyer, orderItem). Stores rating (1-5), comment, ties to seller for analytics. Created only after delivery confirmed on order item. **Object Properties** | Property Name | Type | Required | Default | Definition | |---------------|------|----------|---------|------------| | **rating** | Integer | | N/A | *Rating (1-5 stars) submitted by buyer. Required.* | | **orderId** | ID | | N/A | *Order containing this purchased item. Used for aggregation and validation.* | | **buyerId** | ID | | N/A | *User/buyer leaving feedback. Authenticated user, must match order item buyer.* | | **orderItemId** | ID | | N/A | *Purchased item (line item) in order. Feedback is per (buyer, orderItem).* | | **sellerId** | ID | | N/A | *Seller of product for analytics/aggregation. Not author; used for querying feedback about sellers.* | | **comment** | String | | N/A | *Optional textual feedback comment, max ~500 chars.* | | **productId** | ID | | N/A | *The product listing being reviewed (snapshot at order time).* | **Generated UI Components** - **List Component**: `FeedbackFeedbackAppPageList` - Displays paginated data with filtering and sorting - **Create Modal**: `FeedbackFeedbackAppPageCreateModal` - Form for creating new records - **Update Modal**: `FeedbackFeedbackAppPageUpdateModal` - Form for editing existing records - **Delete Modal**: `FeedbackFeedbackAppPageDeleteModal` - Confirmation dialog for deletion **API Endpoints** - **List**: `GET /feedback/list` - Retrieve paginated list of records - **Get**: `GET /feedback/get` - Retrieve single record by ID - **Create**: `POST /feedback/create` - Create new record - **Update**: `PUT /feedback/update` - Update existing record - **Delete**: `DELETE /feedback/delete` - Delete record by ID **Route Configuration** - **List Route**: `/dashboard/feedback/feedback` - **Create Route**: `/dashboard/feedback/feedback/create` - **Update Route**: `/dashboard/feedback/feedback/update/:id` - **Delete Route**: `/dashboard/feedback/feedback/delete/:id` ### Auth Service Data Objects **Service Overview** - **Service Name**: `auth` - **Service Display Name**: `Auth` - **Total Data Objects**: 1 **Data Objects** #### User Data Object **Basic Information** - **Object Name**: `user` - **Display Name**: `User` - **Component Name**: `AuthUserAppPage` - **Description**: A data object that stores the user information and handles login settings. **Object Properties** | Property Name | Type | Required | Default | Definition | |---------------|------|----------|---------|------------| | **email** | String | | N/A | * A string value to represent the user's email.* | | **password** | String | | N/A | * A string value to represent the user's password. It will be stored as hashed.* | | **fullname** | String | | N/A | *A string value to represent the fullname of the user* | | **avatar** | String | | N/A | *The avatar url of the user. A random avatar will be generated if not provided* | | **roleId** | String | | N/A | *A string value to represent the roleId of the user.* | | **emailVerified** | Boolean | | N/A | *A boolean value to represent the email verification status of the user.* | | **phone** | String | | N/A | *user's phone number* | | **address** | Object | | N/A | *user's adress* | **Generated UI Components** - **List Component**: `AuthUserAppPageList` - Displays paginated data with filtering and sorting - **Create Modal**: `AuthUserAppPageCreateModal` - Form for creating new records - **Update Modal**: `AuthUserAppPageUpdateModal` - Form for editing existing records - **Delete Modal**: `AuthUserAppPageDeleteModal` - Confirmation dialog for deletion **API Endpoints** - **List**: `GET /user/list` - Retrieve paginated list of records - **Get**: `GET /user/get` - Retrieve single record by ID - **Create**: `POST /user/create` - Create new record - **Update**: `PUT /user/update` - Update existing record - **Delete**: `DELETE /user/delete` - Delete record by ID **Route Configuration** - **List Route**: `/dashboard/auth/user` - **Create Route**: `/dashboard/auth/user/create` - **Update Route**: `/dashboard/auth/user/update/:id` - **Delete Route**: `/dashboard/auth/user/delete/:id` ## CRUD Operations ### Create Operations **Create Form Implementation** ```javascript // Create forms are generated as lazy-loaded modal components // Basic form fields are rendered based on data object properties ``` **Create API Integration** ```javascript // Create operations are handled through service-specific API calls // Basic validation is performed client-side ``` ### Read Operations **List View Implementation** ```javascript // List views are implemented using MUI DataGrid // Data is fetched through service-specific API calls ``` ### Update Operations **Update Form Implementation** ```javascript // Update forms are generated as lazy-loaded modal components // Basic form fields are pre-populated with existing data ``` **Update API Integration** ```javascript // Update operations are handled through service-specific API calls // Basic validation is performed client-side ``` ### Delete Operations **Delete Implementation** ```javascript // Delete operations are handled through service-specific API calls // Confirmation dialogs are implemented as modal components ``` ## Data Validation ### Client-Side Validation **Validation Implementation** ```javascript // Basic validation is performed on form fields // Required fields are validated before submission ``` ### Server-Side Validation Integration **API Error Handling** ```javascript // Server validation errors are displayed to users // Error messages are shown in the UI components ``` ## Data Relationships ### Relationship Management **Relationship Implementation** ```javascript // Basic data relationships are handled through form fields // Related data is displayed in select components ``` ## User Experience Patterns ### Loading States **Loading Implementation** ```javascript // Loading states are handled by MUI DataGrid // Skeleton loading is provided by the data grid component ``` ### Error States **Error Handling UI** ```javascript // Error states are displayed through UI components // Error messages are shown to users ``` ### Empty States **Empty State UI** ```javascript // Empty states are handled by MUI DataGrid // Empty content is displayed when no data is available ``` ## Performance Optimization ### Data Pagination **Pagination Implementation** ```javascript // Pagination is handled by MUI DataGrid // Data is loaded in pages as needed ``` # MCP Chat Integration for Ebaycclone Admin Panel This module provides AI-powered chat functionality for the Ebaycclone admin panel using the Model Context Protocol (MCP) to communicate with Anthropic Claude. ## 🚀 Features - **Intercom-style floating chat widget** - Bottom-right corner, collapsible interface - **Real-time AI conversations** - Powered by Anthropic Claude via MCP protocol - **Full Ebaycclone API access** - AI can perform CRUD operations on all services - **JWT authentication** - Seamlessly integrated with existing auth system - **Responsive design** - Works on desktop and mobile devices - **Material-UI styling** - Consistent with admin panel design ## 📁 File Structure ``` src/ ├── lib/ │ └── mcp-client.js # MCP protocol client ├── components/ │ └── mcp-chat/ │ ├── mcp-chat-widget.jsx # Main floating chat widget │ ├── mcp-message-list.jsx # Message display components │ ├── mcp-input.jsx # Message input component │ ├── mcp-client-context.jsx # React context provider │ └── index.js # Component exports ├── hooks/ │ └── use-mcp-chat.js # Custom hook for chat logic └── layouts/ └── dashboard/ └── layout.jsx.ejs # Dashboard layout with chat integration ``` ## 🔧 Configuration ### Environment Variables Add to your `.env` files: ```bash # MCP Server URL - Points to the nodeJs2 service MCP endpoint VITE_MCP_SERVER_URL=http://localhost:3000/mcp # For staging: # VITE_MCP_SERVER_URL=https://your-nodejs2-service.staging.mindbricks.com/mcp # For production: # VITE_MCP_SERVER_URL=https://your-nodejs2-service.prod.mindbricks.com/mcp ``` ### Backend Configuration Ensure your backend (nodeJs2 service) has: ```bash # Anthropic API key (handled on backend) ANTHROPIC_API_KEY=your_anthropic_api_key_here ``` ## 🏗️ Architecture ### Data Flow ``` User Input → MCPInput → MCPClient → MCP Server (/mcp) → Anthropic Claude ↓ MCPMessageList ← MCPClientContext ← MCP Response ← MCP Tools → Ebaycclone APIs ``` ### Component Hierarchy ``` DashboardLayout ├── MCPChatProvider (Context) │ ├── LayoutSection (Main content) │ └── MCPChatWidget (Floating chat) │ ├── MCPMessageList │ └── MCPInput ``` ## 🔌 Integration The chat widget is automatically integrated into the dashboard layout and appears on all dashboard pages. It: 1. **Initializes automatically** when a user is authenticated 2. **Connects to MCP server** using JWT token authentication 3. **Provides AI assistance** for all Ebaycclone service operations 4. **Maintains conversation state** during the session ## 🎨 UI Components ### MCPChatWidget - Floating chat button (bottom-right corner) - Collapsible chat panel - Responsive design for mobile/desktop ### MCPMessageList - Displays conversation history - User and assistant message bubbles - Loading indicators and timestamps ### MCPInput - Text input with send button - Enter to send, Shift+Enter for new line - Loading states and error handling ## 🔐 Security - **JWT Authentication** - All MCP requests include user's access token - **Backend API Key Handling** - Anthropic API key never exposed to frontend - **Session Management** - MCP sessions are properly managed and cleaned up - **Error Handling** - Graceful fallbacks for connection issues ## 🚀 Usage The chat widget is automatically available to all authenticated users. Simply: 1. **Click the chat button** in the bottom-right corner 2. **Type your message** and press Enter 3. **Get AI assistance** for Ebaycclone service operations 4. **Use natural language** to manage your data ## 🛠️ Development ### Adding New Features 1. **Extend MCPClient** - Add new methods for additional MCP operations 2. **Update Context** - Modify MCPChatProvider for new state management 3. **Enhance UI** - Add new components following Material-UI patterns 4. **Test Integration** - Verify MCP server communication ### Debugging - Check browser console for MCP connection logs - Verify JWT token is properly passed to MCP server - Ensure backend MCP server is running and accessible - Check Anthropic API key configuration on backend ## 📝 Service Integration The MCP chat has access to all Ebaycclone services: ### AuctionOffer Service - **Service Name**: `auctionOffer` - **Service URL**: `VITE_AUCTIONOFFER_SERVICE_URL` - **Data Objects**: 2 objects - AuctionOfferOffer, AuctionOfferBid ### CategoryManagement Service - **Service Name**: `categoryManagement` - **Service URL**: `VITE_CATEGORYMANAGEMENT_SERVICE_URL` - **Data Objects**: 2 objects - Category, Subcategory ### Messaging Service - **Service Name**: `messaging` - **Service URL**: `VITE_MESSAGING_SERVICE_URL` - **Data Objects**: 1 objects - MessagingMessage ### NotificationManagement Service - **Service Name**: `notificationManagement` - **Service URL**: `VITE_NOTIFICATIONMANAGEMENT_SERVICE_URL` - **Data Objects**: 1 objects - Notification ### SearchIndexing Service - **Service Name**: `searchIndexing` - **Service URL**: `VITE_SEARCHINDEXING_SERVICE_URL` - **Data Objects**: 1 objects - SearchIndex ### AdminModeration Service - **Service Name**: `adminModeration` - **Service URL**: `VITE_ADMINMODERATION_SERVICE_URL` - **Data Objects**: 1 objects - ModerationAction ### WatchlistCart Service - **Service Name**: `watchlistCart` - **Service URL**: `VITE_WATCHLISTCART_SERVICE_URL` - **Data Objects**: 3 objects - WatchlistItem, CartItem, WatchlistList ### ProductListing Service - **Service Name**: `productListing` - **Service URL**: `VITE_PRODUCTLISTING_SERVICE_URL` - **Data Objects**: 2 objects - ProductListingMedia, ProductListingProduct ### OrderManagement Service - **Service Name**: `orderManagement` - **Service URL**: `VITE_ORDERMANAGEMENT_SERVICE_URL` - **Data Objects**: 5 objects - OrderManagementOrder, OrderManagementOrderItem, Sys_orderManagementOrderPayment, Sys_paymentCustomer, Sys_paymentMethod ### Feedback Service - **Service Name**: `feedback` - **Service URL**: `VITE_FEEDBACK_SERVICE_URL` - **Data Objects**: 1 objects - Feedback ### Auth Service - **Service Name**: `auth` - **Service URL**: `VITE_AUTH_SERVICE_URL` - **Data Objects**: 1 objects - User ## 🔄 Root Generation Integration The MCP chat components are fully integrated into the Genesis project's generation system: ``` Root Generation Flow: ├── src/root-gen.js (Main generator) │ ├── ComponentsRootGenerator │ │ └── MCPChatRootGenerator │ ├── LibRootGenerator │ │ └── mcp-client.js.ejs │ └── HooksRootGenerator │ └── use-mcp-chat.js.ejs ``` ### Generation Process When the Ebaycclone project is built, the root generation system will: 1. **Generate MCP Client** - Creates `src/lib/mcp-client.js` from template 2. **Generate MCP Components** - Creates all chat components in `src/components/mcp-chat/` 3. **Generate Custom Hook** - Creates `src/hooks/use-mcp-chat.js` from template 4. **Integrate with Dashboard** - Chat widget automatically appears in dashboard layout ## 📋 EJS Template Structure All components follow the same EJS template pattern as other Ebaycclone components: ``` src/components/mcp-chat/ ├── root-gen.js # Root generator ├── mcp-chat-widget.jsx.ejs # Main widget template ├── mcp-message-list.jsx.ejs # Message components template ├── mcp-input.jsx.ejs # Input component template ├── mcp-client-context.jsx.ejs # Context provider template └── index.js.ejs # Exports template ``` ## 🎯 Benefits of EJS Integration - **✅ Consistent with project patterns** - Follows exact same structure as other components - **✅ Automatic generation** - Components generated during build process - **✅ Template-based** - Easy to modify and customize - **✅ Root generation system** - Integrated with Ebaycclone build pipeline - **✅ No manual file management** - All files generated automatically ## 🚀 Ready for Build The MCP chat integration is now fully integrated into the Ebaycclone project's build system. When you run the project generation, all MCP chat components will be automatically created from the EJS templates, following the same patterns as all other components in the project. **The implementation is now complete and follows the exact same patterns as the rest of the Ebaycclone project!** 🚀 --- ## 📞 Support For questions or support regarding the MCP chat integration, please contact: - **Architect**: Mindbricks Genesis Engine - **Email**: support@mindbricks.com - **Organization**: Mindbricks Inc. - **Website**: https://mindbricks.com # PANEL SERVICE GUIDE ## Ebaycclone Admin Panel The Ebaycclone Admin Panel is a dynamic, auto-generated frontend application that provides a comprehensive management interface for all backend services and data objects within the Ebaycclone ecosystem. Built using React and Vite, it automatically adapts to the project's service architecture, providing intuitive CRUD operations and real-time data management capabilities. ## Architectural Design Credit and Contact Information The architectural design of this admin panel is credited to Mindbricks Genesis Engine. We encourage open communication and welcome any questions or discussions related to the architectural aspects of this admin panel. ## Documentation Scope Welcome to the official documentation for the Ebaycclone Admin Panel. This document is designed to provide a comprehensive guide to understanding, configuring, and extending the admin panel's functionality. **Intended Audience** This documentation is intended for frontend developers, system administrators, and integrators who need to understand how the admin panel works, how to configure it for different environments, and how to extend its functionality for custom requirements. **Overview** Within these pages, you will find detailed information on the panel's architecture, service integration patterns, authentication flows, data object management, and API integration methods. The admin panel serves as a unified interface for managing all aspects of the Ebaycclone microservices ecosystem. ## Panel Architecture Overview The Ebaycclone Admin Panel is built on a dynamic, pattern-driven architecture that automatically generates user interfaces based on the project's service definitions and data object schemas. ### Core Components **Dynamic Service Integration** - Automatically discovers and integrates with all backend services defined in the project - Generates service-specific navigation and routing structures - Provides unified authentication and session management across all services **Data Object Management** - Dynamically creates CRUD interfaces for each data object within services - Supports complex data relationships and validation rules - Provides real-time data synchronization with backend services **Modular UI Framework** - Built on React with Material-UI components for consistent user experience - Responsive design that works across desktop and mobile devices - Extensible component system for custom functionality ### Service Integration Architecture The admin panel integrates with backend services through a standardized API communication layer: **AuctionOffer Service Integration** - **Service Name**: `auctionOffer` - **Service URL**: `VITE_AUCTIONOFFER_SERVICE_URL` - **Data Objects**: 2 objects - AuctionOfferOffer, AuctionOfferBid **CategoryManagement Service Integration** - **Service Name**: `categoryManagement` - **Service URL**: `VITE_CATEGORYMANAGEMENT_SERVICE_URL` - **Data Objects**: 2 objects - Category, Subcategory **Messaging Service Integration** - **Service Name**: `messaging` - **Service URL**: `VITE_MESSAGING_SERVICE_URL` - **Data Objects**: 1 objects - MessagingMessage **NotificationManagement Service Integration** - **Service Name**: `notificationManagement` - **Service URL**: `VITE_NOTIFICATIONMANAGEMENT_SERVICE_URL` - **Data Objects**: 1 objects - Notification **SearchIndexing Service Integration** - **Service Name**: `searchIndexing` - **Service URL**: `VITE_SEARCHINDEXING_SERVICE_URL` - **Data Objects**: 1 objects - SearchIndex **AdminModeration Service Integration** - **Service Name**: `adminModeration` - **Service URL**: `VITE_ADMINMODERATION_SERVICE_URL` - **Data Objects**: 1 objects - ModerationAction **WatchlistCart Service Integration** - **Service Name**: `watchlistCart` - **Service URL**: `VITE_WATCHLISTCART_SERVICE_URL` - **Data Objects**: 3 objects - WatchlistItem, CartItem, WatchlistList **ProductListing Service Integration** - **Service Name**: `productListing` - **Service URL**: `VITE_PRODUCTLISTING_SERVICE_URL` - **Data Objects**: 2 objects - ProductListingMedia, ProductListingProduct **OrderManagement Service Integration** - **Service Name**: `orderManagement` - **Service URL**: `VITE_ORDERMANAGEMENT_SERVICE_URL` - **Data Objects**: 5 objects - OrderManagementOrder, OrderManagementOrderItem, Sys_orderManagementOrderPayment, Sys_paymentCustomer, Sys_paymentMethod **Feedback Service Integration** - **Service Name**: `feedback` - **Service URL**: `VITE_FEEDBACK_SERVICE_URL` - **Data Objects**: 1 objects - Feedback **Auth Service Integration** - **Service Name**: `auth` - **Service URL**: `VITE_AUTH_SERVICE_URL` - **Data Objects**: 1 objects - User ## Authentication and Authorization The admin panel implements a comprehensive authentication system that integrates with the project's authentication service. ### Authentication Flow **Login Process** 1. User accesses the admin panel login page 2. Credentials are validated against the authentication service 3. JWT access token is received and stored securely 4. Session is established with proper permissions and tenant context **Token Management** - Access tokens are stored in secure HTTP-only cookies - Automatic token refresh mechanisms prevent session expiration - Multi-tenant support with tenant-specific token handling ### Authorization Levels **Role-Based Access Control** - Admin users have full access to all services and data objects - Service-specific permissions control access to individual modules - Data object permissions control CRUD operations on specific entities **Permission Structure** - `adminPanel.access` - Basic admin panel access - `ebaycclone.auctionOffer.manage` - Service management permissions - `ebaycclone.auctionOffer.auctionOfferOffer.crud` - Data object CRUD permissions - `ebaycclone.auctionOffer.auctionOfferBid.crud` - Data object CRUD permissions - `ebaycclone.categoryManagement.manage` - Service management permissions - `ebaycclone.categoryManagement.category.crud` - Data object CRUD permissions - `ebaycclone.categoryManagement.subcategory.crud` - Data object CRUD permissions - `ebaycclone.messaging.manage` - Service management permissions - `ebaycclone.messaging.messagingMessage.crud` - Data object CRUD permissions - `ebaycclone.notificationManagement.manage` - Service management permissions - `ebaycclone.notificationManagement.notification.crud` - Data object CRUD permissions - `ebaycclone.searchIndexing.manage` - Service management permissions - `ebaycclone.searchIndexing.searchIndex.crud` - Data object CRUD permissions - `ebaycclone.adminModeration.manage` - Service management permissions - `ebaycclone.adminModeration.moderationAction.crud` - Data object CRUD permissions - `ebaycclone.watchlistCart.manage` - Service management permissions - `ebaycclone.watchlistCart.watchlistItem.crud` - Data object CRUD permissions - `ebaycclone.watchlistCart.cartItem.crud` - Data object CRUD permissions - `ebaycclone.watchlistCart.watchlistList.crud` - Data object CRUD permissions - `ebaycclone.productListing.manage` - Service management permissions - `ebaycclone.productListing.productListingMedia.crud` - Data object CRUD permissions - `ebaycclone.productListing.productListingProduct.crud` - Data object CRUD permissions - `ebaycclone.orderManagement.manage` - Service management permissions - `ebaycclone.orderManagement.orderManagementOrder.crud` - Data object CRUD permissions - `ebaycclone.orderManagement.orderManagementOrderItem.crud` - Data object CRUD permissions - `ebaycclone.orderManagement.sys_orderManagementOrderPayment.crud` - Data object CRUD permissions - `ebaycclone.orderManagement.sys_paymentCustomer.crud` - Data object CRUD permissions - `ebaycclone.orderManagement.sys_paymentMethod.crud` - Data object CRUD permissions - `ebaycclone.feedback.manage` - Service management permissions - `ebaycclone.feedback.feedback.crud` - Data object CRUD permissions - `ebaycclone.auth.manage` - Service management permissions - `ebaycclone.auth.user.crud` - Data object CRUD permissions ## Service Integration Guide ### Environment Configuration The admin panel connects to backend services through environment-specific configuration: **Development Environment** ```javascript VITE_AUTH_SERVICE_URL=http://localhost:3001 VITE_USER_SERVICE_URL=http://localhost:3002 VITE_PRODUCT_SERVICE_URL=http://localhost:3003 ``` **Staging Environment** ```javascript VITE_AUTH_SERVICE_URL=https://auth-api.ebaycclone.staging.mindbricks.com VITE_USER_SERVICE_URL=https://user-api.ebaycclone.staging.mindbricks.com VITE_PRODUCT_SERVICE_URL=https://product-api.ebaycclone.staging.mindbricks.com ``` **Production Environment** ```javascript VITE_AUTH_SERVICE_URL=https://auth-api.ebaycclone.prod.mindbricks.com VITE_USER_SERVICE_URL=https://user-api.ebaycclone.prod.mindbricks.com VITE_PRODUCT_SERVICE_URL=https://product-api.ebaycclone.prod.mindbricks.com ``` ### API Communication Layer **Axios Configuration** ```javascript // Base configuration for all service communications const apiClient = axios.create({ baseURL: serviceUrl, timeout: 10000, headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${accessToken}` } }); ``` **Request Interceptors** - Automatic token attachment to all requests - Error handling and retry logic for failed requests - Request/response logging for debugging **Response Interceptors** - Automatic token refresh on 401 responses - Error message standardization - Loading state management ## Data Object Management ### Dynamic CRUD Interface Generation The admin panel automatically generates complete CRUD interfaces for each data object based on the service definitions: **AuctionOffer Service Data Objects** **AuctionOfferOffer Management** - **Object Name**: `auctionOfferOffer` - **Component Name**: `AuctionOfferAuctionOfferOfferAppPage` - **Available Operations**: Create, Read, Update, Delete, List - **Route Path**: `/dashboard/auctionOffer/auctionOfferOffer` **Generated Components** - List View: Displays paginated data with filtering and sorting - Create Modal: Form for creating new auctionOfferOffer records - Update Modal: Form for editing existing auctionOfferOffer records - Delete Confirmation: Safe deletion with confirmation dialogs **AuctionOfferBid Management** - **Object Name**: `auctionOfferBid` - **Component Name**: `AuctionOfferAuctionOfferBidAppPage` - **Available Operations**: Create, Read, Update, Delete, List - **Route Path**: `/dashboard/auctionOffer/auctionOfferBid` **Generated Components** - List View: Displays paginated data with filtering and sorting - Create Modal: Form for creating new auctionOfferBid records - Update Modal: Form for editing existing auctionOfferBid records - Delete Confirmation: Safe deletion with confirmation dialogs **CategoryManagement Service Data Objects** **Category Management** - **Object Name**: `category` - **Component Name**: `CategoryManagementCategoryAppPage` - **Available Operations**: Create, Read, Update, Delete, List - **Route Path**: `/dashboard/categoryManagement/category` **Generated Components** - List View: Displays paginated data with filtering and sorting - Create Modal: Form for creating new category records - Update Modal: Form for editing existing category records - Delete Confirmation: Safe deletion with confirmation dialogs **Subcategory Management** - **Object Name**: `subcategory` - **Component Name**: `CategoryManagementSubcategoryAppPage` - **Available Operations**: Create, Read, Update, Delete, List - **Route Path**: `/dashboard/categoryManagement/subcategory` **Generated Components** - List View: Displays paginated data with filtering and sorting - Create Modal: Form for creating new subcategory records - Update Modal: Form for editing existing subcategory records - Delete Confirmation: Safe deletion with confirmation dialogs **Messaging Service Data Objects** **MessagingMessage Management** - **Object Name**: `messagingMessage` - **Component Name**: `MessagingMessagingMessageAppPage` - **Available Operations**: Create, Read, Update, Delete, List - **Route Path**: `/dashboard/messaging/messagingMessage` **Generated Components** - List View: Displays paginated data with filtering and sorting - Create Modal: Form for creating new messagingMessage records - Update Modal: Form for editing existing messagingMessage records - Delete Confirmation: Safe deletion with confirmation dialogs **NotificationManagement Service Data Objects** **Notification Management** - **Object Name**: `notification` - **Component Name**: `NotificationManagementNotificationAppPage` - **Available Operations**: Create, Read, Update, Delete, List - **Route Path**: `/dashboard/notificationManagement/notification` **Generated Components** - List View: Displays paginated data with filtering and sorting - Create Modal: Form for creating new notification records - Update Modal: Form for editing existing notification records - Delete Confirmation: Safe deletion with confirmation dialogs **SearchIndexing Service Data Objects** **SearchIndex Management** - **Object Name**: `searchIndex` - **Component Name**: `SearchIndexingSearchIndexAppPage` - **Available Operations**: Create, Read, Update, Delete, List - **Route Path**: `/dashboard/searchIndexing/searchIndex` **Generated Components** - List View: Displays paginated data with filtering and sorting - Create Modal: Form for creating new searchIndex records - Update Modal: Form for editing existing searchIndex records - Delete Confirmation: Safe deletion with confirmation dialogs **AdminModeration Service Data Objects** **ModerationAction Management** - **Object Name**: `moderationAction` - **Component Name**: `AdminModerationModerationActionAppPage` - **Available Operations**: Create, Read, Update, Delete, List - **Route Path**: `/dashboard/adminModeration/moderationAction` **Generated Components** - List View: Displays paginated data with filtering and sorting - Create Modal: Form for creating new moderationAction records - Update Modal: Form for editing existing moderationAction records - Delete Confirmation: Safe deletion with confirmation dialogs **WatchlistCart Service Data Objects** **WatchlistItem Management** - **Object Name**: `watchlistItem` - **Component Name**: `WatchlistCartWatchlistItemAppPage` - **Available Operations**: Create, Read, Update, Delete, List - **Route Path**: `/dashboard/watchlistCart/watchlistItem` **Generated Components** - List View: Displays paginated data with filtering and sorting - Create Modal: Form for creating new watchlistItem records - Update Modal: Form for editing existing watchlistItem records - Delete Confirmation: Safe deletion with confirmation dialogs **CartItem Management** - **Object Name**: `cartItem` - **Component Name**: `WatchlistCartCartItemAppPage` - **Available Operations**: Create, Read, Update, Delete, List - **Route Path**: `/dashboard/watchlistCart/cartItem` **Generated Components** - List View: Displays paginated data with filtering and sorting - Create Modal: Form for creating new cartItem records - Update Modal: Form for editing existing cartItem records - Delete Confirmation: Safe deletion with confirmation dialogs **WatchlistList Management** - **Object Name**: `watchlistList` - **Component Name**: `WatchlistCartWatchlistListAppPage` - **Available Operations**: Create, Read, Update, Delete, List - **Route Path**: `/dashboard/watchlistCart/watchlistList` **Generated Components** - List View: Displays paginated data with filtering and sorting - Create Modal: Form for creating new watchlistList records - Update Modal: Form for editing existing watchlistList records - Delete Confirmation: Safe deletion with confirmation dialogs **ProductListing Service Data Objects** **ProductListingMedia Management** - **Object Name**: `productListingMedia` - **Component Name**: `ProductListingProductListingMediaAppPage` - **Available Operations**: Create, Read, Update, Delete, List - **Route Path**: `/dashboard/productListing/productListingMedia` **Generated Components** - List View: Displays paginated data with filtering and sorting - Create Modal: Form for creating new productListingMedia records - Update Modal: Form for editing existing productListingMedia records - Delete Confirmation: Safe deletion with confirmation dialogs **ProductListingProduct Management** - **Object Name**: `productListingProduct` - **Component Name**: `ProductListingProductListingProductAppPage` - **Available Operations**: Create, Read, Update, Delete, List - **Route Path**: `/dashboard/productListing/productListingProduct` **Generated Components** - List View: Displays paginated data with filtering and sorting - Create Modal: Form for creating new productListingProduct records - Update Modal: Form for editing existing productListingProduct records - Delete Confirmation: Safe deletion with confirmation dialogs **OrderManagement Service Data Objects** **OrderManagementOrder Management** - **Object Name**: `orderManagementOrder` - **Component Name**: `OrderManagementOrderManagementOrderAppPage` - **Available Operations**: Create, Read, Update, Delete, List - **Route Path**: `/dashboard/orderManagement/orderManagementOrder` **Generated Components** - List View: Displays paginated data with filtering and sorting - Create Modal: Form for creating new orderManagementOrder records - Update Modal: Form for editing existing orderManagementOrder records - Delete Confirmation: Safe deletion with confirmation dialogs **OrderManagementOrderItem Management** - **Object Name**: `orderManagementOrderItem` - **Component Name**: `OrderManagementOrderManagementOrderItemAppPage` - **Available Operations**: Create, Read, Update, Delete, List - **Route Path**: `/dashboard/orderManagement/orderManagementOrderItem` **Generated Components** - List View: Displays paginated data with filtering and sorting - Create Modal: Form for creating new orderManagementOrderItem records - Update Modal: Form for editing existing orderManagementOrderItem records - Delete Confirmation: Safe deletion with confirmation dialogs **Sys_orderManagementOrderPayment Management** - **Object Name**: `sys_orderManagementOrderPayment` - **Component Name**: `OrderManagementSys_orderManagementOrderPaymentAppPage` - **Available Operations**: Create, Read, Update, Delete, List - **Route Path**: `/dashboard/orderManagement/sys_orderManagementOrderPayment` **Generated Components** - List View: Displays paginated data with filtering and sorting - Create Modal: Form for creating new sys_orderManagementOrderPayment records - Update Modal: Form for editing existing sys_orderManagementOrderPayment records - Delete Confirmation: Safe deletion with confirmation dialogs **Sys_paymentCustomer Management** - **Object Name**: `sys_paymentCustomer` - **Component Name**: `OrderManagementSys_paymentCustomerAppPage` - **Available Operations**: Create, Read, Update, Delete, List - **Route Path**: `/dashboard/orderManagement/sys_paymentCustomer` **Generated Components** - List View: Displays paginated data with filtering and sorting - Create Modal: Form for creating new sys_paymentCustomer records - Update Modal: Form for editing existing sys_paymentCustomer records - Delete Confirmation: Safe deletion with confirmation dialogs **Sys_paymentMethod Management** - **Object Name**: `sys_paymentMethod` - **Component Name**: `OrderManagementSys_paymentMethodAppPage` - **Available Operations**: Create, Read, Update, Delete, List - **Route Path**: `/dashboard/orderManagement/sys_paymentMethod` **Generated Components** - List View: Displays paginated data with filtering and sorting - Create Modal: Form for creating new sys_paymentMethod records - Update Modal: Form for editing existing sys_paymentMethod records - Delete Confirmation: Safe deletion with confirmation dialogs **Feedback Service Data Objects** **Feedback Management** - **Object Name**: `feedback` - **Component Name**: `FeedbackFeedbackAppPage` - **Available Operations**: Create, Read, Update, Delete, List - **Route Path**: `/dashboard/feedback/feedback` **Generated Components** - List View: Displays paginated data with filtering and sorting - Create Modal: Form for creating new feedback records - Update Modal: Form for editing existing feedback records - Delete Confirmation: Safe deletion with confirmation dialogs **Auth Service Data Objects** **User Management** - **Object Name**: `user` - **Component Name**: `AuthUserAppPage` - **Available Operations**: Create, Read, Update, Delete, List - **Route Path**: `/dashboard/auth/user` **Generated Components** - List View: Displays paginated data with filtering and sorting - Create Modal: Form for creating new user records - Update Modal: Form for editing existing user records - Delete Confirmation: Safe deletion with confirmation dialogs ### Data Validation and Error Handling **Client-Side Validation** - Real-time validation based on data object property definitions - Type checking and format validation - Required field validation **Server-Side Integration** - API error response handling - Validation error display - Success/error notification system ## API Integration Patterns ### Standard CRUD Operations **List Operations** ```javascript // Get paginated list of data objects const response = await apiClient.get(`/${dataObjectName}/list`, { params: { pageNumber: 1, pageRowCount: 25, getJoins: true, caching: true } }); ``` **Create Operations** ```javascript // Create new data object const response = await apiClient.post(`/${dataObjectName}/create`, { // Data object properties }); ``` **Update Operations** ```javascript // Update existing data object const response = await apiClient.put(`/${dataObjectName}/update`, { id: objectId, // Updated properties }); ``` **Delete Operations** ```javascript // Delete data object const response = await apiClient.delete(`/${dataObjectName}/delete`, { params: { id: objectId } }); ``` ### Advanced Query Features **Filtering and Search** - Dynamic filter generation based on data object properties - Full-text search capabilities - Date range filtering - Multi-select filters for enum properties **Sorting and Pagination** - Multi-column sorting support - Configurable page sizes - Total count and page navigation - Infinite scroll option **Data Relationships** - Automatic join handling for related data objects - Lazy loading for performance optimization - Relationship visualization in forms ## Navigation and Routing ### Dynamic Route Generation The admin panel automatically generates routes based on the service and data object structure: **Main Routes** - `/` - Login page - `/dashboard` - Main dashboard - `/dashboard/auctionOffer` - Service overview - `/dashboard/auctionOffer/auctionOfferOffer` - Data object management - `/dashboard/auctionOffer/auctionOfferBid` - Data object management - `/dashboard/categoryManagement` - Service overview - `/dashboard/categoryManagement/category` - Data object management - `/dashboard/categoryManagement/subcategory` - Data object management - `/dashboard/messaging` - Service overview - `/dashboard/messaging/messagingMessage` - Data object management - `/dashboard/notificationManagement` - Service overview - `/dashboard/notificationManagement/notification` - Data object management - `/dashboard/searchIndexing` - Service overview - `/dashboard/searchIndexing/searchIndex` - Data object management - `/dashboard/adminModeration` - Service overview - `/dashboard/adminModeration/moderationAction` - Data object management - `/dashboard/watchlistCart` - Service overview - `/dashboard/watchlistCart/watchlistItem` - Data object management - `/dashboard/watchlistCart/cartItem` - Data object management - `/dashboard/watchlistCart/watchlistList` - Data object management - `/dashboard/productListing` - Service overview - `/dashboard/productListing/productListingMedia` - Data object management - `/dashboard/productListing/productListingProduct` - Data object management - `/dashboard/orderManagement` - Service overview - `/dashboard/orderManagement/orderManagementOrder` - Data object management - `/dashboard/orderManagement/orderManagementOrderItem` - Data object management - `/dashboard/orderManagement/sys_orderManagementOrderPayment` - Data object management - `/dashboard/orderManagement/sys_paymentCustomer` - Data object management - `/dashboard/orderManagement/sys_paymentMethod` - Data object management - `/dashboard/feedback` - Service overview - `/dashboard/feedback/feedback` - Data object management - `/dashboard/auth` - Service overview - `/dashboard/auth/user` - Data object management **Route Configuration** ```javascript // Automatically generated route structure const dashboardRoutes = [ { path: 'dashboard', element: , children: [ { index: true, element: }, { path: 'auctionOffer', element: , children: [ { path: 'auctionOfferOffer', element: }, { path: 'auctionOfferBid', element: } ] }, { path: 'categoryManagement', element: , children: [ { path: 'category', element: }, { path: 'subcategory', element: } ] }, { path: 'messaging', element: , children: [ { path: 'messagingMessage', element: } ] }, { path: 'notificationManagement', element: , children: [ { path: 'notification', element: } ] }, { path: 'searchIndexing', element: , children: [ { path: 'searchIndex', element: } ] }, { path: 'adminModeration', element: , children: [ { path: 'moderationAction', element: } ] }, { path: 'watchlistCart', element: , children: [ { path: 'watchlistItem', element: }, { path: 'cartItem', element: }, { path: 'watchlistList', element: } ] }, { path: 'productListing', element: , children: [ { path: 'productListingMedia', element: }, { path: 'productListingProduct', element: } ] }, { path: 'orderManagement', element: , children: [ { path: 'orderManagementOrder', element: }, { path: 'orderManagementOrderItem', element: }, { path: 'sys_orderManagementOrderPayment', element: }, { path: 'sys_paymentCustomer', element: }, { path: 'sys_paymentMethod', element: } ] }, { path: 'feedback', element: , children: [ { path: 'feedback', element: } ] }, { path: 'auth', element: , children: [ { path: 'user', element: } ] } ] } ]; ``` ### Navigation Structure **Main Navigation** - Dashboard overview - Service modules (dynamically generated) - User profile and settings - Logout functionality **Service Navigation** - Service-specific data object management - Service configuration and settings - Service health and monitoring ## Error Handling and User Experience ### Error Management System **API Error Handling** - Standardized error response processing - User-friendly error message display - Automatic retry mechanisms for transient failures - Offline detection and handling **Validation Error Display** - Field-specific error highlighting - Inline error messages - Form validation summary **Loading States** - Skeleton loading for data tables - Progress indicators for long operations - Optimistic updates for better UX ### Notification System **Success Notifications** - Operation completion confirmations - Data synchronization status - System health updates **Error Notifications** - API error alerts - Validation error summaries - Network connectivity issues **Warning Notifications** - Data loss prevention warnings - Permission change alerts - System maintenance notifications ## Deployment and Configuration ### Build Configuration **Environment-Specific Builds** - Development builds with debugging enabled - Staging builds with production-like settings - Production builds with optimization and minification **Docker Support** - Multi-stage Docker builds for different environments - Environment variable injection - Health check endpoints ### Performance Optimization **Code Splitting** - Route-based code splitting - Component lazy loading - Dynamic imports for heavy components **Caching Strategies** - API response caching - Static asset caching - Browser cache optimization **Bundle Optimization** - Tree shaking for unused code - Asset compression - CDN integration support ## Security Considerations ### Authentication Security - Secure token storage and transmission - Automatic token refresh - Session timeout handling - Multi-factor authentication support ### Data Protection - Input sanitization and validation - XSS prevention - CSRF protection - Secure API communication ### Access Control - Role-based permission enforcement - Tenant isolation in multi-tenant setups - Audit logging for sensitive operations - Secure logout and session cleanup ## Troubleshooting and Support ### Common Issues **Authentication Problems** - Token expiration handling - Session restoration after page refresh - Multi-tenant login issues **API Integration Issues** - Service connectivity problems - Data synchronization errors - Permission-related access denials **UI/UX Issues** - Component rendering problems - Navigation routing issues - Form validation errors ### Debugging Tools **Development Tools** - React Developer Tools integration - Network request monitoring - State management debugging - Performance profiling **Logging and Monitoring** - Client-side error logging - API request/response logging - User interaction tracking - Performance metrics collection # SERVICE INTEGRATION GUIDE ## Ebaycclone Admin Panel This document provides detailed information about how the Ebaycclone Admin Panel integrates with backend services, including configuration, API communication patterns, and service-specific implementation details. ## Architectural Design Credit and Contact Information The architectural design of this service integration is credited to Mindbricks Genesis Engine. We encourage open communication and welcome any questions or discussions related to the architectural aspects of this service integration. ## Documentation Scope This guide covers the complete integration architecture between the Ebaycclone Admin Panel and its backend services. It includes configuration management, API communication patterns, authentication flows, and service-specific implementation details. **Intended Audience** This documentation is intended for frontend developers, DevOps engineers, and system integrators who need to understand, configure, or extend the admin panel's service integration capabilities. ## Service Integration Architecture ### Overview The admin panel integrates with backend services through service-specific HTTP clients. Each service is configured via environment variables and uses its own Axios instance for API communication. ### Integration Components **Service Configuration** - Service URLs configured via environment variables - Service-specific Axios instances for API communication **API Communication** - Basic HTTP client instances per service - Simple error handling through response interceptors ## Service Configuration ### Environment Variables The admin panel uses environment variables to configure service endpoints and integration settings: **Core Configuration** ```bash # Application Configuration VITE_APP_NAME="Ebaycclone Admin Panel" VITE_APP_VERSION="1.1.10" VITE_ASSETS_DIR="/assets" **Service Endpoints** ```bash # AuctionOffer Service VITE_AUCTIONOFFER_SERVICE_URL="https://auctionOffer-api.ebaycclone.prod.mindbricks.com" ```bash # CategoryManagement Service VITE_CATEGORYMANAGEMENT_SERVICE_URL="https://categoryManagement-api.ebaycclone.prod.mindbricks.com" ```bash # Messaging Service VITE_MESSAGING_SERVICE_URL="https://messaging-api.ebaycclone.prod.mindbricks.com" ```bash # NotificationManagement Service VITE_NOTIFICATIONMANAGEMENT_SERVICE_URL="https://notificationManagement-api.ebaycclone.prod.mindbricks.com" ```bash # SearchIndexing Service VITE_SEARCHINDEXING_SERVICE_URL="https://searchIndexing-api.ebaycclone.prod.mindbricks.com" ```bash # AdminModeration Service VITE_ADMINMODERATION_SERVICE_URL="https://adminModeration-api.ebaycclone.prod.mindbricks.com" ```bash # WatchlistCart Service VITE_WATCHLISTCART_SERVICE_URL="https://watchlistCart-api.ebaycclone.prod.mindbricks.com" ```bash # ProductListing Service VITE_PRODUCTLISTING_SERVICE_URL="https://productListing-api.ebaycclone.prod.mindbricks.com" ```bash # OrderManagement Service VITE_ORDERMANAGEMENT_SERVICE_URL="https://orderManagement-api.ebaycclone.prod.mindbricks.com" ```bash # Feedback Service VITE_FEEDBACK_SERVICE_URL="https://feedback-api.ebaycclone.prod.mindbricks.com" ```bash # Auth Service VITE_AUTH_SERVICE_URL="https://auth-api.ebaycclone.prod.mindbricks.com" ``` ## API Communication Patterns ### HTTP Client Configuration **Service-Specific Axios Instances** ```javascript import axios from 'axios'; import { CONFIG } from 'src/global-config'; const auctionOfferAxiosInstance = axios.create({ baseURL: CONFIG.auctionOfferServiceUrl }); auctionOfferAxiosInstance.interceptors.response.use( (response) => response, (error) => Promise.reject((error.response && error.response.data) || 'Something went wrong!') ); export default auctionOfferAxiosInstance; ``` ```javascript import axios from 'axios'; import { CONFIG } from 'src/global-config'; const categoryManagementAxiosInstance = axios.create({ baseURL: CONFIG.categoryManagementServiceUrl }); categoryManagementAxiosInstance.interceptors.response.use( (response) => response, (error) => Promise.reject((error.response && error.response.data) || 'Something went wrong!') ); export default categoryManagementAxiosInstance; ``` ```javascript import axios from 'axios'; import { CONFIG } from 'src/global-config'; const messagingAxiosInstance = axios.create({ baseURL: CONFIG.messagingServiceUrl }); messagingAxiosInstance.interceptors.response.use( (response) => response, (error) => Promise.reject((error.response && error.response.data) || 'Something went wrong!') ); export default messagingAxiosInstance; ``` ```javascript import axios from 'axios'; import { CONFIG } from 'src/global-config'; const notificationManagementAxiosInstance = axios.create({ baseURL: CONFIG.notificationManagementServiceUrl }); notificationManagementAxiosInstance.interceptors.response.use( (response) => response, (error) => Promise.reject((error.response && error.response.data) || 'Something went wrong!') ); export default notificationManagementAxiosInstance; ``` ```javascript import axios from 'axios'; import { CONFIG } from 'src/global-config'; const searchIndexingAxiosInstance = axios.create({ baseURL: CONFIG.searchIndexingServiceUrl }); searchIndexingAxiosInstance.interceptors.response.use( (response) => response, (error) => Promise.reject((error.response && error.response.data) || 'Something went wrong!') ); export default searchIndexingAxiosInstance; ``` ```javascript import axios from 'axios'; import { CONFIG } from 'src/global-config'; const adminModerationAxiosInstance = axios.create({ baseURL: CONFIG.adminModerationServiceUrl }); adminModerationAxiosInstance.interceptors.response.use( (response) => response, (error) => Promise.reject((error.response && error.response.data) || 'Something went wrong!') ); export default adminModerationAxiosInstance; ``` ```javascript import axios from 'axios'; import { CONFIG } from 'src/global-config'; const watchlistCartAxiosInstance = axios.create({ baseURL: CONFIG.watchlistCartServiceUrl }); watchlistCartAxiosInstance.interceptors.response.use( (response) => response, (error) => Promise.reject((error.response && error.response.data) || 'Something went wrong!') ); export default watchlistCartAxiosInstance; ``` ```javascript import axios from 'axios'; import { CONFIG } from 'src/global-config'; const productListingAxiosInstance = axios.create({ baseURL: CONFIG.productListingServiceUrl }); productListingAxiosInstance.interceptors.response.use( (response) => response, (error) => Promise.reject((error.response && error.response.data) || 'Something went wrong!') ); export default productListingAxiosInstance; ``` ```javascript import axios from 'axios'; import { CONFIG } from 'src/global-config'; const orderManagementAxiosInstance = axios.create({ baseURL: CONFIG.orderManagementServiceUrl }); orderManagementAxiosInstance.interceptors.response.use( (response) => response, (error) => Promise.reject((error.response && error.response.data) || 'Something went wrong!') ); export default orderManagementAxiosInstance; ``` ```javascript import axios from 'axios'; import { CONFIG } from 'src/global-config'; const feedbackAxiosInstance = axios.create({ baseURL: CONFIG.feedbackServiceUrl }); feedbackAxiosInstance.interceptors.response.use( (response) => response, (error) => Promise.reject((error.response && error.response.data) || 'Something went wrong!') ); export default feedbackAxiosInstance; ``` ```javascript import axios from 'axios'; import { CONFIG } from 'src/global-config'; const authAxiosInstance = axios.create({ baseURL: CONFIG.authServiceUrl }); authAxiosInstance.interceptors.response.use( (response) => response, (error) => Promise.reject((error.response && error.response.data) || 'Something went wrong!') ); export default authAxiosInstance; ``` ### Service Endpoints **AuctionOffer Service Endpoints** ```javascript export const auctionOfferEndpoints = { auctionOfferOffer: { updateAuctionOfferOffer: '/v1/auctionofferoffers/:auctionOfferOfferId' , getAuctionOfferOffer: '/v1/auctionofferoffers/:auctionOfferOfferId' , listAuctionOfferOffers: '/v1/auctionofferoffers' , createAuctionOfferOffer: '/v1/auctionofferoffers' , deleteAuctionOfferOffer: '/v1/auctionofferoffers/:auctionOfferOfferId' }, auctionOfferBid: { createAuctionOfferBid: '/v1/auctionofferbids' , getAuctionOfferBid: '/v1/auctionofferbids/:auctionOfferBidId' , updateAuctionOfferBid: '/v1/auctionofferbids/:auctionOfferBidId' , listAuctionOfferBids: '/v1/auctionofferbids' , deleteAuctionOfferBid: '/v1/auctionofferbids/:auctionOfferBidId' } }; ``` **CategoryManagement Service Endpoints** ```javascript export const categoryManagementEndpoints = { category: { deleteCategory: '/v1/categories/:categoryId' , getCategory: '/v1/categories/:categoryId' , listCategories: '/v1/categories' , updateCategory: '/v1/categories/:categoryId' , createCategory: '/v1/categories' }, subcategory: { getSubcategory: '/v1/subcategories/:subcategoryId' , updateSubcategory: '/v1/subcategories/:subcategoryId' , listSubcategories: '/v1/subcategories' , deleteSubcategory: '/v1/subcategories/:subcategoryId' , createSubcategory: '/v1/subcategories' } }; ``` **Messaging Service Endpoints** ```javascript export const messagingEndpoints = { messagingMessage: { listMessagingMessages: '/v1/messagingmessages' , createMessagingMessage: '/v1/messagingmessages' , updateMessagingMessage: '/v1/messagingmessages/:messagingMessageId' , getMessagingMessage: '/v1/messagingmessages/:messagingMessageId' , deleteMessagingMessage: '/v1/messagingmessages/:messagingMessageId' } }; ``` **NotificationManagement Service Endpoints** ```javascript export const notificationManagementEndpoints = { notification: { createNotification: '/v1/notifications' , updateNotification: '/v1/notifications/:notificationId' , listNotifications: '/v1/notifications' , deleteNotification: '/v1/notifications/:notificationId' , getNotification: '/v1/notifications/:notificationId' } }; ``` **SearchIndexing Service Endpoints** ```javascript export const searchIndexingEndpoints = { searchIndex: { listSearchIndexes: '/v1/searchindexes' , updateSearchIndex: '/v1/searchindexs/:searchIndexId' , deleteSearchIndex: '/v1/searchindexs/:searchIndexId' , createSearchIndex: '/v1/searchindexs' , getSearchIndex: '/v1/searchindexs/:searchIndexId' } }; ``` **AdminModeration Service Endpoints** ```javascript export const adminModerationEndpoints = { moderationAction: { getModerationAction: '/v1/moderationactions/:moderationActionId' , deleteModerationAction: '/v1/moderationactions/:moderationActionId' , createModerationAction: '/v1/moderationactions' , listModerationActions: '/v1/moderationactions' , updateModerationAction: '/v1/moderationactions/:moderationActionId' } }; ``` **WatchlistCart Service Endpoints** ```javascript export const watchlistCartEndpoints = { watchlistItem: { createWatchlistItem: '/v1/watchlistitems' , listWatchlistItems: '/v1/watchlistitems' , deleteWatchlistItem: '/v1/watchlistitems/:watchlistItemId' }, cartItem: { listCartItems: '/v1/cartitems' , deleteCartItem: '/v1/cartitems/:cartItemId' , updateCartItemQuantity: '/v1/cartitemquantity/:cartItemId' , createCartItem: '/v1/cartitems' }, watchlistList: { createWatchlistList: '/v1/watchlistlists' , deleteWatchlistList: '/v1/watchlistlists/:watchlistListId' } }; ``` **ProductListing Service Endpoints** ```javascript export const productListingEndpoints = { productListingMedia: { listProductListingMedia: '/v1/productlistingmedias' , getProductListingMedia: '/v1/productlistingmedias/:productListingMediaId' , deleteProductListingMedia: '/v1/productlistingmedias/:productListingMediaId' , createProductListingMedia: '/v1/productlistingmedias' }, productListingProduct: { getProductListingProduct: '/v1/productlistingproducts/:productListingProductId' , listProductListingProducts: '/v1/productlistingproducts' , deleteProductListingProduct: '/v1/productlistingproducts/:productListingProductId' , updateProductListingProduct: '/v1/productlistingproducts/:productListingProductId' , createProductListingProduct: '/v1/productlistingproducts' } }; ``` **OrderManagement Service Endpoints** ```javascript export const orderManagementEndpoints = { orderManagementOrder: { listOrderManagementOrders: '/v1/ordermanagementorders' , deleteOrderManagementOrder: '/v1/ordermanagementorders/:orderManagementOrderId' , getOrderManagementOrder: '/v1/ordermanagementorders/:orderManagementOrderId' , updateOrderManagementOrderStatus: '/v1/ordermanagementorderstatus/:orderManagementOrderId' , completeOrderStripeWebhook: '/v1/completeorderstripewebhook/:orderManagementOrderId' , createOrderManagementOrder: '/v1/ordermanagementorders' , startOrderManagementOrderPayment: '/v1/startordermanagementorderpayment/:orderManagementOrderId' , refreshOrderManagementOrderPayment: '/v1/refreshordermanagementorderpayment/:orderManagementOrderId' , callbackOrderManagementOrderPayment: '/v1/callbackordermanagementorderpayment' }, orderManagementOrderItem: { getOrderManagementOrderItem: '/v1/ordermanagementorderitems/:orderManagementOrderItemId' , listOrderManagementOrderItems: '/v1/ordermanagementorderitems' }, sys_orderManagementOrderPayment: { getOrderManagementOrderPayment2: '/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId' , listOrderManagementOrderPayments2: '/v1/ordermanagementorderpayments2' , createOrderManagementOrderPayment: '/v1/ordermanagementorderpayment' , updateOrderManagementOrderPayment: '/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId' , deleteOrderManagementOrderPayment: '/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId' , listOrderManagementOrderPayments2: '/v1/ordermanagementorderpayments2' , getOrderManagementOrderPaymentByOrderId: '/v1/orderManagementOrderpaymentbyorderid/:orderId' , getOrderManagementOrderPaymentByPaymentId: '/v1/orderManagementOrderpaymentbypaymentid/:paymentId' , getOrderManagementOrderPayment2: '/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId' }, sys_paymentCustomer: { getPaymentCustomerByUserId: '/v1/paymentcustomers/:userId' , listPaymentCustomers: '/v1/paymentcustomers' }, sys_paymentMethod: { listPaymentCustomerMethods: '/v1/paymentcustomermethods/:userId' } }; ``` **Feedback Service Endpoints** ```javascript export const feedbackEndpoints = { feedback: { listFeedbacks: '/v1/feedbacks' , getFeedback: '/v1/feedbacks/:feedbackId' , updateFeedback: '/v1/feedbacks/:feedbackId' , deleteFeedback: '/v1/feedbacks/:feedbackId' , createFeedback: '/v1/feedbacks' } }; ``` **Auth Service Endpoints** ```javascript export const authEndpoints = { login: "/login", me: "/v1/users/:userId", logout: "/logout", user: { getUser: '/v1/users/:userId' , updateUser: '/v1/users/:userId' , updateProfile: '/v1/profile/:userId' , createUser: '/v1/users' , deleteUser: '/v1/users/:userId' , archiveProfile: '/v1/archiveprofile/:userId' , listUsers: '/v1/users' , searchUsers: '/v1/searchusers' , updateUserRole: '/v1/userrole/:userId' , updateUserPassword: '/v1/userpassword/:userId' , updateUserPasswordByAdmin: '/v1/userpasswordbyadmin/:userId' , getBriefUser: '/v1/briefuser/:userId' , registerUser: '/v1/registeruser' } }; ``` ## Authentication Integration ### JWT Token Management **Basic Token Handling** ```javascript // Authentication is handled through the AuthProvider context // Tokens are managed by the JWT authentication system ``` ### Multi-Service Authentication **Service Authentication Implementation** ```javascript // Basic JWT authentication is used across all services // Authentication context is shared between services ``` ## Data Synchronization ### Real-Time Updates **Data Synchronization Implementation** ```javascript // Data is fetched on-demand through API calls // No real-time synchronization is required ``` ### Optimistic Updates **Update Strategy Implementation** ```javascript // Data is updated directly through API calls // Changes are reflected immediately after successful API response ``` ## Error Handling and Resilience ### Error Handling **Error Handling Implementation** ```javascript // Basic error handling through Axios response interceptors // Errors are logged and simplified for display ``` ### Retry Mechanisms **Retry Implementation** ```javascript // Basic error handling through Axios interceptors // Errors are logged and displayed to users ``` ## Service-Specific Integration Details ### AuctionOffer Service Integration **Service Overview** - **Service Name**: `auctionOffer` - **Display Name**: `AuctionOffer` - **Primary Purpose**: Handles auction bids and fixed-price offers for product listings, enforces real-time auction state, handles strict offer workflows including counter-offers, and triggers domain events for bid/offer notifications. No payment or frontend aggregation logic included. **Integration Features** - Basic CRUD operations for data objects - Simple error handling **Data Object Management** - **AuctionOfferOffer**: Represents an offer (best offer/counter-offer) made on a fixed-price product. Tracks buyer, seller, amounts, currency, state transitions, counter-offers, and expiry. - **AuctionOfferBid**: Represents an individual bid placed on an auction-type product. Linked to product and user, tracks bid amount, currency, status (ACTIVE, WON, LOST, CANCELLED), and time placed. **API Endpoints** - Data Operations: Service-specific CRUD endpoints based on business logic **Configuration Requirements** ```bash VITE_AUCTIONOFFER_SERVICE_URL=https://auctionOffer-api.ebaycclone.prod.mindbricks.com ``` ### CategoryManagement Service Integration **Service Overview** - **Service Name**: `categoryManagement` - **Display Name**: `CategoryManagement` - **Primary Purpose**: Handles product categories and subcategories for marketplace browsing and classification, supporting public discovery plus admin-only management. **Integration Features** - Basic CRUD operations for data objects - Simple error handling **Data Object Management** - **Category**: Represents a product category in the marketplace (e.g., Electronics, Clothing, Toys), used for browsing, filtering, and discovery. Admins manage categories. - **Subcategory**: Represents a subcategory within a parent category (e.g., 'Smartphones' under 'Electronics'). Used for more granular product discovery and navigation. 'group' categorizes special display logic. **API Endpoints** - Data Operations: Service-specific CRUD endpoints based on business logic **Configuration Requirements** ```bash VITE_CATEGORYMANAGEMENT_SERVICE_URL=https://categoryManagement-api.ebaycclone.prod.mindbricks.com ``` ### Messaging Service Integration **Service Overview** - **Service Name**: `messaging` - **Display Name**: `Messaging` - **Primary Purpose**: In-app messaging service for direct user-to-user text messages (buyers/sellers). Stores, retrieves, and manages user conversations. Launch version: text-only. **Integration Features** - Basic CRUD operations for data objects - Simple error handling **Data Object Management** - **MessagingMessage**: A direct, text-only in-app message between two users (buyer/seller); stores sender, recipient, content, read status, and timestamp. **API Endpoints** - Data Operations: Service-specific CRUD endpoints based on business logic **Configuration Requirements** ```bash VITE_MESSAGING_SERVICE_URL=https://messaging-api.ebaycclone.prod.mindbricks.com ``` ### NotificationManagement Service Integration **Service Overview** - **Service Name**: `notificationManagement` - **Display Name**: `NotificationManagement` - **Primary Purpose**: Handles storage, management, and event-driven delivery of in-app and email notifications for user-impacting system events (bids, offers, orders, feedback, messaging, etc.). Supports marking notifications as read/unread, structured filtering by event type/channel, and always returns in-app notifications ordered by recency. **Integration Features** - Basic CRUD operations for data objects - Simple error handling **Data Object Management** - **Notification**: Stores and manages in-app and email notifications tied to user-facing events like bids, offers, orders, messaging, shipment, and feedback. Includes event type (notificationType) for filter/search, arbitrary event payload, and delivery channel. Soft-delete enforced. In-app notifications always sorted by createdAt DESC on retrieval. **API Endpoints** - Data Operations: Service-specific CRUD endpoints based on business logic **Configuration Requirements** ```bash VITE_NOTIFICATIONMANAGEMENT_SERVICE_URL=https://notificationManagement-api.ebaycclone.prod.mindbricks.com ``` ### SearchIndexing Service Integration **Service Overview** - **Service Name**: `searchIndexing` - **Display Name**: `SearchIndexing` - **Primary Purpose**: Maintains the denormalized search index (materialized view) for global, public search across products, sellers, categories, and subcategories. Handles indexing in response to entity events and exposes optimized query endpoints for BFF/aggregator. **Integration Features** - Basic CRUD operations for data objects - Simple error handling **Data Object Management** - **SearchIndex**: Materialized/denormalized search index record for a marketplace entity (product, seller, category, subcategory). Used exclusively for high-speed querying in BFF global/public search. **API Endpoints** - Data Operations: Service-specific CRUD endpoints based on business logic **Configuration Requirements** ```bash VITE_SEARCHINDEXING_SERVICE_URL=https://searchIndexing-api.ebaycclone.prod.mindbricks.com ``` ### AdminModeration Service Integration **Service Overview** - **Service Name**: `adminModeration` - **Display Name**: `AdminModeration` - **Primary Purpose**: Administrative backend service for moderation and manual override actions. Responsible for logging all admin interventions (user/product/feedback/media/category/order/notification/searchindex moderation), triggering corrections via interservice calls, and providing comprehensive audit trails for compliance. **Integration Features** - Basic CRUD operations for data objects - Simple error handling **Data Object Management** - **ModerationAction**: Audit record for all admin moderation/override actions affecting core business entities. Links to admin, timestamp, entity type/ID, action performed, and reason. **API Endpoints** - Data Operations: Service-specific CRUD endpoints based on business logic **Configuration Requirements** ```bash VITE_ADMINMODERATION_SERVICE_URL=https://adminModeration-api.ebaycclone.prod.mindbricks.com ``` ### WatchlistCart Service Integration **Service Overview** - **Service Name**: `watchlistCart` - **Display Name**: `WatchlistCart` - **Primary Purpose**: Handles user watchlists (with custom folders) and shopping cart preparation for checkout, strictly enforcing only fixed-price products in carts, supporting item moves/bulk operations, and robust default/folder logic.. **Integration Features** - Basic CRUD operations for data objects - Simple error handling **Data Object Management** - **WatchlistItem**: Item in a user’s watchlist, optionally in a named folder; references product and user. - **CartItem**: Single product pending checkout in a user’s cart. Only fixed-price products permitted; quantity supported for multi-unit purchases (if allowed). - **WatchlistList**: A named folder/list in a user’s watchlist. Default list exists for all users. Custom lists may be created and deleted. **API Endpoints** - Data Operations: Service-specific CRUD endpoints based on business logic **Configuration Requirements** ```bash VITE_WATCHLISTCART_SERVICE_URL=https://watchlistCart-api.ebaycclone.prod.mindbricks.com ``` ### ProductListing Service Integration **Service Overview** - **Service Name**: `productListing` - **Display Name**: `ProductListing` - **Primary Purpose**: Handles product listings (both auction and fixed-price), image/media storage with validations, enforces immutable type, soft-delete, and public product discovery. **Integration Features** - Basic CRUD operations for data objects - Simple error handling **Data Object Management** - **ProductListingMedia**: Stores and manages images/media associated with products, including secure URL, MIME type, and size validation. Each asset can be used by multiple products. - **ProductListingProduct**: Represents a single product listing (fixed-price or auction) in the marketplace, with seller, category, type, price information, shipping details, media references, and dynamic auction fields. **API Endpoints** - Data Operations: Service-specific CRUD endpoints based on business logic **Configuration Requirements** ```bash VITE_PRODUCTLISTING_SERVICE_URL=https://productListing-api.ebaycclone.prod.mindbricks.com ``` ### OrderManagement Service Integration **Service Overview** - **Service Name**: `orderManagement` - **Display Name**: `OrderManagement` - **Primary Purpose**: Handles all marketplace orders, manual checkout flows for fixed-price/offer/auction settlements, Stripe payment processing and webhook reconciliation, explicit status updates (shipping, delivery, cancellation), and feedback eligibility via orderItems. **Integration Features** - Basic CRUD operations for data objects - Simple error handling **Data Object Management** - **OrderManagementOrder**: Marketplace order record. Stores buyer, shipping, status, items, Stripe payment data, and manual shipment/delivery events. Only accessible to admins or the buyer/seller of order items. - **OrderManagementOrderItem**: Order line item representing purchase of a single product from a specific seller as part of an order. Enables feedback, delivery, and per-seller analytics. Immutable after order creation. - **Sys_orderManagementOrderPayment**: A payment storage object to store the payment life cyle of orders based on orderManagementOrder object. It is autocreated based on the source object's checkout config - **Sys_paymentCustomer**: A payment storage object to store the customer values of the payment platform - **Sys_paymentMethod**: A payment storage object to store the payment methods of the platform customers **API Endpoints** - Data Operations: Service-specific CRUD endpoints based on business logic **Configuration Requirements** ```bash VITE_ORDERMANAGEMENT_SERVICE_URL=https://orderManagement-api.ebaycclone.prod.mindbricks.com ``` ### Feedback Service Integration **Service Overview** - **Service Name**: `feedback` - **Display Name**: `Feedback` - **Primary Purpose**: Handles feedback for order items: one feedback per buyer/orderItem, attached to sellerId for analytical feedback/rating aggregation and reputation tracking. Enables querying feedbacks received/given for sellers and buyers. test **Integration Features** - Basic CRUD operations for data objects - Simple error handling **Data Object Management** - **Feedback**: One feedback per (buyer, orderItem). Stores rating (1-5), comment, ties to seller for analytics. Created only after delivery confirmed on order item. **API Endpoints** - Data Operations: Service-specific CRUD endpoints based on business logic **Configuration Requirements** ```bash VITE_FEEDBACK_SERVICE_URL=https://feedback-api.ebaycclone.prod.mindbricks.com ``` ### Auth Service Integration **Service Overview** - **Service Name**: `auth` - **Display Name**: `Auth` - **Primary Purpose**: Authentication service for the project **Integration Features** - Basic CRUD operations for data objects - Simple error handling **Data Object Management** - **User**: A data object that stores the user information and handles login settings. **API Endpoints** - Data Operations: Service-specific CRUD endpoints based on business logic **Configuration Requirements** ```bash VITE_AUTH_SERVICE_URL=https://auth-api.ebaycclone.prod.mindbricks.com ``` ## Performance Optimization ### Caching Strategies **Caching Implementation** ```javascript // Data is fetched on-demand through API calls // No caching is required for current use cases ``` ### Request Batching **Request Batching Implementation** ```javascript // Individual API calls are made as needed // Each operation is handled independently ``` ## Monitoring and Logging ### Service Monitoring **Monitoring Implementation** ```javascript // Basic error logging through console.error // Service health is monitored through API responses ``` ### Error Logging **Error Logging Implementation** ```javascript // Basic error logging through console.error // Errors are displayed to users through UI components ``` # EVENT GUIDE ## ebaycclone-productlisting-service Handles product listings (both auction and fixed-price), image/media storage with validations, enforces immutable type, soft-delete, and public product discovery. ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to: Email: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. # Documentation Scope Welcome to the official documentation for the `ProductListing` Service Event descriptions. This guide is dedicated to detailing how to subscribe to and listen for state changes within the `ProductListing` Service, offering an exclusive focus on event subscription mechanisms. **Intended Audience** This documentation is aimed at developers and integrators looking to monitor `ProductListing` Service state changes. It is especially relevant for those wishing to implement or enhance business logic based on interactions with `ProductListing` objects. **Overview** This section provides detailed instructions on monitoring service events, covering payload structures and demonstrating typical use cases through examples. # Authentication and Authorization Access to the `ProductListing` service's events is facilitated through the project's Kafka server, which is not accessible to the public. Subscription to a Kafka topic requires being on the same network and possessing valid Kafka user credentials. This document presupposes that readers have existing access to the Kafka server. Additionally, the service offers a public subscription option via REST for real-time data management in frontend applications, secured through REST API authentication and authorization mechanisms. To subscribe to service events via the REST API, please consult the Realtime REST API Guide. # Database Events Database events are triggered at the database layer, automatically and atomically, in response to any modifications at the data level. These events serve to notify subscribers about the creation, update, or deletion of objects within the database, distinct from any overarching business logic. Listening to database events is particularly beneficial for those focused on tracking changes at the database level. A typical use case for subscribing to database events is to replicate the data store of one service within another service's scope, ensuring data consistency and syncronization across services. For example, while a business operation such as "approve membership" might generate a high-level business event like `membership-approved`, the underlying database changes could involve multiple state updates to different entities. These might be published as separate events, such as `dbevent-member-updated` and `dbevent-user-updated`, reflecting the granular changes at the database level. Such detailed eventing provides a robust foundation for building responsive, data-driven applications, enabling fine-grained observability and reaction to the dynamics of the data landscape. It also facilitates the architectural pattern of event sourcing, where state changes are captured as a sequence of events, allowing for high-fidelity data replication and history replay for analytical or auditing purposes. ## DbEvent productListingMedia-created **Event topic**: `ebaycclone-productlisting-service-dbevent-productlistingmedia-created` This event is triggered upon the creation of a `productListingMedia` data object in the database. The event payload encompasses the newly created data, encapsulated within the root of the paylod. **Event payload**: ```json {"id":"ID","mimeType":"String","productId":"ID","url":"String","size":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent productListingMedia-updated **Event topic**: `ebaycclone-productlisting-service-dbevent-productlistingmedia-updated` Activation of this event follows the update of a `productListingMedia` data object. The payload contains the updated information under the `productListingMedia` attribute, along with the original data prior to update, labeled as `old_productListingMedia` and also you can find the old and new versions of updated-only portion of the data.. **Event payload**: ```json { old_productListingMedia:{"id":"ID","mimeType":"String","productId":"ID","url":"String","size":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, productListingMedia:{"id":"ID","mimeType":"String","productId":"ID","url":"String","size":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, oldDataValues, newDataValues } ``` ## DbEvent productListingMedia-deleted **Event topic**: `ebaycclone-productlisting-service-dbevent-productlistingmedia-deleted` This event announces the deletion of a `productListingMedia` data object, covering both hard deletions (permanent removal) and soft deletions (where the `isActive` attribute is set to false). Regardless of the deletion type, the event payload will present the data as it was immediately before deletion, highlighting an `isActive` status of false for soft deletions. **Event payload**: ```json {"id":"ID","mimeType":"String","productId":"ID","url":"String","size":"Integer","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent productListingProduct-created **Event topic**: `ebaycclone-productlisting-service-dbevent-productlistingproduct-created` This event is triggered upon the creation of a `productListingProduct` data object in the database. The event payload encompasses the newly created data, encapsulated within the root of the paylod. **Event payload**: ```json {"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent productListingProduct-updated **Event topic**: `ebaycclone-productlisting-service-dbevent-productlistingproduct-updated` Activation of this event follows the update of a `productListingProduct` data object. The payload contains the updated information under the `productListingProduct` attribute, along with the original data prior to update, labeled as `old_productListingProduct` and also you can find the old and new versions of updated-only portion of the data.. **Event payload**: ```json { old_productListingProduct:{"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, productListingProduct:{"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, oldDataValues, newDataValues } ``` ## DbEvent productListingProduct-deleted **Event topic**: `ebaycclone-productlisting-service-dbevent-productlistingproduct-deleted` This event announces the deletion of a `productListingProduct` data object, covering both hard deletions (permanent removal) and soft deletions (where the `isActive` attribute is set to false). Regardless of the deletion type, the event payload will present the data as it was immediately before deletion, highlighting an `isActive` status of false for soft deletions. **Event payload**: ```json {"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` # ElasticSearch Index Events Within the `ProductListing` service, most data objects are mirrored in ElasticSearch indices, ensuring these indices remain syncronized with their database counterparts through creation, updates, and deletions. These indices serve dual purposes: they act as a data source for external services and furnish aggregated data tailored to enhance frontend user experiences. Consequently, an ElasticSearch index might encapsulate data in its original form or aggregate additional information from other data objects. These aggregations can include both one-to-one and one-to-many relationships not only with database objects within the same service but also across different services. This capability allows developers to access comprehensive, aggregated data efficiently. By subscribing to ElasticSearch index events, developers are notified when an index is updated and can directly obtain the aggregated entity within the event payload, bypassing the need for separate ElasticSearch queries. It's noteworthy that some services may augment another service's index by appending to the entity’s `extends` object. In such scenarios, an `*-extended` event will contain only the newly added data. Should you require the complete dataset, you would need to retrieve the full ElasticSearch index entity using the provided ID. This approach to indexing and event handling facilitates a modular, interconnected architecture where services can seamlessly integrate and react to changes, enriching the overall data ecosystem and enabling more dynamic, responsive applications. ## Index Event productlistingmedia-created **Event topic**: `elastic-index-ebaycclone_productlistingmedia-created` **Event payload**: ```json {"id":"ID","mimeType":"String","productId":"ID","url":"String","size":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event productlistingmedia-updated **Event topic**: `elastic-index-ebaycclone_productlistingmedia-created` **Event payload**: ```json {"id":"ID","mimeType":"String","productId":"ID","url":"String","size":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event productlistingmedia-deleted **Event topic**: `elastic-index-ebaycclone_productlistingmedia-deleted` **Event payload**: ```json {"id":"ID","mimeType":"String","productId":"ID","url":"String","size":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event productlistingmedia-extended **Event topic**: `elastic-index-ebaycclone_productlistingmedia-extended` **Event payload**: ```js { id: id, extends: { [extendName]: "Object", [extendName + "_count"]: "Number", }, } ``` # Route Events Route events are emitted following the successful execution of a route. While most routes perform CRUD (Create, Read, Update, Delete) operations on data objects, resulting in route events that closely resemble database events, there are distinctions worth noting. A single route execution might trigger multiple CRUD actions and ElasticSearch indexing operations. However, for those primarily concerned with the overarching business logic and its outcomes, listening to the consolidated route event, published once at the conclusion of the route's execution, is more pertinent. Moreover, routes often deliver aggregated data beyond the primary database object, catering to specific client needs. For instance, creating a data object via a route might not only return the entity's data but also route-specific metrics, such as the executing user's permissions related to the entity. Alternatively, a route might automatically generate default child entities following the creation of a parent object. Consequently, the route event encapsulates a unified dataset encompassing both the parent and its children, in contrast to individual events triggered for each entity created. Therefore, subscribing to route events can offer a richer, more contextually relevant set of information aligned with business logic. The payload of a route event mirrors the REST response JSON of the route, providing a direct and comprehensive reflection of the data and metadata communicated to the client. This ensures that subscribers to route events receive a payload that encapsulates both the primary data involved and any additional information deemed significant at the business level, facilitating a deeper understanding and integration of the service's functional outcomes. ## Route Event productlistingmedia-listed **Event topic** : `ebaycclone-productlisting-service-productlistingmedia-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `productListingMedias` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`productListingMedias`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingMedias","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","productListingMedias":[{"id":"ID","mimeType":"String","productId":"ID","url":"String","size":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event productlistingproduct-retrived **Event topic** : `ebaycclone-productlisting-service-productlistingproduct-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `productListingProduct` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`productListingProduct`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingProduct","method":"GET","action":"get","appVersion":"Version","rowCount":1,"productListingProduct":{"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event productlistingownproducts-listed **Event topic** : `ebaycclone-productlisting-service-productlistingownproducts-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `productListingProducts` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`productListingProducts`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingProducts","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","productListingProducts":[{"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event productlistingmedia-retrived **Event topic** : `ebaycclone-productlisting-service-productlistingmedia-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `productListingMedia` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`productListingMedia`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingMedia","method":"GET","action":"get","appVersion":"Version","rowCount":1,"productListingMedia":{"id":"ID","mimeType":"String","productId":"ID","url":"String","size":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event productlistingproducts-listed **Event topic** : `ebaycclone-productlisting-service-productlistingproducts-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `productListingProducts` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`productListingProducts`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingProducts","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","productListingProducts":[{"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event productlistingproduct-deleted **Event topic** : `ebaycclone-productlisting-service-productlistingproduct-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `productListingProduct` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`productListingProduct`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingProduct","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"productListingProduct":{"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event productlistingproduct-updated **Event topic** : `ebaycclone-productlisting-service-productlistingproduct-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `productListingProduct` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`productListingProduct`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingProduct","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"productListingProduct":{"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event productlistingproduct-created **Event topic** : `ebaycclone-productlisting-service-productlistingproduct-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `productListingProduct` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`productListingProduct`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingProduct","method":"POST","action":"create","appVersion":"Version","rowCount":1,"productListingProduct":{"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event productlistingmedia-deleted **Event topic** : `ebaycclone-productlisting-service-productlistingmedia-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `productListingMedia` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`productListingMedia`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingMedia","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"productListingMedia":{"id":"ID","mimeType":"String","productId":"ID","url":"String","size":"Integer","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event productlistingmedia-created **Event topic** : `ebaycclone-productlisting-service-productlistingmedia-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `productListingMedia` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`productListingMedia`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingMedia","method":"POST","action":"create","appVersion":"Version","rowCount":1,"productListingMedia":{"id":"ID","mimeType":"String","productId":"ID","url":"String","size":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Index Event productlistingproduct-created **Event topic**: `elastic-index-ebaycclone_productlistingproduct-created` **Event payload**: ```json {"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event productlistingproduct-updated **Event topic**: `elastic-index-ebaycclone_productlistingproduct-created` **Event payload**: ```json {"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event productlistingproduct-deleted **Event topic**: `elastic-index-ebaycclone_productlistingproduct-deleted` **Event payload**: ```json {"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event productlistingproduct-extended **Event topic**: `elastic-index-ebaycclone_productlistingproduct-extended` **Event payload**: ```js { id: id, extends: { [extendName]: "Object", [extendName + "_count"]: "Number", }, } ``` # Route Events Route events are emitted following the successful execution of a route. While most routes perform CRUD (Create, Read, Update, Delete) operations on data objects, resulting in route events that closely resemble database events, there are distinctions worth noting. A single route execution might trigger multiple CRUD actions and ElasticSearch indexing operations. However, for those primarily concerned with the overarching business logic and its outcomes, listening to the consolidated route event, published once at the conclusion of the route's execution, is more pertinent. Moreover, routes often deliver aggregated data beyond the primary database object, catering to specific client needs. For instance, creating a data object via a route might not only return the entity's data but also route-specific metrics, such as the executing user's permissions related to the entity. Alternatively, a route might automatically generate default child entities following the creation of a parent object. Consequently, the route event encapsulates a unified dataset encompassing both the parent and its children, in contrast to individual events triggered for each entity created. Therefore, subscribing to route events can offer a richer, more contextually relevant set of information aligned with business logic. The payload of a route event mirrors the REST response JSON of the route, providing a direct and comprehensive reflection of the data and metadata communicated to the client. This ensures that subscribers to route events receive a payload that encapsulates both the primary data involved and any additional information deemed significant at the business level, facilitating a deeper understanding and integration of the service's functional outcomes. ## Route Event productlistingmedia-listed **Event topic** : `ebaycclone-productlisting-service-productlistingmedia-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `productListingMedias` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`productListingMedias`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingMedias","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","productListingMedias":[{"id":"ID","mimeType":"String","productId":"ID","url":"String","size":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event productlistingproduct-retrived **Event topic** : `ebaycclone-productlisting-service-productlistingproduct-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `productListingProduct` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`productListingProduct`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingProduct","method":"GET","action":"get","appVersion":"Version","rowCount":1,"productListingProduct":{"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event productlistingownproducts-listed **Event topic** : `ebaycclone-productlisting-service-productlistingownproducts-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `productListingProducts` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`productListingProducts`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingProducts","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","productListingProducts":[{"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event productlistingmedia-retrived **Event topic** : `ebaycclone-productlisting-service-productlistingmedia-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `productListingMedia` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`productListingMedia`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingMedia","method":"GET","action":"get","appVersion":"Version","rowCount":1,"productListingMedia":{"id":"ID","mimeType":"String","productId":"ID","url":"String","size":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event productlistingproducts-listed **Event topic** : `ebaycclone-productlisting-service-productlistingproducts-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `productListingProducts` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`productListingProducts`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingProducts","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","productListingProducts":[{"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event productlistingproduct-deleted **Event topic** : `ebaycclone-productlisting-service-productlistingproduct-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `productListingProduct` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`productListingProduct`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingProduct","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"productListingProduct":{"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event productlistingproduct-updated **Event topic** : `ebaycclone-productlisting-service-productlistingproduct-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `productListingProduct` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`productListingProduct`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingProduct","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"productListingProduct":{"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event productlistingproduct-created **Event topic** : `ebaycclone-productlisting-service-productlistingproduct-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `productListingProduct` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`productListingProduct`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingProduct","method":"POST","action":"create","appVersion":"Version","rowCount":1,"productListingProduct":{"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event productlistingmedia-deleted **Event topic** : `ebaycclone-productlisting-service-productlistingmedia-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `productListingMedia` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`productListingMedia`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingMedia","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"productListingMedia":{"id":"ID","mimeType":"String","productId":"ID","url":"String","size":"Integer","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event productlistingmedia-created **Event topic** : `ebaycclone-productlisting-service-productlistingmedia-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `productListingMedia` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`productListingMedia`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingMedia","method":"POST","action":"create","appVersion":"Version","rowCount":1,"productListingMedia":{"id":"ID","mimeType":"String","productId":"ID","url":"String","size":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` # Copyright All sources, documents and other digital materials are copyright of . # About Us For more information please visit our website: . . . # **EBAYCCLONE** FRONTEND GUIDE FOR AI CODING AGENTS This document is a rest api guide for the ebaycclone project. The document is designed for AI agents who will generate frontend code that will consume the project backend. The project has got 1 auth service, 1 notification service, 1 bff service and business services. Each service is a separate microservice application and listens the HTTP request from different service urls. The services may be in preview server, staging server or real production server. So each service have got 3 acess urls. Frontend application should support all deployemnt servers in the development phase, and user should be able to select the target api server in the login page. ## Project Introduction ebaycClone is a comprehensive backend for an online marketplace supporting auctions and fixed-price sales of physical goods, with role-based access, public user registration, Stripe payments, notifications, and robust ownership enforcement. ## API Structure ### Object Structure of a Successfull Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client. **HTTP Status Codes:** - **200 OK**: This status code is returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request has been processed successfully. - **201 Created**: This status code is specific to CREATE operations, signifying that the requested resource has been successfully created. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling the successful execution of the request. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` - **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation performed. ### Additional Data Each api may have include addtional data other than the main data object according to the business logic of the API. They will be given in each API's response signature. ### Error Response If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity: - **400 Bad Request**: The request was improperly formatted or contained invalid parameters, preventing the server from processing it. - **401 Unauthorized**: The request lacked valid authentication token , login required - **403 Forbidden Error** Curent token provided do not grant access to the requested resource. - **404 Not Found**: The requested resource was not found on the server. - **500 Internal Server Error**: The server encountered an unexpected condition that prevented it from fulfilling the request. Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Accessing the backend Each service of the backend has got its own url according to the deployment environement. User may want to test the frontend in one of the 3 deployments of the application, preview, staging and production. Please ensure that register and login pages do have a deployemnt server selection option, so as the frontned coding agent you can arrange the base url path of all services. The base url of the application in each environment is as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com` * **Staging:** `https://ebaycclone-stage.mindbricks.co` * **Production:** `https://ebaycclone.mindbricks.co` For the auth service the base url is as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` For each other service, the service base url will be given in service sections. Any login requied request to the backend should have a valid token, when a user makes a successfull login, the ressponse JSON includes a JWT access token in the `accessToken`fields. In normal conditions, this token is also set to the cookie and then consumed automatically, but since AI coding agents preview options may fail to use cookies, please ensure that in each request include the access token in the bearer auth header. ## Registration Management First of all please ensure that register and login pages do have a deployemnt server selection option, so as the frontned coding agent you can arrange the base url path of all services. Start with a landing page and arranging register, verification and login flow. So at the first step, you need a general knowledge of the application to make a good landing page and the authetication flow. ### How To Register Using `registeruser` route of auth api, send the required fields to the backend in your registration page. The registerUser api in in `auth` service, is described with request and response structure below. Note that since `registerUser` api is a business api, it has a version control, so please call it with the given version like `/v1/registeruser` ### `Register User` API This api is used by public users to register themselves **Rest Route** The `registerUser` API REST controller can be triggered via the following route: `/v1/registeruser` **Rest Request Parameters** The `registerUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **password** : The password defined by the the user that is being registered. **fullname** : The fullname defined by the the user that is being registered. **email** : The email defined by the the user that is being registered. **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` After a successful registration, frontend code should handle the verification needs. The registration response will have a `user` object in the root envelope, this object will have user information with an `id` parameter. ### Email Verification In the registration response, you should check the property `emailVerificationNeeded` in the reponse root, and if this property is true you should start the email verification flow. After login process, if you get an HTTP error status, and if there is an `errCode` property in the response with `EmailVerificationNeeded` value, you should start the email verification flow. 1. Call the email verification `start` route of the backend (described below) with the user email, backend will send a secret code to the given email adresss. **Backend can send the email message if the architect defined a real mail service or smtp server, so during the development time backend will send the secret code also to the frontend. You can get this secret code from the response within the `secretCode` property**. 2. The secret code in the sent email message will be a 6 digits code , and you should arrange an input page so that the user can paste this code to the frontend application. Please navigate to this input page after you start the verification process. **If the secretCode is sent to the frontend for test purposes, then you should show it as info in the input page, so that user can copy and paste it**. 3. There is a `codeIndex` property in the start response, please show it's value on the input page, so that user can match the index in the message with the one on the screen. 4. When the user submits the code, please complete the email verification using the `complete` route of the backend (described below) with the user email and the secret code. 5. After you get a successful response from email verification, you can navigate to the login page. Here is the `start`and `complete` routes of email verification. These are system routes , so they dont have a version control. #### `POST /verification-services/email-verification/start` **Purpose:** Starts the email verification by generating and sending a secret code. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `email` | String | Yes | User’s email address to verify | **Example Request** ```json { "email": "user@example.com" } ``` **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ In production, `secretCode` is **not** returned — only sent via email. **Error Responses** * `400 Bad Request`: Already verified * `403 Forbidden`: Too many attempts (rate limit) --- #### `POST /verification-services/email-verification/complete` **Purpose:** Completes the verification using the received code. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `email` | String | Yes | User’s email | | `secretCode` | String | Yes | Verification code | **Success Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` **Error Responses** * `403 Forbidden`: Code expired or mismatched * `404 Not Found`: No verification in progress --- ## Login Management After a successfull login and completing required verifications, user can now login. Please make a fancy minimal login page where user can enter his email and password. ## Bucket Management This application has a bucket service and is used to store user or other objects related files. Bucket service is login agnostic, so when accessing for write or private read, you should insert a bucket token (given by services) to your request authorization header as bearer token. **User Bucket** This bucket is used to store public user files for each user. When a user logs in, or in /currentuser response there is `userBucketToken` to be used when sending user related public files to the bucket service. To upload `POST {baseUrl}/bucket/upload` Request body is form data which includes the bucketId and the file as binary in `files` property. ```js { bucketId: "{userId}-public-user-bucket", files: {binary} } ``` Response status is 200 on succesfull result, eg body: ```json { "success": true, "data": [ { "fileId": "9da03f6d-0409-41ad-bb06-225a244ae408", "originalName": "test (10).png", "mimeType": "image/png", "size": 604063, "status": "uploaded", "bucketName": "f7103b85-fcda-4dec-92c6-c336f71fd3a2-public-user-bucket", "isPublic": true, "downloadUrl": "https://babilcom.mindbricks.co/bucket/download/9da03f6d-0409-41ad-bb06-225a244ae408" } ] } ``` To download a file from the bucket, you should know its fileId, so if youupload an avatar or something else, be sure that the download url or the fileId is stored in backend. Bucket is mostly used, in object creations where alos demands an addtional file like a product image or user avatar. So after you upload your image to the bucket, insert the returned download url to the related property in the related object creation. **Application Bucket** This Ebaycclone application alos has common public bucket which everybody has a read access, but only users who have `superAdmin`, `admin` or `saasAdmin` roles can write (upload) to the bucket. The common public project bucket id is `"ebaycclone-public-common-bucket"` and in certain areas like product image uploads, since the user will already have the admin bucket token, he will be able to upload realted object images. Please make your UI arrangements as able to upload files to the bucket using these bucket tokens. **Object Buckets** Some objects may return also a bucket token, to upload or access related files with object. For example, when you get a project's data in a project management application, if there is a public or private bucket token, this is provided mostly for uploading project related files or downloading them with the token. These buckets will be used according to the descriptions given along with the object definitions. ## Role Management This Ebaycclone may have different role names defined fro different business logic. But unless another case is asked by the user, respect to the admin roles which may be `superAdmin`, `admin` or `saasAdmin` in the currentuser or login response given with the `roleId`property. ```json { // ... "roleId":"superAdmin", // ... } ``` If the application needs an admin panel, or any admin related page, please use these roleId's to decide if the user can access those pages or not. ## 1. Authentication Routes ### 1.1 `POST /login` — User Login **Purpose:** Verifies user credentials and creates an authenticated session with a JWT access token. **Access Routes:** * `GET /login`: Returns a minimal HTML login page (for browser-based testing). * `POST /login`: Authenticates user credentials and returns an access token and session. #### Request Parameters | Parameter | Type | Required | Source | | ---------- | ------ | -------- | ----------------------- | | `username` | String | Yes | `request.body.username` | | `password` | String | Yes | `request.body.password` | #### Behavior * Authenticates credentials and returns a session object. * Sets cookie: `projectname-access-token[-tenantCodename]` * Adds the same token in response headers. * Accepts either `username` or `email` fields (if both exist, `username` is prioritized). #### Example ```js axios.post("/login", { username: "user@example.com", password: "securePassword" }); ``` #### Success Response ```json { "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", //... } ``` #### Error Responses * `401 Unauthorized`: Invalid credentials * `403 Forbidden`: Email/mobile verification or 2FA pending * `400 Bad Request`: Missing parameters --- ### 1.2 `POST /logout` — User Logout **Purpose:** Terminates the current session and clears associated authentication tokens. #### Behavior * Invalidates session (if exists). * Clears cookie `projectname-access-token[-tenantCodename]`. * Returns a confirmation response (always `200 OK`). #### Example ```js axios.post("/logout", {}, { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` #### Notes * Can be called without a session (idempotent behavior). * Works for both cookie-based and token-based sessions. #### Success Response ```json { "status": "OK", "message": "User logged out successfully" } ``` --- ## 2. Verification Services Overview All verification routes are grouped under the `/verification-services` base path. They follow a **two-step verification pattern**: `start` → `complete`. --- ## 3. Email Verification ### 3.1 Trigger Scenarios * After registration (`emailVerificationRequiredForLogin` = true) * When updating email address * When login fails due to unverified email ### 3.2 Flow Summary 1. `/start` → Generate & send code via email. 2. `/complete` → Verify code and mark email as verified. ** PLEASE NOTE ** Email verification is a frontend triiggered process. After user registers, the frontend should start the email verification process and navigate to its code input page. --- ### 3.3 `POST /verification-services/email-verification/start` **Purpose:** Starts the email verification by generating and sending a secret code. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `email` | String | Yes | User’s email address to verify | **Example Request** ```json { "email": "user@example.com" } ``` **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ In production, `secretCode` is **not** returned — only sent via email. **Error Responses** * `400 Bad Request`: Already verified * `403 Forbidden`: Too many attempts (rate limit) --- ### 3.4 `POST /verification-services/email-verification/complete` **Purpose:** Completes the verification using the received code. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `email` | String | Yes | User’s email | | `secretCode` | String | Yes | Verification code | **Success Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` **Error Responses** * `403 Forbidden`: Code expired or mismatched * `404 Not Found`: No verification in progress --- ### 3.5 Behavioral Notes * **Resend Cooldown:** `resendTimeWindow` (e.g. 60s) * **Expiration:** Codes expire after `expireTimeWindow` (e.g. 1 day) * **Single Active Session:** One verification per user --- ## 4. Mobile Verification ### 4.1 Trigger Scenarios * After registration (`mobileVerificationRequiredForLogin` = true) * When updating phone number * On login requiring mobile verification ### 4.2 Flow 1. `/start` → Sends verification code via SMS 2. `/complete` → Validates code and confirms number --- ### 4.3 `POST /verification-services/mobile-verification/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------ | | `email` | String | Yes | User’s email to locate mobile record | **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 180, "verificationType": "byCode", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ `secretCode` returned only in development. **Errors** * `400 Bad Request`: Already verified * `403 Forbidden`: Rate-limited --- ### 4.4 `POST /verification-services/mobile-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------------- | | `email` | String | Yes | Associated email | | `secretCode` | String | Yes | Code received via SMS | **Success Response** ```json { "status": "OK", "isVerified": true, "mobile": "+1 333 ...", // in testMode "userId": "user-uuid", } ``` --- ### 4.5 Behavioral Notes * **Cooldown:** One code per minute * **Expiration:** Codes valid for 1 day * **One Session Per User** --- ## 5. Two-Factor Authentication (2FA) ### 5.1 Email 2FA **Flow** 1. `/start` → Generates and sends email code 2. `/complete` → Verifies code and updates session --- #### `POST /verification-services/email-2factor-verification/start` | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ---------------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Current session | | `client` | String | No | Optional context | | `reason` | String | No | Reason for 2FA | **Response** ```json { "status": "OK", "sessionId": "user session id UUID", "userId": "user-uuid", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", } ``` --- #### `POST /verification-services/email-2factor-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `secretCode` | String | Yes | Code from email | **Response** ```json { // user session data "sessionId": "session-uuid", // ... } ``` --- ### 5.2 Mobile 2FA **Flow** 1. `/start` → Sends SMS code 2. `/complete` → Validates and finalizes session --- #### `POST /verification-services/mobile-2factor-verification/start` | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ----------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `client` | String | No | Context | | `reason` | String | No | Reason | **Response** ```json { "status": "OK", "sessionId": "user session id UUID", "userId": "user-uuid", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", } ``` --- #### `POST /verification-services/mobile-2factor-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------ | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `secretCode` | String | Yes | Code via SMS | **Response** ```json { // user session data "sessionId": "session-uuid", // ... } ``` --- ### 5.3 2FA Behavioral Notes * One active code per session * Cooldown: `resendTimeWindow` (e.g., 60s) * Expiration: `expireTimeWindow` (e.g., 5m) --- ## 6. Password Reset ### 6.1 By Email **Flow** 1. `/start` → Sends verification code via email 2. `/complete` → Validates and resets password --- #### `POST /verification-services/password-reset-by-email/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------- | | `email` | String | Yes | User email | **Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` #### `POST /verification-services/password-reset-by-email/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------- | | `email` | String | Yes | User email | | `secretCode` | String | Yes | Code received | | `password` | String | Yes | New password | **Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` --- ### 6.2 By Mobile **Flow** 1. `/start` → Sends SMS code 2. `/complete` → Validates and resets password --- #### `POST /verification-services/password-reset-by-mobile/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------- | | `mobile` | String | Yes | Mobile number | **Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` #### `POST /verification-services/password-reset-by-mobile/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ---------------- | | `email` | String | Yes | Associated email | | `secretCode` | String | Yes | Code via SMS | | `password` | String | Yes | New password | **Response** ```json { "status": "OK", "isVerified": true, "mobile": "+1 444 ....", // in testMode "userId": "user-uuid", } ``` --- ### 6.3 Behavioral Notes * Cooldown: 60s resend * Expiration: 24h * One session per user * Works without an active login session --- ## 7. Verification Method Types ### 7.1 `byCode` User manually enters the 6-digit code in frontend. ### 7.2 `byLink` Frontend handles a one-click verification via email/SMS link containing code parameters. ## 8) `GET /currentuser` — Current Session **Purpose** Return the currently authenticated user’s session. **Route Type** `sessionInfo` **Authentication** Requires a valid access token (header or cookie). ### Request *No parameters.* ### Example ```js axios.get("/currentuser", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) Returns the session object (identity, tenancy, token metadata): ```json { "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", "roleId": "user", "tenantId": "abc123", "accessToken": "jwt-token-string", "...": "..." } ``` ### Errors * **401 Unauthorized** — No active session/token ```json { "status": "ERR", "message": "No login found" } ``` **Notes** * Commonly called by web/mobile clients after login to hydrate session state. * Includes key identity/tenant fields and a token reference (if applicable). * Ensure a valid token is supplied to receive a 200 response. --- ## 9) `GET /permissions` — List Effective Permissions **Purpose** Return all effective permission grants for the current user. **Route Type** `permissionFetch` **Authentication** Requires a valid access token. ### Request *No parameters.* ### Example ```js axios.get("/permissions", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) Array of permission grants (aligned with `givenPermissions`): ```json [ { "id": "perm1", "permissionName": "adminPanel.access", "roleId": "admin", "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" }, { "id": "perm2", "permissionName": "orders.manage", "roleId": null, "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" } ] ``` **Field meanings (per item):** * `permissionName`: Granted permission key. * `roleId`: Present if granted via role. * `subjectUserId`: Present if granted directly to the user. * `subjectUserGroupId`: Present if granted via group. * `objectId`: Present if scoped to a specific object (OBAC). * `canDo`: `true` if enabled, `false` if restricted. ### Errors * **401 Unauthorized** — No active session ```json { "status": "ERR", "message": "No login found" } ``` * **500 Internal Server Error** — Unexpected failure **Notes** * Available on all Mindbricks-generated services (not only Auth). * **Auth service:** Reads live `givenPermissions` from DB. * **Other services:** Typically respond from a cached/projected view (e.g., ElasticSearch) for faster checks. > **Tip:** Cache permission results client-side/server-side and refresh after login or permission updates. --- ## 10) `GET /permissions/:permissionName` — Check Permission Scope **Purpose** Check whether the current user has a specific permission and return any scoped object exceptions/inclusions. **Route Type** `permissionScopeCheck` **Authentication** Requires a valid access token. ### Path Parameters | Name | Type | Required | Source | | ---------------- | ------ | -------- | ------------------------------- | | `permissionName` | String | Yes | `request.params.permissionName` | ### Example ```js axios.get("/permissions/orders.manage", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) ```json { "canDo": true, "exceptions": [ "a1f2e3d4-xxxx-yyyy-zzzz-object1", "b2c3d4e5-xxxx-yyyy-zzzz-object2" ] } ``` **Interpretation** * If `canDo: true`: permission is generally granted **except** the listed `exceptions` (restrictions). * If `canDo: false`: permission is generally **not** granted, **only** allowed for the listed `exceptions` (selective overrides). * `exceptions` contains object IDs (UUID strings) from the relevant domain model. ### Errors * **401 Unauthorized** — No active session/token. ## Services And Data Object ## Auth Service Authentication service for the project ### Auth Service Data Objects **User** A data object that stores the user information and handles login settings. ### Auth Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` ### `Get User` API This api is used by admin roles or the users themselves to get the user profile information. **Rest Route** The `getUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `getUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users/:userId** ```js axios({ method: 'GET', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update User` API This route is used by admins to update user profiles. **Rest Route** The `updateUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `updateUser` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/users/:userId** ```js axios({ method: 'PATCH', url: `/v1/users/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Profile` API This route is used by users to update their profiles. **Rest Route** The `updateProfile` API REST controller can be triggered via the following route: `/v1/profile/:userId` **Rest Request Parameters** The `updateProfile` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/profile/:userId** ```js axios({ method: 'PATCH', url: `/v1/profile/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create User` API This api is used by admin roles to create a new user manually from admin panels **Rest Route** The `createUser` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `createUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | email | String | true | request.body?.email | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **email** : A string value to represent the user's email. **password** : A string value to represent the user's password. It will be stored as hashed. **fullname** : A string value to represent the fullname of the user **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/users** ```js axios({ method: 'POST', url: '/v1/users', data: { avatar:"String", email:"String", password:"String", fullname:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete User` API This api is used by admins to delete user profiles. **Rest Route** The `deleteUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `deleteUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/users/:userId** ```js axios({ method: 'DELETE', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Archive Profile` API This api is used by users to archive their profiles. **Rest Route** The `archiveProfile` API REST controller can be triggered via the following route: `/v1/archiveprofile/:userId` **Rest Request Parameters** The `archiveProfile` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/archiveprofile/:userId** ```js axios({ method: 'DELETE', url: `/v1/archiveprofile/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Users` API The list of users is filtered by the tenantId. **Rest Route** The `listUsers` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `listUsers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users** ```js axios({ method: 'GET', url: '/v1/users', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Search Users` API The list of users is filtered by the tenantId. **Rest Route** The `searchUsers` API REST controller can be triggered via the following route: `/v1/searchusers` **Rest Request Parameters** The `searchUsers` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | keyword | String | true | request.query?.keyword | **keyword** : **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchusers** ```js axios({ method: 'GET', url: '/v1/searchusers', data: { }, params: { keyword:'"String"', } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Userrole` API This route is used by admin roles to update the user role.The default role is user when a user is registered. A user's role can be updated by superAdmin or admin **Rest Route** The `updateUserRole` API REST controller can be triggered via the following route: `/v1/userrole/:userId` **Rest Request Parameters** The `updateUserRole` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | roleId | String | true | request.body?.roleId | **userId** : This id paremeter is used to select the required data object that will be updated **roleId** : The new roleId of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userrole/:userId** ```js axios({ method: 'PATCH', url: `/v1/userrole/${userId}`, data: { roleId:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpassword` API This route is used to update the password of users in the profile page by users themselves **Rest Route** The `updateUserPassword` API REST controller can be triggered via the following route: `/v1/userpassword/:userId` **Rest Request Parameters** The `updateUserPassword` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | oldPassword | String | true | request.body?.oldPassword | | newPassword | String | true | request.body?.newPassword | **userId** : This id paremeter is used to select the required data object that will be updated **oldPassword** : The old password of the user that will be overridden bu the new one. Send for double check. **newPassword** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpassword/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpassword/${userId}`, data: { oldPassword:"String", newPassword:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpasswordbyadmin` API This route is used to change any user password by admins only. Superadmin can chnage all passwords, admins can change only nonadmin passwords **Rest Route** The `updateUserPasswordByAdmin` API REST controller can be triggered via the following route: `/v1/userpasswordbyadmin/:userId` **Rest Request Parameters** The `updateUserPasswordByAdmin` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | password | String | true | request.body?.password | **userId** : This id paremeter is used to select the required data object that will be updated **password** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpasswordbyadmin/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpasswordbyadmin/${userId}`, data: { password:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Briefuser` API This route is used by public to get simple user profile information. **Rest Route** The `getBriefUser` API REST controller can be triggered via the following route: `/v1/briefuser/:userId` **Rest Request Parameters** The `getBriefUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/briefuser/:userId** ```js axios({ method: 'GET', url: `/v1/briefuser/${userId}`, data: { }, params: { } }); ``` **REST Response** This route's response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "fullname": "String", "avatar": "String", "isActive": true } } ``` ### `Register User` API This api is used by public users to register themselves **Rest Route** The `registerUser` API REST controller can be triggered via the following route: `/v1/registeruser` **Rest Request Parameters** The `registerUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **password** : The password defined by the the user that is being registered. **fullname** : The fullname defined by the the user that is being registered. **email** : The email defined by the the user that is being registered. **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## AuctionOffer Service Handles auction bids and fixed-price offers for product listings, enforces real-time auction state, handles strict offer workflows including counter-offers, and triggers domain events for bid/offer notifications. No payment or frontend aggregation logic included. ### AuctionOffer Service Data Objects **AuctionOfferOffer** Represents an offer (best offer/counter-offer) made on a fixed-price product. Tracks buyer, seller, amounts, currency, state transitions, counter-offers, and expiry. **AuctionOfferBid** Represents an individual bid placed on an auction-type product. Linked to product and user, tracks bid amount, currency, status (ACTIVE, WON, LOST, CANCELLED), and time placed. ### AuctionOffer Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auctionoffer-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auctionoffer-api` * **Production:** `https://ebaycclone.mindbricks.co/auctionoffer-api` ### `Update Auctionofferoffer` API Updates offer: accepts/declines/counters by seller, withdraws by buyer before response. Enforces status transition rules, sets respondedAt. Triggers event. **Rest Route** The `updateAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `updateAuctionOfferOffer` api has got 8 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | message | String | false | request.body?.message | | status | Enum | false | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | **auctionOfferOfferId** : This id paremeter is used to select the required data object that will be updated **counterOfferId** : References another offer (counter-offer chain). **counterMessage** : Message accompanying seller's counter-offer (optional). **counterAmount** : Counter-offer amount (when offer is COUNTERED). **message** : Message/special notes from buyer (optional). **status** : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). **expiresAt** : When this offer expires (optional). **respondedAt** : When the seller (or buyer, for counter-offer) responded/updated the offer status. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Auctionofferbid` API Creates a new bid for an auction product. Validates auction status, not seller, product type, bid window, and ensures min. increment. Updates product.currentBid and product.highestBidderId atomically. Triggers notification event. **Rest Route** The `createAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids` **Rest Request Parameters** The `createAuctionOfferBid` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | bidAmount | Double | true | request.body?.bidAmount | | currency | String | true | request.body?.currency | | status | Enum | true | request.body?.status | | productId | ID | true | request.body?.productId | **bidAmount** : Bid amount placed by the user. **currency** : ISO currency for the bid (e.g., USD, EUR). **status** : Bid status: ACTIVE, WON, LOST, CANCELLED. **productId** : Product being bid on (must be AUCTION type). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/auctionofferbids** ```js axios({ method: 'POST', url: '/v1/auctionofferbids', data: { bidAmount:"Double", currency:"String", status:"Enum", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Auctionofferbid` API Gets a single bid (only visible to owner/admin or for auction history). **Rest Route** The `getAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `getAuctionOfferBid` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | **auctionOfferBidId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'GET', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Auctionofferoffer` API Gets a single offer (shown to buyer/seller or admin). **Rest Route** The `getAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `getAuctionOfferOffer` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | **auctionOfferOfferId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'GET', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Auctionofferoffers` API Lists offers by product, user, status, or counterOffer chain. **Rest Route** The `listAuctionOfferOffers` API REST controller can be triggered via the following route: `/v1/auctionofferoffers` **Rest Request Parameters** The `listAuctionOfferOffers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers** ```js axios({ method: 'GET', url: '/v1/auctionofferoffers', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferOffers": [ { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Auctionofferbid` API Updates a bid’s status (allow only status update, e.g. CANCELLED, WIN/LOSE on admin settlement). Only owner/admin, and only if auction not ended or not settled. Triggers notification event. **Rest Route** The `updateAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `updateAuctionOfferBid` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | | status | Enum | false | request.body?.status | **auctionOfferBidId** : This id paremeter is used to select the required data object that will be updated **status** : Bid status: ACTIVE, WON, LOST, CANCELLED. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { status:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Auctionofferoffer` API Creates a new offer for a fixed-price product, validating acceptOffers, type, eligibility, and product/seller/buyer active. Defaults to PENDING state. Triggers notification event. **Rest Route** The `createAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers` **Rest Request Parameters** The `createAuctionOfferOffer` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | productId | ID | true | request.body?.productId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | offerAmount | Double | true | request.body?.offerAmount | | message | String | false | request.body?.message | | status | Enum | true | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | **currency** : ISO currency (e.g., USD, EUR) for the offer. **productId** : Product the offer applies to (must be fixed-price, acceptOffers true). **counterOfferId** : References another offer (counter-offer chain). **counterMessage** : Message accompanying seller's counter-offer (optional). **counterAmount** : Counter-offer amount (when offer is COUNTERED). **offerAmount** : Primary offer amount from buyer. **message** : Message/special notes from buyer (optional). **status** : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). **expiresAt** : When this offer expires (optional). **respondedAt** : When the seller (or buyer, for counter-offer) responded/updated the offer status. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/auctionofferoffers** ```js axios({ method: 'POST', url: '/v1/auctionofferoffers', data: { currency:"String", productId:"ID", counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", offerAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Auctionofferbids` API Lists bids by product, user, or auction, supports history/analytics. **Rest Route** The `listAuctionOfferBids` API REST controller can be triggered via the following route: `/v1/auctionofferbids` **Rest Request Parameters** The `listAuctionOfferBids` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids** ```js axios({ method: 'GET', url: '/v1/auctionofferbids', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBids", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferBids": [ { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Auctionofferbid` API Soft-deletes a bid (for admin or self before auction ends). **Rest Route** The `deleteAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `deleteAuctionOfferBid` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | **auctionOfferBidId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Auctionofferoffer` API Soft-deletes an offer (allowed only in non-accepted/expired state). **Rest Route** The `deleteAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `deleteAuctionOfferOffer` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | **auctionOfferOfferId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## CategoryManagement Service Handles product categories and subcategories for marketplace browsing and classification, supporting public discovery plus admin-only management. ### CategoryManagement Service Data Objects **Category** Represents a product category in the marketplace (e.g., Electronics, Clothing, Toys), used for browsing, filtering, and discovery. Admins manage categories. **Subcategory** Represents a subcategory within a parent category (e.g., 'Smartphones' under 'Electronics'). Used for more granular product discovery and navigation. 'group' categorizes special display logic. ### CategoryManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/categorymanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/categorymanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/categorymanagement-api` ### `Delete Category` API Soft-delete a category (admin-only). **Rest Route** The `deleteCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `deleteCategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | **categoryId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/categories/:categoryId** ```js axios({ method: 'DELETE', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Subcategory` API Get a subcategory by ID. Public - only active subcategories returned except for admin. **Rest Route** The `getSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `getSubcategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | **subcategoryId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/subcategories/:subcategoryId** ```js axios({ method: 'GET', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Category` API Get a single category by ID. Public - only active categories returned (for non-admins). **Rest Route** The `getCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `getCategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | **categoryId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/categories/:categoryId** ```js axios({ method: 'GET', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Subcategory` API Update subcategory (admin-only), including group enum change. **Rest Route** The `updateSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `updateSubcategory` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | name | String | false | request.body?.name | | group | Enum | false | request.body?.group | **subcategoryId** : This id paremeter is used to select the required data object that will be updated **categoryId** : Reference to the parent category (category.id). **name** : Display name of the subcategory. **group** : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/subcategories/:subcategoryId** ```js axios({ method: 'PATCH', url: `/v1/subcategories/${subcategoryId}`, data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Subcategories` API List all subcategories for browsing/filtering, with support for group enum and parent category queries. Only active subcategories shown to public/non-admin users. **Rest Route** The `listSubcategories` API REST controller can be triggered via the following route: `/v1/subcategories` **Rest Request Parameters** The `listSubcategories` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/subcategories** ```js axios({ method: 'GET', url: '/v1/subcategories', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "subcategories": [ { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Subcategory` API Soft-delete a subcategory (admin-only). **Rest Route** The `deleteSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `deleteSubcategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | **subcategoryId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/subcategories/:subcategoryId** ```js axios({ method: 'DELETE', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Categories` API List all categories for browsing and filtering. Only active categories shown to public/non-admin users. **Rest Route** The `listCategories` API REST controller can be triggered via the following route: `/v1/categories` **Rest Request Parameters** The `listCategories` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/categories** ```js axios({ method: 'GET', url: '/v1/categories', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "categories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "categories": [ { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Category` API Update category details (admin-only). **Rest Route** The `updateCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `updateCategory` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | false | request.body?.title | **categoryId** : This id paremeter is used to select the required data object that will be updated **imageUrl** : URL for category image/avatar (optional, used for homepage visuals). **subtitle** : Optional short description for UI/tooltips. **title** : Display name of the category. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/categories/:categoryId** ```js axios({ method: 'PATCH', url: `/v1/categories/${categoryId}`, data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Subcategory` API Create a new subcategory under a given category (admin-only), with enum group constraint. **Rest Route** The `createSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories` **Rest Request Parameters** The `createSubcategory` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.body?.categoryId | | name | String | true | request.body?.name | | group | Enum | true | request.body?.group | **categoryId** : Reference to the parent category (category.id). **name** : Display name of the subcategory. **group** : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/subcategories** ```js axios({ method: 'POST', url: '/v1/subcategories', data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Category` API Create a new category (admin-only) for product classification. **Rest Route** The `createCategory` API REST controller can be triggered via the following route: `/v1/categories` **Rest Request Parameters** The `createCategory` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | true | request.body?.title | **imageUrl** : URL for category image/avatar (optional, used for homepage visuals). **subtitle** : Optional short description for UI/tooltips. **title** : Display name of the category. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/categories** ```js axios({ method: 'POST', url: '/v1/categories', data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## Messaging Service In-app messaging service for direct user-to-user text messages (buyers/sellers). Stores, retrieves, and manages user conversations. Launch version: text-only. ### Messaging Service Data Objects **MessagingMessage** A direct, text-only in-app message between two users (buyer/seller); stores sender, recipient, content, read status, and timestamp. ### Messaging Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/messaging-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/messaging-api` * **Production:** `https://ebaycclone.mindbricks.co/messaging-api` ### `List Messagingmessages` API List all messages in the conversation between the logged-in user and another party, ordered by sentAt descending. Can filter unread with isRead. Returns only messages visible to user (isActive). **Rest Route** The `listMessagingMessages` API REST controller can be triggered via the following route: `/v1/messagingmessages` **Rest Request Parameters** The `listMessagingMessages` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages** ```js axios({ method: 'GET', url: '/v1/messagingmessages', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessages", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "messagingMessages": [ { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Messagingmessage` API Send a new text message from the logged-in user to a recipient. Sender is set from session. Launch version supports only text content. **Rest Route** The `createMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages` **Rest Request Parameters** The `createMessagingMessage` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | toUserId | ID | true | request.body?.toUserId | | content | String | true | request.body?.content | | isRead | Boolean | true | request.body?.isRead | **toUserId** : Recipient (user) of this message. **content** : Text content of the message. No files or attachments for launch. **isRead** : If true, recipient has marked this message as read. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/messagingmessages** ```js axios({ method: 'POST', url: '/v1/messagingmessages', data: { toUserId:"ID", content:"String", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Messagingmessage` API Update a message (mark as read/unread). Only the recipient or admin can change isRead. No content edits. Sender, content, sentAt are immutable. **Rest Route** The `updateMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `updateMessagingMessage` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | | isRead | Boolean | false | request.body?.isRead | **messagingMessageId** : This id paremeter is used to select the required data object that will be updated **isRead** : If true, recipient has marked this message as read. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'PATCH', url: `/v1/messagingmessages/${messagingMessageId}`, data: { isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Messagingmessage` API Get a message by ID. Only accessible to the sender, the recipient, or an admin. Used for message detail view or reading a single message in a thread. **Rest Route** The `getMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `getMessagingMessage` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | **messagingMessageId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'GET', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Messagingmessage` API Delete a message (soft-delete). Only sender, recipient, or admin may delete a message. Deletion only hides it for the user; not a full erase unless both delete. **Rest Route** The `deleteMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `deleteMessagingMessage` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | **messagingMessageId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'DELETE', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## NotificationManagement Service Handles storage, management, and event-driven delivery of in-app and email notifications for user-impacting system events (bids, offers, orders, feedback, messaging, etc.). Supports marking notifications as read/unread, structured filtering by event type/channel, and always returns in-app notifications ordered by recency. ### NotificationManagement Service Data Objects **Notification** Stores and manages in-app and email notifications tied to user-facing events like bids, offers, orders, messaging, shipment, and feedback. Includes event type (notificationType) for filter/search, arbitrary event payload, and delivery channel. Soft-delete enforced. In-app notifications always sorted by createdAt DESC on retrieval. ### NotificationManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/notificationmanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/notificationmanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/notificationmanagement-api` ### `Create Notification` API Creates a notification entry in response to a system/business event. Only allowed for system/event processes and admins (not standard user/action). Typically event-driven, receives userId, notificationType, payload, and channel. **Rest Route** The `createNotification` API REST controller can be triggered via the following route: `/v1/notifications` **Rest Request Parameters** The `createNotification` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationType | Enum | true | request.body?.notificationType | | userId | ID | true | request.body?.userId | | channel | Enum | true | request.body?.channel | | payload | Object | true | request.body?.payload | | isRead | Boolean | true | request.body?.isRead | **notificationType** : Type of event triggering notification (e.g., BID_UPDATED, ORDER_SHIPPED, MESSAGE_RECEIVED, etc.). Used for display/icon and query filter. **userId** : User receiving the notification (recipient). **channel** : Channel by which notification is delivered: IN_APP or EMAIL. **payload** : Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. **isRead** : Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/notifications** ```js axios({ method: 'POST', url: '/v1/notifications', data: { notificationType:"Enum", userId:"ID", channel:"Enum", payload:"Object", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Notification` API Updates a notification (mark as read/unread, payload patch for e.g. admin fix). Only receiver (userId) or admins may update. isRead is primary update scenario; others very limited. **Rest Route** The `updateNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `updateNotification` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | | payload | Object | false | request.body?.payload | | isRead | Boolean | false | request.body?.isRead | **notificationId** : This id paremeter is used to select the required data object that will be updated **payload** : Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. **isRead** : Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/notifications/:notificationId** ```js axios({ method: 'PATCH', url: `/v1/notifications/${notificationId}`, data: { payload:"Object", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Notifications` API Returns filtered list of notifications for a user, with optional filters: notificationType, isRead, channel. Always sorted by createdAt (descending) for in-app notifications. Only retrieval allowed for owner/admin. **Rest Route** The `listNotifications` API REST controller can be triggered via the following route: `/v1/notifications` **Rest Request Parameters** The `listNotifications` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/notifications** ```js axios({ method: 'GET', url: '/v1/notifications', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notifications", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "notifications": [ { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Notification` API Soft-delete a notification record. Only receiver or admin may delete. **Rest Route** The `deleteNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `deleteNotification` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | **notificationId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/notifications/:notificationId** ```js axios({ method: 'DELETE', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Notification` API Retrieves a notification for the receiver or admin. Used to populate content on detail/expanded view. **Rest Route** The `getNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `getNotification` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | **notificationId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/notifications/:notificationId** ```js axios({ method: 'GET', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## SearchIndexing Service Maintains the denormalized search index (materialized view) for global, public search across products, sellers, categories, and subcategories. Handles indexing in response to entity events and exposes optimized query endpoints for BFF/aggregator. ### SearchIndexing Service Data Objects **SearchIndex** Materialized/denormalized search index record for a marketplace entity (product, seller, category, subcategory). Used exclusively for high-speed querying in BFF global/public search. ### SearchIndexing Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/searchindexing-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/searchindexing-api` * **Production:** `https://ebaycclone.mindbricks.co/searchindexing-api` ### `List Searchindexes` API List/search search index entries by type or referenceId (used by BFF/global search). Always excludes inactive (soft-deleted) records. Supports filtering and full-text search filters by documentType/referenceId for admin/maintenance use. **Rest Route** The `listSearchIndexes` API REST controller can be triggered via the following route: `/v1/searchindexes` **Rest Request Parameters** The `listSearchIndexes` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchindexes** ```js axios({ method: 'GET', url: '/v1/searchindexes', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndices", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "searchIndices": [ { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Searchindex` API Update an existing searchIndex record (by (documentType, referenceId) or id). Used in response to events (entity edit, data change); internal/automation/admin only. **Rest Route** The `updateSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `updateSearchIndex` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | | documentType | Enum | false | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | false | request.body?.indexedAt | **searchIndexId** : This id paremeter is used to select the required data object that will be updated **documentType** : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY **document** : Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. **referenceId** : ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. **indexedAt** : Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/searchindexs/:searchIndexId** ```js axios({ method: 'PATCH', url: `/v1/searchindexs/${searchIndexId}`, data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Searchindex` API Soft-delete a searchIndex record (by id or by (documentType, referenceId)). Typical use: in response to entity soft-delete; internal/automation/admin only. **Rest Route** The `deleteSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `deleteSearchIndex` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | **searchIndexId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/searchindexs/:searchIndexId** ```js axios({ method: 'DELETE', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Searchindex` API Create a new searchIndex record (internal, used by event triggers and admin tools only). Typically called when a new product/seller/category/subcategory is created. **Rest Route** The `createSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs` **Rest Request Parameters** The `createSearchIndex` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | documentType | Enum | true | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | true | request.body?.indexedAt | **documentType** : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY **document** : Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. **referenceId** : ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. **indexedAt** : Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/searchindexs** ```js axios({ method: 'POST', url: '/v1/searchindexs', data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Searchindex` API Get a single denormalized index record (by id, or documentType+referenceId). Used by BFF for full entity search. Always excludes inactive records unless forced (admin only path). **Rest Route** The `getSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `getSearchIndex` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | **searchIndexId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchindexs/:searchIndexId** ```js axios({ method: 'GET', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## AdminModeration Service Administrative backend service for moderation and manual override actions. Responsible for logging all admin interventions (user/product/feedback/media/category/order/notification/searchindex moderation), triggering corrections via interservice calls, and providing comprehensive audit trails for compliance. ### AdminModeration Service Data Objects **ModerationAction** Audit record for all admin moderation/override actions affecting core business entities. Links to admin, timestamp, entity type/ID, action performed, and reason. ### AdminModeration Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/adminmoderation-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/adminmoderation-api` * **Production:** `https://ebaycclone.mindbricks.co/adminmoderation-api` ### `Get Moderationaction` API Get a single moderation action log by ID. Used to review admin audit trails; accessible only to platform admins. **Rest Route** The `getModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `getModerationAction` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | **moderationActionId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/moderationactions/:moderationActionId** ```js axios({ method: 'GET', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Moderationaction` API Soft-deletes a moderation action log record (dangerous; allowed only to superadmins or strict manual correction), primarily for audit correction or internal error cleanup. Usually, moderation logs are immutable. **Rest Route** The `deleteModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `deleteModerationAction` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | **moderationActionId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/moderationactions/:moderationActionId** ```js axios({ method: 'DELETE', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Moderationaction` API Logs an admin moderation or override action in the system for audit and traceability. Requires admin login, takes context from session, and creates an audit entry for any admin operation over any entity type. **Rest Route** The `createModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions` **Rest Request Parameters** The `createModerationAction` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | entityId | ID | true | request.body?.entityId | | entityType | Enum | true | request.body?.entityType | | reason | String | true | request.body?.reason | | actionType | Enum | true | request.body?.actionType | **entityId** : ID of target entity affected by moderation (user/product/etc). **entityType** : Type of entity affected (USER, PRODUCT, FEEDBACK, MEDIA, CATEGORY, NOTIFICATION, ORDER, SEARCHINDEX). **reason** : Explanation or justification for the moderation action performed. **actionType** : Type of moderation action (e.g., SOFT_DELETE, RESTORE, UPDATE_ROLE, MANUAL_CORRECTION, MEDIA_FLAG, INDEX_REBUILD, PAYMENT_FIX, FEEDBACK_OVERRIDE, ADMIN_NOTE). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/moderationactions** ```js axios({ method: 'POST', url: '/v1/moderationactions', data: { entityId:"ID", entityType:"Enum", reason:"String", actionType:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Moderationactions` API List moderation actions for admin dashboard/audit search. Supports filtering by admin, entityType, entityId, actionType, and date. Always sorted by most recent action. **Rest Route** The `listModerationActions` API REST controller can be triggered via the following route: `/v1/moderationactions` **Rest Request Parameters** The `listModerationActions` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/moderationactions** ```js axios({ method: 'GET', url: '/v1/moderationactions', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationActions", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "moderationActions": [ { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Moderationaction` API Allows update of explanation/note on a moderation action for correction (typically by admin or superadmin only). No entity/type/admin may be changed after creation; only 'reason' is editable for audit consistency. **Rest Route** The `updateModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `updateModerationAction` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | | reason | String | false | request.body?.reason | **moderationActionId** : This id paremeter is used to select the required data object that will be updated **reason** : Explanation or justification for the moderation action performed. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/moderationactions/:moderationActionId** ```js axios({ method: 'PATCH', url: `/v1/moderationactions/${moderationActionId}`, data: { reason:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## WatchlistCart Service Handles user watchlists (with custom folders) and shopping cart preparation for checkout, strictly enforcing only fixed-price products in carts, supporting item moves/bulk operations, and robust default/folder logic.. ### WatchlistCart Service Data Objects **WatchlistItem** Item in a user’s watchlist, optionally in a named folder; references product and user. **CartItem** Single product pending checkout in a user’s cart. Only fixed-price products permitted; quantity supported for multi-unit purchases (if allowed). **WatchlistList** A named folder/list in a user’s watchlist. Default list exists for all users. Custom lists may be created and deleted. ### WatchlistCart Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/watchlistcart-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/watchlistcart-api` * **Production:** `https://ebaycclone.mindbricks.co/watchlistcart-api` ### `List Watchlistlist` API List all lists in user’s watchlists. Supports listing by listId for folders. **Rest Route** The `listWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists` **Rest Request Parameters** The `listWatchlistList` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/watchlistlists** ```js axios({ method: 'GET', url: '/v1/watchlistlists', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Cartitems` API List all cart items for a user (pending checkout). **Rest Route** The `listCartItems` API REST controller can be triggered via the following route: `/v1/cartitems` **Rest Request Parameters** The `listCartItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/cartitems** ```js axios({ method: 'GET', url: '/v1/cartitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "price": "Double", "title": "String", "type": "Enum", "type_idx": "Integer", "mediaAssetIds": "ID" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Cartitem` API Remove an item from the user’s cart. **Rest Route** The `deleteCartItem` API REST controller can be triggered via the following route: `/v1/cartitems/:cartItemId` **Rest Request Parameters** The `deleteCartItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | **cartItemId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/cartitems/:cartItemId** ```js axios({ method: 'DELETE', url: `/v1/cartitems/${cartItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Watchlistitem` API Add product to user’s watchlist (default or target list/folder). One (user, product, list) per item enforced. Block duplicates. **Rest Route** The `createWatchlistItem` API REST controller can be triggered via the following route: `/v1/watchlistitems` **Rest Request Parameters** The `createWatchlistItem` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | productId | ID | true | request.body?.productId | | listId | ID | false | request.body?.listId | **addedAt** : Timestamp watchlist item created. **productId** : Referenced product in the watchlist. **listId** : Owning watchlistList; null if in default watchlist. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/watchlistitems** ```js axios({ method: 'POST', url: '/v1/watchlistitems', data: { addedAt:"Date", productId:"ID", listId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Watchlistitems` API List all products in user’s watchlists. Supports listing by listId for folders. **Rest Route** The `listWatchlistItems` API REST controller can be triggered via the following route: `/v1/watchlistitems` **Rest Request Parameters** The `listWatchlistItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/watchlistitems** ```js axios({ method: 'GET', url: '/v1/watchlistitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Cartitemquantity` API Change the quantity for a cart item. User must own the item. **Rest Route** The `updateCartItemQuantity` API REST controller can be triggered via the following route: `/v1/cartitemquantity/:cartItemId` **Rest Request Parameters** The `updateCartItemQuantity` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | | quantity | Integer | false | request.body?.quantity | **cartItemId** : This id paremeter is used to select the required data object that will be updated **quantity** : How many units (if product allows). **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/cartitemquantity/:cartItemId** ```js axios({ method: 'PATCH', url: `/v1/cartitemquantity/${cartItemId}`, data: { quantity:"Integer", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Watchlistlist` API Create a new custom watchlist folder. Name must be unique per user; ‘Default’ is reserved for system. **Rest Route** The `createWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists` **Rest Request Parameters** The `createWatchlistList` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | name | String | true | request.body?.name | **name** : Custom folder or list name. 'Default' is reserved (non-deletable for each user). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/watchlistlists** ```js axios({ method: 'POST', url: '/v1/watchlistlists', data: { name:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Watchlistlist` API Delete a custom watchlist (folder). Items are reassigned to user’s default list. Cannot delete default list. **Rest Route** The `deleteWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists/:watchlistListId` **Rest Request Parameters** The `deleteWatchlistList` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistListId | ID | true | request.params?.watchlistListId | **watchlistListId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistlists/:watchlistListId** ```js axios({ method: 'DELETE', url: `/v1/watchlistlists/${watchlistListId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Watchlistitem` API Remove a product from a user’s watchlist. **Rest Route** The `deleteWatchlistItem` API REST controller can be triggered via the following route: `/v1/watchlistitems/:watchlistItemId` **Rest Request Parameters** The `deleteWatchlistItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistItemId | ID | true | request.params?.watchlistItemId | **watchlistItemId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistitems/:watchlistItemId** ```js axios({ method: 'DELETE', url: `/v1/watchlistitems/${watchlistItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Cartitem` API Add an item to the user’s cart. Only fixed-price products allowed. Duplicates not permitted. **Rest Route** The `createCartItem` API REST controller can be triggered via the following route: `/v1/cartitems` **Rest Request Parameters** The `createCartItem` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | **addedAt** : Timestamp added to cart. **quantity** : How many units (if product allows). **productId** : Product being checked out. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/cartitems** ```js axios({ method: 'POST', url: '/v1/cartitems', data: { addedAt:"Date", quantity:"Integer", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Do Userwatchlist` API userwatchlist **Rest Route** The `userwatchlist` API REST controller can be triggered via the following route: `/v1/userwatchlist` **Rest Request Parameters** The `userwatchlist` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userwatchlist** ```js axios({ method: 'GET', url: '/v1/userwatchlist', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Usercartitems` API list all cart items adde by user **Rest Route** The `listUserCartItems` API REST controller can be triggered via the following route: `/v1/usercartitems` **Rest Request Parameters** The `listUserCartItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/usercartitems** ```js axios({ method: 'GET', url: '/v1/usercartitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "shipping": "Double" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Do Userwatchlistlists` API list all watch lists created by user **Rest Route** The `userwatchlistlists` API REST controller can be triggered via the following route: `/v1/userwatchlistlists` **Rest Request Parameters** The `userwatchlistlists` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userwatchlistlists** ```js axios({ method: 'GET', url: '/v1/userwatchlistlists', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ## ProductListing Service Handles product listings (both auction and fixed-price), image/media storage with validations, enforces immutable type, soft-delete, and public product discovery. ### ProductListing Service Data Objects **ProductListingMedia** Stores and manages images/media associated with products, including secure URL, MIME type, and size validation. Each asset can be used by multiple products. **ProductListingProduct** Represents a single product listing (fixed-price or auction) in the marketplace, with seller, category, type, price information, shipping details, media references, and dynamic auction fields. ### ProductListing Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/productlisting-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/productlisting-api` * **Production:** `https://ebaycclone.mindbricks.co/productlisting-api` ### `List Productlistingmedia` API List all media assets (admin or for media management/bulk preview). **Rest Route** The `listProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias` **Rest Request Parameters** The `listProductListingMedia` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias** ```js axios({ method: 'GET', url: '/v1/productlistingmedias', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedias", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingMedias": [ { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Productlistingproduct` API Get a single product listing. Checks isActive and public status. Includes media, category, subcategory, and seller info via joins. **Rest Route** The `getProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `getProductListingProduct` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | **productListingProductId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'GET', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Productlistingownproducts` API listing the loggedin user's products **Rest Route** The `listProductListingOwnProducts` API REST controller can be triggered via the following route: `/v1/productlistingownproducts` **Rest Request Parameters** The `listProductListingOwnProducts` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingownproducts** ```js axios({ method: 'GET', url: '/v1/productlistingownproducts', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Productlistingmedia` API Get a single media asset by ID (for admin or to display in product UI). **Rest Route** The `getProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` **Rest Request Parameters** The `getProductListingMedia` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | **productListingMediaId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'GET', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Productlistingproducts` API List public product listings. Only isActive=true records are returned. Includes category, subcategory, seller, media joins. Supports filtering. **Rest Route** The `listProductListingProducts` API REST controller can be triggered via the following route: `/v1/productlistingproducts` **Rest Request Parameters** The `listProductListingProducts` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts** ```js axios({ method: 'GET', url: '/v1/productlistingproducts', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Productlistingproduct` API Soft-delete a product listing. Only owner or admin can delete. **Rest Route** The `deleteProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `deleteProductListingProduct` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | **productListingProductId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'DELETE', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Productlistingproduct` API Update a product listing. Product type cannot be changed (immutable). **Rest Route** The `updateProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `updateProductListingProduct` api has got 21 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | | currency | String | false | request.body?.currency | | description | Text | false | request.body?.description | | condition | Enum | false | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | false | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | false | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | false | request.body?.shippingMethod | | shipping | Double | false | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | false | request.body?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | **productListingProductId** : This id paremeter is used to select the required data object that will be updated **currency** : ISO currency code (e.g. USD, EUR) **description** : Product detailed description **condition** : Condition of product: BRAND_NEW, NEW, or USED **startBid** : The opening bid value (for auction type products) **endPrice** : Optional immediate sale/upper end price for auction (if AUCTION type) **price** : Product price (required if fixed price type) **title** : Product title **startPrice** : Minimum starting price for auction (required if AUCTION type) **endBid** : The upper (max) bid value for auction products (if any) **estimatedDelivery** : Estimated delivery date for this product **shippingCurrency** : Currency code for shipping cost **mediaAssetIds** : References to associated product/media assets **shippingMethod** : Shipping option for product: STANDARD, EXPRESS, or FREE **shipping** : Shipping cost for this product **startBidDate** : Date/time when auction bidding begins **subcategoryId** : Reference to subcategory **categoryId** : Reference to parent category **endBidDate** : Date/time when auction bidding ends **currentBid** : Current highest bid for auction-type product (updated atomically on bid placement) **highestBidderId** : User ID of current highest bidder (auction-only, updated by auction microservice) **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'PATCH', url: `/v1/productlistingproducts/${productListingProductId}`, data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Productlistingproduct` API Create a new product listing (fixed or auction), conditioned on product type. Type is immutable after creation. **Rest Route** The `createProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts` **Rest Request Parameters** The `createProductListingProduct` api has got 21 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | description | Text | true | request.body?.description | | condition | Enum | true | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | true | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | type | Enum | true | request.body?.type | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | true | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | true | request.body?.shippingMethod | | shipping | Double | true | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | true | request.body?.subcategoryId | | categoryId | ID | true | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | **currency** : ISO currency code (e.g. USD, EUR) **description** : Product detailed description **condition** : Condition of product: BRAND_NEW, NEW, or USED **startBid** : The opening bid value (for auction type products) **endPrice** : Optional immediate sale/upper end price for auction (if AUCTION type) **price** : Product price (required if fixed price type) **title** : Product title **startPrice** : Minimum starting price for auction (required if AUCTION type) **type** : Product listing type, either FIXED or AUCTION (immutable after creation) **endBid** : The upper (max) bid value for auction products (if any) **estimatedDelivery** : Estimated delivery date for this product **shippingCurrency** : Currency code for shipping cost **mediaAssetIds** : References to associated product/media assets **shippingMethod** : Shipping option for product: STANDARD, EXPRESS, or FREE **shipping** : Shipping cost for this product **startBidDate** : Date/time when auction bidding begins **subcategoryId** : Reference to subcategory **categoryId** : Reference to parent category **endBidDate** : Date/time when auction bidding ends **currentBid** : Current highest bid for auction-type product (updated atomically on bid placement) **highestBidderId** : User ID of current highest bidder (auction-only, updated by auction microservice) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/productlistingproducts** ```js axios({ method: 'POST', url: '/v1/productlistingproducts', data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", type:"Enum", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Productlistingmedia` API Soft-delete a media asset (typically by admin or media owner for flagged/invalid content). **Rest Route** The `deleteProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` **Rest Request Parameters** The `deleteProductListingMedia` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | **productListingMediaId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'DELETE', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Productlistingmedia` API Create a new media asset record after validation. Used mainly by edge controller after upload. **Rest Route** The `createProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias` **Rest Request Parameters** The `createProductListingMedia` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | mimeType | String | true | request.body?.mimeType | | productId | ID | false | request.body?.productId | | url | String | true | request.body?.url | | size | Integer | true | request.body?.size | **mimeType** : MIME type of the uploaded media (e.g., image/jpeg) **productId** : ID of product associated with this media asset **url** : Secure, validated URL for the media asset (S3 or equivalent) **size** : Media size in bytes (for validation and quota) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/productlistingmedias** ```js axios({ method: 'POST', url: '/v1/productlistingmedias', data: { mimeType:"String", productId:"ID", url:"String", size:"Integer", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## OrderManagement Service Handles all marketplace orders, manual checkout flows for fixed-price/offer/auction settlements, Stripe payment processing and webhook reconciliation, explicit status updates (shipping, delivery, cancellation), and feedback eligibility via orderItems. ### OrderManagement Service Data Objects **OrderManagementOrder** Marketplace order record. Stores buyer, shipping, status, items, Stripe payment data, and manual shipment/delivery events. Only accessible to admins or the buyer/seller of order items. **OrderManagementOrderItem** Order line item representing purchase of a single product from a specific seller as part of an order. Enables feedback, delivery, and per-seller analytics. Immutable after order creation. **Sys_orderManagementOrderPayment** A payment storage object to store the payment life cyle of orders based on orderManagementOrder object. It is autocreated based on the source object's checkout config **Sys_paymentCustomer** A payment storage object to store the customer values of the payment platform **Sys_paymentMethod** A payment storage object to store the payment methods of the platform customers ### OrderManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/ordermanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/ordermanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/ordermanagement-api` ### `List Ordermanagementorders` API List orders, filtered for buyer and/or seller, or by admin. Includes select orderItems. **Rest Route** The `listOrderManagementOrders` API REST controller can be triggered via the following route: `/v1/ordermanagementorders` **Rest Request Parameters** The `listOrderManagementOrders` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ordermanagementorders', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Ordermanagementorderitem` API Get a specific order item (for feedback/business logic). **Rest Route** The `getOrderManagementOrderItem` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems/:orderManagementOrderItemId` **Rest Request Parameters** The `getOrderManagementOrderItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderItemId | ID | true | request.params?.orderManagementOrderItemId | **orderManagementOrderItemId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems/:orderManagementOrderItemId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderitems/${orderManagementOrderItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Ordermanagementorder` API Soft-delete/cancel order by admin or eligible actor prior to shipment. Sets status to CANCELLED and cancels active payment intent if pending. Irreversible and blocks feedback. **Rest Route** The `deleteOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` **Rest Request Parameters** The `deleteOrderManagementOrder` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorder` API Get single order by ID. Only accessible to admin, buyer, or relevant sellers of items within this order. Includes all orderItems. **Rest Route** The `getOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` **Rest Request Parameters** The `getOrderManagementOrder` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | **orderManagementOrderId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Ordermanagementorderstatus` API Update order status (manual shipment, delivery, cancellation/refund). Restricted: only seller of all items can mark as shipped, only buyer can confirm delivery, only admin can set refund/cancelled. Timestamps updated as per business rule. **Rest Route** The `updateOrderManagementOrderStatus` API REST controller can be triggered via the following route: `/v1/ordermanagementorderstatus/:orderManagementOrderId` **Rest Request Parameters** The `updateOrderManagementOrderStatus` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **status** : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderstatus/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderstatus/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Complete Orderstripewebhook` API Webhook endpoint called by Stripe to reconcile payment state and update order status based on paymentIntentId and event data. No authentication required (Stripe IPs only). **Rest Route** The `completeOrderStripeWebhook` API REST controller can be triggered via the following route: `/v1/completeorderstripewebhook/:orderManagementOrderId` **Rest Request Parameters** The `completeOrderStripeWebhook` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **status** : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/completeorderstripewebhook/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/completeorderstripewebhook/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderbyproductid` API get orders by productId **Rest Route** The `getOrderManagementOrderByProductId` API REST controller can be triggered via the following route: `/v1/ordermanagementorderbyproductid/:items` **Rest Request Parameters** The `getOrderManagementOrderByProductId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | items | String | true | request.params?.items | **orderManagementOrderId** : This id paremeter is used to query the required data object. **items** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderbyproductid/:items** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderbyproductid/${items}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Ordermanagementorder` API Creates an order and initiates Stripe payment. Validates that all products in the order are fixed-price, populates orderItems, saves Stripe customer/paymentMethod/paymentIntentId for reconciliation. Only accessible to buyers for own checkouts and only allows fixed-price product checkout (no auction). **Rest Route** The `createOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders` **Rest Request Parameters** The `createOrderManagementOrder` api has got 14 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderNumber | String | true | request.body?.orderNumber | | items | ID | false | request.body?.items | | paymentMethodId | String | true | request.body?.paymentMethodId | | stripeCustomerId | String | true | request.body?.stripeCustomerId | | paymentIntentId | String | false | request.body?.paymentIntentId | | shippingAddress | Object | true | request.body?.shippingAddress | | summary | Object | true | request.body?.summary | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderNumber** : Unique, human-friendly order number (displayed to users); enforced unique. **items** : Array of orderManagementOrderItem ids representing items in this order. **paymentMethodId** : Stripe paymentMethodId used for payment. Not stored if cash or other payment (future). **stripeCustomerId** : Stripe customerId of buyer; enables saved/paymentMethodId flows. **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **shippingAddress** : Shipping address for the order (copy of buyer address at purchase time). **summary** : Object with total, subtotal, currency, shipping, discount breakdown as snapshot of order at time of purchase. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorders** ```js axios({ method: 'POST', url: '/v1/ordermanagementorders', data: { orderNumber:"String", items:"ID", paymentMethodId:"String", stripeCustomerId:"String", paymentIntentId:"String", shippingAddress:"Object", summary:"Object", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderitems` API List order items for a given order or for buyer/seller analytics. Used for feedback management. **Rest Route** The `listOrderManagementOrderItems` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems` **Rest Request Parameters** The `listOrderManagementOrderItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Ownordermanagementorders` API list the loggedin user orders **Rest Route** The `listOwnOrderManagementOrders` API REST controller can be triggered via the following route: `/v1/ownordermanagementorders` **Rest Request Parameters** The `listOwnOrderManagementOrders` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ownordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ownordermanagementorders', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Lis Ordermanagementownorderitem` API list the loggedin user's order items **Rest Route** The `lisOrderManagementOwnOrderItem` API REST controller can be triggered via the following route: `/v1/lisordermanagementownorderitem` **Rest Request Parameters** The `lisOrderManagementOwnOrderItem` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/lisordermanagementownorderitem** ```js axios({ method: 'GET', url: '/v1/lisordermanagementownorderitem', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Ordermanagementorderitem` API create order item **Rest Route** The `createOrderManagementOrderItem` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems` **Rest Request Parameters** The `createOrderManagementOrderItem` api has got 8 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | shipping | Double | true | request.body?.shipping | | orderId | ID | true | request.body?.orderId | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | | price | Double | true | request.body?.price | | sellerId | ID | true | request.body?.sellerId | | title | String | true | request.body?.title | | currency | String | true | request.body?.currency | **shipping** : Shipping cost for this product (may be 0 for free shipping). **orderId** : Parent order this item belongs to; enables join and lifecycle tracking. **quantity** : Number of units purchased for this product. **productId** : ID of product purchased in this line item. **price** : Unit price for this product at purchase time. **sellerId** : UserId of seller (owner of product at purchase time). **title** : Product title at purchase time (copied for convenience/audit). **currency** : Currency code for price/shipping (ISO 4217). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderitems** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderitems', data: { shipping:"Double", orderId:"ID", quantity:"Integer", productId:"ID", price:"Double", sellerId:"ID", title:"String", currency:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpayment2` API This route is used to get the payment information by ID. **Rest Route** The `getOrderManagementOrderPayment2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `getOrderManagementOrderPayment2` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderpayments2` API This route is used to list all payments. **Rest Route** The `listOrderManagementOrderPayments2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayments2` **Rest Request Parameters** The `listOrderManagementOrderPayments2` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Ordermanagementorderpayment` API This route is used to create a new payment. **Rest Route** The `createOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment` **Rest Request Parameters** The `createOrderManagementOrderPayment` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderId | ID | true | request.body?.orderId | | paymentId | String | true | request.body?.paymentId | | paymentStatus | String | true | request.body?.paymentStatus | | statusLiteral | String | true | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | **orderId** : an ID value to represent the orderId which is the ID parameter of the source orderManagementOrder object **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderpayment', data: { orderId:"ID", paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Ordermanagementorderpayment` API This route is used to update an existing payment. **Rest Route** The `updateOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `updateOrderManagementOrderPayment` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | false | request.body?.paymentId | | paymentStatus | String | false | request.body?.paymentStatus | | statusLiteral | String | false | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | **sys_orderManagementOrderPaymentId** : This id paremeter is used to select the required data object that will be updated **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Ordermanagementorderpayment` API This route is used to delete a payment. **Rest Route** The `deleteOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `deleteOrderManagementOrderPayment` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderpayments2` API This route is used to list all payments. **Rest Route** The `listOrderManagementOrderPayments2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayments2` **Rest Request Parameters** The `listOrderManagementOrderPayments2` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Ordermanagementorderpaymentbyorderid` API This route is used to get the payment information by order id. **Rest Route** The `getOrderManagementOrderPaymentByOrderId` API REST controller can be triggered via the following route: `/v1/orderManagementOrderpaymentbyorderid/:orderId` **Rest Request Parameters** The `getOrderManagementOrderPaymentByOrderId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | orderId | String | true | request.params?.orderId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **orderId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbyorderid/:orderId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbyorderid/${orderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpaymentbypaymentid` API This route is used to get the payment information by payment id. **Rest Route** The `getOrderManagementOrderPaymentByPaymentId` API REST controller can be triggered via the following route: `/v1/orderManagementOrderpaymentbypaymentid/:paymentId` **Rest Request Parameters** The `getOrderManagementOrderPaymentByPaymentId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | true | request.params?.paymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **paymentId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbypaymentid/:paymentId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbypaymentid/${paymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpayment2` API This route is used to get the payment information by ID. **Rest Route** The `getOrderManagementOrderPayment2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `getOrderManagementOrderPayment2` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Start Ordermanagementorderpayment` API Start payment for orderManagementOrder **Rest Route** The `startOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/startordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `startOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to start a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/startordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/startordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Refresh Ordermanagementorderpayment` API Refresh payment info for orderManagementOrder from Stripe **Rest Route** The `refreshOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/refreshordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `refreshOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to refresh a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/refreshordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/refreshordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Callback Ordermanagementorderpayment` API Refresh payment values by gateway webhook call for orderManagementOrder **Rest Route** The `callbackOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/callbackordermanagementorderpayment` **Rest Request Parameters** The `callbackOrderManagementOrderPayment` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.body?.orderManagementOrderId | **orderManagementOrderId** : The order id parameter that will be read from webhook callback params **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/callbackordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/callbackordermanagementorderpayment', data: { orderManagementOrderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Get Paymentcustomerbyuserid` API This route is used to get the payment customer information by user id. **Rest Route** The `getPaymentCustomerByUserId` API REST controller can be triggered via the following route: `/v1/paymentcustomers/:userId` **Rest Request Parameters** The `getPaymentCustomerByUserId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_paymentCustomerId | ID | true | request.params?.sys_paymentCustomerId | | userId | String | true | request.params?.userId | **sys_paymentCustomerId** : This id paremeter is used to query the required data object. **userId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomers/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_paymentCustomer": { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Paymentcustomers` API This route is used to list all payment customers. **Rest Route** The `listPaymentCustomers` API REST controller can be triggered via the following route: `/v1/paymentcustomers` **Rest Request Parameters** The `listPaymentCustomers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers** ```js axios({ method: 'GET', url: '/v1/paymentcustomers', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentCustomers": [ { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Paymentcustomermethods` API This route is used to list all payment customer methods. **Rest Route** The `listPaymentCustomerMethods` API REST controller can be triggered via the following route: `/v1/paymentcustomermethods/:userId` **Rest Request Parameters** The `listPaymentCustomerMethods` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | String | true | request.params?.userId | **userId** : This parameter will be used to select the data objects that want to be listed **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomermethods/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomermethods/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentMethods", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentMethods": [ { "id": "ID", "paymentMethodId": "String", "userId": "ID", "customerId": "String", "cardHolderName": "String", "cardHolderZip": "String", "platform": "String", "cardInfo": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ## Feedback Service Handles feedback for order items: one feedback per buyer/orderItem, attached to sellerId for analytical feedback/rating aggregation and reputation tracking. Enables querying feedbacks received/given for sellers and buyers. test ### Feedback Service Data Objects **Feedback** One feedback per (buyer, orderItem). Stores rating (1-5), comment, ties to seller for analytics. Created only after delivery confirmed on order item. ### Feedback Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/feedback-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/feedback-api` * **Production:** `https://ebaycclone.mindbricks.co/feedback-api` ### `List Feedbacks` API List feedback with filtering by buyerId (given), sellerId (received), productId, or orderItemId. Used for showing seller profile, buyer profile, or order analytics. **Rest Route** The `listFeedbacks` API REST controller can be triggered via the following route: `/v1/feedbacks` **Rest Request Parameters** The `listFeedbacks` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/feedbacks** ```js axios({ method: 'GET', url: '/v1/feedbacks', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedbacks", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "feedbacks": [ { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Feedback` API Get a single feedback by id. Accessible to public (for seller profile, product, or audit views). **Rest Route** The `getFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `getFeedback` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | **feedbackId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/feedbacks/:feedbackId** ```js axios({ method: 'GET', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Feedback` API Update feedback (comment/rating) for existing feedback record (buyer only). Admin can update as override. **Rest Route** The `updateFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `updateFeedback` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | | rating | Integer | false | request.body?.rating | | comment | String | false | request.body?.comment | **feedbackId** : This id paremeter is used to select the required data object that will be updated **rating** : Rating (1-5 stars) submitted by buyer. Required. **comment** : Optional textual feedback comment, max ~500 chars. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/feedbacks/:feedbackId** ```js axios({ method: 'PATCH', url: `/v1/feedbacks/${feedbackId}`, data: { rating:"Integer", comment:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Feedback` API Delete (soft-delete) feedback (by buyer or admin). Only feedback owner or admin. **Rest Route** The `deleteFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `deleteFeedback` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | **feedbackId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/feedbacks/:feedbackId** ```js axios({ method: 'DELETE', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Feedback` API Buyer creates feedback for a delivered order item. Only allowed once per (buyer, orderItemId). Allowed only once order item is delivered. **Rest Route** The `createFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks` **Rest Request Parameters** The `createFeedback` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | rating | Integer | true | request.body?.rating | | orderId | ID | true | request.body?.orderId | | orderItemId | ID | true | request.body?.orderItemId | | sellerId | ID | true | request.body?.sellerId | | comment | String | false | request.body?.comment | | productId | ID | true | request.body?.productId | **rating** : Rating (1-5 stars) submitted by buyer. Required. **orderId** : Order containing this purchased item. Used for aggregation and validation. **orderItemId** : Purchased item (line item) in order. Feedback is per (buyer, orderItem). **sellerId** : Seller of product for analytics/aggregation. Not author; used for querying feedback about sellers. **comment** : Optional textual feedback comment, max ~500 chars. **productId** : The product listing being reviewed (snapshot at order time). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/feedbacks** ```js axios({ method: 'POST', url: '/v1/feedbacks', data: { rating:"Integer", orderId:"ID", orderItemId:"ID", sellerId:"ID", comment:"String", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # REST API GUIDE ## ebaycclone-productlisting-service Handles product listings (both auction and fixed-price), image/media storage with validations, enforces immutable type, soft-delete, and public product discovery. ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to: Email: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. ## Documentation Scope Welcome to the official documentation for the ProductListing Service's REST API. This document is designed to provide a comprehensive guide to interfacing with our ProductListing Service exclusively through RESTful API endpoints. **Intended Audience** This documentation is intended for developers and integrators who are looking to interact with the ProductListing Service via HTTP requests for purposes such as creating, updating, deleting and querying ProductListing objects. **Overview** Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases. Beyond REST It's important to note that the ProductListing Service also supports alternative methods of interaction, such as gRPC and messaging via a Message Broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation. ## Authentication And Authorization To ensure secure access to the ProductListing service's protected endpoints, a project-wide access token is required. This token serves as the primary method for authenticating requests to our service. However, it's important to note that access control varies across different routes: **Protected API**: Certain API (routes) require specific authorization levels. Access to these routes is contingent upon the possession of a valid access token that meets the route-specific authorization criteria. Unauthorized requests to these routes will be rejected. **Public API **: The service also includes public API (routes) that are accessible without authentication. These public endpoints are designed for open access and do not require an access token. ### Token Locations When including your access token in a request, ensure it is placed in one of the following specified locations. The service will sequentially search these locations for the token, utilizing the first one it encounters. | Location | Token Name / Param Name | | ---------------------- | ---------------------------- | | Query | access_token | | Authorization Header | Bearer | | Header | ebaycclone-access-token| | Cookie | ebaycclone-access-token| Please ensure the token is correctly placed in one of these locations, using the appropriate label as indicated. The service prioritizes these locations in the order listed, processing the first token it successfully identifies. ## Api Definitions This section outlines the API endpoints available within the ProductListing service. Each endpoint can receive parameters through various methods, meticulously described in the following definitions. It's important to understand the flexibility in how parameters can be included in requests to effectively interact with the ProductListing service. This service is configured to listen for HTTP requests on port `3001`, serving both the main API interface and default administrative endpoints. The following routes are available by default: * **API Test Interface (API Face):** `/` * **Swagger Documentation:** `/swagger` * **Postman Collection Download:** `/getPostmanCollection` * **Health Checks:** `/health` and `/admin/health` * **Current Session Info:** `/currentuser` * **Favicon:** `/favicon.ico` This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/productlisting-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/productlisting-api` * **Production:** `https://ebaycclone.mindbricks.co/productlisting-api` **Parameter Inclusion Methods:** Parameters can be incorporated into API requests in several ways, each with its designated location. Understanding these methods is crucial for correctly constructing your requests: **Query Parameters:** Included directly in the URL's query string. **Path Parameters:** Embedded within the URL's path. **Body Parameters:** Sent within the JSON body of the request. **Session Parameters:** Automatically read from the session object. This method is used for parameters that are intrinsic to the user's session, such as userId. When using an API that involves session parameters, you can omit these from your request. The service will automatically bind them to the API layer, provided that a session is associated with your request. **Note on Session Parameters:** Session parameters represent a unique method of parameter inclusion, relying on the context of the user's session. A common example of a session parameter is userId, which the service automatically associates with your request when a session exists. This feature ensures seamless integration of user-specific data without manual input for each request. By adhering to the specified parameter inclusion methods, you can effectively utilize the ProductListing service's API endpoints. For detailed information on each endpoint, including required parameters and their accepted locations, refer to the individual API definitions below. ### Common Parameters The `ProductListing` service's business API support several common parameters designed to modify and enhance the behavior of API requests. These parameters are not individually listed in the API route definitions to avoid repetition. Instead, refer to this section to understand how to leverage these common behaviors across different routes. Note that all common parameters should be included in the query part of the URL. ### Supported Common Parameters: - **getJoins (BOOLEAN)**: Controls whether to retrieve associated objects along with the main object. By default, `getJoins` is assumed to be `true`. Set it to `false` if you prefer to receive only the main fields of an object, excluding its associations. - **excludeCQRS (BOOLEAN)**: Applicable only when `getJoins` is `true`. By default, `excludeCQRS` is set to `false`. Enabling this parameter (`true`) omits non-local associations, which are typically more resource-intensive as they require querying external services like ElasticSearch for additional information. Use this to optimize response times and resource usage. - **requestId (String)**: Identifies a request to enable tracking through the service's log chain. A random hex string of 32 characters is assigned by default. If you wish to use a custom `requestId`, simply include it in your query parameters. - **caching (BOOLEAN)**: Determines the use of caching for query API. By default, caching is enabled (`true`). To ensure the freshest data directly from the database, set this parameter to `false`, bypassing the cache. - **cacheTTL (Integer)**: Specifies the Time-To-Live (TTL) for query caching, in seconds. This is particularly useful for adjusting the default caching duration (5 minutes) for `get list` queries. Setting a custom `cacheTTL` allows you to fine-tune the cache lifespan to meet your needs. - **pageNumber (Integer)**: For paginated `get list` API's, this parameter selects which page of results to retrieve. The default is `1`, indicating the first page. To disable pagination and retrieve all results, set `pageNumber` to `0`. - **pageRowCount (Integer)**: In conjunction with paginated API's, this parameter defines the number of records per page. The default value is `25`. Adjusting `pageRowCount` allows you to control the volume of data returned in a single request. By utilizing these common parameters, you can tailor the behavior of API requests to suit your specific requirements, ensuring optimal performance and usability of the `ProductListing` service. ### Error Response If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity: - **400 Bad Request**: The request was improperly formatted or contained invalid parameters, preventing the server from processing it. - **401 Unauthorized**: The request lacked valid authentication credentials or the credentials provided do not grant access to the requested resource. - **404 Not Found**: The requested resource was not found on the server. - **500 Internal Server Error**: The server encountered an unexpected condition that prevented it from fulfilling the request. Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ### Object Structure of a Successfull Response When the `ProductListing` service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client. **Key Characteristics of the Response Envelope:** - **Data Presentation**: Depending on the nature of the request, the service returns either a single data object or an array of objects encapsulated within the JSON envelope. - **Creation and Update API**: These API routes return the unmodified (pure) form of the data object(s), without any associations to other data objects. - **Delete API**: Even though the data is removed from the database, the last known state of the data object(s) is returned in its pure form. - **Get Requests**: A single data object is returned in JSON format. - **Get List Requests**: An array of data objects is provided, reflecting a collection of resources. - **Data Structure and Joins**: The complexity of the data structure in the response can vary based on the API's architectural design and the join options specified in the request. The architecture might inherently limit join operations, or they might be dynamically controlled through query parameters. - **Pure Data Forms**: In some cases, the response mirrors the exact structure found in the primary data table, without extensions. - **Extended Data Forms**: Alternatively, responses might include data extended through joins with tables within the same service or aggregated from external sources, such as ElasticSearch indices related to other services. - **Join Varieties**: The extensions might involve one-to-one joins, resulting in single object associations, or one-to-many joins, leading to an array of objects. In certain instances, the data might even feature nested inclusions from other data objects. **Design Considerations**: The structure of a API's response data is meticulously crafted during the service's architectural planning. This design ensures that responses adequately reflect the intended data relationships and service logic, providing clients with rich and meaningful information. **Brief Data**: Certain API's return a condensed version of the object data, intentionally selecting only specific fields deemed useful for that request. In such instances, the API documentation will detail the properties included in the response, guiding developers on what to expect. ### API Response Structure The API utilizes a standardized JSON envelope to encapsulate responses. This envelope is designed to consistently deliver both the requested data and essential metadata, ensuring that clients can efficiently interpret and utilize the response. **HTTP Status Codes:** - **200 OK**: This status code is returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request has been processed successfully. - **201 Created**: This status code is specific to CREATE operations, signifying that the requested resource has been successfully created. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling the successful execution of the request. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3 "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` - **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation performed. **Handling Errors:** For details on handling error scenarios and understanding the structure of error responses, please refer to the "Error Response" section provided earlier in this documentation. It outlines how error conditions are communicated, including the use of HTTP status codes and standardized JSON structures for error messages. ## Resources ProductListing service provides the following resources which are stored in its own database as a data object. Note that a resource for an api access is a data object for the service. ### ProductListingMedia resource *Resource Definition* : Stores and manages images/media associated with products, including secure URL, MIME type, and size validation. Each asset can be used by multiple products. *ProductListingMedia Resource Properties* | Name | Type | Required | Default | Definition | | ---- | ---- | -------- | ------- | ---------- | | **mimeType** | String | | | *MIME type of the uploaded media (e.g., image/jpeg)* | | **productId** | ID | | | *ID of product associated with this media asset* | | **url** | String | | | *Secure, validated URL for the media asset (S3 or equivalent)* | | **size** | Integer | | | *Media size in bytes (for validation and quota)* | ### ProductListingProduct resource *Resource Definition* : Represents a single product listing (fixed-price or auction) in the marketplace, with seller, category, type, price information, shipping details, media references, and dynamic auction fields. *ProductListingProduct Resource Properties* | Name | Type | Required | Default | Definition | | ---- | ---- | -------- | ------- | ---------- | | **currency** | String | | | *ISO currency code (e.g. USD, EUR)* | | **description** | Text | | | *Product detailed description* | | **condition** | Enum | | | *Condition of product: BRAND_NEW, NEW, or USED* | | **startBid** | Double | | | *The opening bid value (for auction type products)* | | **endPrice** | Double | | | *Optional immediate sale/upper end price for auction (if AUCTION type)* | | **price** | Double | | | *Product price (required if fixed price type)* | | **title** | String | | | *Product title* | | **startPrice** | Double | | | *Minimum starting price for auction (required if AUCTION type)* | | **type** | Enum | | | *Product listing type, either FIXED or AUCTION (immutable after creation)* | | **endBid** | Double | | | *The upper (max) bid value for auction products (if any)* | | **estimatedDelivery** | Date | | | *Estimated delivery date for this product* | | **shippingCurrency** | String | | | *Currency code for shipping cost* | | **sellerId** | ID | | | *Reference to user who listed the product* | | **mediaAssetIds** | ID | | | *References to associated product/media assets* | | **shippingMethod** | Enum | | | *Shipping option for product: STANDARD, EXPRESS, or FREE* | | **shipping** | Double | | | *Shipping cost for this product* | | **startBidDate** | Date | | | *Date/time when auction bidding begins* | | **subcategoryId** | ID | | | *Reference to subcategory* | | **categoryId** | ID | | | *Reference to parent category* | | **endBidDate** | Date | | | *Date/time when auction bidding ends* | | **currentBid** | Double | | | *Current highest bid for auction-type product (updated atomically on bid placement)* | | **highestBidderId** | ID | | | *User ID of current highest bidder (auction-only, updated by auction microservice)* | #### Enum Properties Enum properties are represented as strings in the database. The values are mapped to their corresponding names in the application layer. ##### condition Enum Property *Property Definition* : Condition of product: BRAND_NEW, NEW, or USED*Enum Options* | Name | Value | Index | | ---- | ----- | ----- | | **BRAND_NEW** | `"BRAND_NEW""` | 0 | | **NEW** | `"NEW""` | 1 | | **USED** | `"USED""` | 2 | ##### type Enum Property *Property Definition* : Product listing type, either FIXED or AUCTION (immutable after creation)*Enum Options* | Name | Value | Index | | ---- | ----- | ----- | | **FIXED** | `"FIXED""` | 0 | | **AUCTION** | `"AUCTION""` | 1 | ##### shippingMethod Enum Property *Property Definition* : Shipping option for product: STANDARD, EXPRESS, or FREE*Enum Options* | Name | Value | Index | | ---- | ----- | ----- | | **STANDARD** | `"STANDARD""` | 0 | | **EXPRESS** | `"EXPRESS""` | 1 | | **FREE** | `"FREE""` | 2 | ## Business Api ### List Productlistingmedia API *API Definition* : List all media assets (admin or for media management/bulk preview). *API Crud Type* : list *Default access route* : *GET* `/v1/productlistingmedias` The listProductListingMedia api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias** ```js axios({ method: 'GET', url: '/v1/productlistingmedias', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`productListingMedias`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingMedias","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","productListingMedias":[{"id":"ID","mimeType":"String","productId":"ID","url":"String","size":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For List Productlistingmedia](businessApi/listProductListingMedia). ### Get Productlistingproduct API *API Definition* : Get a single product listing. Checks isActive and public status. Includes media, category, subcategory, and seller info via joins. *API Crud Type* : get *Default access route* : *GET* `/v1/productlistingproducts/:productListingProductId` #### Parameters The getProductListingProduct api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'GET', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`productListingProduct`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingProduct","method":"GET","action":"get","appVersion":"Version","rowCount":1,"productListingProduct":{"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Get Productlistingproduct](businessApi/getProductListingProduct). ### List Productlistingownproducts API *API Definition* : listing the loggedin user's products *API Crud Type* : list *Default access route* : *GET* `/v1/productlistingownproducts` The listProductListingOwnProducts api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/productlistingownproducts** ```js axios({ method: 'GET', url: '/v1/productlistingownproducts', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`productListingProducts`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingProducts","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","productListingProducts":[{"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For List Productlistingownproducts](businessApi/listProductListingOwnProducts). ### Get Productlistingmedia API *API Definition* : Get a single media asset by ID (for admin or to display in product UI). *API Crud Type* : get *Default access route* : *GET* `/v1/productlistingmedias/:productListingMediaId` #### Parameters The getProductListingMedia api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'GET', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`productListingMedia`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingMedia","method":"GET","action":"get","appVersion":"Version","rowCount":1,"productListingMedia":{"id":"ID","mimeType":"String","productId":"ID","url":"String","size":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Get Productlistingmedia](businessApi/getProductListingMedia). ### List Productlistingproducts API *API Definition* : List public product listings. Only isActive=true records are returned. Includes category, subcategory, seller, media joins. Supports filtering. *API Crud Type* : list *Default access route* : *GET* `/v1/productlistingproducts` The listProductListingProducts api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts** ```js axios({ method: 'GET', url: '/v1/productlistingproducts', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`productListingProducts`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingProducts","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","productListingProducts":[{"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For List Productlistingproducts](businessApi/listProductListingProducts). ### Delete Productlistingproduct API *API Definition* : Soft-delete a product listing. Only owner or admin can delete. *API Crud Type* : delete *Default access route* : *DELETE* `/v1/productlistingproducts/:productListingProductId` #### Parameters The deleteProductListingProduct api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'DELETE', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`productListingProduct`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingProduct","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"productListingProduct":{"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Delete Productlistingproduct](businessApi/deleteProductListingProduct). ### Update Productlistingproduct API *API Definition* : Update a product listing. Product type cannot be changed (immutable). *API Crud Type* : update *Default access route* : *PATCH* `/v1/productlistingproducts/:productListingProductId` #### Parameters The updateProductListingProduct api has got 21 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | | currency | String | false | request.body?.currency | | description | Text | false | request.body?.description | | condition | Enum | false | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | false | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | false | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | false | request.body?.shippingMethod | | shipping | Double | false | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | false | request.body?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | To access the api you can use the **REST** controller with the path **PATCH /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'PATCH', url: `/v1/productlistingproducts/${productListingProductId}`, data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`productListingProduct`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingProduct","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"productListingProduct":{"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Update Productlistingproduct](businessApi/updateProductListingProduct). ### Create Productlistingproduct API *API Definition* : Create a new product listing (fixed or auction), conditioned on product type. Type is immutable after creation. *API Crud Type* : create *Default access route* : *POST* `/v1/productlistingproducts` #### Parameters The createProductListingProduct api has got 21 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | description | Text | true | request.body?.description | | condition | Enum | true | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | true | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | type | Enum | true | request.body?.type | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | true | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | true | request.body?.shippingMethod | | shipping | Double | true | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | true | request.body?.subcategoryId | | categoryId | ID | true | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | To access the api you can use the **REST** controller with the path **POST /v1/productlistingproducts** ```js axios({ method: 'POST', url: '/v1/productlistingproducts', data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", type:"Enum", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`productListingProduct`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingProduct","method":"POST","action":"create","appVersion":"Version","rowCount":1,"productListingProduct":{"id":"ID","currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","startBid":"Double","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","endBid":"Double","estimatedDelivery":"Date","shippingCurrency":"String","sellerId":"ID","mediaAssetIds":"ID","shippingMethod":"Enum","shippingMethod_idx":"Integer","shipping":"Double","startBidDate":"Date","subcategoryId":"ID","categoryId":"ID","endBidDate":"Date","currentBid":"Double","highestBidderId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Create Productlistingproduct](businessApi/createProductListingProduct). ### Delete Productlistingmedia API *API Definition* : Soft-delete a media asset (typically by admin or media owner for flagged/invalid content). *API Crud Type* : delete *Default access route* : *DELETE* `/v1/productlistingmedias/:productListingMediaId` #### Parameters The deleteProductListingMedia api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'DELETE', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`productListingMedia`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingMedia","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"productListingMedia":{"id":"ID","mimeType":"String","productId":"ID","url":"String","size":"Integer","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Delete Productlistingmedia](businessApi/deleteProductListingMedia). ### Create Productlistingmedia API *API Definition* : Create a new media asset record after validation. Used mainly by edge controller after upload. *API Crud Type* : create *Default access route* : *POST* `/v1/productlistingmedias` #### Parameters The createProductListingMedia api has got 4 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | mimeType | String | true | request.body?.mimeType | | productId | ID | false | request.body?.productId | | url | String | true | request.body?.url | | size | Integer | true | request.body?.size | To access the api you can use the **REST** controller with the path **POST /v1/productlistingmedias** ```js axios({ method: 'POST', url: '/v1/productlistingmedias', data: { mimeType:"String", productId:"ID", url:"String", size:"Integer", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`productListingMedia`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"productListingMedia","method":"POST","action":"create","appVersion":"Version","rowCount":1,"productListingMedia":{"id":"ID","mimeType":"String","productId":"ID","url":"String","size":"Integer","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Create Productlistingmedia](businessApi/createProductListingMedia). ### Authentication Specific Routes ### Common Routes ### Route: currentuser *Route Definition*: Retrieves the currently authenticated user's session information. *Route Type*: sessionInfo *Access Route*: `GET /currentuser` #### Parameters This route does **not** require any request parameters. #### Behavior - Returns the authenticated session object associated with the current access token. - If no valid session exists, responds with a 401 Unauthorized. ```js // Sample GET /currentuser call axios.get("/currentuser", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** Returns the session object, including user-related data and token information. ``` { "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", "roleId": "user", "tenantId": "abc123", "accessToken": "jwt-token-string", ... } ``` **Error Response** **401 Unauthorized:** No active session found. ``` { "status": "ERR", "message": "No login found" } ``` **Notes** * This route is typically used by frontend or mobile applications to fetch the current session state after login. * The returned session includes key user identity fields, tenant information (if applicable), and the access token for further authenticated requests. * Always ensure a valid access token is provided in the request to retrieve the session. ### Route: permissions `*Route Definition*`: Retrieves all effective permission records assigned to the currently authenticated user. `*Route Type*`: permissionFetch *Access Route*: `GET /permissions` #### Parameters This route does **not** require any request parameters. #### Behavior - Fetches all active permission records (`givenPermissions` entries) associated with the current user session. - Returns a full array of permission objects. - Requires a valid session (`access token`) to be available. ```js // Sample GET /permissions call axios.get("/permissions", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** Returns an array of permission objects. ```json [ { "id": "perm1", "permissionName": "adminPanel.access", "roleId": "admin", "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" }, { "id": "perm2", "permissionName": "orders.manage", "roleId": null, "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" } ] ``` Each object reflects a single permission grant, aligned with the givenPermissions model: - `**permissionName**`: The permission the user has. - `**roleId**`: If the permission was granted through a role. -` **subjectUserId**`: If directly granted to the user. - `**subjectUserGroupId**`: If granted through a group. - `**objectId**`: If tied to a specific object (OBAC). - `**canDo**`: True or false flag to represent if permission is active or restricted. **Error Responses** * **401 Unauthorized**: No active session found. ```json { "status": "ERR", "message": "No login found" } ``` * **500 Internal Server Error**: Unexpected error fetching permissions. **Notes** * The /permissions route is available across all backend services generated by Mindbricks, not just the auth service. * Auth service: Fetches permissions freshly from the live database (givenPermissions table). * Other services: Typically use a cached or projected view of permissions stored in a common ElasticSearch store, optimized for faster authorization checks. > **Tip**: > Applications can cache permission results client-side or server-side, but should occasionally refresh by calling this endpoint, especially after login or permission-changing operations. ### Route: permissions/:permissionName *Route Definition*: Checks whether the current user has access to a specific permission, and provides a list of scoped object exceptions or inclusions. *Route Type*: permissionScopeCheck *Access Route*: `GET /permissions/:permissionName` #### Parameters | Parameter | Type | Required | Population | |------------------|--------|----------|------------------------| | permissionName | String | Yes | `request.params.permissionName` | #### Behavior - Evaluates whether the current user **has access** to the given `permissionName`. - Returns a structured object indicating: - Whether the permission is generally granted (`canDo`) - Which object IDs are explicitly included or excluded from access (`exceptions`) - Requires a valid session (`access token`). ```js // Sample GET /permissions/orders.manage axios.get("/permissions/orders.manage", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** ```json { "canDo": true, "exceptions": [ "a1f2e3d4-xxxx-yyyy-zzzz-object1", "b2c3d4e5-xxxx-yyyy-zzzz-object2" ] } ``` * If `canDo` is `true`, the user generally has the permission, but not for the objects listed in `exceptions` (i.e., restrictions). * If `canDo` is `false`, the user does not have the permission by default — but only for the objects in `exceptions`, they do have permission (i.e., selective overrides). * The exceptions array contains valid **UUID strings**, each corresponding to an object ID (typically from the data model targeted by the permission). ## Copyright All sources, documents and other digital materials are copyright of . ## About Us For more information please visit our website: . . . # Service Design Specification **ebaycclone-productlisting-service** documentation -Version:**`1.0.2`** ## Scope This document provides a structured architectural overview of the `productListing` microservice, detailing its configuration, data model, authorization logic, business rules, and API design. It has been automatically generated based on the service definition within Mindbricks, ensuring that the information reflects the source of truth used during code generation and deployment. The document is intended to serve multiple audiences: * **Service architects** can use it to validate design decisions and ensure alignment with broader architectural goals. * **Developers and maintainers** will find it useful for understanding the structure and behavior of the service, facilitating easier debugging, feature extension, and integration with other systems. * **Stakeholders and reviewers** can use it to gain a clear understanding of the service's capabilities and domain logic. > **Note for Frontend Developers**: While this document is valuable for understanding business logic and data interactions, please refer to the [Service API Documentation](#) for endpoint-level specifications and integration details. > **Note for Backend Developers**: Since the code for this service is automatically generated by Mindbricks, you typically won't need to implement or modify it manually. However, this document is especially valuable when you're building other services—whether within Mindbricks or externally—that need to interact with or depend on this service. It provides a clear reference to the service's data contracts, business rules, and API structure, helping ensure compatibility and correct integration. ## `ProductListing` Service Settings [**Edit**](productlisting/serviceSettings) Handles product listings (both auction and fixed-price), image/media storage with validations, enforces immutable type, soft-delete, and public product discovery. ### Service Overview This service is configured to listen for HTTP requests on port `3001`, serving both the main API interface and default administrative endpoints. The following routes are available by default: * **API Test Interface (API Face):** `/` * **Swagger Documentation:** `/swagger` * **Postman Collection Download:** `/getPostmanCollection` * **Health Checks:** `/health` and `/admin/health` * **Current Session Info:** `/currentuser` * **Favicon:** `/favicon.ico` The service uses a **PostgreSQL** database for data storage, with the database name set to `ebaycclone-productlisting-service`. This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/productlisting-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/productlisting-api` * **Production:** `https://ebaycclone.mindbricks.co/productlisting-api` ### Authentication & Security - **Login Required**: Yes This service requires user authentication for access. It supports both JWT and RSA-based authentication mechanisms, ensuring secure user sessions and data integrity. If a crud route also is configured to require login, it will check a valid JWT token in the request query/header/bearer/cookie. If the token is valid, it will extract the user information from the token and make the fetched session data available in the request context. ### Service Data Objects The service uses a **PostgreSQL** database for data storage, with the database name set to `ebaycclone-productlisting-service`. Data deletion is managed using a **soft delete** strategy. Instead of removing records from the database, they are flagged as inactive by setting the `isActive` field to `false`. | Object Name | Description | Public Access | |-------------|-------------|---------------| | `productListingMedia` | Stores and manages images/media associated with products, including secure URL, MIME type, and size validation. Each asset can be used by multiple products. | accessProtected | | `productListingProduct` | Represents a single product listing (fixed-price or auction) in the marketplace, with seller, category, type, price information, shipping details, media references, and dynamic auction fields. | accessProtected | ## productListingMedia Data Object ### Object Overview **Description:** Stores and manages images/media associated with products, including secure URL, MIME type, and size validation. Each asset can be used by multiple products. This object represents a core data structure within the service and acts as the blueprint for database interaction, API generation, and business logic enforcement. It is defined using the `ObjectSettings` pattern, which governs its behavior, access control, caching strategy, and integration points with other systems such as Stripe and Redis. ### Core Configuration - **Soft Delete:** Enabled — Determines whether records are marked inactive (`isActive = false`) instead of being physically deleted. - **Public Access:** accessProtected — If enabled, anonymous users may access this object’s data depending on API-level rules. ### Properties Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `mimeType` | String | Yes | MIME type of the uploaded media (e.g., image/jpeg) | | `productId` | ID | No | ID of product associated with this media asset | | `url` | String | Yes | Secure, validated URL for the media asset (S3 or equivalent) | | `size` | Integer | Yes | Media size in bytes (for validation and quota) | * Required properties are mandatory for creating objects and must be provided in the request body if no default value is set. ### Default Values Default values are automatically assigned to properties when a new object is created, if no value is provided in the request body. Since default values are applied on db level, they should be literal values, not expressions.If you want to use expressions, you can use transposed parameters in any business API to set default values dynamically. - **mimeType**: 'default' - **url**: 'default' - **size**: 0 ### Constant Properties `mimeType` `url` `size` Constant properties are defined to be immutable after creation, meaning they cannot be updated or changed once set. They are typically used for properties that should remain constant throughout the object's lifecycle. A property is set to be constant if the `Allow Update` option is set to `false`. ### Auto Update Properties `mimeType` `productId` `url` `size` An update crud API created with the option `Auto Params` enabled will automatically update these properties with the provided values in the request body. If you want to update any property in your own business logic not by user input, you can set the `Allow Auto Update` option to false. These properties will be added to the update API's body parameters and can be updated by the user if any value is provided in the request body. ### Database Indexing `productId` Properties that are indexed in the database will be optimized for query performance, allowing for faster data retrieval. Make a property indexed in the database if you want to use it frequently in query filters or sorting. ### Relation Properties `productId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. You can define relations in the data object properties, which will be used to create foreign key constraints in the database. For complex joins operations, Mindbricks supportsa BFF pattern, where you can view dynamic and static views based on Elastic Search Indexes. Use db level relations for simple one-to-one or one-to-many relationships, and use BFF views for complex joins that require multiple data objects to be joined together. - **productId**: ID Relation to `productListingProduct`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: No ## productListingProduct Data Object ### Object Overview **Description:** Represents a single product listing (fixed-price or auction) in the marketplace, with seller, category, type, price information, shipping details, media references, and dynamic auction fields. This object represents a core data structure within the service and acts as the blueprint for database interaction, API generation, and business logic enforcement. It is defined using the `ObjectSettings` pattern, which governs its behavior, access control, caching strategy, and integration points with other systems such as Stripe and Redis. ### Core Configuration - **Soft Delete:** Enabled — Determines whether records are marked inactive (`isActive = false`) instead of being physically deleted. - **Public Access:** accessProtected — If enabled, anonymous users may access this object’s data depending on API-level rules. ### Properties Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `currency` | String | Yes | ISO currency code (e.g. USD, EUR) | | `description` | Text | Yes | Product detailed description | | `condition` | Enum | Yes | Condition of product: BRAND_NEW, NEW, or USED | | `startBid` | Double | No | The opening bid value (for auction type products) | | `endPrice` | Double | No | Optional immediate sale/upper end price for auction (if AUCTION type) | | `price` | Double | No | Product price (required if fixed price type) | | `title` | String | Yes | Product title | | `startPrice` | Double | No | Minimum starting price for auction (required if AUCTION type) | | `type` | Enum | Yes | Product listing type, either FIXED or AUCTION (immutable after creation) | | `endBid` | Double | No | The upper (max) bid value for auction products (if any) | | `estimatedDelivery` | Date | No | Estimated delivery date for this product | | `shippingCurrency` | String | Yes | Currency code for shipping cost | | `sellerId` | ID | Yes | Reference to user who listed the product | | `mediaAssetIds` | ID | No | References to associated product/media assets | | `shippingMethod` | Enum | Yes | Shipping option for product: STANDARD, EXPRESS, or FREE | | `shipping` | Double | Yes | Shipping cost for this product | | `startBidDate` | Date | No | Date/time when auction bidding begins | | `subcategoryId` | ID | Yes | Reference to subcategory | | `categoryId` | ID | Yes | Reference to parent category | | `endBidDate` | Date | No | Date/time when auction bidding ends | | `currentBid` | Double | No | Current highest bid for auction-type product (updated atomically on bid placement) | | `highestBidderId` | ID | No | User ID of current highest bidder (auction-only, updated by auction microservice) | * Required properties are mandatory for creating objects and must be provided in the request body if no default value is set. ### Array Properties `mediaAssetIds` Array properties can hold multiple values and are indicated by the `[]` suffix in their type. Avoid using arrays in properties that are used for relations, as they will not work correctly. Note that using connection objects instead of arrays is recommended for relations, as they provide better performance and flexibility. ### Default Values Default values are automatically assigned to properties when a new object is created, if no value is provided in the request body. Since default values are applied on db level, they should be literal values, not expressions.If you want to use expressions, you can use transposed parameters in any business API to set default values dynamically. - **currency**: 'default' - **description**: 'text' - **condition**: "BRAND_NEW" - **title**: 'default' - **type**: "FIXED" - **shippingCurrency**: 'default' - **sellerId**: '00000000-0000-0000-0000-000000000000' - **shippingMethod**: "STANDARD" - **shipping**: 0.0 - **subcategoryId**: '00000000-0000-0000-0000-000000000000' - **categoryId**: '00000000-0000-0000-0000-000000000000' ### Constant Properties `type` `sellerId` Constant properties are defined to be immutable after creation, meaning they cannot be updated or changed once set. They are typically used for properties that should remain constant throughout the object's lifecycle. A property is set to be constant if the `Allow Update` option is set to `false`. ### Auto Update Properties `currency` `description` `condition` `startBid` `endPrice` `price` `title` `startPrice` `type` `endBid` `estimatedDelivery` `shippingCurrency` `sellerId` `mediaAssetIds` `shippingMethod` `shipping` `startBidDate` `subcategoryId` `categoryId` `endBidDate` `currentBid` `highestBidderId` An update crud API created with the option `Auto Params` enabled will automatically update these properties with the provided values in the request body. If you want to update any property in your own business logic not by user input, you can set the `Allow Auto Update` option to false. These properties will be added to the update API's body parameters and can be updated by the user if any value is provided in the request body. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an addtional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the index property to sort by the enum value or when your enum options represent a sequence of values. - **condition**: [BRAND_NEW, NEW, USED] - **type**: [FIXED, AUCTION] - **shippingMethod**: [STANDARD, EXPRESS, FREE] ### Elastic Search Indexing `currency` `description` `condition` `price` `title` `type` `sellerId` `startBidDate` `subcategoryId` `categoryId` `endBidDate` `currentBid` Properties that are indexed in Elastic Search will be searchable via the Elastic Search API. While all properties are stored in the elastic search index of the data object, only those marked for Elastic Search indexing will be available for search queries. ### Database Indexing `condition` `price` `title` `type` `sellerId` `shipping` `subcategoryId` `categoryId` Properties that are indexed in the database will be optimized for query performance, allowing for faster data retrieval. Make a property indexed in the database if you want to use it frequently in query filters or sorting. ### Relation Properties `sellerId` `mediaAssetIds` `subcategoryId` `categoryId` `highestBidderId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. You can define relations in the data object properties, which will be used to create foreign key constraints in the database. For complex joins operations, Mindbricks supportsa BFF pattern, where you can view dynamic and static views based on Elastic Search Indexes. Use db level relations for simple one-to-one or one-to-many relationships, and use BFF views for complex joins that require multiple data objects to be joined together. - **sellerId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes - **mediaAssetIds**: ID Relation to `productListingMedia`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: No - **subcategoryId**: ID Relation to `subcategory`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes - **categoryId**: ID Relation to `category`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes - **highestBidderId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: No ### Session Data Properties `sellerId` Session data properties are used to store data that is specific to the user session, allowing for personalized experiences and temporary data storage. If a property is configured as session data, it will be automatically mapped to the related field in the user session during CRUD operations. Note that session data properties can not be mutated by the user, but only by the system. - **sellerId**: ID property will be mapped to the session parameter `userId`. This property is also used to store the owner of the session data, allowing for ownership checks and access control. ### Filter Properties `currency` `condition` `price` `title` `type` `sellerId` `subcategoryId` `categoryId` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's that have "Auto Params" enabled. - **currency**: String has a filter named `currency` - **condition**: Enum has a filter named `condition` - **price**: Double has a filter named `price` - **title**: String has a filter named `title` - **type**: Enum has a filter named `type` - **sellerId**: ID has a filter named `sellerId` - **subcategoryId**: ID has a filter named `subcategoryId` - **categoryId**: ID has a filter named `categoryId` ## Business Logic productListing has got 10 Business APIs to manage its internal and crud logic. For the details of each business API refer to its chapter. * [List Productlistingmedia](/businessLogic/listproductlistingmedia) * [Get Productlistingproduct](/businessLogic/getproductlistingproduct) * [List Productlistingownproducts](/businessLogic/listproductlistingownproducts) * [Get Productlistingmedia](/businessLogic/getproductlistingmedia) * [List Productlistingproducts](/businessLogic/listproductlistingproducts) * [Delete Productlistingproduct](/businessLogic/deleteproductlistingproduct) * [Update Productlistingproduct](/businessLogic/updateproductlistingproduct) * [Create Productlistingproduct](/businessLogic/createproductlistingproduct) * [Delete Productlistingmedia](/businessLogic/deleteproductlistingmedia) * [Create Productlistingmedia](/businessLogic/createproductlistingmedia) ## Edge Controllers ### uploadMedia **Configuration:** - **Function Name**: `uploadMedia` - **Login Required**: Yes **REST Settings:** - **Path**: `/api/media/upload` - **Method**: --- --- ## Service Library ### Functions No general functions defined. ### Hook Functions No hook functions defined. ### Edge Functions #### uploadMedia.js ```js const acceptedTypes = ['image/jpeg','image/png','image/webp','image/gif'];\nconst maxSize = 10485760; // 10MB\nmodule.exports = async (request) => {\n const { file } = request.body;\n if (!file) {\n return { status: 400, error: { code: 'no_file', message: 'No file uploaded.' } };\n }\n if (!acceptedTypes.includes(file.mimetype)) {\n return { status: 400, error: { code: 'invalid_mime', message: 'Invalid file type.' } };\n }\n if (file.size > maxSize) {\n return { status: 400, error: { code: 'too_large', message: 'File too large (10MB max).' } };\n }\n // Implement bucket/storage upload here (e.g., S3), get url\n const url = await uploadToBucket(file); /* implementation not shown */\n // Now create productListingMedia\n const media = await createProductListingMedia({ url, mimeType: file.mimetype, size: file.size });\n return { status: 200, mediaAssetId: media.id, url: media.url, mimeType: media.mimeType, size: media.size };\n}; ``` ### Templates No templates defined. ### Assets No assets defined. ### Public Assets No public assets defined. --- ### Event Emission --- ## Integration Patterns ## Deployment Considerations ### Environment Configuration - **HTTP Port**: `3001` - **Database Type**: MongoDB - **Global Soft Delete**: Enabled ## Implementation Guidelines ### Development Workflow 1. **Data Model Implementation**: Generate database schema from data object definitions 2. **CRUD Route Generation**: Implement auto-generated routes with custom logic 3. **Custom Logic Integration**: Implement hook functions and edge functions 4. **Authentication Integration**: Configure with project-level authentication 5. **Testing**: Unit and integration testing for all components ### Code Generation Expectations - **Database Schema**: Auto-generated from data objects and relationships - **API Routes**: REST endpoints with customizable behavior - **Validation Logic**: Input validation from property definitions - **Access Control**: Authentication and authorization middleware ### Custom Code Integration Points - **Hook Functions**: Lifecycle-specific custom logic - **Edge Functions**: Full request/response control - **Library Functions**: Reusable business logic - **Templates**: Dynamic content rendering ### Testing Strategy #### Unit Testing - Test all custom library functions - Test validation logic and business rules - Test hook function implementations #### Integration Testing - Test API endpoints with authentication scenarios - Test database operations and transactions - Test external integrations - Test event emission and Kafka integration #### Performance Testing - Load test high-traffic endpoints - Test caching effectiveness - Monitor database query performance - Test scalability under load --- ## Appendices ### Data Type Reference | Type | Description | Storage | |------|-------------|---------| | ID | Unique identifier | UUID (SQL) / ObjectID (NoSQL) | | String | Short text (≤255 chars) | VARCHAR | | Text | Long-form text | TEXT | | Integer | 32-bit whole numbers | INT | | Boolean | True/false values | BOOLEAN | | Double | 64-bit floating point | DOUBLE | | Float | 32-bit floating point | FLOAT | | Short | 16-bit integers | SMALLINT | | Object | JSON object | JSONB (PostgreSQL) / Object (MongoDB) | | Date | ISO 8601 timestamp | TIMESTAMP | | Enum | Fixed numeric values | SMALLINT with lookup | ### Enum Value Mappings #### Request Locations - `0`: Bearer token in Authorization header - `1`: Cookie value - `2`: Custom HTTP header - `3`: Query parameter - `4`: Request body property - `5`: URL path parameter - `6`: Session data - `7`: Root request object #### HTTP Methods - `0`: GET - `1`: POST - `2`: PUT - `3`: PATCH - `4`: DELETE ### Edge Function Signature ```javascript async function edgeFunction(request) { // Custom request processing // Return response object or throw error return { data: {}, status: 200, message: "Success" }; } ``` --- *This document was generated from the service architecture definition and should be kept in sync with implementation changes.* -------------------------------------------------------- title: QuickStart description: Test slug: quick-start date: 01.04.2025 -------------------------------------------------------- # EVENT GUIDE ## ebaycclone-searchindexing-service Maintains the denormalized search index (materialized view) for global, public search across products, sellers, categories, and subcategories. Handles indexing in response to entity events and exposes optimized query endpoints for BFF/aggregator. ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to: Email: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. # Documentation Scope Welcome to the official documentation for the `SearchIndexing` Service Event descriptions. This guide is dedicated to detailing how to subscribe to and listen for state changes within the `SearchIndexing` Service, offering an exclusive focus on event subscription mechanisms. **Intended Audience** This documentation is aimed at developers and integrators looking to monitor `SearchIndexing` Service state changes. It is especially relevant for those wishing to implement or enhance business logic based on interactions with `SearchIndexing` objects. **Overview** This section provides detailed instructions on monitoring service events, covering payload structures and demonstrating typical use cases through examples. # Authentication and Authorization Access to the `SearchIndexing` service's events is facilitated through the project's Kafka server, which is not accessible to the public. Subscription to a Kafka topic requires being on the same network and possessing valid Kafka user credentials. This document presupposes that readers have existing access to the Kafka server. Additionally, the service offers a public subscription option via REST for real-time data management in frontend applications, secured through REST API authentication and authorization mechanisms. To subscribe to service events via the REST API, please consult the Realtime REST API Guide. # Database Events Database events are triggered at the database layer, automatically and atomically, in response to any modifications at the data level. These events serve to notify subscribers about the creation, update, or deletion of objects within the database, distinct from any overarching business logic. Listening to database events is particularly beneficial for those focused on tracking changes at the database level. A typical use case for subscribing to database events is to replicate the data store of one service within another service's scope, ensuring data consistency and syncronization across services. For example, while a business operation such as "approve membership" might generate a high-level business event like `membership-approved`, the underlying database changes could involve multiple state updates to different entities. These might be published as separate events, such as `dbevent-member-updated` and `dbevent-user-updated`, reflecting the granular changes at the database level. Such detailed eventing provides a robust foundation for building responsive, data-driven applications, enabling fine-grained observability and reaction to the dynamics of the data landscape. It also facilitates the architectural pattern of event sourcing, where state changes are captured as a sequence of events, allowing for high-fidelity data replication and history replay for analytical or auditing purposes. ## DbEvent searchIndex-created **Event topic**: `ebaycclone-searchindexing-service-dbevent-searchindex-created` This event is triggered upon the creation of a `searchIndex` data object in the database. The event payload encompasses the newly created data, encapsulated within the root of the paylod. **Event payload**: ```json {"id":"ID","documentType":"Enum","documentType_idx":"Integer","document":"Object","referenceId":"ID","indexedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent searchIndex-updated **Event topic**: `ebaycclone-searchindexing-service-dbevent-searchindex-updated` Activation of this event follows the update of a `searchIndex` data object. The payload contains the updated information under the `searchIndex` attribute, along with the original data prior to update, labeled as `old_searchIndex` and also you can find the old and new versions of updated-only portion of the data.. **Event payload**: ```json { old_searchIndex:{"id":"ID","documentType":"Enum","documentType_idx":"Integer","document":"Object","referenceId":"ID","indexedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, searchIndex:{"id":"ID","documentType":"Enum","documentType_idx":"Integer","document":"Object","referenceId":"ID","indexedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, oldDataValues, newDataValues } ``` ## DbEvent searchIndex-deleted **Event topic**: `ebaycclone-searchindexing-service-dbevent-searchindex-deleted` This event announces the deletion of a `searchIndex` data object, covering both hard deletions (permanent removal) and soft deletions (where the `isActive` attribute is set to false). Regardless of the deletion type, the event payload will present the data as it was immediately before deletion, highlighting an `isActive` status of false for soft deletions. **Event payload**: ```json {"id":"ID","documentType":"Enum","documentType_idx":"Integer","document":"Object","referenceId":"ID","indexedAt":"Date","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` # ElasticSearch Index Events Within the `SearchIndexing` service, most data objects are mirrored in ElasticSearch indices, ensuring these indices remain syncronized with their database counterparts through creation, updates, and deletions. These indices serve dual purposes: they act as a data source for external services and furnish aggregated data tailored to enhance frontend user experiences. Consequently, an ElasticSearch index might encapsulate data in its original form or aggregate additional information from other data objects. These aggregations can include both one-to-one and one-to-many relationships not only with database objects within the same service but also across different services. This capability allows developers to access comprehensive, aggregated data efficiently. By subscribing to ElasticSearch index events, developers are notified when an index is updated and can directly obtain the aggregated entity within the event payload, bypassing the need for separate ElasticSearch queries. It's noteworthy that some services may augment another service's index by appending to the entity’s `extends` object. In such scenarios, an `*-extended` event will contain only the newly added data. Should you require the complete dataset, you would need to retrieve the full ElasticSearch index entity using the provided ID. This approach to indexing and event handling facilitates a modular, interconnected architecture where services can seamlessly integrate and react to changes, enriching the overall data ecosystem and enabling more dynamic, responsive applications. ## Index Event searchindex-created **Event topic**: `elastic-index-ebaycclone_searchindex-created` **Event payload**: ```json {"id":"ID","documentType":"Enum","documentType_idx":"Integer","document":"Object","referenceId":"ID","indexedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event searchindex-updated **Event topic**: `elastic-index-ebaycclone_searchindex-created` **Event payload**: ```json {"id":"ID","documentType":"Enum","documentType_idx":"Integer","document":"Object","referenceId":"ID","indexedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event searchindex-deleted **Event topic**: `elastic-index-ebaycclone_searchindex-deleted` **Event payload**: ```json {"id":"ID","documentType":"Enum","documentType_idx":"Integer","document":"Object","referenceId":"ID","indexedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event searchindex-extended **Event topic**: `elastic-index-ebaycclone_searchindex-extended` **Event payload**: ```js { id: id, extends: { [extendName]: "Object", [extendName + "_count"]: "Number", }, } ``` # Route Events Route events are emitted following the successful execution of a route. While most routes perform CRUD (Create, Read, Update, Delete) operations on data objects, resulting in route events that closely resemble database events, there are distinctions worth noting. A single route execution might trigger multiple CRUD actions and ElasticSearch indexing operations. However, for those primarily concerned with the overarching business logic and its outcomes, listening to the consolidated route event, published once at the conclusion of the route's execution, is more pertinent. Moreover, routes often deliver aggregated data beyond the primary database object, catering to specific client needs. For instance, creating a data object via a route might not only return the entity's data but also route-specific metrics, such as the executing user's permissions related to the entity. Alternatively, a route might automatically generate default child entities following the creation of a parent object. Consequently, the route event encapsulates a unified dataset encompassing both the parent and its children, in contrast to individual events triggered for each entity created. Therefore, subscribing to route events can offer a richer, more contextually relevant set of information aligned with business logic. The payload of a route event mirrors the REST response JSON of the route, providing a direct and comprehensive reflection of the data and metadata communicated to the client. This ensures that subscribers to route events receive a payload that encapsulates both the primary data involved and any additional information deemed significant at the business level, facilitating a deeper understanding and integration of the service's functional outcomes. ## Route Event searchindexes-listed **Event topic** : `ebaycclone-searchindexing-service-searchindexes-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `searchIndices` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`searchIndices`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"searchIndices","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","searchIndices":[{"id":"ID","documentType":"Enum","documentType_idx":"Integer","document":"Object","referenceId":"ID","indexedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event searchindex-updated **Event topic** : `ebaycclone-searchindexing-service-searchindex-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `searchIndex` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`searchIndex`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"searchIndex","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"searchIndex":{"id":"ID","documentType":"Enum","documentType_idx":"Integer","document":"Object","referenceId":"ID","indexedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event searchindex-deleted **Event topic** : `ebaycclone-searchindexing-service-searchindex-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `searchIndex` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`searchIndex`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"searchIndex","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"searchIndex":{"id":"ID","documentType":"Enum","documentType_idx":"Integer","document":"Object","referenceId":"ID","indexedAt":"Date","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event searchindex-created **Event topic** : `ebaycclone-searchindexing-service-searchindex-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `searchIndex` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`searchIndex`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"searchIndex","method":"POST","action":"create","appVersion":"Version","rowCount":1,"searchIndex":{"id":"ID","documentType":"Enum","documentType_idx":"Integer","document":"Object","referenceId":"ID","indexedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event searchindex-retrived **Event topic** : `ebaycclone-searchindexing-service-searchindex-retrived` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `searchIndex` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`searchIndex`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"searchIndex","method":"GET","action":"get","appVersion":"Version","rowCount":1,"searchIndex":{"id":"ID","documentType":"Enum","documentType_idx":"Integer","document":"Object","referenceId":"ID","indexedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` # Copyright All sources, documents and other digital materials are copyright of . # About Us For more information please visit our website: . . . # **EBAYCCLONE** FRONTEND GUIDE FOR AI CODING AGENTS This document is a rest api guide for the ebaycclone project. The document is designed for AI agents who will generate frontend code that will consume the project backend. The project has got 1 auth service, 1 notification service, 1 bff service and business services. Each service is a separate microservice application and listens the HTTP request from different service urls. The services may be in preview server, staging server or real production server. So each service have got 3 acess urls. Frontend application should support all deployemnt servers in the development phase, and user should be able to select the target api server in the login page. ## Project Introduction ebaycClone is a comprehensive backend for an online marketplace supporting auctions and fixed-price sales of physical goods, with role-based access, public user registration, Stripe payments, notifications, and robust ownership enforcement. ## API Structure ### Object Structure of a Successfull Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client. **HTTP Status Codes:** - **200 OK**: This status code is returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request has been processed successfully. - **201 Created**: This status code is specific to CREATE operations, signifying that the requested resource has been successfully created. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling the successful execution of the request. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` - **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation performed. ### Additional Data Each api may have include addtional data other than the main data object according to the business logic of the API. They will be given in each API's response signature. ### Error Response If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity: - **400 Bad Request**: The request was improperly formatted or contained invalid parameters, preventing the server from processing it. - **401 Unauthorized**: The request lacked valid authentication token , login required - **403 Forbidden Error** Curent token provided do not grant access to the requested resource. - **404 Not Found**: The requested resource was not found on the server. - **500 Internal Server Error**: The server encountered an unexpected condition that prevented it from fulfilling the request. Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Accessing the backend Each service of the backend has got its own url according to the deployment environement. User may want to test the frontend in one of the 3 deployments of the application, preview, staging and production. Please ensure that register and login pages do have a deployemnt server selection option, so as the frontned coding agent you can arrange the base url path of all services. The base url of the application in each environment is as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com` * **Staging:** `https://ebaycclone-stage.mindbricks.co` * **Production:** `https://ebaycclone.mindbricks.co` For the auth service the base url is as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` For each other service, the service base url will be given in service sections. Any login requied request to the backend should have a valid token, when a user makes a successfull login, the ressponse JSON includes a JWT access token in the `accessToken`fields. In normal conditions, this token is also set to the cookie and then consumed automatically, but since AI coding agents preview options may fail to use cookies, please ensure that in each request include the access token in the bearer auth header. ## Registration Management First of all please ensure that register and login pages do have a deployemnt server selection option, so as the frontned coding agent you can arrange the base url path of all services. Start with a landing page and arranging register, verification and login flow. So at the first step, you need a general knowledge of the application to make a good landing page and the authetication flow. ### How To Register Using `registeruser` route of auth api, send the required fields to the backend in your registration page. The registerUser api in in `auth` service, is described with request and response structure below. Note that since `registerUser` api is a business api, it has a version control, so please call it with the given version like `/v1/registeruser` ### `Register User` API This api is used by public users to register themselves **Rest Route** The `registerUser` API REST controller can be triggered via the following route: `/v1/registeruser` **Rest Request Parameters** The `registerUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **password** : The password defined by the the user that is being registered. **fullname** : The fullname defined by the the user that is being registered. **email** : The email defined by the the user that is being registered. **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` After a successful registration, frontend code should handle the verification needs. The registration response will have a `user` object in the root envelope, this object will have user information with an `id` parameter. ### Email Verification In the registration response, you should check the property `emailVerificationNeeded` in the reponse root, and if this property is true you should start the email verification flow. After login process, if you get an HTTP error status, and if there is an `errCode` property in the response with `EmailVerificationNeeded` value, you should start the email verification flow. 1. Call the email verification `start` route of the backend (described below) with the user email, backend will send a secret code to the given email adresss. **Backend can send the email message if the architect defined a real mail service or smtp server, so during the development time backend will send the secret code also to the frontend. You can get this secret code from the response within the `secretCode` property**. 2. The secret code in the sent email message will be a 6 digits code , and you should arrange an input page so that the user can paste this code to the frontend application. Please navigate to this input page after you start the verification process. **If the secretCode is sent to the frontend for test purposes, then you should show it as info in the input page, so that user can copy and paste it**. 3. There is a `codeIndex` property in the start response, please show it's value on the input page, so that user can match the index in the message with the one on the screen. 4. When the user submits the code, please complete the email verification using the `complete` route of the backend (described below) with the user email and the secret code. 5. After you get a successful response from email verification, you can navigate to the login page. Here is the `start`and `complete` routes of email verification. These are system routes , so they dont have a version control. #### `POST /verification-services/email-verification/start` **Purpose:** Starts the email verification by generating and sending a secret code. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `email` | String | Yes | User’s email address to verify | **Example Request** ```json { "email": "user@example.com" } ``` **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ In production, `secretCode` is **not** returned — only sent via email. **Error Responses** * `400 Bad Request`: Already verified * `403 Forbidden`: Too many attempts (rate limit) --- #### `POST /verification-services/email-verification/complete` **Purpose:** Completes the verification using the received code. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `email` | String | Yes | User’s email | | `secretCode` | String | Yes | Verification code | **Success Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` **Error Responses** * `403 Forbidden`: Code expired or mismatched * `404 Not Found`: No verification in progress --- ## Login Management After a successfull login and completing required verifications, user can now login. Please make a fancy minimal login page where user can enter his email and password. ## Bucket Management This application has a bucket service and is used to store user or other objects related files. Bucket service is login agnostic, so when accessing for write or private read, you should insert a bucket token (given by services) to your request authorization header as bearer token. **User Bucket** This bucket is used to store public user files for each user. When a user logs in, or in /currentuser response there is `userBucketToken` to be used when sending user related public files to the bucket service. To upload `POST {baseUrl}/bucket/upload` Request body is form data which includes the bucketId and the file as binary in `files` property. ```js { bucketId: "{userId}-public-user-bucket", files: {binary} } ``` Response status is 200 on succesfull result, eg body: ```json { "success": true, "data": [ { "fileId": "9da03f6d-0409-41ad-bb06-225a244ae408", "originalName": "test (10).png", "mimeType": "image/png", "size": 604063, "status": "uploaded", "bucketName": "f7103b85-fcda-4dec-92c6-c336f71fd3a2-public-user-bucket", "isPublic": true, "downloadUrl": "https://babilcom.mindbricks.co/bucket/download/9da03f6d-0409-41ad-bb06-225a244ae408" } ] } ``` To download a file from the bucket, you should know its fileId, so if youupload an avatar or something else, be sure that the download url or the fileId is stored in backend. Bucket is mostly used, in object creations where alos demands an addtional file like a product image or user avatar. So after you upload your image to the bucket, insert the returned download url to the related property in the related object creation. **Application Bucket** This Ebaycclone application alos has common public bucket which everybody has a read access, but only users who have `superAdmin`, `admin` or `saasAdmin` roles can write (upload) to the bucket. The common public project bucket id is `"ebaycclone-public-common-bucket"` and in certain areas like product image uploads, since the user will already have the admin bucket token, he will be able to upload realted object images. Please make your UI arrangements as able to upload files to the bucket using these bucket tokens. **Object Buckets** Some objects may return also a bucket token, to upload or access related files with object. For example, when you get a project's data in a project management application, if there is a public or private bucket token, this is provided mostly for uploading project related files or downloading them with the token. These buckets will be used according to the descriptions given along with the object definitions. ## Role Management This Ebaycclone may have different role names defined fro different business logic. But unless another case is asked by the user, respect to the admin roles which may be `superAdmin`, `admin` or `saasAdmin` in the currentuser or login response given with the `roleId`property. ```json { // ... "roleId":"superAdmin", // ... } ``` If the application needs an admin panel, or any admin related page, please use these roleId's to decide if the user can access those pages or not. ## 1. Authentication Routes ### 1.1 `POST /login` — User Login **Purpose:** Verifies user credentials and creates an authenticated session with a JWT access token. **Access Routes:** * `GET /login`: Returns a minimal HTML login page (for browser-based testing). * `POST /login`: Authenticates user credentials and returns an access token and session. #### Request Parameters | Parameter | Type | Required | Source | | ---------- | ------ | -------- | ----------------------- | | `username` | String | Yes | `request.body.username` | | `password` | String | Yes | `request.body.password` | #### Behavior * Authenticates credentials and returns a session object. * Sets cookie: `projectname-access-token[-tenantCodename]` * Adds the same token in response headers. * Accepts either `username` or `email` fields (if both exist, `username` is prioritized). #### Example ```js axios.post("/login", { username: "user@example.com", password: "securePassword" }); ``` #### Success Response ```json { "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", //... } ``` #### Error Responses * `401 Unauthorized`: Invalid credentials * `403 Forbidden`: Email/mobile verification or 2FA pending * `400 Bad Request`: Missing parameters --- ### 1.2 `POST /logout` — User Logout **Purpose:** Terminates the current session and clears associated authentication tokens. #### Behavior * Invalidates session (if exists). * Clears cookie `projectname-access-token[-tenantCodename]`. * Returns a confirmation response (always `200 OK`). #### Example ```js axios.post("/logout", {}, { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` #### Notes * Can be called without a session (idempotent behavior). * Works for both cookie-based and token-based sessions. #### Success Response ```json { "status": "OK", "message": "User logged out successfully" } ``` --- ## 2. Verification Services Overview All verification routes are grouped under the `/verification-services` base path. They follow a **two-step verification pattern**: `start` → `complete`. --- ## 3. Email Verification ### 3.1 Trigger Scenarios * After registration (`emailVerificationRequiredForLogin` = true) * When updating email address * When login fails due to unverified email ### 3.2 Flow Summary 1. `/start` → Generate & send code via email. 2. `/complete` → Verify code and mark email as verified. ** PLEASE NOTE ** Email verification is a frontend triiggered process. After user registers, the frontend should start the email verification process and navigate to its code input page. --- ### 3.3 `POST /verification-services/email-verification/start` **Purpose:** Starts the email verification by generating and sending a secret code. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `email` | String | Yes | User’s email address to verify | **Example Request** ```json { "email": "user@example.com" } ``` **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ In production, `secretCode` is **not** returned — only sent via email. **Error Responses** * `400 Bad Request`: Already verified * `403 Forbidden`: Too many attempts (rate limit) --- ### 3.4 `POST /verification-services/email-verification/complete` **Purpose:** Completes the verification using the received code. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `email` | String | Yes | User’s email | | `secretCode` | String | Yes | Verification code | **Success Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` **Error Responses** * `403 Forbidden`: Code expired or mismatched * `404 Not Found`: No verification in progress --- ### 3.5 Behavioral Notes * **Resend Cooldown:** `resendTimeWindow` (e.g. 60s) * **Expiration:** Codes expire after `expireTimeWindow` (e.g. 1 day) * **Single Active Session:** One verification per user --- ## 4. Mobile Verification ### 4.1 Trigger Scenarios * After registration (`mobileVerificationRequiredForLogin` = true) * When updating phone number * On login requiring mobile verification ### 4.2 Flow 1. `/start` → Sends verification code via SMS 2. `/complete` → Validates code and confirms number --- ### 4.3 `POST /verification-services/mobile-verification/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------ | | `email` | String | Yes | User’s email to locate mobile record | **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 180, "verificationType": "byCode", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ `secretCode` returned only in development. **Errors** * `400 Bad Request`: Already verified * `403 Forbidden`: Rate-limited --- ### 4.4 `POST /verification-services/mobile-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------------- | | `email` | String | Yes | Associated email | | `secretCode` | String | Yes | Code received via SMS | **Success Response** ```json { "status": "OK", "isVerified": true, "mobile": "+1 333 ...", // in testMode "userId": "user-uuid", } ``` --- ### 4.5 Behavioral Notes * **Cooldown:** One code per minute * **Expiration:** Codes valid for 1 day * **One Session Per User** --- ## 5. Two-Factor Authentication (2FA) ### 5.1 Email 2FA **Flow** 1. `/start` → Generates and sends email code 2. `/complete` → Verifies code and updates session --- #### `POST /verification-services/email-2factor-verification/start` | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ---------------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Current session | | `client` | String | No | Optional context | | `reason` | String | No | Reason for 2FA | **Response** ```json { "status": "OK", "sessionId": "user session id UUID", "userId": "user-uuid", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", } ``` --- #### `POST /verification-services/email-2factor-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `secretCode` | String | Yes | Code from email | **Response** ```json { // user session data "sessionId": "session-uuid", // ... } ``` --- ### 5.2 Mobile 2FA **Flow** 1. `/start` → Sends SMS code 2. `/complete` → Validates and finalizes session --- #### `POST /verification-services/mobile-2factor-verification/start` | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ----------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `client` | String | No | Context | | `reason` | String | No | Reason | **Response** ```json { "status": "OK", "sessionId": "user session id UUID", "userId": "user-uuid", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", } ``` --- #### `POST /verification-services/mobile-2factor-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------ | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `secretCode` | String | Yes | Code via SMS | **Response** ```json { // user session data "sessionId": "session-uuid", // ... } ``` --- ### 5.3 2FA Behavioral Notes * One active code per session * Cooldown: `resendTimeWindow` (e.g., 60s) * Expiration: `expireTimeWindow` (e.g., 5m) --- ## 6. Password Reset ### 6.1 By Email **Flow** 1. `/start` → Sends verification code via email 2. `/complete` → Validates and resets password --- #### `POST /verification-services/password-reset-by-email/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------- | | `email` | String | Yes | User email | **Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` #### `POST /verification-services/password-reset-by-email/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------- | | `email` | String | Yes | User email | | `secretCode` | String | Yes | Code received | | `password` | String | Yes | New password | **Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` --- ### 6.2 By Mobile **Flow** 1. `/start` → Sends SMS code 2. `/complete` → Validates and resets password --- #### `POST /verification-services/password-reset-by-mobile/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------- | | `mobile` | String | Yes | Mobile number | **Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` #### `POST /verification-services/password-reset-by-mobile/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ---------------- | | `email` | String | Yes | Associated email | | `secretCode` | String | Yes | Code via SMS | | `password` | String | Yes | New password | **Response** ```json { "status": "OK", "isVerified": true, "mobile": "+1 444 ....", // in testMode "userId": "user-uuid", } ``` --- ### 6.3 Behavioral Notes * Cooldown: 60s resend * Expiration: 24h * One session per user * Works without an active login session --- ## 7. Verification Method Types ### 7.1 `byCode` User manually enters the 6-digit code in frontend. ### 7.2 `byLink` Frontend handles a one-click verification via email/SMS link containing code parameters. ## 8) `GET /currentuser` — Current Session **Purpose** Return the currently authenticated user’s session. **Route Type** `sessionInfo` **Authentication** Requires a valid access token (header or cookie). ### Request *No parameters.* ### Example ```js axios.get("/currentuser", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) Returns the session object (identity, tenancy, token metadata): ```json { "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", "roleId": "user", "tenantId": "abc123", "accessToken": "jwt-token-string", "...": "..." } ``` ### Errors * **401 Unauthorized** — No active session/token ```json { "status": "ERR", "message": "No login found" } ``` **Notes** * Commonly called by web/mobile clients after login to hydrate session state. * Includes key identity/tenant fields and a token reference (if applicable). * Ensure a valid token is supplied to receive a 200 response. --- ## 9) `GET /permissions` — List Effective Permissions **Purpose** Return all effective permission grants for the current user. **Route Type** `permissionFetch` **Authentication** Requires a valid access token. ### Request *No parameters.* ### Example ```js axios.get("/permissions", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) Array of permission grants (aligned with `givenPermissions`): ```json [ { "id": "perm1", "permissionName": "adminPanel.access", "roleId": "admin", "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" }, { "id": "perm2", "permissionName": "orders.manage", "roleId": null, "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" } ] ``` **Field meanings (per item):** * `permissionName`: Granted permission key. * `roleId`: Present if granted via role. * `subjectUserId`: Present if granted directly to the user. * `subjectUserGroupId`: Present if granted via group. * `objectId`: Present if scoped to a specific object (OBAC). * `canDo`: `true` if enabled, `false` if restricted. ### Errors * **401 Unauthorized** — No active session ```json { "status": "ERR", "message": "No login found" } ``` * **500 Internal Server Error** — Unexpected failure **Notes** * Available on all Mindbricks-generated services (not only Auth). * **Auth service:** Reads live `givenPermissions` from DB. * **Other services:** Typically respond from a cached/projected view (e.g., ElasticSearch) for faster checks. > **Tip:** Cache permission results client-side/server-side and refresh after login or permission updates. --- ## 10) `GET /permissions/:permissionName` — Check Permission Scope **Purpose** Check whether the current user has a specific permission and return any scoped object exceptions/inclusions. **Route Type** `permissionScopeCheck` **Authentication** Requires a valid access token. ### Path Parameters | Name | Type | Required | Source | | ---------------- | ------ | -------- | ------------------------------- | | `permissionName` | String | Yes | `request.params.permissionName` | ### Example ```js axios.get("/permissions/orders.manage", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) ```json { "canDo": true, "exceptions": [ "a1f2e3d4-xxxx-yyyy-zzzz-object1", "b2c3d4e5-xxxx-yyyy-zzzz-object2" ] } ``` **Interpretation** * If `canDo: true`: permission is generally granted **except** the listed `exceptions` (restrictions). * If `canDo: false`: permission is generally **not** granted, **only** allowed for the listed `exceptions` (selective overrides). * `exceptions` contains object IDs (UUID strings) from the relevant domain model. ### Errors * **401 Unauthorized** — No active session/token. ## Services And Data Object ## Auth Service Authentication service for the project ### Auth Service Data Objects **User** A data object that stores the user information and handles login settings. ### Auth Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` ### `Get User` API This api is used by admin roles or the users themselves to get the user profile information. **Rest Route** The `getUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `getUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users/:userId** ```js axios({ method: 'GET', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update User` API This route is used by admins to update user profiles. **Rest Route** The `updateUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `updateUser` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/users/:userId** ```js axios({ method: 'PATCH', url: `/v1/users/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Profile` API This route is used by users to update their profiles. **Rest Route** The `updateProfile` API REST controller can be triggered via the following route: `/v1/profile/:userId` **Rest Request Parameters** The `updateProfile` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/profile/:userId** ```js axios({ method: 'PATCH', url: `/v1/profile/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create User` API This api is used by admin roles to create a new user manually from admin panels **Rest Route** The `createUser` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `createUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | email | String | true | request.body?.email | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **email** : A string value to represent the user's email. **password** : A string value to represent the user's password. It will be stored as hashed. **fullname** : A string value to represent the fullname of the user **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/users** ```js axios({ method: 'POST', url: '/v1/users', data: { avatar:"String", email:"String", password:"String", fullname:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete User` API This api is used by admins to delete user profiles. **Rest Route** The `deleteUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `deleteUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/users/:userId** ```js axios({ method: 'DELETE', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Archive Profile` API This api is used by users to archive their profiles. **Rest Route** The `archiveProfile` API REST controller can be triggered via the following route: `/v1/archiveprofile/:userId` **Rest Request Parameters** The `archiveProfile` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/archiveprofile/:userId** ```js axios({ method: 'DELETE', url: `/v1/archiveprofile/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Users` API The list of users is filtered by the tenantId. **Rest Route** The `listUsers` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `listUsers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users** ```js axios({ method: 'GET', url: '/v1/users', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Search Users` API The list of users is filtered by the tenantId. **Rest Route** The `searchUsers` API REST controller can be triggered via the following route: `/v1/searchusers` **Rest Request Parameters** The `searchUsers` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | keyword | String | true | request.query?.keyword | **keyword** : **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchusers** ```js axios({ method: 'GET', url: '/v1/searchusers', data: { }, params: { keyword:'"String"', } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Userrole` API This route is used by admin roles to update the user role.The default role is user when a user is registered. A user's role can be updated by superAdmin or admin **Rest Route** The `updateUserRole` API REST controller can be triggered via the following route: `/v1/userrole/:userId` **Rest Request Parameters** The `updateUserRole` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | roleId | String | true | request.body?.roleId | **userId** : This id paremeter is used to select the required data object that will be updated **roleId** : The new roleId of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userrole/:userId** ```js axios({ method: 'PATCH', url: `/v1/userrole/${userId}`, data: { roleId:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpassword` API This route is used to update the password of users in the profile page by users themselves **Rest Route** The `updateUserPassword` API REST controller can be triggered via the following route: `/v1/userpassword/:userId` **Rest Request Parameters** The `updateUserPassword` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | oldPassword | String | true | request.body?.oldPassword | | newPassword | String | true | request.body?.newPassword | **userId** : This id paremeter is used to select the required data object that will be updated **oldPassword** : The old password of the user that will be overridden bu the new one. Send for double check. **newPassword** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpassword/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpassword/${userId}`, data: { oldPassword:"String", newPassword:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpasswordbyadmin` API This route is used to change any user password by admins only. Superadmin can chnage all passwords, admins can change only nonadmin passwords **Rest Route** The `updateUserPasswordByAdmin` API REST controller can be triggered via the following route: `/v1/userpasswordbyadmin/:userId` **Rest Request Parameters** The `updateUserPasswordByAdmin` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | password | String | true | request.body?.password | **userId** : This id paremeter is used to select the required data object that will be updated **password** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpasswordbyadmin/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpasswordbyadmin/${userId}`, data: { password:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Briefuser` API This route is used by public to get simple user profile information. **Rest Route** The `getBriefUser` API REST controller can be triggered via the following route: `/v1/briefuser/:userId` **Rest Request Parameters** The `getBriefUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/briefuser/:userId** ```js axios({ method: 'GET', url: `/v1/briefuser/${userId}`, data: { }, params: { } }); ``` **REST Response** This route's response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "fullname": "String", "avatar": "String", "isActive": true } } ``` ### `Register User` API This api is used by public users to register themselves **Rest Route** The `registerUser` API REST controller can be triggered via the following route: `/v1/registeruser` **Rest Request Parameters** The `registerUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **password** : The password defined by the the user that is being registered. **fullname** : The fullname defined by the the user that is being registered. **email** : The email defined by the the user that is being registered. **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## AuctionOffer Service Handles auction bids and fixed-price offers for product listings, enforces real-time auction state, handles strict offer workflows including counter-offers, and triggers domain events for bid/offer notifications. No payment or frontend aggregation logic included. ### AuctionOffer Service Data Objects **AuctionOfferOffer** Represents an offer (best offer/counter-offer) made on a fixed-price product. Tracks buyer, seller, amounts, currency, state transitions, counter-offers, and expiry. **AuctionOfferBid** Represents an individual bid placed on an auction-type product. Linked to product and user, tracks bid amount, currency, status (ACTIVE, WON, LOST, CANCELLED), and time placed. ### AuctionOffer Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auctionoffer-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auctionoffer-api` * **Production:** `https://ebaycclone.mindbricks.co/auctionoffer-api` ### `Update Auctionofferoffer` API Updates offer: accepts/declines/counters by seller, withdraws by buyer before response. Enforces status transition rules, sets respondedAt. Triggers event. **Rest Route** The `updateAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `updateAuctionOfferOffer` api has got 8 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | message | String | false | request.body?.message | | status | Enum | false | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | **auctionOfferOfferId** : This id paremeter is used to select the required data object that will be updated **counterOfferId** : References another offer (counter-offer chain). **counterMessage** : Message accompanying seller's counter-offer (optional). **counterAmount** : Counter-offer amount (when offer is COUNTERED). **message** : Message/special notes from buyer (optional). **status** : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). **expiresAt** : When this offer expires (optional). **respondedAt** : When the seller (or buyer, for counter-offer) responded/updated the offer status. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Auctionofferbid` API Creates a new bid for an auction product. Validates auction status, not seller, product type, bid window, and ensures min. increment. Updates product.currentBid and product.highestBidderId atomically. Triggers notification event. **Rest Route** The `createAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids` **Rest Request Parameters** The `createAuctionOfferBid` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | bidAmount | Double | true | request.body?.bidAmount | | currency | String | true | request.body?.currency | | status | Enum | true | request.body?.status | | productId | ID | true | request.body?.productId | **bidAmount** : Bid amount placed by the user. **currency** : ISO currency for the bid (e.g., USD, EUR). **status** : Bid status: ACTIVE, WON, LOST, CANCELLED. **productId** : Product being bid on (must be AUCTION type). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/auctionofferbids** ```js axios({ method: 'POST', url: '/v1/auctionofferbids', data: { bidAmount:"Double", currency:"String", status:"Enum", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Auctionofferbid` API Gets a single bid (only visible to owner/admin or for auction history). **Rest Route** The `getAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `getAuctionOfferBid` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | **auctionOfferBidId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'GET', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Auctionofferoffer` API Gets a single offer (shown to buyer/seller or admin). **Rest Route** The `getAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `getAuctionOfferOffer` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | **auctionOfferOfferId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'GET', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Auctionofferoffers` API Lists offers by product, user, status, or counterOffer chain. **Rest Route** The `listAuctionOfferOffers` API REST controller can be triggered via the following route: `/v1/auctionofferoffers` **Rest Request Parameters** The `listAuctionOfferOffers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers** ```js axios({ method: 'GET', url: '/v1/auctionofferoffers', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferOffers": [ { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Auctionofferbid` API Updates a bid’s status (allow only status update, e.g. CANCELLED, WIN/LOSE on admin settlement). Only owner/admin, and only if auction not ended or not settled. Triggers notification event. **Rest Route** The `updateAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `updateAuctionOfferBid` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | | status | Enum | false | request.body?.status | **auctionOfferBidId** : This id paremeter is used to select the required data object that will be updated **status** : Bid status: ACTIVE, WON, LOST, CANCELLED. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { status:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Auctionofferoffer` API Creates a new offer for a fixed-price product, validating acceptOffers, type, eligibility, and product/seller/buyer active. Defaults to PENDING state. Triggers notification event. **Rest Route** The `createAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers` **Rest Request Parameters** The `createAuctionOfferOffer` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | productId | ID | true | request.body?.productId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | offerAmount | Double | true | request.body?.offerAmount | | message | String | false | request.body?.message | | status | Enum | true | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | **currency** : ISO currency (e.g., USD, EUR) for the offer. **productId** : Product the offer applies to (must be fixed-price, acceptOffers true). **counterOfferId** : References another offer (counter-offer chain). **counterMessage** : Message accompanying seller's counter-offer (optional). **counterAmount** : Counter-offer amount (when offer is COUNTERED). **offerAmount** : Primary offer amount from buyer. **message** : Message/special notes from buyer (optional). **status** : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). **expiresAt** : When this offer expires (optional). **respondedAt** : When the seller (or buyer, for counter-offer) responded/updated the offer status. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/auctionofferoffers** ```js axios({ method: 'POST', url: '/v1/auctionofferoffers', data: { currency:"String", productId:"ID", counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", offerAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Auctionofferbids` API Lists bids by product, user, or auction, supports history/analytics. **Rest Route** The `listAuctionOfferBids` API REST controller can be triggered via the following route: `/v1/auctionofferbids` **Rest Request Parameters** The `listAuctionOfferBids` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids** ```js axios({ method: 'GET', url: '/v1/auctionofferbids', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBids", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferBids": [ { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Auctionofferbid` API Soft-deletes a bid (for admin or self before auction ends). **Rest Route** The `deleteAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `deleteAuctionOfferBid` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | **auctionOfferBidId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Auctionofferoffer` API Soft-deletes an offer (allowed only in non-accepted/expired state). **Rest Route** The `deleteAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `deleteAuctionOfferOffer` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | **auctionOfferOfferId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## CategoryManagement Service Handles product categories and subcategories for marketplace browsing and classification, supporting public discovery plus admin-only management. ### CategoryManagement Service Data Objects **Category** Represents a product category in the marketplace (e.g., Electronics, Clothing, Toys), used for browsing, filtering, and discovery. Admins manage categories. **Subcategory** Represents a subcategory within a parent category (e.g., 'Smartphones' under 'Electronics'). Used for more granular product discovery and navigation. 'group' categorizes special display logic. ### CategoryManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/categorymanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/categorymanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/categorymanagement-api` ### `Delete Category` API Soft-delete a category (admin-only). **Rest Route** The `deleteCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `deleteCategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | **categoryId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/categories/:categoryId** ```js axios({ method: 'DELETE', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Subcategory` API Get a subcategory by ID. Public - only active subcategories returned except for admin. **Rest Route** The `getSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `getSubcategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | **subcategoryId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/subcategories/:subcategoryId** ```js axios({ method: 'GET', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Category` API Get a single category by ID. Public - only active categories returned (for non-admins). **Rest Route** The `getCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `getCategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | **categoryId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/categories/:categoryId** ```js axios({ method: 'GET', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Subcategory` API Update subcategory (admin-only), including group enum change. **Rest Route** The `updateSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `updateSubcategory` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | name | String | false | request.body?.name | | group | Enum | false | request.body?.group | **subcategoryId** : This id paremeter is used to select the required data object that will be updated **categoryId** : Reference to the parent category (category.id). **name** : Display name of the subcategory. **group** : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/subcategories/:subcategoryId** ```js axios({ method: 'PATCH', url: `/v1/subcategories/${subcategoryId}`, data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Subcategories` API List all subcategories for browsing/filtering, with support for group enum and parent category queries. Only active subcategories shown to public/non-admin users. **Rest Route** The `listSubcategories` API REST controller can be triggered via the following route: `/v1/subcategories` **Rest Request Parameters** The `listSubcategories` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/subcategories** ```js axios({ method: 'GET', url: '/v1/subcategories', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "subcategories": [ { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Subcategory` API Soft-delete a subcategory (admin-only). **Rest Route** The `deleteSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `deleteSubcategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | **subcategoryId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/subcategories/:subcategoryId** ```js axios({ method: 'DELETE', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Categories` API List all categories for browsing and filtering. Only active categories shown to public/non-admin users. **Rest Route** The `listCategories` API REST controller can be triggered via the following route: `/v1/categories` **Rest Request Parameters** The `listCategories` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/categories** ```js axios({ method: 'GET', url: '/v1/categories', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "categories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "categories": [ { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Category` API Update category details (admin-only). **Rest Route** The `updateCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `updateCategory` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | false | request.body?.title | **categoryId** : This id paremeter is used to select the required data object that will be updated **imageUrl** : URL for category image/avatar (optional, used for homepage visuals). **subtitle** : Optional short description for UI/tooltips. **title** : Display name of the category. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/categories/:categoryId** ```js axios({ method: 'PATCH', url: `/v1/categories/${categoryId}`, data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Subcategory` API Create a new subcategory under a given category (admin-only), with enum group constraint. **Rest Route** The `createSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories` **Rest Request Parameters** The `createSubcategory` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.body?.categoryId | | name | String | true | request.body?.name | | group | Enum | true | request.body?.group | **categoryId** : Reference to the parent category (category.id). **name** : Display name of the subcategory. **group** : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/subcategories** ```js axios({ method: 'POST', url: '/v1/subcategories', data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Category` API Create a new category (admin-only) for product classification. **Rest Route** The `createCategory` API REST controller can be triggered via the following route: `/v1/categories` **Rest Request Parameters** The `createCategory` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | true | request.body?.title | **imageUrl** : URL for category image/avatar (optional, used for homepage visuals). **subtitle** : Optional short description for UI/tooltips. **title** : Display name of the category. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/categories** ```js axios({ method: 'POST', url: '/v1/categories', data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## Messaging Service In-app messaging service for direct user-to-user text messages (buyers/sellers). Stores, retrieves, and manages user conversations. Launch version: text-only. ### Messaging Service Data Objects **MessagingMessage** A direct, text-only in-app message between two users (buyer/seller); stores sender, recipient, content, read status, and timestamp. ### Messaging Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/messaging-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/messaging-api` * **Production:** `https://ebaycclone.mindbricks.co/messaging-api` ### `List Messagingmessages` API List all messages in the conversation between the logged-in user and another party, ordered by sentAt descending. Can filter unread with isRead. Returns only messages visible to user (isActive). **Rest Route** The `listMessagingMessages` API REST controller can be triggered via the following route: `/v1/messagingmessages` **Rest Request Parameters** The `listMessagingMessages` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages** ```js axios({ method: 'GET', url: '/v1/messagingmessages', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessages", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "messagingMessages": [ { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Messagingmessage` API Send a new text message from the logged-in user to a recipient. Sender is set from session. Launch version supports only text content. **Rest Route** The `createMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages` **Rest Request Parameters** The `createMessagingMessage` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | toUserId | ID | true | request.body?.toUserId | | content | String | true | request.body?.content | | isRead | Boolean | true | request.body?.isRead | **toUserId** : Recipient (user) of this message. **content** : Text content of the message. No files or attachments for launch. **isRead** : If true, recipient has marked this message as read. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/messagingmessages** ```js axios({ method: 'POST', url: '/v1/messagingmessages', data: { toUserId:"ID", content:"String", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Messagingmessage` API Update a message (mark as read/unread). Only the recipient or admin can change isRead. No content edits. Sender, content, sentAt are immutable. **Rest Route** The `updateMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `updateMessagingMessage` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | | isRead | Boolean | false | request.body?.isRead | **messagingMessageId** : This id paremeter is used to select the required data object that will be updated **isRead** : If true, recipient has marked this message as read. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'PATCH', url: `/v1/messagingmessages/${messagingMessageId}`, data: { isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Messagingmessage` API Get a message by ID. Only accessible to the sender, the recipient, or an admin. Used for message detail view or reading a single message in a thread. **Rest Route** The `getMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `getMessagingMessage` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | **messagingMessageId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'GET', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Messagingmessage` API Delete a message (soft-delete). Only sender, recipient, or admin may delete a message. Deletion only hides it for the user; not a full erase unless both delete. **Rest Route** The `deleteMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `deleteMessagingMessage` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | **messagingMessageId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'DELETE', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## NotificationManagement Service Handles storage, management, and event-driven delivery of in-app and email notifications for user-impacting system events (bids, offers, orders, feedback, messaging, etc.). Supports marking notifications as read/unread, structured filtering by event type/channel, and always returns in-app notifications ordered by recency. ### NotificationManagement Service Data Objects **Notification** Stores and manages in-app and email notifications tied to user-facing events like bids, offers, orders, messaging, shipment, and feedback. Includes event type (notificationType) for filter/search, arbitrary event payload, and delivery channel. Soft-delete enforced. In-app notifications always sorted by createdAt DESC on retrieval. ### NotificationManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/notificationmanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/notificationmanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/notificationmanagement-api` ### `Create Notification` API Creates a notification entry in response to a system/business event. Only allowed for system/event processes and admins (not standard user/action). Typically event-driven, receives userId, notificationType, payload, and channel. **Rest Route** The `createNotification` API REST controller can be triggered via the following route: `/v1/notifications` **Rest Request Parameters** The `createNotification` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationType | Enum | true | request.body?.notificationType | | userId | ID | true | request.body?.userId | | channel | Enum | true | request.body?.channel | | payload | Object | true | request.body?.payload | | isRead | Boolean | true | request.body?.isRead | **notificationType** : Type of event triggering notification (e.g., BID_UPDATED, ORDER_SHIPPED, MESSAGE_RECEIVED, etc.). Used for display/icon and query filter. **userId** : User receiving the notification (recipient). **channel** : Channel by which notification is delivered: IN_APP or EMAIL. **payload** : Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. **isRead** : Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/notifications** ```js axios({ method: 'POST', url: '/v1/notifications', data: { notificationType:"Enum", userId:"ID", channel:"Enum", payload:"Object", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Notification` API Updates a notification (mark as read/unread, payload patch for e.g. admin fix). Only receiver (userId) or admins may update. isRead is primary update scenario; others very limited. **Rest Route** The `updateNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `updateNotification` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | | payload | Object | false | request.body?.payload | | isRead | Boolean | false | request.body?.isRead | **notificationId** : This id paremeter is used to select the required data object that will be updated **payload** : Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. **isRead** : Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/notifications/:notificationId** ```js axios({ method: 'PATCH', url: `/v1/notifications/${notificationId}`, data: { payload:"Object", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Notifications` API Returns filtered list of notifications for a user, with optional filters: notificationType, isRead, channel. Always sorted by createdAt (descending) for in-app notifications. Only retrieval allowed for owner/admin. **Rest Route** The `listNotifications` API REST controller can be triggered via the following route: `/v1/notifications` **Rest Request Parameters** The `listNotifications` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/notifications** ```js axios({ method: 'GET', url: '/v1/notifications', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notifications", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "notifications": [ { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Notification` API Soft-delete a notification record. Only receiver or admin may delete. **Rest Route** The `deleteNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `deleteNotification` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | **notificationId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/notifications/:notificationId** ```js axios({ method: 'DELETE', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Notification` API Retrieves a notification for the receiver or admin. Used to populate content on detail/expanded view. **Rest Route** The `getNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `getNotification` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | **notificationId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/notifications/:notificationId** ```js axios({ method: 'GET', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## SearchIndexing Service Maintains the denormalized search index (materialized view) for global, public search across products, sellers, categories, and subcategories. Handles indexing in response to entity events and exposes optimized query endpoints for BFF/aggregator. ### SearchIndexing Service Data Objects **SearchIndex** Materialized/denormalized search index record for a marketplace entity (product, seller, category, subcategory). Used exclusively for high-speed querying in BFF global/public search. ### SearchIndexing Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/searchindexing-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/searchindexing-api` * **Production:** `https://ebaycclone.mindbricks.co/searchindexing-api` ### `List Searchindexes` API List/search search index entries by type or referenceId (used by BFF/global search). Always excludes inactive (soft-deleted) records. Supports filtering and full-text search filters by documentType/referenceId for admin/maintenance use. **Rest Route** The `listSearchIndexes` API REST controller can be triggered via the following route: `/v1/searchindexes` **Rest Request Parameters** The `listSearchIndexes` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchindexes** ```js axios({ method: 'GET', url: '/v1/searchindexes', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndices", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "searchIndices": [ { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Searchindex` API Update an existing searchIndex record (by (documentType, referenceId) or id). Used in response to events (entity edit, data change); internal/automation/admin only. **Rest Route** The `updateSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `updateSearchIndex` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | | documentType | Enum | false | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | false | request.body?.indexedAt | **searchIndexId** : This id paremeter is used to select the required data object that will be updated **documentType** : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY **document** : Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. **referenceId** : ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. **indexedAt** : Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/searchindexs/:searchIndexId** ```js axios({ method: 'PATCH', url: `/v1/searchindexs/${searchIndexId}`, data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Searchindex` API Soft-delete a searchIndex record (by id or by (documentType, referenceId)). Typical use: in response to entity soft-delete; internal/automation/admin only. **Rest Route** The `deleteSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `deleteSearchIndex` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | **searchIndexId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/searchindexs/:searchIndexId** ```js axios({ method: 'DELETE', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Searchindex` API Create a new searchIndex record (internal, used by event triggers and admin tools only). Typically called when a new product/seller/category/subcategory is created. **Rest Route** The `createSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs` **Rest Request Parameters** The `createSearchIndex` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | documentType | Enum | true | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | true | request.body?.indexedAt | **documentType** : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY **document** : Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. **referenceId** : ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. **indexedAt** : Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/searchindexs** ```js axios({ method: 'POST', url: '/v1/searchindexs', data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Searchindex` API Get a single denormalized index record (by id, or documentType+referenceId). Used by BFF for full entity search. Always excludes inactive records unless forced (admin only path). **Rest Route** The `getSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `getSearchIndex` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | **searchIndexId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchindexs/:searchIndexId** ```js axios({ method: 'GET', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## AdminModeration Service Administrative backend service for moderation and manual override actions. Responsible for logging all admin interventions (user/product/feedback/media/category/order/notification/searchindex moderation), triggering corrections via interservice calls, and providing comprehensive audit trails for compliance. ### AdminModeration Service Data Objects **ModerationAction** Audit record for all admin moderation/override actions affecting core business entities. Links to admin, timestamp, entity type/ID, action performed, and reason. ### AdminModeration Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/adminmoderation-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/adminmoderation-api` * **Production:** `https://ebaycclone.mindbricks.co/adminmoderation-api` ### `Get Moderationaction` API Get a single moderation action log by ID. Used to review admin audit trails; accessible only to platform admins. **Rest Route** The `getModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `getModerationAction` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | **moderationActionId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/moderationactions/:moderationActionId** ```js axios({ method: 'GET', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Moderationaction` API Soft-deletes a moderation action log record (dangerous; allowed only to superadmins or strict manual correction), primarily for audit correction or internal error cleanup. Usually, moderation logs are immutable. **Rest Route** The `deleteModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `deleteModerationAction` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | **moderationActionId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/moderationactions/:moderationActionId** ```js axios({ method: 'DELETE', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Moderationaction` API Logs an admin moderation or override action in the system for audit and traceability. Requires admin login, takes context from session, and creates an audit entry for any admin operation over any entity type. **Rest Route** The `createModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions` **Rest Request Parameters** The `createModerationAction` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | entityId | ID | true | request.body?.entityId | | entityType | Enum | true | request.body?.entityType | | reason | String | true | request.body?.reason | | actionType | Enum | true | request.body?.actionType | **entityId** : ID of target entity affected by moderation (user/product/etc). **entityType** : Type of entity affected (USER, PRODUCT, FEEDBACK, MEDIA, CATEGORY, NOTIFICATION, ORDER, SEARCHINDEX). **reason** : Explanation or justification for the moderation action performed. **actionType** : Type of moderation action (e.g., SOFT_DELETE, RESTORE, UPDATE_ROLE, MANUAL_CORRECTION, MEDIA_FLAG, INDEX_REBUILD, PAYMENT_FIX, FEEDBACK_OVERRIDE, ADMIN_NOTE). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/moderationactions** ```js axios({ method: 'POST', url: '/v1/moderationactions', data: { entityId:"ID", entityType:"Enum", reason:"String", actionType:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Moderationactions` API List moderation actions for admin dashboard/audit search. Supports filtering by admin, entityType, entityId, actionType, and date. Always sorted by most recent action. **Rest Route** The `listModerationActions` API REST controller can be triggered via the following route: `/v1/moderationactions` **Rest Request Parameters** The `listModerationActions` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/moderationactions** ```js axios({ method: 'GET', url: '/v1/moderationactions', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationActions", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "moderationActions": [ { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Moderationaction` API Allows update of explanation/note on a moderation action for correction (typically by admin or superadmin only). No entity/type/admin may be changed after creation; only 'reason' is editable for audit consistency. **Rest Route** The `updateModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `updateModerationAction` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | | reason | String | false | request.body?.reason | **moderationActionId** : This id paremeter is used to select the required data object that will be updated **reason** : Explanation or justification for the moderation action performed. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/moderationactions/:moderationActionId** ```js axios({ method: 'PATCH', url: `/v1/moderationactions/${moderationActionId}`, data: { reason:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## WatchlistCart Service Handles user watchlists (with custom folders) and shopping cart preparation for checkout, strictly enforcing only fixed-price products in carts, supporting item moves/bulk operations, and robust default/folder logic.. ### WatchlistCart Service Data Objects **WatchlistItem** Item in a user’s watchlist, optionally in a named folder; references product and user. **CartItem** Single product pending checkout in a user’s cart. Only fixed-price products permitted; quantity supported for multi-unit purchases (if allowed). **WatchlistList** A named folder/list in a user’s watchlist. Default list exists for all users. Custom lists may be created and deleted. ### WatchlistCart Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/watchlistcart-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/watchlistcart-api` * **Production:** `https://ebaycclone.mindbricks.co/watchlistcart-api` ### `List Watchlistlist` API List all lists in user’s watchlists. Supports listing by listId for folders. **Rest Route** The `listWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists` **Rest Request Parameters** The `listWatchlistList` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/watchlistlists** ```js axios({ method: 'GET', url: '/v1/watchlistlists', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Cartitems` API List all cart items for a user (pending checkout). **Rest Route** The `listCartItems` API REST controller can be triggered via the following route: `/v1/cartitems` **Rest Request Parameters** The `listCartItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/cartitems** ```js axios({ method: 'GET', url: '/v1/cartitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "price": "Double", "title": "String", "type": "Enum", "type_idx": "Integer", "mediaAssetIds": "ID" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Cartitem` API Remove an item from the user’s cart. **Rest Route** The `deleteCartItem` API REST controller can be triggered via the following route: `/v1/cartitems/:cartItemId` **Rest Request Parameters** The `deleteCartItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | **cartItemId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/cartitems/:cartItemId** ```js axios({ method: 'DELETE', url: `/v1/cartitems/${cartItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Watchlistitem` API Add product to user’s watchlist (default or target list/folder). One (user, product, list) per item enforced. Block duplicates. **Rest Route** The `createWatchlistItem` API REST controller can be triggered via the following route: `/v1/watchlistitems` **Rest Request Parameters** The `createWatchlistItem` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | productId | ID | true | request.body?.productId | | listId | ID | false | request.body?.listId | **addedAt** : Timestamp watchlist item created. **productId** : Referenced product in the watchlist. **listId** : Owning watchlistList; null if in default watchlist. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/watchlistitems** ```js axios({ method: 'POST', url: '/v1/watchlistitems', data: { addedAt:"Date", productId:"ID", listId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Watchlistitems` API List all products in user’s watchlists. Supports listing by listId for folders. **Rest Route** The `listWatchlistItems` API REST controller can be triggered via the following route: `/v1/watchlistitems` **Rest Request Parameters** The `listWatchlistItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/watchlistitems** ```js axios({ method: 'GET', url: '/v1/watchlistitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Cartitemquantity` API Change the quantity for a cart item. User must own the item. **Rest Route** The `updateCartItemQuantity` API REST controller can be triggered via the following route: `/v1/cartitemquantity/:cartItemId` **Rest Request Parameters** The `updateCartItemQuantity` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | | quantity | Integer | false | request.body?.quantity | **cartItemId** : This id paremeter is used to select the required data object that will be updated **quantity** : How many units (if product allows). **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/cartitemquantity/:cartItemId** ```js axios({ method: 'PATCH', url: `/v1/cartitemquantity/${cartItemId}`, data: { quantity:"Integer", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Watchlistlist` API Create a new custom watchlist folder. Name must be unique per user; ‘Default’ is reserved for system. **Rest Route** The `createWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists` **Rest Request Parameters** The `createWatchlistList` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | name | String | true | request.body?.name | **name** : Custom folder or list name. 'Default' is reserved (non-deletable for each user). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/watchlistlists** ```js axios({ method: 'POST', url: '/v1/watchlistlists', data: { name:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Watchlistlist` API Delete a custom watchlist (folder). Items are reassigned to user’s default list. Cannot delete default list. **Rest Route** The `deleteWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists/:watchlistListId` **Rest Request Parameters** The `deleteWatchlistList` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistListId | ID | true | request.params?.watchlistListId | **watchlistListId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistlists/:watchlistListId** ```js axios({ method: 'DELETE', url: `/v1/watchlistlists/${watchlistListId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Watchlistitem` API Remove a product from a user’s watchlist. **Rest Route** The `deleteWatchlistItem` API REST controller can be triggered via the following route: `/v1/watchlistitems/:watchlistItemId` **Rest Request Parameters** The `deleteWatchlistItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistItemId | ID | true | request.params?.watchlistItemId | **watchlistItemId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistitems/:watchlistItemId** ```js axios({ method: 'DELETE', url: `/v1/watchlistitems/${watchlistItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Cartitem` API Add an item to the user’s cart. Only fixed-price products allowed. Duplicates not permitted. **Rest Route** The `createCartItem` API REST controller can be triggered via the following route: `/v1/cartitems` **Rest Request Parameters** The `createCartItem` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | **addedAt** : Timestamp added to cart. **quantity** : How many units (if product allows). **productId** : Product being checked out. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/cartitems** ```js axios({ method: 'POST', url: '/v1/cartitems', data: { addedAt:"Date", quantity:"Integer", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Do Userwatchlist` API userwatchlist **Rest Route** The `userwatchlist` API REST controller can be triggered via the following route: `/v1/userwatchlist` **Rest Request Parameters** The `userwatchlist` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userwatchlist** ```js axios({ method: 'GET', url: '/v1/userwatchlist', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Usercartitems` API list all cart items adde by user **Rest Route** The `listUserCartItems` API REST controller can be triggered via the following route: `/v1/usercartitems` **Rest Request Parameters** The `listUserCartItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/usercartitems** ```js axios({ method: 'GET', url: '/v1/usercartitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "shipping": "Double" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Do Userwatchlistlists` API list all watch lists created by user **Rest Route** The `userwatchlistlists` API REST controller can be triggered via the following route: `/v1/userwatchlistlists` **Rest Request Parameters** The `userwatchlistlists` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userwatchlistlists** ```js axios({ method: 'GET', url: '/v1/userwatchlistlists', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ## ProductListing Service Handles product listings (both auction and fixed-price), image/media storage with validations, enforces immutable type, soft-delete, and public product discovery. ### ProductListing Service Data Objects **ProductListingMedia** Stores and manages images/media associated with products, including secure URL, MIME type, and size validation. Each asset can be used by multiple products. **ProductListingProduct** Represents a single product listing (fixed-price or auction) in the marketplace, with seller, category, type, price information, shipping details, media references, and dynamic auction fields. ### ProductListing Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/productlisting-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/productlisting-api` * **Production:** `https://ebaycclone.mindbricks.co/productlisting-api` ### `List Productlistingmedia` API List all media assets (admin or for media management/bulk preview). **Rest Route** The `listProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias` **Rest Request Parameters** The `listProductListingMedia` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias** ```js axios({ method: 'GET', url: '/v1/productlistingmedias', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedias", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingMedias": [ { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Productlistingproduct` API Get a single product listing. Checks isActive and public status. Includes media, category, subcategory, and seller info via joins. **Rest Route** The `getProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `getProductListingProduct` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | **productListingProductId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'GET', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Productlistingownproducts` API listing the loggedin user's products **Rest Route** The `listProductListingOwnProducts` API REST controller can be triggered via the following route: `/v1/productlistingownproducts` **Rest Request Parameters** The `listProductListingOwnProducts` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingownproducts** ```js axios({ method: 'GET', url: '/v1/productlistingownproducts', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Productlistingmedia` API Get a single media asset by ID (for admin or to display in product UI). **Rest Route** The `getProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` **Rest Request Parameters** The `getProductListingMedia` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | **productListingMediaId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'GET', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Productlistingproducts` API List public product listings. Only isActive=true records are returned. Includes category, subcategory, seller, media joins. Supports filtering. **Rest Route** The `listProductListingProducts` API REST controller can be triggered via the following route: `/v1/productlistingproducts` **Rest Request Parameters** The `listProductListingProducts` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts** ```js axios({ method: 'GET', url: '/v1/productlistingproducts', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Productlistingproduct` API Soft-delete a product listing. Only owner or admin can delete. **Rest Route** The `deleteProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `deleteProductListingProduct` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | **productListingProductId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'DELETE', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Productlistingproduct` API Update a product listing. Product type cannot be changed (immutable). **Rest Route** The `updateProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `updateProductListingProduct` api has got 21 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | | currency | String | false | request.body?.currency | | description | Text | false | request.body?.description | | condition | Enum | false | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | false | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | false | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | false | request.body?.shippingMethod | | shipping | Double | false | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | false | request.body?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | **productListingProductId** : This id paremeter is used to select the required data object that will be updated **currency** : ISO currency code (e.g. USD, EUR) **description** : Product detailed description **condition** : Condition of product: BRAND_NEW, NEW, or USED **startBid** : The opening bid value (for auction type products) **endPrice** : Optional immediate sale/upper end price for auction (if AUCTION type) **price** : Product price (required if fixed price type) **title** : Product title **startPrice** : Minimum starting price for auction (required if AUCTION type) **endBid** : The upper (max) bid value for auction products (if any) **estimatedDelivery** : Estimated delivery date for this product **shippingCurrency** : Currency code for shipping cost **mediaAssetIds** : References to associated product/media assets **shippingMethod** : Shipping option for product: STANDARD, EXPRESS, or FREE **shipping** : Shipping cost for this product **startBidDate** : Date/time when auction bidding begins **subcategoryId** : Reference to subcategory **categoryId** : Reference to parent category **endBidDate** : Date/time when auction bidding ends **currentBid** : Current highest bid for auction-type product (updated atomically on bid placement) **highestBidderId** : User ID of current highest bidder (auction-only, updated by auction microservice) **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'PATCH', url: `/v1/productlistingproducts/${productListingProductId}`, data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Productlistingproduct` API Create a new product listing (fixed or auction), conditioned on product type. Type is immutable after creation. **Rest Route** The `createProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts` **Rest Request Parameters** The `createProductListingProduct` api has got 21 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | description | Text | true | request.body?.description | | condition | Enum | true | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | true | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | type | Enum | true | request.body?.type | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | true | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | true | request.body?.shippingMethod | | shipping | Double | true | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | true | request.body?.subcategoryId | | categoryId | ID | true | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | **currency** : ISO currency code (e.g. USD, EUR) **description** : Product detailed description **condition** : Condition of product: BRAND_NEW, NEW, or USED **startBid** : The opening bid value (for auction type products) **endPrice** : Optional immediate sale/upper end price for auction (if AUCTION type) **price** : Product price (required if fixed price type) **title** : Product title **startPrice** : Minimum starting price for auction (required if AUCTION type) **type** : Product listing type, either FIXED or AUCTION (immutable after creation) **endBid** : The upper (max) bid value for auction products (if any) **estimatedDelivery** : Estimated delivery date for this product **shippingCurrency** : Currency code for shipping cost **mediaAssetIds** : References to associated product/media assets **shippingMethod** : Shipping option for product: STANDARD, EXPRESS, or FREE **shipping** : Shipping cost for this product **startBidDate** : Date/time when auction bidding begins **subcategoryId** : Reference to subcategory **categoryId** : Reference to parent category **endBidDate** : Date/time when auction bidding ends **currentBid** : Current highest bid for auction-type product (updated atomically on bid placement) **highestBidderId** : User ID of current highest bidder (auction-only, updated by auction microservice) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/productlistingproducts** ```js axios({ method: 'POST', url: '/v1/productlistingproducts', data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", type:"Enum", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Productlistingmedia` API Soft-delete a media asset (typically by admin or media owner for flagged/invalid content). **Rest Route** The `deleteProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` **Rest Request Parameters** The `deleteProductListingMedia` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | **productListingMediaId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'DELETE', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Productlistingmedia` API Create a new media asset record after validation. Used mainly by edge controller after upload. **Rest Route** The `createProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias` **Rest Request Parameters** The `createProductListingMedia` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | mimeType | String | true | request.body?.mimeType | | productId | ID | false | request.body?.productId | | url | String | true | request.body?.url | | size | Integer | true | request.body?.size | **mimeType** : MIME type of the uploaded media (e.g., image/jpeg) **productId** : ID of product associated with this media asset **url** : Secure, validated URL for the media asset (S3 or equivalent) **size** : Media size in bytes (for validation and quota) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/productlistingmedias** ```js axios({ method: 'POST', url: '/v1/productlistingmedias', data: { mimeType:"String", productId:"ID", url:"String", size:"Integer", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## OrderManagement Service Handles all marketplace orders, manual checkout flows for fixed-price/offer/auction settlements, Stripe payment processing and webhook reconciliation, explicit status updates (shipping, delivery, cancellation), and feedback eligibility via orderItems. ### OrderManagement Service Data Objects **OrderManagementOrder** Marketplace order record. Stores buyer, shipping, status, items, Stripe payment data, and manual shipment/delivery events. Only accessible to admins or the buyer/seller of order items. **OrderManagementOrderItem** Order line item representing purchase of a single product from a specific seller as part of an order. Enables feedback, delivery, and per-seller analytics. Immutable after order creation. **Sys_orderManagementOrderPayment** A payment storage object to store the payment life cyle of orders based on orderManagementOrder object. It is autocreated based on the source object's checkout config **Sys_paymentCustomer** A payment storage object to store the customer values of the payment platform **Sys_paymentMethod** A payment storage object to store the payment methods of the platform customers ### OrderManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/ordermanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/ordermanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/ordermanagement-api` ### `List Ordermanagementorders` API List orders, filtered for buyer and/or seller, or by admin. Includes select orderItems. **Rest Route** The `listOrderManagementOrders` API REST controller can be triggered via the following route: `/v1/ordermanagementorders` **Rest Request Parameters** The `listOrderManagementOrders` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ordermanagementorders', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Ordermanagementorderitem` API Get a specific order item (for feedback/business logic). **Rest Route** The `getOrderManagementOrderItem` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems/:orderManagementOrderItemId` **Rest Request Parameters** The `getOrderManagementOrderItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderItemId | ID | true | request.params?.orderManagementOrderItemId | **orderManagementOrderItemId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems/:orderManagementOrderItemId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderitems/${orderManagementOrderItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Ordermanagementorder` API Soft-delete/cancel order by admin or eligible actor prior to shipment. Sets status to CANCELLED and cancels active payment intent if pending. Irreversible and blocks feedback. **Rest Route** The `deleteOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` **Rest Request Parameters** The `deleteOrderManagementOrder` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorder` API Get single order by ID. Only accessible to admin, buyer, or relevant sellers of items within this order. Includes all orderItems. **Rest Route** The `getOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` **Rest Request Parameters** The `getOrderManagementOrder` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | **orderManagementOrderId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Ordermanagementorderstatus` API Update order status (manual shipment, delivery, cancellation/refund). Restricted: only seller of all items can mark as shipped, only buyer can confirm delivery, only admin can set refund/cancelled. Timestamps updated as per business rule. **Rest Route** The `updateOrderManagementOrderStatus` API REST controller can be triggered via the following route: `/v1/ordermanagementorderstatus/:orderManagementOrderId` **Rest Request Parameters** The `updateOrderManagementOrderStatus` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **status** : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderstatus/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderstatus/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Complete Orderstripewebhook` API Webhook endpoint called by Stripe to reconcile payment state and update order status based on paymentIntentId and event data. No authentication required (Stripe IPs only). **Rest Route** The `completeOrderStripeWebhook` API REST controller can be triggered via the following route: `/v1/completeorderstripewebhook/:orderManagementOrderId` **Rest Request Parameters** The `completeOrderStripeWebhook` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **status** : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/completeorderstripewebhook/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/completeorderstripewebhook/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderbyproductid` API get orders by productId **Rest Route** The `getOrderManagementOrderByProductId` API REST controller can be triggered via the following route: `/v1/ordermanagementorderbyproductid/:items` **Rest Request Parameters** The `getOrderManagementOrderByProductId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | items | String | true | request.params?.items | **orderManagementOrderId** : This id paremeter is used to query the required data object. **items** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderbyproductid/:items** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderbyproductid/${items}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Ordermanagementorder` API Creates an order and initiates Stripe payment. Validates that all products in the order are fixed-price, populates orderItems, saves Stripe customer/paymentMethod/paymentIntentId for reconciliation. Only accessible to buyers for own checkouts and only allows fixed-price product checkout (no auction). **Rest Route** The `createOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders` **Rest Request Parameters** The `createOrderManagementOrder` api has got 14 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderNumber | String | true | request.body?.orderNumber | | items | ID | false | request.body?.items | | paymentMethodId | String | true | request.body?.paymentMethodId | | stripeCustomerId | String | true | request.body?.stripeCustomerId | | paymentIntentId | String | false | request.body?.paymentIntentId | | shippingAddress | Object | true | request.body?.shippingAddress | | summary | Object | true | request.body?.summary | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderNumber** : Unique, human-friendly order number (displayed to users); enforced unique. **items** : Array of orderManagementOrderItem ids representing items in this order. **paymentMethodId** : Stripe paymentMethodId used for payment. Not stored if cash or other payment (future). **stripeCustomerId** : Stripe customerId of buyer; enables saved/paymentMethodId flows. **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **shippingAddress** : Shipping address for the order (copy of buyer address at purchase time). **summary** : Object with total, subtotal, currency, shipping, discount breakdown as snapshot of order at time of purchase. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorders** ```js axios({ method: 'POST', url: '/v1/ordermanagementorders', data: { orderNumber:"String", items:"ID", paymentMethodId:"String", stripeCustomerId:"String", paymentIntentId:"String", shippingAddress:"Object", summary:"Object", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderitems` API List order items for a given order or for buyer/seller analytics. Used for feedback management. **Rest Route** The `listOrderManagementOrderItems` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems` **Rest Request Parameters** The `listOrderManagementOrderItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Ownordermanagementorders` API list the loggedin user orders **Rest Route** The `listOwnOrderManagementOrders` API REST controller can be triggered via the following route: `/v1/ownordermanagementorders` **Rest Request Parameters** The `listOwnOrderManagementOrders` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ownordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ownordermanagementorders', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Lis Ordermanagementownorderitem` API list the loggedin user's order items **Rest Route** The `lisOrderManagementOwnOrderItem` API REST controller can be triggered via the following route: `/v1/lisordermanagementownorderitem` **Rest Request Parameters** The `lisOrderManagementOwnOrderItem` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/lisordermanagementownorderitem** ```js axios({ method: 'GET', url: '/v1/lisordermanagementownorderitem', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Ordermanagementorderitem` API create order item **Rest Route** The `createOrderManagementOrderItem` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems` **Rest Request Parameters** The `createOrderManagementOrderItem` api has got 8 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | shipping | Double | true | request.body?.shipping | | orderId | ID | true | request.body?.orderId | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | | price | Double | true | request.body?.price | | sellerId | ID | true | request.body?.sellerId | | title | String | true | request.body?.title | | currency | String | true | request.body?.currency | **shipping** : Shipping cost for this product (may be 0 for free shipping). **orderId** : Parent order this item belongs to; enables join and lifecycle tracking. **quantity** : Number of units purchased for this product. **productId** : ID of product purchased in this line item. **price** : Unit price for this product at purchase time. **sellerId** : UserId of seller (owner of product at purchase time). **title** : Product title at purchase time (copied for convenience/audit). **currency** : Currency code for price/shipping (ISO 4217). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderitems** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderitems', data: { shipping:"Double", orderId:"ID", quantity:"Integer", productId:"ID", price:"Double", sellerId:"ID", title:"String", currency:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpayment2` API This route is used to get the payment information by ID. **Rest Route** The `getOrderManagementOrderPayment2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `getOrderManagementOrderPayment2` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderpayments2` API This route is used to list all payments. **Rest Route** The `listOrderManagementOrderPayments2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayments2` **Rest Request Parameters** The `listOrderManagementOrderPayments2` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Ordermanagementorderpayment` API This route is used to create a new payment. **Rest Route** The `createOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment` **Rest Request Parameters** The `createOrderManagementOrderPayment` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderId | ID | true | request.body?.orderId | | paymentId | String | true | request.body?.paymentId | | paymentStatus | String | true | request.body?.paymentStatus | | statusLiteral | String | true | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | **orderId** : an ID value to represent the orderId which is the ID parameter of the source orderManagementOrder object **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderpayment', data: { orderId:"ID", paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Ordermanagementorderpayment` API This route is used to update an existing payment. **Rest Route** The `updateOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `updateOrderManagementOrderPayment` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | false | request.body?.paymentId | | paymentStatus | String | false | request.body?.paymentStatus | | statusLiteral | String | false | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | **sys_orderManagementOrderPaymentId** : This id paremeter is used to select the required data object that will be updated **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Ordermanagementorderpayment` API This route is used to delete a payment. **Rest Route** The `deleteOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `deleteOrderManagementOrderPayment` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderpayments2` API This route is used to list all payments. **Rest Route** The `listOrderManagementOrderPayments2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayments2` **Rest Request Parameters** The `listOrderManagementOrderPayments2` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Ordermanagementorderpaymentbyorderid` API This route is used to get the payment information by order id. **Rest Route** The `getOrderManagementOrderPaymentByOrderId` API REST controller can be triggered via the following route: `/v1/orderManagementOrderpaymentbyorderid/:orderId` **Rest Request Parameters** The `getOrderManagementOrderPaymentByOrderId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | orderId | String | true | request.params?.orderId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **orderId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbyorderid/:orderId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbyorderid/${orderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpaymentbypaymentid` API This route is used to get the payment information by payment id. **Rest Route** The `getOrderManagementOrderPaymentByPaymentId` API REST controller can be triggered via the following route: `/v1/orderManagementOrderpaymentbypaymentid/:paymentId` **Rest Request Parameters** The `getOrderManagementOrderPaymentByPaymentId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | true | request.params?.paymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **paymentId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbypaymentid/:paymentId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbypaymentid/${paymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpayment2` API This route is used to get the payment information by ID. **Rest Route** The `getOrderManagementOrderPayment2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `getOrderManagementOrderPayment2` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Start Ordermanagementorderpayment` API Start payment for orderManagementOrder **Rest Route** The `startOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/startordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `startOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to start a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/startordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/startordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Refresh Ordermanagementorderpayment` API Refresh payment info for orderManagementOrder from Stripe **Rest Route** The `refreshOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/refreshordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `refreshOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to refresh a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/refreshordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/refreshordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Callback Ordermanagementorderpayment` API Refresh payment values by gateway webhook call for orderManagementOrder **Rest Route** The `callbackOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/callbackordermanagementorderpayment` **Rest Request Parameters** The `callbackOrderManagementOrderPayment` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.body?.orderManagementOrderId | **orderManagementOrderId** : The order id parameter that will be read from webhook callback params **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/callbackordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/callbackordermanagementorderpayment', data: { orderManagementOrderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Get Paymentcustomerbyuserid` API This route is used to get the payment customer information by user id. **Rest Route** The `getPaymentCustomerByUserId` API REST controller can be triggered via the following route: `/v1/paymentcustomers/:userId` **Rest Request Parameters** The `getPaymentCustomerByUserId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_paymentCustomerId | ID | true | request.params?.sys_paymentCustomerId | | userId | String | true | request.params?.userId | **sys_paymentCustomerId** : This id paremeter is used to query the required data object. **userId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomers/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_paymentCustomer": { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Paymentcustomers` API This route is used to list all payment customers. **Rest Route** The `listPaymentCustomers` API REST controller can be triggered via the following route: `/v1/paymentcustomers` **Rest Request Parameters** The `listPaymentCustomers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers** ```js axios({ method: 'GET', url: '/v1/paymentcustomers', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentCustomers": [ { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Paymentcustomermethods` API This route is used to list all payment customer methods. **Rest Route** The `listPaymentCustomerMethods` API REST controller can be triggered via the following route: `/v1/paymentcustomermethods/:userId` **Rest Request Parameters** The `listPaymentCustomerMethods` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | String | true | request.params?.userId | **userId** : This parameter will be used to select the data objects that want to be listed **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomermethods/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomermethods/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentMethods", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentMethods": [ { "id": "ID", "paymentMethodId": "String", "userId": "ID", "customerId": "String", "cardHolderName": "String", "cardHolderZip": "String", "platform": "String", "cardInfo": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ## Feedback Service Handles feedback for order items: one feedback per buyer/orderItem, attached to sellerId for analytical feedback/rating aggregation and reputation tracking. Enables querying feedbacks received/given for sellers and buyers. test ### Feedback Service Data Objects **Feedback** One feedback per (buyer, orderItem). Stores rating (1-5), comment, ties to seller for analytics. Created only after delivery confirmed on order item. ### Feedback Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/feedback-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/feedback-api` * **Production:** `https://ebaycclone.mindbricks.co/feedback-api` ### `List Feedbacks` API List feedback with filtering by buyerId (given), sellerId (received), productId, or orderItemId. Used for showing seller profile, buyer profile, or order analytics. **Rest Route** The `listFeedbacks` API REST controller can be triggered via the following route: `/v1/feedbacks` **Rest Request Parameters** The `listFeedbacks` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/feedbacks** ```js axios({ method: 'GET', url: '/v1/feedbacks', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedbacks", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "feedbacks": [ { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Feedback` API Get a single feedback by id. Accessible to public (for seller profile, product, or audit views). **Rest Route** The `getFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `getFeedback` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | **feedbackId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/feedbacks/:feedbackId** ```js axios({ method: 'GET', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Feedback` API Update feedback (comment/rating) for existing feedback record (buyer only). Admin can update as override. **Rest Route** The `updateFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `updateFeedback` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | | rating | Integer | false | request.body?.rating | | comment | String | false | request.body?.comment | **feedbackId** : This id paremeter is used to select the required data object that will be updated **rating** : Rating (1-5 stars) submitted by buyer. Required. **comment** : Optional textual feedback comment, max ~500 chars. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/feedbacks/:feedbackId** ```js axios({ method: 'PATCH', url: `/v1/feedbacks/${feedbackId}`, data: { rating:"Integer", comment:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Feedback` API Delete (soft-delete) feedback (by buyer or admin). Only feedback owner or admin. **Rest Route** The `deleteFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `deleteFeedback` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | **feedbackId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/feedbacks/:feedbackId** ```js axios({ method: 'DELETE', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Feedback` API Buyer creates feedback for a delivered order item. Only allowed once per (buyer, orderItemId). Allowed only once order item is delivered. **Rest Route** The `createFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks` **Rest Request Parameters** The `createFeedback` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | rating | Integer | true | request.body?.rating | | orderId | ID | true | request.body?.orderId | | orderItemId | ID | true | request.body?.orderItemId | | sellerId | ID | true | request.body?.sellerId | | comment | String | false | request.body?.comment | | productId | ID | true | request.body?.productId | **rating** : Rating (1-5 stars) submitted by buyer. Required. **orderId** : Order containing this purchased item. Used for aggregation and validation. **orderItemId** : Purchased item (line item) in order. Feedback is per (buyer, orderItem). **sellerId** : Seller of product for analytics/aggregation. Not author; used for querying feedback about sellers. **comment** : Optional textual feedback comment, max ~500 chars. **productId** : The product listing being reviewed (snapshot at order time). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/feedbacks** ```js axios({ method: 'POST', url: '/v1/feedbacks', data: { rating:"Integer", orderId:"ID", orderItemId:"ID", sellerId:"ID", comment:"String", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # REST API GUIDE ## ebaycclone-searchindexing-service Maintains the denormalized search index (materialized view) for global, public search across products, sellers, categories, and subcategories. Handles indexing in response to entity events and exposes optimized query endpoints for BFF/aggregator. ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to: Email: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. ## Documentation Scope Welcome to the official documentation for the SearchIndexing Service's REST API. This document is designed to provide a comprehensive guide to interfacing with our SearchIndexing Service exclusively through RESTful API endpoints. **Intended Audience** This documentation is intended for developers and integrators who are looking to interact with the SearchIndexing Service via HTTP requests for purposes such as creating, updating, deleting and querying SearchIndexing objects. **Overview** Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases. Beyond REST It's important to note that the SearchIndexing Service also supports alternative methods of interaction, such as gRPC and messaging via a Message Broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation. ## Authentication And Authorization To ensure secure access to the SearchIndexing service's protected endpoints, a project-wide access token is required. This token serves as the primary method for authenticating requests to our service. However, it's important to note that access control varies across different routes: **Protected API**: Certain API (routes) require specific authorization levels. Access to these routes is contingent upon the possession of a valid access token that meets the route-specific authorization criteria. Unauthorized requests to these routes will be rejected. **Public API **: The service also includes public API (routes) that are accessible without authentication. These public endpoints are designed for open access and do not require an access token. ### Token Locations When including your access token in a request, ensure it is placed in one of the following specified locations. The service will sequentially search these locations for the token, utilizing the first one it encounters. | Location | Token Name / Param Name | | ---------------------- | ---------------------------- | | Query | access_token | | Authorization Header | Bearer | | Header | ebaycclone-access-token| | Cookie | ebaycclone-access-token| Please ensure the token is correctly placed in one of these locations, using the appropriate label as indicated. The service prioritizes these locations in the order listed, processing the first token it successfully identifies. ## Api Definitions This section outlines the API endpoints available within the SearchIndexing service. Each endpoint can receive parameters through various methods, meticulously described in the following definitions. It's important to understand the flexibility in how parameters can be included in requests to effectively interact with the SearchIndexing service. This service is configured to listen for HTTP requests on port `3008`, serving both the main API interface and default administrative endpoints. The following routes are available by default: * **API Test Interface (API Face):** `/` * **Swagger Documentation:** `/swagger` * **Postman Collection Download:** `/getPostmanCollection` * **Health Checks:** `/health` and `/admin/health` * **Current Session Info:** `/currentuser` * **Favicon:** `/favicon.ico` This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/searchindexing-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/searchindexing-api` * **Production:** `https://ebaycclone.mindbricks.co/searchindexing-api` **Parameter Inclusion Methods:** Parameters can be incorporated into API requests in several ways, each with its designated location. Understanding these methods is crucial for correctly constructing your requests: **Query Parameters:** Included directly in the URL's query string. **Path Parameters:** Embedded within the URL's path. **Body Parameters:** Sent within the JSON body of the request. **Session Parameters:** Automatically read from the session object. This method is used for parameters that are intrinsic to the user's session, such as userId. When using an API that involves session parameters, you can omit these from your request. The service will automatically bind them to the API layer, provided that a session is associated with your request. **Note on Session Parameters:** Session parameters represent a unique method of parameter inclusion, relying on the context of the user's session. A common example of a session parameter is userId, which the service automatically associates with your request when a session exists. This feature ensures seamless integration of user-specific data without manual input for each request. By adhering to the specified parameter inclusion methods, you can effectively utilize the SearchIndexing service's API endpoints. For detailed information on each endpoint, including required parameters and their accepted locations, refer to the individual API definitions below. ### Common Parameters The `SearchIndexing` service's business API support several common parameters designed to modify and enhance the behavior of API requests. These parameters are not individually listed in the API route definitions to avoid repetition. Instead, refer to this section to understand how to leverage these common behaviors across different routes. Note that all common parameters should be included in the query part of the URL. ### Supported Common Parameters: - **getJoins (BOOLEAN)**: Controls whether to retrieve associated objects along with the main object. By default, `getJoins` is assumed to be `true`. Set it to `false` if you prefer to receive only the main fields of an object, excluding its associations. - **excludeCQRS (BOOLEAN)**: Applicable only when `getJoins` is `true`. By default, `excludeCQRS` is set to `false`. Enabling this parameter (`true`) omits non-local associations, which are typically more resource-intensive as they require querying external services like ElasticSearch for additional information. Use this to optimize response times and resource usage. - **requestId (String)**: Identifies a request to enable tracking through the service's log chain. A random hex string of 32 characters is assigned by default. If you wish to use a custom `requestId`, simply include it in your query parameters. - **caching (BOOLEAN)**: Determines the use of caching for query API. By default, caching is enabled (`true`). To ensure the freshest data directly from the database, set this parameter to `false`, bypassing the cache. - **cacheTTL (Integer)**: Specifies the Time-To-Live (TTL) for query caching, in seconds. This is particularly useful for adjusting the default caching duration (5 minutes) for `get list` queries. Setting a custom `cacheTTL` allows you to fine-tune the cache lifespan to meet your needs. - **pageNumber (Integer)**: For paginated `get list` API's, this parameter selects which page of results to retrieve. The default is `1`, indicating the first page. To disable pagination and retrieve all results, set `pageNumber` to `0`. - **pageRowCount (Integer)**: In conjunction with paginated API's, this parameter defines the number of records per page. The default value is `25`. Adjusting `pageRowCount` allows you to control the volume of data returned in a single request. By utilizing these common parameters, you can tailor the behavior of API requests to suit your specific requirements, ensuring optimal performance and usability of the `SearchIndexing` service. ### Error Response If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity: - **400 Bad Request**: The request was improperly formatted or contained invalid parameters, preventing the server from processing it. - **401 Unauthorized**: The request lacked valid authentication credentials or the credentials provided do not grant access to the requested resource. - **404 Not Found**: The requested resource was not found on the server. - **500 Internal Server Error**: The server encountered an unexpected condition that prevented it from fulfilling the request. Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ### Object Structure of a Successfull Response When the `SearchIndexing` service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client. **Key Characteristics of the Response Envelope:** - **Data Presentation**: Depending on the nature of the request, the service returns either a single data object or an array of objects encapsulated within the JSON envelope. - **Creation and Update API**: These API routes return the unmodified (pure) form of the data object(s), without any associations to other data objects. - **Delete API**: Even though the data is removed from the database, the last known state of the data object(s) is returned in its pure form. - **Get Requests**: A single data object is returned in JSON format. - **Get List Requests**: An array of data objects is provided, reflecting a collection of resources. - **Data Structure and Joins**: The complexity of the data structure in the response can vary based on the API's architectural design and the join options specified in the request. The architecture might inherently limit join operations, or they might be dynamically controlled through query parameters. - **Pure Data Forms**: In some cases, the response mirrors the exact structure found in the primary data table, without extensions. - **Extended Data Forms**: Alternatively, responses might include data extended through joins with tables within the same service or aggregated from external sources, such as ElasticSearch indices related to other services. - **Join Varieties**: The extensions might involve one-to-one joins, resulting in single object associations, or one-to-many joins, leading to an array of objects. In certain instances, the data might even feature nested inclusions from other data objects. **Design Considerations**: The structure of a API's response data is meticulously crafted during the service's architectural planning. This design ensures that responses adequately reflect the intended data relationships and service logic, providing clients with rich and meaningful information. **Brief Data**: Certain API's return a condensed version of the object data, intentionally selecting only specific fields deemed useful for that request. In such instances, the API documentation will detail the properties included in the response, guiding developers on what to expect. ### API Response Structure The API utilizes a standardized JSON envelope to encapsulate responses. This envelope is designed to consistently deliver both the requested data and essential metadata, ensuring that clients can efficiently interpret and utilize the response. **HTTP Status Codes:** - **200 OK**: This status code is returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request has been processed successfully. - **201 Created**: This status code is specific to CREATE operations, signifying that the requested resource has been successfully created. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling the successful execution of the request. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3 "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` - **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation performed. **Handling Errors:** For details on handling error scenarios and understanding the structure of error responses, please refer to the "Error Response" section provided earlier in this documentation. It outlines how error conditions are communicated, including the use of HTTP status codes and standardized JSON structures for error messages. ## Resources SearchIndexing service provides the following resources which are stored in its own database as a data object. Note that a resource for an api access is a data object for the service. ### SearchIndex resource *Resource Definition* : Materialized/denormalized search index record for a marketplace entity (product, seller, category, subcategory). Used exclusively for high-speed querying in BFF global/public search. *SearchIndex Resource Properties* | Name | Type | Required | Default | Definition | | ---- | ---- | -------- | ------- | ---------- | | **documentType** | Enum | | | *Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY* | | **document** | Object | | | *Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType.* | | **referenceId** | ID | | | *ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers.* | | **indexedAt** | Date | | | *Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing.* | #### Enum Properties Enum properties are represented as strings in the database. The values are mapped to their corresponding names in the application layer. ##### documentType Enum Property *Property Definition* : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY*Enum Options* | Name | Value | Index | | ---- | ----- | ----- | | **PRODUCT** | `"PRODUCT""` | 0 | | **SELLER** | `"SELLER""` | 1 | | **CATEGORY** | `"CATEGORY""` | 2 | | **SUBCATEGORY** | `"SUBCATEGORY""` | 3 | ## Business Api ### List Searchindexes API *API Definition* : List/search search index entries by type or referenceId (used by BFF/global search). Always excludes inactive (soft-deleted) records. Supports filtering and full-text search filters by documentType/referenceId for admin/maintenance use. *API Crud Type* : list *Default access route* : *GET* `/v1/searchindexes` The listSearchIndexes api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/searchindexes** ```js axios({ method: 'GET', url: '/v1/searchindexes', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`searchIndices`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"searchIndices","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","searchIndices":[{"id":"ID","documentType":"Enum","documentType_idx":"Integer","document":"Object","referenceId":"ID","indexedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For List Searchindexes](businessApi/listSearchIndexes). ### Update Searchindex API *API Definition* : Update an existing searchIndex record (by (documentType, referenceId) or id). Used in response to events (entity edit, data change); internal/automation/admin only. *API Crud Type* : update *Default access route* : *PATCH* `/v1/searchindexs/:searchIndexId` #### Parameters The updateSearchIndex api has got 5 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | | documentType | Enum | false | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | false | request.body?.indexedAt | To access the api you can use the **REST** controller with the path **PATCH /v1/searchindexs/:searchIndexId** ```js axios({ method: 'PATCH', url: `/v1/searchindexs/${searchIndexId}`, data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`searchIndex`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"searchIndex","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"searchIndex":{"id":"ID","documentType":"Enum","documentType_idx":"Integer","document":"Object","referenceId":"ID","indexedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Update Searchindex](businessApi/updateSearchIndex). ### Delete Searchindex API *API Definition* : Soft-delete a searchIndex record (by id or by (documentType, referenceId)). Typical use: in response to entity soft-delete; internal/automation/admin only. *API Crud Type* : delete *Default access route* : *DELETE* `/v1/searchindexs/:searchIndexId` #### Parameters The deleteSearchIndex api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | To access the api you can use the **REST** controller with the path **DELETE /v1/searchindexs/:searchIndexId** ```js axios({ method: 'DELETE', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`searchIndex`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"searchIndex","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"searchIndex":{"id":"ID","documentType":"Enum","documentType_idx":"Integer","document":"Object","referenceId":"ID","indexedAt":"Date","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Delete Searchindex](businessApi/deleteSearchIndex). ### Create Searchindex API *API Definition* : Create a new searchIndex record (internal, used by event triggers and admin tools only). Typically called when a new product/seller/category/subcategory is created. *API Crud Type* : create *Default access route* : *POST* `/v1/searchindexs` #### Parameters The createSearchIndex api has got 4 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | documentType | Enum | true | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | true | request.body?.indexedAt | To access the api you can use the **REST** controller with the path **POST /v1/searchindexs** ```js axios({ method: 'POST', url: '/v1/searchindexs', data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`searchIndex`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"searchIndex","method":"POST","action":"create","appVersion":"Version","rowCount":1,"searchIndex":{"id":"ID","documentType":"Enum","documentType_idx":"Integer","document":"Object","referenceId":"ID","indexedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Create Searchindex](businessApi/createSearchIndex). ### Get Searchindex API *API Definition* : Get a single denormalized index record (by id, or documentType+referenceId). Used by BFF for full entity search. Always excludes inactive records unless forced (admin only path). *API Crud Type* : get *Default access route* : *GET* `/v1/searchindexs/:searchIndexId` #### Parameters The getSearchIndex api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | To access the api you can use the **REST** controller with the path **GET /v1/searchindexs/:searchIndexId** ```js axios({ method: 'GET', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`searchIndex`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"searchIndex","method":"GET","action":"get","appVersion":"Version","rowCount":1,"searchIndex":{"id":"ID","documentType":"Enum","documentType_idx":"Integer","document":"Object","referenceId":"ID","indexedAt":"Date","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Get Searchindex](businessApi/getSearchIndex). ### Authentication Specific Routes ### Common Routes ### Route: currentuser *Route Definition*: Retrieves the currently authenticated user's session information. *Route Type*: sessionInfo *Access Route*: `GET /currentuser` #### Parameters This route does **not** require any request parameters. #### Behavior - Returns the authenticated session object associated with the current access token. - If no valid session exists, responds with a 401 Unauthorized. ```js // Sample GET /currentuser call axios.get("/currentuser", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** Returns the session object, including user-related data and token information. ``` { "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", "roleId": "user", "tenantId": "abc123", "accessToken": "jwt-token-string", ... } ``` **Error Response** **401 Unauthorized:** No active session found. ``` { "status": "ERR", "message": "No login found" } ``` **Notes** * This route is typically used by frontend or mobile applications to fetch the current session state after login. * The returned session includes key user identity fields, tenant information (if applicable), and the access token for further authenticated requests. * Always ensure a valid access token is provided in the request to retrieve the session. ### Route: permissions `*Route Definition*`: Retrieves all effective permission records assigned to the currently authenticated user. `*Route Type*`: permissionFetch *Access Route*: `GET /permissions` #### Parameters This route does **not** require any request parameters. #### Behavior - Fetches all active permission records (`givenPermissions` entries) associated with the current user session. - Returns a full array of permission objects. - Requires a valid session (`access token`) to be available. ```js // Sample GET /permissions call axios.get("/permissions", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** Returns an array of permission objects. ```json [ { "id": "perm1", "permissionName": "adminPanel.access", "roleId": "admin", "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" }, { "id": "perm2", "permissionName": "orders.manage", "roleId": null, "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" } ] ``` Each object reflects a single permission grant, aligned with the givenPermissions model: - `**permissionName**`: The permission the user has. - `**roleId**`: If the permission was granted through a role. -` **subjectUserId**`: If directly granted to the user. - `**subjectUserGroupId**`: If granted through a group. - `**objectId**`: If tied to a specific object (OBAC). - `**canDo**`: True or false flag to represent if permission is active or restricted. **Error Responses** * **401 Unauthorized**: No active session found. ```json { "status": "ERR", "message": "No login found" } ``` * **500 Internal Server Error**: Unexpected error fetching permissions. **Notes** * The /permissions route is available across all backend services generated by Mindbricks, not just the auth service. * Auth service: Fetches permissions freshly from the live database (givenPermissions table). * Other services: Typically use a cached or projected view of permissions stored in a common ElasticSearch store, optimized for faster authorization checks. > **Tip**: > Applications can cache permission results client-side or server-side, but should occasionally refresh by calling this endpoint, especially after login or permission-changing operations. ### Route: permissions/:permissionName *Route Definition*: Checks whether the current user has access to a specific permission, and provides a list of scoped object exceptions or inclusions. *Route Type*: permissionScopeCheck *Access Route*: `GET /permissions/:permissionName` #### Parameters | Parameter | Type | Required | Population | |------------------|--------|----------|------------------------| | permissionName | String | Yes | `request.params.permissionName` | #### Behavior - Evaluates whether the current user **has access** to the given `permissionName`. - Returns a structured object indicating: - Whether the permission is generally granted (`canDo`) - Which object IDs are explicitly included or excluded from access (`exceptions`) - Requires a valid session (`access token`). ```js // Sample GET /permissions/orders.manage axios.get("/permissions/orders.manage", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** ```json { "canDo": true, "exceptions": [ "a1f2e3d4-xxxx-yyyy-zzzz-object1", "b2c3d4e5-xxxx-yyyy-zzzz-object2" ] } ``` * If `canDo` is `true`, the user generally has the permission, but not for the objects listed in `exceptions` (i.e., restrictions). * If `canDo` is `false`, the user does not have the permission by default — but only for the objects in `exceptions`, they do have permission (i.e., selective overrides). * The exceptions array contains valid **UUID strings**, each corresponding to an object ID (typically from the data model targeted by the permission). ## Copyright All sources, documents and other digital materials are copyright of . ## About Us For more information please visit our website: . . . # Service Design Specification **ebaycclone-searchindexing-service** documentation -Version:**`1.0.0`** ## Scope This document provides a structured architectural overview of the `searchIndexing` microservice, detailing its configuration, data model, authorization logic, business rules, and API design. It has been automatically generated based on the service definition within Mindbricks, ensuring that the information reflects the source of truth used during code generation and deployment. The document is intended to serve multiple audiences: * **Service architects** can use it to validate design decisions and ensure alignment with broader architectural goals. * **Developers and maintainers** will find it useful for understanding the structure and behavior of the service, facilitating easier debugging, feature extension, and integration with other systems. * **Stakeholders and reviewers** can use it to gain a clear understanding of the service's capabilities and domain logic. > **Note for Frontend Developers**: While this document is valuable for understanding business logic and data interactions, please refer to the [Service API Documentation](#) for endpoint-level specifications and integration details. > **Note for Backend Developers**: Since the code for this service is automatically generated by Mindbricks, you typically won't need to implement or modify it manually. However, this document is especially valuable when you're building other services—whether within Mindbricks or externally—that need to interact with or depend on this service. It provides a clear reference to the service's data contracts, business rules, and API structure, helping ensure compatibility and correct integration. ## `SearchIndexing` Service Settings [**Edit**](searchindexing/serviceSettings) Maintains the denormalized search index (materialized view) for global, public search across products, sellers, categories, and subcategories. Handles indexing in response to entity events and exposes optimized query endpoints for BFF/aggregator. ### Service Overview This service is configured to listen for HTTP requests on port `3008`, serving both the main API interface and default administrative endpoints. The following routes are available by default: * **API Test Interface (API Face):** `/` * **Swagger Documentation:** `/swagger` * **Postman Collection Download:** `/getPostmanCollection` * **Health Checks:** `/health` and `/admin/health` * **Current Session Info:** `/currentuser` * **Favicon:** `/favicon.ico` The service uses a **PostgreSQL** database for data storage, with the database name set to `ebaycclone-searchindexing-service`. This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/searchindexing-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/searchindexing-api` * **Production:** `https://ebaycclone.mindbricks.co/searchindexing-api` ### Authentication & Security - **Login Required**: Yes This service requires user authentication for access. It supports both JWT and RSA-based authentication mechanisms, ensuring secure user sessions and data integrity. If a crud route also is configured to require login, it will check a valid JWT token in the request query/header/bearer/cookie. If the token is valid, it will extract the user information from the token and make the fetched session data available in the request context. ### Service Data Objects The service uses a **PostgreSQL** database for data storage, with the database name set to `ebaycclone-searchindexing-service`. Data deletion is managed using a **soft delete** strategy. Instead of removing records from the database, they are flagged as inactive by setting the `isActive` field to `false`. | Object Name | Description | Public Access | |-------------|-------------|---------------| | `searchIndex` | Materialized/denormalized search index record for a marketplace entity (product, seller, category, subcategory). Used exclusively for high-speed querying in BFF global/public search. | accessProtected | ## searchIndex Data Object ### Object Overview **Description:** Materialized/denormalized search index record for a marketplace entity (product, seller, category, subcategory). Used exclusively for high-speed querying in BFF global/public search. This object represents a core data structure within the service and acts as the blueprint for database interaction, API generation, and business logic enforcement. It is defined using the `ObjectSettings` pattern, which governs its behavior, access control, caching strategy, and integration points with other systems such as Stripe and Redis. ### Core Configuration - **Soft Delete:** Enabled — Determines whether records are marked inactive (`isActive = false`) instead of being physically deleted. - **Public Access:** accessProtected — If enabled, anonymous users may access this object’s data depending on API-level rules. ### Composite Indexes - **searchIndex_type_refid_unique**: [documentType, referenceId] This composite index is defined to optimize query performance for complex queries involving multiple fields. The index also defines a conflict resolution strategy for duplicate key violations. When a new record would violate this composite index, the following action will be taken: **On Duplicate**: `doUpdate` The existing record will be updated with the new data.No error will be thrown. ### Properties Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `documentType` | Enum | Yes | Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY | | `document` | Object | Yes | Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. | | `referenceId` | ID | Yes | ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. | | `indexedAt` | Date | Yes | Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value is set. ### Default Values Default values are automatically assigned to properties when a new object is created, if no value is provided in the request body. Since default values are applied on db level, they should be literal values, not expressions.If you want to use expressions, you can use transposed parameters in any business API to set default values dynamically. - **documentType**: "PRODUCT" - **document**: {} - **referenceId**: '00000000-0000-0000-0000-000000000000' - **indexedAt**: new Date() ### Auto Update Properties `documentType` `document` `referenceId` `indexedAt` An update crud API created with the option `Auto Params` enabled will automatically update these properties with the provided values in the request body. If you want to update any property in your own business logic not by user input, you can set the `Allow Auto Update` option to false. These properties will be added to the update API's body parameters and can be updated by the user if any value is provided in the request body. ### Enum Properties Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an addtional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the index property to sort by the enum value or when your enum options represent a sequence of values. - **documentType**: [PRODUCT, SELLER, CATEGORY, SUBCATEGORY] ### Elastic Search Indexing `documentType` `document` `referenceId` `indexedAt` Properties that are indexed in Elastic Search will be searchable via the Elastic Search API. While all properties are stored in the elastic search index of the data object, only those marked for Elastic Search indexing will be available for search queries. ### Database Indexing `documentType` `referenceId` `indexedAt` Properties that are indexed in the database will be optimized for query performance, allowing for faster data retrieval. Make a property indexed in the database if you want to use it frequently in query filters or sorting. ### Cache Select Properties `referenceId` Cache select properties are used to collect data from Redis entity cache with a different key than the data object id. This allows you to cache data that is not directly related to the data object id, but a frequently used filter. ### Secondary Key Properties `referenceId` Secondary key properties are used to create an additional indexed identifiers for the data object, allowing for alternative access patterns. Different than normal indexed properties, secondary keys will act as primary keys and Mindbricks will provide automatic secondary key db utility functions to access the data object by the secondary key. ### Filter Properties `documentType` `referenceId` `indexedAt` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's that have "Auto Params" enabled. - **documentType**: Enum has a filter named `documentType` - **referenceId**: ID has a filter named `referenceId` - **indexedAt**: Date has a filter named `indexedAt` ## Business Logic searchIndexing has got 5 Business APIs to manage its internal and crud logic. For the details of each business API refer to its chapter. * [List Searchindexes](/businessLogic/listsearchindexes) * [Update Searchindex](/businessLogic/updatesearchindex) * [Delete Searchindex](/businessLogic/deletesearchindex) * [Create Searchindex](/businessLogic/createsearchindex) * [Get Searchindex](/businessLogic/getsearchindex) ## Edge Controllers ### rebuildSearchIndex **Configuration:** - **Function Name**: `rebuildSearchIndex` - **Login Required**: Yes **REST Settings:** - **Path**: `/admin/rebuild-search-index` - **Method**: --- --- ## Service Library ### Functions No general functions defined. ### Hook Functions No hook functions defined. ### Edge Functions #### rebuildSearchIndex.js ```js // Admin/automation function to force full index regeneration for all materialized types. module.exports = async (request) => { // Example: Get all products, sellers, categories, subcategories (from upstream APIs). // For each, denormalize data and write as a searchIndex (upsert by (documentType, referenceId)). // Set indexedAt to now for each. // Details of fetching entities and document transformation are handled externally. return { status: 200, message: "Reindex triggered. Actual rebuild will be handled by backend process queue." }; }; ``` ### Templates No templates defined. ### Assets No assets defined. ### Public Assets No public assets defined. --- ### Event Emission --- ## Integration Patterns ## Deployment Considerations ### Environment Configuration - **HTTP Port**: `3008` - **Database Type**: MongoDB - **Global Soft Delete**: Enabled ## Implementation Guidelines ### Development Workflow 1. **Data Model Implementation**: Generate database schema from data object definitions 2. **CRUD Route Generation**: Implement auto-generated routes with custom logic 3. **Custom Logic Integration**: Implement hook functions and edge functions 4. **Authentication Integration**: Configure with project-level authentication 5. **Testing**: Unit and integration testing for all components ### Code Generation Expectations - **Database Schema**: Auto-generated from data objects and relationships - **API Routes**: REST endpoints with customizable behavior - **Validation Logic**: Input validation from property definitions - **Access Control**: Authentication and authorization middleware ### Custom Code Integration Points - **Hook Functions**: Lifecycle-specific custom logic - **Edge Functions**: Full request/response control - **Library Functions**: Reusable business logic - **Templates**: Dynamic content rendering ### Testing Strategy #### Unit Testing - Test all custom library functions - Test validation logic and business rules - Test hook function implementations #### Integration Testing - Test API endpoints with authentication scenarios - Test database operations and transactions - Test external integrations - Test event emission and Kafka integration #### Performance Testing - Load test high-traffic endpoints - Test caching effectiveness - Monitor database query performance - Test scalability under load --- ## Appendices ### Data Type Reference | Type | Description | Storage | |------|-------------|---------| | ID | Unique identifier | UUID (SQL) / ObjectID (NoSQL) | | String | Short text (≤255 chars) | VARCHAR | | Text | Long-form text | TEXT | | Integer | 32-bit whole numbers | INT | | Boolean | True/false values | BOOLEAN | | Double | 64-bit floating point | DOUBLE | | Float | 32-bit floating point | FLOAT | | Short | 16-bit integers | SMALLINT | | Object | JSON object | JSONB (PostgreSQL) / Object (MongoDB) | | Date | ISO 8601 timestamp | TIMESTAMP | | Enum | Fixed numeric values | SMALLINT with lookup | ### Enum Value Mappings #### Request Locations - `0`: Bearer token in Authorization header - `1`: Cookie value - `2`: Custom HTTP header - `3`: Query parameter - `4`: Request body property - `5`: URL path parameter - `6`: Session data - `7`: Root request object #### HTTP Methods - `0`: GET - `1`: POST - `2`: PUT - `3`: PATCH - `4`: DELETE ### Edge Function Signature ```javascript async function edgeFunction(request) { // Custom request processing // Return response object or throw error return { data: {}, status: 200, message: "Success" }; } ``` --- *This document was generated from the service architecture definition and should be kept in sync with implementation changes.* # EVENT GUIDE ## ebaycclone-watchlistcart-service Handles user watchlists (with custom folders) and shopping cart preparation for checkout, strictly enforcing only fixed-price products in carts, supporting item moves/bulk operations, and robust default/folder logic.. ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to: Email: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. # Documentation Scope Welcome to the official documentation for the `WatchlistCart` Service Event descriptions. This guide is dedicated to detailing how to subscribe to and listen for state changes within the `WatchlistCart` Service, offering an exclusive focus on event subscription mechanisms. **Intended Audience** This documentation is aimed at developers and integrators looking to monitor `WatchlistCart` Service state changes. It is especially relevant for those wishing to implement or enhance business logic based on interactions with `WatchlistCart` objects. **Overview** This section provides detailed instructions on monitoring service events, covering payload structures and demonstrating typical use cases through examples. # Authentication and Authorization Access to the `WatchlistCart` service's events is facilitated through the project's Kafka server, which is not accessible to the public. Subscription to a Kafka topic requires being on the same network and possessing valid Kafka user credentials. This document presupposes that readers have existing access to the Kafka server. Additionally, the service offers a public subscription option via REST for real-time data management in frontend applications, secured through REST API authentication and authorization mechanisms. To subscribe to service events via the REST API, please consult the Realtime REST API Guide. # Database Events Database events are triggered at the database layer, automatically and atomically, in response to any modifications at the data level. These events serve to notify subscribers about the creation, update, or deletion of objects within the database, distinct from any overarching business logic. Listening to database events is particularly beneficial for those focused on tracking changes at the database level. A typical use case for subscribing to database events is to replicate the data store of one service within another service's scope, ensuring data consistency and syncronization across services. For example, while a business operation such as "approve membership" might generate a high-level business event like `membership-approved`, the underlying database changes could involve multiple state updates to different entities. These might be published as separate events, such as `dbevent-member-updated` and `dbevent-user-updated`, reflecting the granular changes at the database level. Such detailed eventing provides a robust foundation for building responsive, data-driven applications, enabling fine-grained observability and reaction to the dynamics of the data landscape. It also facilitates the architectural pattern of event sourcing, where state changes are captured as a sequence of events, allowing for high-fidelity data replication and history replay for analytical or auditing purposes. ## DbEvent watchlistItem-created **Event topic**: `ebaycclone-watchlistcart-service-dbevent-watchlistitem-created` This event is triggered upon the creation of a `watchlistItem` data object in the database. The event payload encompasses the newly created data, encapsulated within the root of the paylod. **Event payload**: ```json {"id":"ID","userId":"ID","addedAt":"Date","productId":"ID","listId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent watchlistItem-updated **Event topic**: `ebaycclone-watchlistcart-service-dbevent-watchlistitem-updated` Activation of this event follows the update of a `watchlistItem` data object. The payload contains the updated information under the `watchlistItem` attribute, along with the original data prior to update, labeled as `old_watchlistItem` and also you can find the old and new versions of updated-only portion of the data.. **Event payload**: ```json { old_watchlistItem:{"id":"ID","userId":"ID","addedAt":"Date","productId":"ID","listId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, watchlistItem:{"id":"ID","userId":"ID","addedAt":"Date","productId":"ID","listId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, oldDataValues, newDataValues } ``` ## DbEvent watchlistItem-deleted **Event topic**: `ebaycclone-watchlistcart-service-dbevent-watchlistitem-deleted` This event announces the deletion of a `watchlistItem` data object, covering both hard deletions (permanent removal) and soft deletions (where the `isActive` attribute is set to false). Regardless of the deletion type, the event payload will present the data as it was immediately before deletion, highlighting an `isActive` status of false for soft deletions. **Event payload**: ```json {"id":"ID","userId":"ID","addedAt":"Date","productId":"ID","listId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent cartItem-created **Event topic**: `ebaycclone-watchlistcart-service-dbevent-cartitem-created` This event is triggered upon the creation of a `cartItem` data object in the database. The event payload encompasses the newly created data, encapsulated within the root of the paylod. **Event payload**: ```json {"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent cartItem-updated **Event topic**: `ebaycclone-watchlistcart-service-dbevent-cartitem-updated` Activation of this event follows the update of a `cartItem` data object. The payload contains the updated information under the `cartItem` attribute, along with the original data prior to update, labeled as `old_cartItem` and also you can find the old and new versions of updated-only portion of the data.. **Event payload**: ```json { old_cartItem:{"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, cartItem:{"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, oldDataValues, newDataValues } ``` ## DbEvent cartItem-deleted **Event topic**: `ebaycclone-watchlistcart-service-dbevent-cartitem-deleted` This event announces the deletion of a `cartItem` data object, covering both hard deletions (permanent removal) and soft deletions (where the `isActive` attribute is set to false). Regardless of the deletion type, the event payload will present the data as it was immediately before deletion, highlighting an `isActive` status of false for soft deletions. **Event payload**: ```json {"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent watchlistList-created **Event topic**: `ebaycclone-watchlistcart-service-dbevent-watchlistlist-created` This event is triggered upon the creation of a `watchlistList` data object in the database. The event payload encompasses the newly created data, encapsulated within the root of the paylod. **Event payload**: ```json {"id":"ID","name":"String","itemCount":"Integer","userId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## DbEvent watchlistList-updated **Event topic**: `ebaycclone-watchlistcart-service-dbevent-watchlistlist-updated` Activation of this event follows the update of a `watchlistList` data object. The payload contains the updated information under the `watchlistList` attribute, along with the original data prior to update, labeled as `old_watchlistList` and also you can find the old and new versions of updated-only portion of the data.. **Event payload**: ```json { old_watchlistList:{"id":"ID","name":"String","itemCount":"Integer","userId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, watchlistList:{"id":"ID","name":"String","itemCount":"Integer","userId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}, oldDataValues, newDataValues } ``` ## DbEvent watchlistList-deleted **Event topic**: `ebaycclone-watchlistcart-service-dbevent-watchlistlist-deleted` This event announces the deletion of a `watchlistList` data object, covering both hard deletions (permanent removal) and soft deletions (where the `isActive` attribute is set to false). Regardless of the deletion type, the event payload will present the data as it was immediately before deletion, highlighting an `isActive` status of false for soft deletions. **Event payload**: ```json {"id":"ID","name":"String","itemCount":"Integer","userId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` # ElasticSearch Index Events Within the `WatchlistCart` service, most data objects are mirrored in ElasticSearch indices, ensuring these indices remain syncronized with their database counterparts through creation, updates, and deletions. These indices serve dual purposes: they act as a data source for external services and furnish aggregated data tailored to enhance frontend user experiences. Consequently, an ElasticSearch index might encapsulate data in its original form or aggregate additional information from other data objects. These aggregations can include both one-to-one and one-to-many relationships not only with database objects within the same service but also across different services. This capability allows developers to access comprehensive, aggregated data efficiently. By subscribing to ElasticSearch index events, developers are notified when an index is updated and can directly obtain the aggregated entity within the event payload, bypassing the need for separate ElasticSearch queries. It's noteworthy that some services may augment another service's index by appending to the entity’s `extends` object. In such scenarios, an `*-extended` event will contain only the newly added data. Should you require the complete dataset, you would need to retrieve the full ElasticSearch index entity using the provided ID. This approach to indexing and event handling facilitates a modular, interconnected architecture where services can seamlessly integrate and react to changes, enriching the overall data ecosystem and enabling more dynamic, responsive applications. ## Index Event watchlistitem-created **Event topic**: `elastic-index-ebaycclone_watchlistitem-created` **Event payload**: ```json {"id":"ID","userId":"ID","addedAt":"Date","productId":"ID","listId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event watchlistitem-updated **Event topic**: `elastic-index-ebaycclone_watchlistitem-created` **Event payload**: ```json {"id":"ID","userId":"ID","addedAt":"Date","productId":"ID","listId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event watchlistitem-deleted **Event topic**: `elastic-index-ebaycclone_watchlistitem-deleted` **Event payload**: ```json {"id":"ID","userId":"ID","addedAt":"Date","productId":"ID","listId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event watchlistitem-extended **Event topic**: `elastic-index-ebaycclone_watchlistitem-extended` **Event payload**: ```js { id: id, extends: { [extendName]: "Object", [extendName + "_count"]: "Number", }, } ``` # Route Events Route events are emitted following the successful execution of a route. While most routes perform CRUD (Create, Read, Update, Delete) operations on data objects, resulting in route events that closely resemble database events, there are distinctions worth noting. A single route execution might trigger multiple CRUD actions and ElasticSearch indexing operations. However, for those primarily concerned with the overarching business logic and its outcomes, listening to the consolidated route event, published once at the conclusion of the route's execution, is more pertinent. Moreover, routes often deliver aggregated data beyond the primary database object, catering to specific client needs. For instance, creating a data object via a route might not only return the entity's data but also route-specific metrics, such as the executing user's permissions related to the entity. Alternatively, a route might automatically generate default child entities following the creation of a parent object. Consequently, the route event encapsulates a unified dataset encompassing both the parent and its children, in contrast to individual events triggered for each entity created. Therefore, subscribing to route events can offer a richer, more contextually relevant set of information aligned with business logic. The payload of a route event mirrors the REST response JSON of the route, providing a direct and comprehensive reflection of the data and metadata communicated to the client. This ensures that subscribers to route events receive a payload that encapsulates both the primary data involved and any additional information deemed significant at the business level, facilitating a deeper understanding and integration of the service's functional outcomes. ## Route Event watchlistlist-listed **Event topic** : `ebaycclone-watchlistcart-service-watchlistlist-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `watchlistLists` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`watchlistLists`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistLists","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","watchlistLists":[{"id":"ID","name":"String","itemCount":"Integer","userId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event cartitems-listed **Event topic** : `ebaycclone-watchlistcart-service-cartitems-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `cartItems` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`cartItems`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"cartItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","cartItems":[{"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID","product":[{"currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","price":"Double","title":"String","type":"Enum","type_idx":"Integer","mediaAssetIds":"ID"},{},{}]},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event cartitem-deleted **Event topic** : `ebaycclone-watchlistcart-service-cartitem-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `cartItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`cartItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"cartItem","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"cartItem":{"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event watchlistitem-created **Event topic** : `ebaycclone-watchlistcart-service-watchlistitem-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `watchlistItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`watchlistItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistItem","method":"POST","action":"create","appVersion":"Version","rowCount":1,"watchlistItem":{"id":"ID","userId":"ID","addedAt":"Date","productId":"ID","listId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event watchlistitems-listed **Event topic** : `ebaycclone-watchlistcart-service-watchlistitems-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `watchlistItems` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`watchlistItems`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","watchlistItems":[{"id":"ID","userId":"ID","addedAt":"Date","productId":"ID","listId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event cartitemquantity-updated **Event topic** : `ebaycclone-watchlistcart-service-cartitemquantity-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `cartItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`cartItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"cartItem","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"cartItem":{"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event watchlistlist-created **Event topic** : `ebaycclone-watchlistcart-service-watchlistlist-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `watchlistList` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`watchlistList`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistList","method":"POST","action":"create","appVersion":"Version","rowCount":1,"watchlistList":{"id":"ID","name":"String","itemCount":"Integer","userId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event watchlistlist-deleted **Event topic** : `ebaycclone-watchlistcart-service-watchlistlist-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `watchlistList` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`watchlistList`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistList","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"watchlistList":{"id":"ID","name":"String","itemCount":"Integer","userId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event watchlistitem-deleted **Event topic** : `ebaycclone-watchlistcart-service-watchlistitem-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `watchlistItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`watchlistItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistItem","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"watchlistItem":{"id":"ID","userId":"ID","addedAt":"Date","productId":"ID","listId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event cartitem-created **Event topic** : `ebaycclone-watchlistcart-service-cartitem-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `cartItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`cartItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"cartItem","method":"POST","action":"create","appVersion":"Version","rowCount":1,"cartItem":{"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event userwatchlist-done **Event topic** : `ebaycclone-watchlistcart-service-userwatchlist-done` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `watchlistItems` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`watchlistItems`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","watchlistItems":[{"id":"ID","userId":"ID","addedAt":"Date","productId":"ID","listId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event usercartitems-listed **Event topic** : `ebaycclone-watchlistcart-service-usercartitems-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `cartItems` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`cartItems`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"cartItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","cartItems":[{"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID","product":[{"currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","shipping":"Double"},{},{}]},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event userwatchlistlists-done **Event topic** : `ebaycclone-watchlistcart-service-userwatchlistlists-done` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `watchlistLists` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`watchlistLists`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistLists","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","watchlistLists":[{"id":"ID","name":"String","itemCount":"Integer","userId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Index Event cartitem-created **Event topic**: `elastic-index-ebaycclone_cartitem-created` **Event payload**: ```json {"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event cartitem-updated **Event topic**: `elastic-index-ebaycclone_cartitem-created` **Event payload**: ```json {"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event cartitem-deleted **Event topic**: `elastic-index-ebaycclone_cartitem-deleted` **Event payload**: ```json {"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event cartitem-extended **Event topic**: `elastic-index-ebaycclone_cartitem-extended` **Event payload**: ```js { id: id, extends: { [extendName]: "Object", [extendName + "_count"]: "Number", }, } ``` # Route Events Route events are emitted following the successful execution of a route. While most routes perform CRUD (Create, Read, Update, Delete) operations on data objects, resulting in route events that closely resemble database events, there are distinctions worth noting. A single route execution might trigger multiple CRUD actions and ElasticSearch indexing operations. However, for those primarily concerned with the overarching business logic and its outcomes, listening to the consolidated route event, published once at the conclusion of the route's execution, is more pertinent. Moreover, routes often deliver aggregated data beyond the primary database object, catering to specific client needs. For instance, creating a data object via a route might not only return the entity's data but also route-specific metrics, such as the executing user's permissions related to the entity. Alternatively, a route might automatically generate default child entities following the creation of a parent object. Consequently, the route event encapsulates a unified dataset encompassing both the parent and its children, in contrast to individual events triggered for each entity created. Therefore, subscribing to route events can offer a richer, more contextually relevant set of information aligned with business logic. The payload of a route event mirrors the REST response JSON of the route, providing a direct and comprehensive reflection of the data and metadata communicated to the client. This ensures that subscribers to route events receive a payload that encapsulates both the primary data involved and any additional information deemed significant at the business level, facilitating a deeper understanding and integration of the service's functional outcomes. ## Route Event watchlistlist-listed **Event topic** : `ebaycclone-watchlistcart-service-watchlistlist-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `watchlistLists` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`watchlistLists`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistLists","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","watchlistLists":[{"id":"ID","name":"String","itemCount":"Integer","userId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event cartitems-listed **Event topic** : `ebaycclone-watchlistcart-service-cartitems-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `cartItems` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`cartItems`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"cartItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","cartItems":[{"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID","product":[{"currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","price":"Double","title":"String","type":"Enum","type_idx":"Integer","mediaAssetIds":"ID"},{},{}]},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event cartitem-deleted **Event topic** : `ebaycclone-watchlistcart-service-cartitem-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `cartItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`cartItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"cartItem","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"cartItem":{"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event watchlistitem-created **Event topic** : `ebaycclone-watchlistcart-service-watchlistitem-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `watchlistItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`watchlistItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistItem","method":"POST","action":"create","appVersion":"Version","rowCount":1,"watchlistItem":{"id":"ID","userId":"ID","addedAt":"Date","productId":"ID","listId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event watchlistitems-listed **Event topic** : `ebaycclone-watchlistcart-service-watchlistitems-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `watchlistItems` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`watchlistItems`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","watchlistItems":[{"id":"ID","userId":"ID","addedAt":"Date","productId":"ID","listId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event cartitemquantity-updated **Event topic** : `ebaycclone-watchlistcart-service-cartitemquantity-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `cartItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`cartItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"cartItem","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"cartItem":{"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event watchlistlist-created **Event topic** : `ebaycclone-watchlistcart-service-watchlistlist-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `watchlistList` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`watchlistList`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistList","method":"POST","action":"create","appVersion":"Version","rowCount":1,"watchlistList":{"id":"ID","name":"String","itemCount":"Integer","userId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event watchlistlist-deleted **Event topic** : `ebaycclone-watchlistcart-service-watchlistlist-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `watchlistList` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`watchlistList`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistList","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"watchlistList":{"id":"ID","name":"String","itemCount":"Integer","userId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event watchlistitem-deleted **Event topic** : `ebaycclone-watchlistcart-service-watchlistitem-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `watchlistItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`watchlistItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistItem","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"watchlistItem":{"id":"ID","userId":"ID","addedAt":"Date","productId":"ID","listId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event cartitem-created **Event topic** : `ebaycclone-watchlistcart-service-cartitem-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `cartItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`cartItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"cartItem","method":"POST","action":"create","appVersion":"Version","rowCount":1,"cartItem":{"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event userwatchlist-done **Event topic** : `ebaycclone-watchlistcart-service-userwatchlist-done` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `watchlistItems` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`watchlistItems`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","watchlistItems":[{"id":"ID","userId":"ID","addedAt":"Date","productId":"ID","listId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event usercartitems-listed **Event topic** : `ebaycclone-watchlistcart-service-usercartitems-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `cartItems` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`cartItems`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"cartItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","cartItems":[{"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID","product":[{"currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","shipping":"Double"},{},{}]},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event userwatchlistlists-done **Event topic** : `ebaycclone-watchlistcart-service-userwatchlistlists-done` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `watchlistLists` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`watchlistLists`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistLists","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","watchlistLists":[{"id":"ID","name":"String","itemCount":"Integer","userId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Index Event watchlistlist-created **Event topic**: `elastic-index-ebaycclone_watchlistlist-created` **Event payload**: ```json {"id":"ID","name":"String","itemCount":"Integer","userId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event watchlistlist-updated **Event topic**: `elastic-index-ebaycclone_watchlistlist-created` **Event payload**: ```json {"id":"ID","name":"String","itemCount":"Integer","userId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event watchlistlist-deleted **Event topic**: `elastic-index-ebaycclone_watchlistlist-deleted` **Event payload**: ```json {"id":"ID","name":"String","itemCount":"Integer","userId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"} ``` ## Index Event watchlistlist-extended **Event topic**: `elastic-index-ebaycclone_watchlistlist-extended` **Event payload**: ```js { id: id, extends: { [extendName]: "Object", [extendName + "_count"]: "Number", }, } ``` # Route Events Route events are emitted following the successful execution of a route. While most routes perform CRUD (Create, Read, Update, Delete) operations on data objects, resulting in route events that closely resemble database events, there are distinctions worth noting. A single route execution might trigger multiple CRUD actions and ElasticSearch indexing operations. However, for those primarily concerned with the overarching business logic and its outcomes, listening to the consolidated route event, published once at the conclusion of the route's execution, is more pertinent. Moreover, routes often deliver aggregated data beyond the primary database object, catering to specific client needs. For instance, creating a data object via a route might not only return the entity's data but also route-specific metrics, such as the executing user's permissions related to the entity. Alternatively, a route might automatically generate default child entities following the creation of a parent object. Consequently, the route event encapsulates a unified dataset encompassing both the parent and its children, in contrast to individual events triggered for each entity created. Therefore, subscribing to route events can offer a richer, more contextually relevant set of information aligned with business logic. The payload of a route event mirrors the REST response JSON of the route, providing a direct and comprehensive reflection of the data and metadata communicated to the client. This ensures that subscribers to route events receive a payload that encapsulates both the primary data involved and any additional information deemed significant at the business level, facilitating a deeper understanding and integration of the service's functional outcomes. ## Route Event watchlistlist-listed **Event topic** : `ebaycclone-watchlistcart-service-watchlistlist-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `watchlistLists` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`watchlistLists`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistLists","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","watchlistLists":[{"id":"ID","name":"String","itemCount":"Integer","userId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event cartitems-listed **Event topic** : `ebaycclone-watchlistcart-service-cartitems-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `cartItems` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`cartItems`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"cartItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","cartItems":[{"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID","product":[{"currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","price":"Double","title":"String","type":"Enum","type_idx":"Integer","mediaAssetIds":"ID"},{},{}]},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event cartitem-deleted **Event topic** : `ebaycclone-watchlistcart-service-cartitem-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `cartItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`cartItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"cartItem","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"cartItem":{"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event watchlistitem-created **Event topic** : `ebaycclone-watchlistcart-service-watchlistitem-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `watchlistItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`watchlistItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistItem","method":"POST","action":"create","appVersion":"Version","rowCount":1,"watchlistItem":{"id":"ID","userId":"ID","addedAt":"Date","productId":"ID","listId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event watchlistitems-listed **Event topic** : `ebaycclone-watchlistcart-service-watchlistitems-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `watchlistItems` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`watchlistItems`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","watchlistItems":[{"id":"ID","userId":"ID","addedAt":"Date","productId":"ID","listId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event cartitemquantity-updated **Event topic** : `ebaycclone-watchlistcart-service-cartitemquantity-updated` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `cartItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`cartItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"cartItem","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"cartItem":{"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event watchlistlist-created **Event topic** : `ebaycclone-watchlistcart-service-watchlistlist-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `watchlistList` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`watchlistList`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistList","method":"POST","action":"create","appVersion":"Version","rowCount":1,"watchlistList":{"id":"ID","name":"String","itemCount":"Integer","userId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event watchlistlist-deleted **Event topic** : `ebaycclone-watchlistcart-service-watchlistlist-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `watchlistList` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`watchlistList`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistList","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"watchlistList":{"id":"ID","name":"String","itemCount":"Integer","userId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event watchlistitem-deleted **Event topic** : `ebaycclone-watchlistcart-service-watchlistitem-deleted` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `watchlistItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`watchlistItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistItem","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"watchlistItem":{"id":"ID","userId":"ID","addedAt":"Date","productId":"ID","listId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event cartitem-created **Event topic** : `ebaycclone-watchlistcart-service-cartitem-created` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `cartItem` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`cartItem`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"cartItem","method":"POST","action":"create","appVersion":"Version","rowCount":1,"cartItem":{"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` ## Route Event userwatchlist-done **Event topic** : `ebaycclone-watchlistcart-service-userwatchlist-done` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `watchlistItems` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`watchlistItems`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","watchlistItems":[{"id":"ID","userId":"ID","addedAt":"Date","productId":"ID","listId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event usercartitems-listed **Event topic** : `ebaycclone-watchlistcart-service-usercartitems-listed` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `cartItems` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`cartItems`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"cartItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","cartItems":[{"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID","product":[{"currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","shipping":"Double"},{},{}]},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` ## Route Event userwatchlistlists-done **Event topic** : `ebaycclone-watchlistcart-service-userwatchlistlists-done` **Event payload**: The event payload, mirroring the REST API response, is structured as an encapsulated JSON. It includes metadata related to the API as well as the `watchlistLists` data object itself. The following JSON included in the payload illustrates the fullest representation of the **`watchlistLists`** object. Note, however, that certain properties might be excluded in accordance with the object's inherent logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistLists","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","watchlistLists":[{"id":"ID","name":"String","itemCount":"Integer","userId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` # Copyright All sources, documents and other digital materials are copyright of . # About Us For more information please visit our website: . . . # **EBAYCCLONE** FRONTEND GUIDE FOR AI CODING AGENTS This document is a rest api guide for the ebaycclone project. The document is designed for AI agents who will generate frontend code that will consume the project backend. The project has got 1 auth service, 1 notification service, 1 bff service and business services. Each service is a separate microservice application and listens the HTTP request from different service urls. The services may be in preview server, staging server or real production server. So each service have got 3 acess urls. Frontend application should support all deployemnt servers in the development phase, and user should be able to select the target api server in the login page. ## Project Introduction ebaycClone is a comprehensive backend for an online marketplace supporting auctions and fixed-price sales of physical goods, with role-based access, public user registration, Stripe payments, notifications, and robust ownership enforcement. ## API Structure ### Object Structure of a Successfull Response When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client. **HTTP Status Codes:** - **200 OK**: This status code is returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request has been processed successfully. - **201 Created**: This status code is specific to CREATE operations, signifying that the requested resource has been successfully created. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling the successful execution of the request. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3, "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` - **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation performed. ### Additional Data Each api may have include addtional data other than the main data object according to the business logic of the API. They will be given in each API's response signature. ### Error Response If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity: - **400 Bad Request**: The request was improperly formatted or contained invalid parameters, preventing the server from processing it. - **401 Unauthorized**: The request lacked valid authentication token , login required - **403 Forbidden Error** Curent token provided do not grant access to the requested resource. - **404 Not Found**: The requested resource was not found on the server. - **500 Internal Server Error**: The server encountered an unexpected condition that prevented it from fulfilling the request. Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ## Accessing the backend Each service of the backend has got its own url according to the deployment environement. User may want to test the frontend in one of the 3 deployments of the application, preview, staging and production. Please ensure that register and login pages do have a deployemnt server selection option, so as the frontned coding agent you can arrange the base url path of all services. The base url of the application in each environment is as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com` * **Staging:** `https://ebaycclone-stage.mindbricks.co` * **Production:** `https://ebaycclone.mindbricks.co` For the auth service the base url is as follows: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` For each other service, the service base url will be given in service sections. Any login requied request to the backend should have a valid token, when a user makes a successfull login, the ressponse JSON includes a JWT access token in the `accessToken`fields. In normal conditions, this token is also set to the cookie and then consumed automatically, but since AI coding agents preview options may fail to use cookies, please ensure that in each request include the access token in the bearer auth header. ## Registration Management First of all please ensure that register and login pages do have a deployemnt server selection option, so as the frontned coding agent you can arrange the base url path of all services. Start with a landing page and arranging register, verification and login flow. So at the first step, you need a general knowledge of the application to make a good landing page and the authetication flow. ### How To Register Using `registeruser` route of auth api, send the required fields to the backend in your registration page. The registerUser api in in `auth` service, is described with request and response structure below. Note that since `registerUser` api is a business api, it has a version control, so please call it with the given version like `/v1/registeruser` ### `Register User` API This api is used by public users to register themselves **Rest Route** The `registerUser` API REST controller can be triggered via the following route: `/v1/registeruser` **Rest Request Parameters** The `registerUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **password** : The password defined by the the user that is being registered. **fullname** : The fullname defined by the the user that is being registered. **email** : The email defined by the the user that is being registered. **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` After a successful registration, frontend code should handle the verification needs. The registration response will have a `user` object in the root envelope, this object will have user information with an `id` parameter. ### Email Verification In the registration response, you should check the property `emailVerificationNeeded` in the reponse root, and if this property is true you should start the email verification flow. After login process, if you get an HTTP error status, and if there is an `errCode` property in the response with `EmailVerificationNeeded` value, you should start the email verification flow. 1. Call the email verification `start` route of the backend (described below) with the user email, backend will send a secret code to the given email adresss. **Backend can send the email message if the architect defined a real mail service or smtp server, so during the development time backend will send the secret code also to the frontend. You can get this secret code from the response within the `secretCode` property**. 2. The secret code in the sent email message will be a 6 digits code , and you should arrange an input page so that the user can paste this code to the frontend application. Please navigate to this input page after you start the verification process. **If the secretCode is sent to the frontend for test purposes, then you should show it as info in the input page, so that user can copy and paste it**. 3. There is a `codeIndex` property in the start response, please show it's value on the input page, so that user can match the index in the message with the one on the screen. 4. When the user submits the code, please complete the email verification using the `complete` route of the backend (described below) with the user email and the secret code. 5. After you get a successful response from email verification, you can navigate to the login page. Here is the `start`and `complete` routes of email verification. These are system routes , so they dont have a version control. #### `POST /verification-services/email-verification/start` **Purpose:** Starts the email verification by generating and sending a secret code. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `email` | String | Yes | User’s email address to verify | **Example Request** ```json { "email": "user@example.com" } ``` **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ In production, `secretCode` is **not** returned — only sent via email. **Error Responses** * `400 Bad Request`: Already verified * `403 Forbidden`: Too many attempts (rate limit) --- #### `POST /verification-services/email-verification/complete` **Purpose:** Completes the verification using the received code. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `email` | String | Yes | User’s email | | `secretCode` | String | Yes | Verification code | **Success Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` **Error Responses** * `403 Forbidden`: Code expired or mismatched * `404 Not Found`: No verification in progress --- ## Login Management After a successfull login and completing required verifications, user can now login. Please make a fancy minimal login page where user can enter his email and password. ## Bucket Management This application has a bucket service and is used to store user or other objects related files. Bucket service is login agnostic, so when accessing for write or private read, you should insert a bucket token (given by services) to your request authorization header as bearer token. **User Bucket** This bucket is used to store public user files for each user. When a user logs in, or in /currentuser response there is `userBucketToken` to be used when sending user related public files to the bucket service. To upload `POST {baseUrl}/bucket/upload` Request body is form data which includes the bucketId and the file as binary in `files` property. ```js { bucketId: "{userId}-public-user-bucket", files: {binary} } ``` Response status is 200 on succesfull result, eg body: ```json { "success": true, "data": [ { "fileId": "9da03f6d-0409-41ad-bb06-225a244ae408", "originalName": "test (10).png", "mimeType": "image/png", "size": 604063, "status": "uploaded", "bucketName": "f7103b85-fcda-4dec-92c6-c336f71fd3a2-public-user-bucket", "isPublic": true, "downloadUrl": "https://babilcom.mindbricks.co/bucket/download/9da03f6d-0409-41ad-bb06-225a244ae408" } ] } ``` To download a file from the bucket, you should know its fileId, so if youupload an avatar or something else, be sure that the download url or the fileId is stored in backend. Bucket is mostly used, in object creations where alos demands an addtional file like a product image or user avatar. So after you upload your image to the bucket, insert the returned download url to the related property in the related object creation. **Application Bucket** This Ebaycclone application alos has common public bucket which everybody has a read access, but only users who have `superAdmin`, `admin` or `saasAdmin` roles can write (upload) to the bucket. The common public project bucket id is `"ebaycclone-public-common-bucket"` and in certain areas like product image uploads, since the user will already have the admin bucket token, he will be able to upload realted object images. Please make your UI arrangements as able to upload files to the bucket using these bucket tokens. **Object Buckets** Some objects may return also a bucket token, to upload or access related files with object. For example, when you get a project's data in a project management application, if there is a public or private bucket token, this is provided mostly for uploading project related files or downloading them with the token. These buckets will be used according to the descriptions given along with the object definitions. ## Role Management This Ebaycclone may have different role names defined fro different business logic. But unless another case is asked by the user, respect to the admin roles which may be `superAdmin`, `admin` or `saasAdmin` in the currentuser or login response given with the `roleId`property. ```json { // ... "roleId":"superAdmin", // ... } ``` If the application needs an admin panel, or any admin related page, please use these roleId's to decide if the user can access those pages or not. ## 1. Authentication Routes ### 1.1 `POST /login` — User Login **Purpose:** Verifies user credentials and creates an authenticated session with a JWT access token. **Access Routes:** * `GET /login`: Returns a minimal HTML login page (for browser-based testing). * `POST /login`: Authenticates user credentials and returns an access token and session. #### Request Parameters | Parameter | Type | Required | Source | | ---------- | ------ | -------- | ----------------------- | | `username` | String | Yes | `request.body.username` | | `password` | String | Yes | `request.body.password` | #### Behavior * Authenticates credentials and returns a session object. * Sets cookie: `projectname-access-token[-tenantCodename]` * Adds the same token in response headers. * Accepts either `username` or `email` fields (if both exist, `username` is prioritized). #### Example ```js axios.post("/login", { username: "user@example.com", password: "securePassword" }); ``` #### Success Response ```json { "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", //... } ``` #### Error Responses * `401 Unauthorized`: Invalid credentials * `403 Forbidden`: Email/mobile verification or 2FA pending * `400 Bad Request`: Missing parameters --- ### 1.2 `POST /logout` — User Logout **Purpose:** Terminates the current session and clears associated authentication tokens. #### Behavior * Invalidates session (if exists). * Clears cookie `projectname-access-token[-tenantCodename]`. * Returns a confirmation response (always `200 OK`). #### Example ```js axios.post("/logout", {}, { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` #### Notes * Can be called without a session (idempotent behavior). * Works for both cookie-based and token-based sessions. #### Success Response ```json { "status": "OK", "message": "User logged out successfully" } ``` --- ## 2. Verification Services Overview All verification routes are grouped under the `/verification-services` base path. They follow a **two-step verification pattern**: `start` → `complete`. --- ## 3. Email Verification ### 3.1 Trigger Scenarios * After registration (`emailVerificationRequiredForLogin` = true) * When updating email address * When login fails due to unverified email ### 3.2 Flow Summary 1. `/start` → Generate & send code via email. 2. `/complete` → Verify code and mark email as verified. ** PLEASE NOTE ** Email verification is a frontend triiggered process. After user registers, the frontend should start the email verification process and navigate to its code input page. --- ### 3.3 `POST /verification-services/email-verification/start` **Purpose:** Starts the email verification by generating and sending a secret code. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `email` | String | Yes | User’s email address to verify | **Example Request** ```json { "email": "user@example.com" } ``` **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ In production, `secretCode` is **not** returned — only sent via email. **Error Responses** * `400 Bad Request`: Already verified * `403 Forbidden`: Too many attempts (rate limit) --- ### 3.4 `POST /verification-services/email-verification/complete` **Purpose:** Completes the verification using the received code. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `email` | String | Yes | User’s email | | `secretCode` | String | Yes | Verification code | **Success Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` **Error Responses** * `403 Forbidden`: Code expired or mismatched * `404 Not Found`: No verification in progress --- ### 3.5 Behavioral Notes * **Resend Cooldown:** `resendTimeWindow` (e.g. 60s) * **Expiration:** Codes expire after `expireTimeWindow` (e.g. 1 day) * **Single Active Session:** One verification per user --- ## 4. Mobile Verification ### 4.1 Trigger Scenarios * After registration (`mobileVerificationRequiredForLogin` = true) * When updating phone number * On login requiring mobile verification ### 4.2 Flow 1. `/start` → Sends verification code via SMS 2. `/complete` → Validates code and confirms number --- ### 4.3 `POST /verification-services/mobile-verification/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------ | | `email` | String | Yes | User’s email to locate mobile record | **Success Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 180, "verificationType": "byCode", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` > ⚠️ `secretCode` returned only in development. **Errors** * `400 Bad Request`: Already verified * `403 Forbidden`: Rate-limited --- ### 4.4 `POST /verification-services/mobile-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------------- | | `email` | String | Yes | Associated email | | `secretCode` | String | Yes | Code received via SMS | **Success Response** ```json { "status": "OK", "isVerified": true, "mobile": "+1 333 ...", // in testMode "userId": "user-uuid", } ``` --- ### 4.5 Behavioral Notes * **Cooldown:** One code per minute * **Expiration:** Codes valid for 1 day * **One Session Per User** --- ## 5. Two-Factor Authentication (2FA) ### 5.1 Email 2FA **Flow** 1. `/start` → Generates and sends email code 2. `/complete` → Verifies code and updates session --- #### `POST /verification-services/email-2factor-verification/start` | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ---------------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Current session | | `client` | String | No | Optional context | | `reason` | String | No | Reason for 2FA | **Response** ```json { "status": "OK", "sessionId": "user session id UUID", "userId": "user-uuid", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", } ``` --- #### `POST /verification-services/email-2factor-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `secretCode` | String | Yes | Code from email | **Response** ```json { // user session data "sessionId": "session-uuid", // ... } ``` --- ### 5.2 Mobile 2FA **Flow** 1. `/start` → Sends SMS code 2. `/complete` → Validates and finalizes session --- #### `POST /verification-services/mobile-2factor-verification/start` | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ----------- | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `client` | String | No | Context | | `reason` | String | No | Reason | **Response** ```json { "status": "OK", "sessionId": "user session id UUID", "userId": "user-uuid", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", } ``` --- #### `POST /verification-services/mobile-2factor-verification/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------ | | `userId` | String | Yes | User ID | | `sessionId` | String | Yes | Session ID | | `secretCode` | String | Yes | Code via SMS | **Response** ```json { // user session data "sessionId": "session-uuid", // ... } ``` --- ### 5.3 2FA Behavioral Notes * One active code per session * Cooldown: `resendTimeWindow` (e.g., 60s) * Expiration: `expireTimeWindow` (e.g., 5m) --- ## 6. Password Reset ### 6.1 By Email **Flow** 1. `/start` → Sends verification code via email 2. `/complete` → Validates and resets password --- #### `POST /verification-services/password-reset-by-email/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------- | | `email` | String | Yes | User email | **Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` #### `POST /verification-services/password-reset-by-email/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------- | | `email` | String | Yes | User email | | `secretCode` | String | Yes | Code received | | `password` | String | Yes | New password | **Response** ```json { "status": "OK", "isVerified": true, "email": "user@email.com", // in testMode "userId": "user-uuid", } ``` --- ### 6.2 By Mobile **Flow** 1. `/start` → Sends SMS code 2. `/complete` → Validates and resets password --- #### `POST /verification-services/password-reset-by-mobile/start` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------- | | `mobile` | String | Yes | Mobile number | **Response** ```json { "status": "OK", "codeIndex": 1, // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT "timeStamp": 1784578660000, "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)", // expireTime: in seconds "expireTime": 86400, "verificationType": "byLink", // in testMode "secretCode": "123456", "userId": "user-uuid", } ``` #### `POST /verification-services/password-reset-by-mobile/complete` | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ---------------- | | `email` | String | Yes | Associated email | | `secretCode` | String | Yes | Code via SMS | | `password` | String | Yes | New password | **Response** ```json { "status": "OK", "isVerified": true, "mobile": "+1 444 ....", // in testMode "userId": "user-uuid", } ``` --- ### 6.3 Behavioral Notes * Cooldown: 60s resend * Expiration: 24h * One session per user * Works without an active login session --- ## 7. Verification Method Types ### 7.1 `byCode` User manually enters the 6-digit code in frontend. ### 7.2 `byLink` Frontend handles a one-click verification via email/SMS link containing code parameters. ## 8) `GET /currentuser` — Current Session **Purpose** Return the currently authenticated user’s session. **Route Type** `sessionInfo` **Authentication** Requires a valid access token (header or cookie). ### Request *No parameters.* ### Example ```js axios.get("/currentuser", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) Returns the session object (identity, tenancy, token metadata): ```json { "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", "roleId": "user", "tenantId": "abc123", "accessToken": "jwt-token-string", "...": "..." } ``` ### Errors * **401 Unauthorized** — No active session/token ```json { "status": "ERR", "message": "No login found" } ``` **Notes** * Commonly called by web/mobile clients after login to hydrate session state. * Includes key identity/tenant fields and a token reference (if applicable). * Ensure a valid token is supplied to receive a 200 response. --- ## 9) `GET /permissions` — List Effective Permissions **Purpose** Return all effective permission grants for the current user. **Route Type** `permissionFetch` **Authentication** Requires a valid access token. ### Request *No parameters.* ### Example ```js axios.get("/permissions", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) Array of permission grants (aligned with `givenPermissions`): ```json [ { "id": "perm1", "permissionName": "adminPanel.access", "roleId": "admin", "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" }, { "id": "perm2", "permissionName": "orders.manage", "roleId": null, "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" } ] ``` **Field meanings (per item):** * `permissionName`: Granted permission key. * `roleId`: Present if granted via role. * `subjectUserId`: Present if granted directly to the user. * `subjectUserGroupId`: Present if granted via group. * `objectId`: Present if scoped to a specific object (OBAC). * `canDo`: `true` if enabled, `false` if restricted. ### Errors * **401 Unauthorized** — No active session ```json { "status": "ERR", "message": "No login found" } ``` * **500 Internal Server Error** — Unexpected failure **Notes** * Available on all Mindbricks-generated services (not only Auth). * **Auth service:** Reads live `givenPermissions` from DB. * **Other services:** Typically respond from a cached/projected view (e.g., ElasticSearch) for faster checks. > **Tip:** Cache permission results client-side/server-side and refresh after login or permission updates. --- ## 10) `GET /permissions/:permissionName` — Check Permission Scope **Purpose** Check whether the current user has a specific permission and return any scoped object exceptions/inclusions. **Route Type** `permissionScopeCheck` **Authentication** Requires a valid access token. ### Path Parameters | Name | Type | Required | Source | | ---------------- | ------ | -------- | ------------------------------- | | `permissionName` | String | Yes | `request.params.permissionName` | ### Example ```js axios.get("/permissions/orders.manage", { headers: { Authorization: "Bearer " } }); ``` ### Success (200) ```json { "canDo": true, "exceptions": [ "a1f2e3d4-xxxx-yyyy-zzzz-object1", "b2c3d4e5-xxxx-yyyy-zzzz-object2" ] } ``` **Interpretation** * If `canDo: true`: permission is generally granted **except** the listed `exceptions` (restrictions). * If `canDo: false`: permission is generally **not** granted, **only** allowed for the listed `exceptions` (selective overrides). * `exceptions` contains object IDs (UUID strings) from the relevant domain model. ### Errors * **401 Unauthorized** — No active session/token. ## Services And Data Object ## Auth Service Authentication service for the project ### Auth Service Data Objects **User** A data object that stores the user information and handles login settings. ### Auth Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auth-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auth-api` * **Production:** `https://ebaycclone.mindbricks.co/auth-api` ### `Get User` API This api is used by admin roles or the users themselves to get the user profile information. **Rest Route** The `getUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `getUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users/:userId** ```js axios({ method: 'GET', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update User` API This route is used by admins to update user profiles. **Rest Route** The `updateUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `updateUser` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/users/:userId** ```js axios({ method: 'PATCH', url: `/v1/users/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Profile` API This route is used by users to update their profiles. **Rest Route** The `updateProfile` API REST controller can be triggered via the following route: `/v1/profile/:userId` **Rest Request Parameters** The `updateProfile` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **userId** : This id paremeter is used to select the required data object that will be updated **fullname** : A string value to represent the fullname of the user **avatar** : The avatar url of the user. A random avatar will be generated if not provided **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/profile/:userId** ```js axios({ method: 'PATCH', url: `/v1/profile/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create User` API This api is used by admin roles to create a new user manually from admin panels **Rest Route** The `createUser` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `createUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | email | String | true | request.body?.email | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **email** : A string value to represent the user's email. **password** : A string value to represent the user's password. It will be stored as hashed. **fullname** : A string value to represent the fullname of the user **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/users** ```js axios({ method: 'POST', url: '/v1/users', data: { avatar:"String", email:"String", password:"String", fullname:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete User` API This api is used by admins to delete user profiles. **Rest Route** The `deleteUser` API REST controller can be triggered via the following route: `/v1/users/:userId` **Rest Request Parameters** The `deleteUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/users/:userId** ```js axios({ method: 'DELETE', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Archive Profile` API This api is used by users to archive their profiles. **Rest Route** The `archiveProfile` API REST controller can be triggered via the following route: `/v1/archiveprofile/:userId` **Rest Request Parameters** The `archiveProfile` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/archiveprofile/:userId** ```js axios({ method: 'DELETE', url: `/v1/archiveprofile/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Users` API The list of users is filtered by the tenantId. **Rest Route** The `listUsers` API REST controller can be triggered via the following route: `/v1/users` **Rest Request Parameters** The `listUsers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/users** ```js axios({ method: 'GET', url: '/v1/users', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Search Users` API The list of users is filtered by the tenantId. **Rest Route** The `searchUsers` API REST controller can be triggered via the following route: `/v1/searchusers` **Rest Request Parameters** The `searchUsers` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | keyword | String | true | request.query?.keyword | **keyword** : **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchusers** ```js axios({ method: 'GET', url: '/v1/searchusers', data: { }, params: { keyword:'"String"', } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Userrole` API This route is used by admin roles to update the user role.The default role is user when a user is registered. A user's role can be updated by superAdmin or admin **Rest Route** The `updateUserRole` API REST controller can be triggered via the following route: `/v1/userrole/:userId` **Rest Request Parameters** The `updateUserRole` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | roleId | String | true | request.body?.roleId | **userId** : This id paremeter is used to select the required data object that will be updated **roleId** : The new roleId of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userrole/:userId** ```js axios({ method: 'PATCH', url: `/v1/userrole/${userId}`, data: { roleId:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpassword` API This route is used to update the password of users in the profile page by users themselves **Rest Route** The `updateUserPassword` API REST controller can be triggered via the following route: `/v1/userpassword/:userId` **Rest Request Parameters** The `updateUserPassword` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | oldPassword | String | true | request.body?.oldPassword | | newPassword | String | true | request.body?.newPassword | **userId** : This id paremeter is used to select the required data object that will be updated **oldPassword** : The old password of the user that will be overridden bu the new one. Send for double check. **newPassword** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpassword/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpassword/${userId}`, data: { oldPassword:"String", newPassword:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Userpasswordbyadmin` API This route is used to change any user password by admins only. Superadmin can chnage all passwords, admins can change only nonadmin passwords **Rest Route** The `updateUserPasswordByAdmin` API REST controller can be triggered via the following route: `/v1/userpasswordbyadmin/:userId` **Rest Request Parameters** The `updateUserPasswordByAdmin` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | password | String | true | request.body?.password | **userId** : This id paremeter is used to select the required data object that will be updated **password** : The new password of the user to be updated **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/userpasswordbyadmin/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpasswordbyadmin/${userId}`, data: { password:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Briefuser` API This route is used by public to get simple user profile information. **Rest Route** The `getBriefUser` API REST controller can be triggered via the following route: `/v1/briefuser/:userId` **Rest Request Parameters** The `getBriefUser` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | **userId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/briefuser/:userId** ```js axios({ method: 'GET', url: `/v1/briefuser/${userId}`, data: { }, params: { } }); ``` **REST Response** This route's response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "fullname": "String", "avatar": "String", "isActive": true } } ``` ### `Register User` API This api is used by public users to register themselves **Rest Route** The `registerUser` API REST controller can be triggered via the following route: `/v1/registeruser` **Rest Request Parameters** The `registerUser` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | **avatar** : The avatar url of the user. If not sent, a default random one will be generated. **password** : The password defined by the the user that is being registered. **fullname** : The fullname defined by the the user that is being registered. **email** : The email defined by the the user that is being registered. **phone** : user's phone number **address** : user's adress **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## AuctionOffer Service Handles auction bids and fixed-price offers for product listings, enforces real-time auction state, handles strict offer workflows including counter-offers, and triggers domain events for bid/offer notifications. No payment or frontend aggregation logic included. ### AuctionOffer Service Data Objects **AuctionOfferOffer** Represents an offer (best offer/counter-offer) made on a fixed-price product. Tracks buyer, seller, amounts, currency, state transitions, counter-offers, and expiry. **AuctionOfferBid** Represents an individual bid placed on an auction-type product. Linked to product and user, tracks bid amount, currency, status (ACTIVE, WON, LOST, CANCELLED), and time placed. ### AuctionOffer Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/auctionoffer-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/auctionoffer-api` * **Production:** `https://ebaycclone.mindbricks.co/auctionoffer-api` ### `Update Auctionofferoffer` API Updates offer: accepts/declines/counters by seller, withdraws by buyer before response. Enforces status transition rules, sets respondedAt. Triggers event. **Rest Route** The `updateAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `updateAuctionOfferOffer` api has got 8 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | message | String | false | request.body?.message | | status | Enum | false | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | **auctionOfferOfferId** : This id paremeter is used to select the required data object that will be updated **counterOfferId** : References another offer (counter-offer chain). **counterMessage** : Message accompanying seller's counter-offer (optional). **counterAmount** : Counter-offer amount (when offer is COUNTERED). **message** : Message/special notes from buyer (optional). **status** : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). **expiresAt** : When this offer expires (optional). **respondedAt** : When the seller (or buyer, for counter-offer) responded/updated the offer status. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Auctionofferbid` API Creates a new bid for an auction product. Validates auction status, not seller, product type, bid window, and ensures min. increment. Updates product.currentBid and product.highestBidderId atomically. Triggers notification event. **Rest Route** The `createAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids` **Rest Request Parameters** The `createAuctionOfferBid` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | bidAmount | Double | true | request.body?.bidAmount | | currency | String | true | request.body?.currency | | status | Enum | true | request.body?.status | | productId | ID | true | request.body?.productId | **bidAmount** : Bid amount placed by the user. **currency** : ISO currency for the bid (e.g., USD, EUR). **status** : Bid status: ACTIVE, WON, LOST, CANCELLED. **productId** : Product being bid on (must be AUCTION type). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/auctionofferbids** ```js axios({ method: 'POST', url: '/v1/auctionofferbids', data: { bidAmount:"Double", currency:"String", status:"Enum", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Auctionofferbid` API Gets a single bid (only visible to owner/admin or for auction history). **Rest Route** The `getAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `getAuctionOfferBid` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | **auctionOfferBidId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'GET', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Auctionofferoffer` API Gets a single offer (shown to buyer/seller or admin). **Rest Route** The `getAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `getAuctionOfferOffer` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | **auctionOfferOfferId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'GET', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Auctionofferoffers` API Lists offers by product, user, status, or counterOffer chain. **Rest Route** The `listAuctionOfferOffers` API REST controller can be triggered via the following route: `/v1/auctionofferoffers` **Rest Request Parameters** The `listAuctionOfferOffers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers** ```js axios({ method: 'GET', url: '/v1/auctionofferoffers', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferOffers": [ { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Auctionofferbid` API Updates a bid’s status (allow only status update, e.g. CANCELLED, WIN/LOSE on admin settlement). Only owner/admin, and only if auction not ended or not settled. Triggers notification event. **Rest Route** The `updateAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `updateAuctionOfferBid` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | | status | Enum | false | request.body?.status | **auctionOfferBidId** : This id paremeter is used to select the required data object that will be updated **status** : Bid status: ACTIVE, WON, LOST, CANCELLED. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { status:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Auctionofferoffer` API Creates a new offer for a fixed-price product, validating acceptOffers, type, eligibility, and product/seller/buyer active. Defaults to PENDING state. Triggers notification event. **Rest Route** The `createAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers` **Rest Request Parameters** The `createAuctionOfferOffer` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | productId | ID | true | request.body?.productId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | offerAmount | Double | true | request.body?.offerAmount | | message | String | false | request.body?.message | | status | Enum | true | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | **currency** : ISO currency (e.g., USD, EUR) for the offer. **productId** : Product the offer applies to (must be fixed-price, acceptOffers true). **counterOfferId** : References another offer (counter-offer chain). **counterMessage** : Message accompanying seller's counter-offer (optional). **counterAmount** : Counter-offer amount (when offer is COUNTERED). **offerAmount** : Primary offer amount from buyer. **message** : Message/special notes from buyer (optional). **status** : Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). **expiresAt** : When this offer expires (optional). **respondedAt** : When the seller (or buyer, for counter-offer) responded/updated the offer status. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/auctionofferoffers** ```js axios({ method: 'POST', url: '/v1/auctionofferoffers', data: { currency:"String", productId:"ID", counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", offerAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Auctionofferbids` API Lists bids by product, user, or auction, supports history/analytics. **Rest Route** The `listAuctionOfferBids` API REST controller can be triggered via the following route: `/v1/auctionofferbids` **Rest Request Parameters** The `listAuctionOfferBids` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids** ```js axios({ method: 'GET', url: '/v1/auctionofferbids', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBids", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferBids": [ { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Auctionofferbid` API Soft-deletes a bid (for admin or self before auction ends). **Rest Route** The `deleteAuctionOfferBid` API REST controller can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` **Rest Request Parameters** The `deleteAuctionOfferBid` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | **auctionOfferBidId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Auctionofferoffer` API Soft-deletes an offer (allowed only in non-accepted/expired state). **Rest Route** The `deleteAuctionOfferOffer` API REST controller can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` **Rest Request Parameters** The `deleteAuctionOfferOffer` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | **auctionOfferOfferId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## CategoryManagement Service Handles product categories and subcategories for marketplace browsing and classification, supporting public discovery plus admin-only management. ### CategoryManagement Service Data Objects **Category** Represents a product category in the marketplace (e.g., Electronics, Clothing, Toys), used for browsing, filtering, and discovery. Admins manage categories. **Subcategory** Represents a subcategory within a parent category (e.g., 'Smartphones' under 'Electronics'). Used for more granular product discovery and navigation. 'group' categorizes special display logic. ### CategoryManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/categorymanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/categorymanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/categorymanagement-api` ### `Delete Category` API Soft-delete a category (admin-only). **Rest Route** The `deleteCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `deleteCategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | **categoryId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/categories/:categoryId** ```js axios({ method: 'DELETE', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Subcategory` API Get a subcategory by ID. Public - only active subcategories returned except for admin. **Rest Route** The `getSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `getSubcategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | **subcategoryId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/subcategories/:subcategoryId** ```js axios({ method: 'GET', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Category` API Get a single category by ID. Public - only active categories returned (for non-admins). **Rest Route** The `getCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `getCategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | **categoryId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/categories/:categoryId** ```js axios({ method: 'GET', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Subcategory` API Update subcategory (admin-only), including group enum change. **Rest Route** The `updateSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `updateSubcategory` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | name | String | false | request.body?.name | | group | Enum | false | request.body?.group | **subcategoryId** : This id paremeter is used to select the required data object that will be updated **categoryId** : Reference to the parent category (category.id). **name** : Display name of the subcategory. **group** : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/subcategories/:subcategoryId** ```js axios({ method: 'PATCH', url: `/v1/subcategories/${subcategoryId}`, data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Subcategories` API List all subcategories for browsing/filtering, with support for group enum and parent category queries. Only active subcategories shown to public/non-admin users. **Rest Route** The `listSubcategories` API REST controller can be triggered via the following route: `/v1/subcategories` **Rest Request Parameters** The `listSubcategories` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/subcategories** ```js axios({ method: 'GET', url: '/v1/subcategories', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "subcategories": [ { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Subcategory` API Soft-delete a subcategory (admin-only). **Rest Route** The `deleteSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories/:subcategoryId` **Rest Request Parameters** The `deleteSubcategory` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | **subcategoryId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/subcategories/:subcategoryId** ```js axios({ method: 'DELETE', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Categories` API List all categories for browsing and filtering. Only active categories shown to public/non-admin users. **Rest Route** The `listCategories` API REST controller can be triggered via the following route: `/v1/categories` **Rest Request Parameters** The `listCategories` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/categories** ```js axios({ method: 'GET', url: '/v1/categories', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "categories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "categories": [ { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Category` API Update category details (admin-only). **Rest Route** The `updateCategory` API REST controller can be triggered via the following route: `/v1/categories/:categoryId` **Rest Request Parameters** The `updateCategory` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | false | request.body?.title | **categoryId** : This id paremeter is used to select the required data object that will be updated **imageUrl** : URL for category image/avatar (optional, used for homepage visuals). **subtitle** : Optional short description for UI/tooltips. **title** : Display name of the category. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/categories/:categoryId** ```js axios({ method: 'PATCH', url: `/v1/categories/${categoryId}`, data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Subcategory` API Create a new subcategory under a given category (admin-only), with enum group constraint. **Rest Route** The `createSubcategory` API REST controller can be triggered via the following route: `/v1/subcategories` **Rest Request Parameters** The `createSubcategory` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.body?.categoryId | | name | String | true | request.body?.name | | group | Enum | true | request.body?.group | **categoryId** : Reference to the parent category (category.id). **name** : Display name of the subcategory. **group** : Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/subcategories** ```js axios({ method: 'POST', url: '/v1/subcategories', data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Category` API Create a new category (admin-only) for product classification. **Rest Route** The `createCategory` API REST controller can be triggered via the following route: `/v1/categories` **Rest Request Parameters** The `createCategory` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | true | request.body?.title | **imageUrl** : URL for category image/avatar (optional, used for homepage visuals). **subtitle** : Optional short description for UI/tooltips. **title** : Display name of the category. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/categories** ```js axios({ method: 'POST', url: '/v1/categories', data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## Messaging Service In-app messaging service for direct user-to-user text messages (buyers/sellers). Stores, retrieves, and manages user conversations. Launch version: text-only. ### Messaging Service Data Objects **MessagingMessage** A direct, text-only in-app message between two users (buyer/seller); stores sender, recipient, content, read status, and timestamp. ### Messaging Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/messaging-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/messaging-api` * **Production:** `https://ebaycclone.mindbricks.co/messaging-api` ### `List Messagingmessages` API List all messages in the conversation between the logged-in user and another party, ordered by sentAt descending. Can filter unread with isRead. Returns only messages visible to user (isActive). **Rest Route** The `listMessagingMessages` API REST controller can be triggered via the following route: `/v1/messagingmessages` **Rest Request Parameters** The `listMessagingMessages` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages** ```js axios({ method: 'GET', url: '/v1/messagingmessages', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessages", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "messagingMessages": [ { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Messagingmessage` API Send a new text message from the logged-in user to a recipient. Sender is set from session. Launch version supports only text content. **Rest Route** The `createMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages` **Rest Request Parameters** The `createMessagingMessage` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | toUserId | ID | true | request.body?.toUserId | | content | String | true | request.body?.content | | isRead | Boolean | true | request.body?.isRead | **toUserId** : Recipient (user) of this message. **content** : Text content of the message. No files or attachments for launch. **isRead** : If true, recipient has marked this message as read. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/messagingmessages** ```js axios({ method: 'POST', url: '/v1/messagingmessages', data: { toUserId:"ID", content:"String", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Messagingmessage` API Update a message (mark as read/unread). Only the recipient or admin can change isRead. No content edits. Sender, content, sentAt are immutable. **Rest Route** The `updateMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `updateMessagingMessage` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | | isRead | Boolean | false | request.body?.isRead | **messagingMessageId** : This id paremeter is used to select the required data object that will be updated **isRead** : If true, recipient has marked this message as read. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'PATCH', url: `/v1/messagingmessages/${messagingMessageId}`, data: { isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Messagingmessage` API Get a message by ID. Only accessible to the sender, the recipient, or an admin. Used for message detail view or reading a single message in a thread. **Rest Route** The `getMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `getMessagingMessage` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | **messagingMessageId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'GET', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Messagingmessage` API Delete a message (soft-delete). Only sender, recipient, or admin may delete a message. Deletion only hides it for the user; not a full erase unless both delete. **Rest Route** The `deleteMessagingMessage` API REST controller can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` **Rest Request Parameters** The `deleteMessagingMessage` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | **messagingMessageId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'DELETE', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## NotificationManagement Service Handles storage, management, and event-driven delivery of in-app and email notifications for user-impacting system events (bids, offers, orders, feedback, messaging, etc.). Supports marking notifications as read/unread, structured filtering by event type/channel, and always returns in-app notifications ordered by recency. ### NotificationManagement Service Data Objects **Notification** Stores and manages in-app and email notifications tied to user-facing events like bids, offers, orders, messaging, shipment, and feedback. Includes event type (notificationType) for filter/search, arbitrary event payload, and delivery channel. Soft-delete enforced. In-app notifications always sorted by createdAt DESC on retrieval. ### NotificationManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/notificationmanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/notificationmanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/notificationmanagement-api` ### `Create Notification` API Creates a notification entry in response to a system/business event. Only allowed for system/event processes and admins (not standard user/action). Typically event-driven, receives userId, notificationType, payload, and channel. **Rest Route** The `createNotification` API REST controller can be triggered via the following route: `/v1/notifications` **Rest Request Parameters** The `createNotification` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationType | Enum | true | request.body?.notificationType | | userId | ID | true | request.body?.userId | | channel | Enum | true | request.body?.channel | | payload | Object | true | request.body?.payload | | isRead | Boolean | true | request.body?.isRead | **notificationType** : Type of event triggering notification (e.g., BID_UPDATED, ORDER_SHIPPED, MESSAGE_RECEIVED, etc.). Used for display/icon and query filter. **userId** : User receiving the notification (recipient). **channel** : Channel by which notification is delivered: IN_APP or EMAIL. **payload** : Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. **isRead** : Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/notifications** ```js axios({ method: 'POST', url: '/v1/notifications', data: { notificationType:"Enum", userId:"ID", channel:"Enum", payload:"Object", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Notification` API Updates a notification (mark as read/unread, payload patch for e.g. admin fix). Only receiver (userId) or admins may update. isRead is primary update scenario; others very limited. **Rest Route** The `updateNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `updateNotification` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | | payload | Object | false | request.body?.payload | | isRead | Boolean | false | request.body?.isRead | **notificationId** : This id paremeter is used to select the required data object that will be updated **payload** : Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. **isRead** : Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/notifications/:notificationId** ```js axios({ method: 'PATCH', url: `/v1/notifications/${notificationId}`, data: { payload:"Object", isRead:"Boolean", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Notifications` API Returns filtered list of notifications for a user, with optional filters: notificationType, isRead, channel. Always sorted by createdAt (descending) for in-app notifications. Only retrieval allowed for owner/admin. **Rest Route** The `listNotifications` API REST controller can be triggered via the following route: `/v1/notifications` **Rest Request Parameters** The `listNotifications` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/notifications** ```js axios({ method: 'GET', url: '/v1/notifications', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notifications", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "notifications": [ { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Notification` API Soft-delete a notification record. Only receiver or admin may delete. **Rest Route** The `deleteNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `deleteNotification` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | **notificationId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/notifications/:notificationId** ```js axios({ method: 'DELETE', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Notification` API Retrieves a notification for the receiver or admin. Used to populate content on detail/expanded view. **Rest Route** The `getNotification` API REST controller can be triggered via the following route: `/v1/notifications/:notificationId` **Rest Request Parameters** The `getNotification` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | **notificationId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/notifications/:notificationId** ```js axios({ method: 'GET', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## SearchIndexing Service Maintains the denormalized search index (materialized view) for global, public search across products, sellers, categories, and subcategories. Handles indexing in response to entity events and exposes optimized query endpoints for BFF/aggregator. ### SearchIndexing Service Data Objects **SearchIndex** Materialized/denormalized search index record for a marketplace entity (product, seller, category, subcategory). Used exclusively for high-speed querying in BFF global/public search. ### SearchIndexing Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/searchindexing-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/searchindexing-api` * **Production:** `https://ebaycclone.mindbricks.co/searchindexing-api` ### `List Searchindexes` API List/search search index entries by type or referenceId (used by BFF/global search). Always excludes inactive (soft-deleted) records. Supports filtering and full-text search filters by documentType/referenceId for admin/maintenance use. **Rest Route** The `listSearchIndexes` API REST controller can be triggered via the following route: `/v1/searchindexes` **Rest Request Parameters** The `listSearchIndexes` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchindexes** ```js axios({ method: 'GET', url: '/v1/searchindexes', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndices", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "searchIndices": [ { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Searchindex` API Update an existing searchIndex record (by (documentType, referenceId) or id). Used in response to events (entity edit, data change); internal/automation/admin only. **Rest Route** The `updateSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `updateSearchIndex` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | | documentType | Enum | false | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | false | request.body?.indexedAt | **searchIndexId** : This id paremeter is used to select the required data object that will be updated **documentType** : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY **document** : Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. **referenceId** : ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. **indexedAt** : Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/searchindexs/:searchIndexId** ```js axios({ method: 'PATCH', url: `/v1/searchindexs/${searchIndexId}`, data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Searchindex` API Soft-delete a searchIndex record (by id or by (documentType, referenceId)). Typical use: in response to entity soft-delete; internal/automation/admin only. **Rest Route** The `deleteSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `deleteSearchIndex` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | **searchIndexId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/searchindexs/:searchIndexId** ```js axios({ method: 'DELETE', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Searchindex` API Create a new searchIndex record (internal, used by event triggers and admin tools only). Typically called when a new product/seller/category/subcategory is created. **Rest Route** The `createSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs` **Rest Request Parameters** The `createSearchIndex` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | documentType | Enum | true | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | true | request.body?.indexedAt | **documentType** : Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY **document** : Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. **referenceId** : ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. **indexedAt** : Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/searchindexs** ```js axios({ method: 'POST', url: '/v1/searchindexs', data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Searchindex` API Get a single denormalized index record (by id, or documentType+referenceId). Used by BFF for full entity search. Always excludes inactive records unless forced (admin only path). **Rest Route** The `getSearchIndex` API REST controller can be triggered via the following route: `/v1/searchindexs/:searchIndexId` **Rest Request Parameters** The `getSearchIndex` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | **searchIndexId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/searchindexs/:searchIndexId** ```js axios({ method: 'GET', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## AdminModeration Service Administrative backend service for moderation and manual override actions. Responsible for logging all admin interventions (user/product/feedback/media/category/order/notification/searchindex moderation), triggering corrections via interservice calls, and providing comprehensive audit trails for compliance. ### AdminModeration Service Data Objects **ModerationAction** Audit record for all admin moderation/override actions affecting core business entities. Links to admin, timestamp, entity type/ID, action performed, and reason. ### AdminModeration Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/adminmoderation-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/adminmoderation-api` * **Production:** `https://ebaycclone.mindbricks.co/adminmoderation-api` ### `Get Moderationaction` API Get a single moderation action log by ID. Used to review admin audit trails; accessible only to platform admins. **Rest Route** The `getModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `getModerationAction` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | **moderationActionId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/moderationactions/:moderationActionId** ```js axios({ method: 'GET', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Moderationaction` API Soft-deletes a moderation action log record (dangerous; allowed only to superadmins or strict manual correction), primarily for audit correction or internal error cleanup. Usually, moderation logs are immutable. **Rest Route** The `deleteModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `deleteModerationAction` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | **moderationActionId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/moderationactions/:moderationActionId** ```js axios({ method: 'DELETE', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Moderationaction` API Logs an admin moderation or override action in the system for audit and traceability. Requires admin login, takes context from session, and creates an audit entry for any admin operation over any entity type. **Rest Route** The `createModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions` **Rest Request Parameters** The `createModerationAction` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | entityId | ID | true | request.body?.entityId | | entityType | Enum | true | request.body?.entityType | | reason | String | true | request.body?.reason | | actionType | Enum | true | request.body?.actionType | **entityId** : ID of target entity affected by moderation (user/product/etc). **entityType** : Type of entity affected (USER, PRODUCT, FEEDBACK, MEDIA, CATEGORY, NOTIFICATION, ORDER, SEARCHINDEX). **reason** : Explanation or justification for the moderation action performed. **actionType** : Type of moderation action (e.g., SOFT_DELETE, RESTORE, UPDATE_ROLE, MANUAL_CORRECTION, MEDIA_FLAG, INDEX_REBUILD, PAYMENT_FIX, FEEDBACK_OVERRIDE, ADMIN_NOTE). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/moderationactions** ```js axios({ method: 'POST', url: '/v1/moderationactions', data: { entityId:"ID", entityType:"Enum", reason:"String", actionType:"Enum", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Moderationactions` API List moderation actions for admin dashboard/audit search. Supports filtering by admin, entityType, entityId, actionType, and date. Always sorted by most recent action. **Rest Route** The `listModerationActions` API REST controller can be triggered via the following route: `/v1/moderationactions` **Rest Request Parameters** The `listModerationActions` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/moderationactions** ```js axios({ method: 'GET', url: '/v1/moderationactions', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationActions", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "moderationActions": [ { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Moderationaction` API Allows update of explanation/note on a moderation action for correction (typically by admin or superadmin only). No entity/type/admin may be changed after creation; only 'reason' is editable for audit consistency. **Rest Route** The `updateModerationAction` API REST controller can be triggered via the following route: `/v1/moderationactions/:moderationActionId` **Rest Request Parameters** The `updateModerationAction` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | | reason | String | false | request.body?.reason | **moderationActionId** : This id paremeter is used to select the required data object that will be updated **reason** : Explanation or justification for the moderation action performed. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/moderationactions/:moderationActionId** ```js axios({ method: 'PATCH', url: `/v1/moderationactions/${moderationActionId}`, data: { reason:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## WatchlistCart Service Handles user watchlists (with custom folders) and shopping cart preparation for checkout, strictly enforcing only fixed-price products in carts, supporting item moves/bulk operations, and robust default/folder logic.. ### WatchlistCart Service Data Objects **WatchlistItem** Item in a user’s watchlist, optionally in a named folder; references product and user. **CartItem** Single product pending checkout in a user’s cart. Only fixed-price products permitted; quantity supported for multi-unit purchases (if allowed). **WatchlistList** A named folder/list in a user’s watchlist. Default list exists for all users. Custom lists may be created and deleted. ### WatchlistCart Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/watchlistcart-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/watchlistcart-api` * **Production:** `https://ebaycclone.mindbricks.co/watchlistcart-api` ### `List Watchlistlist` API List all lists in user’s watchlists. Supports listing by listId for folders. **Rest Route** The `listWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists` **Rest Request Parameters** The `listWatchlistList` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/watchlistlists** ```js axios({ method: 'GET', url: '/v1/watchlistlists', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Cartitems` API List all cart items for a user (pending checkout). **Rest Route** The `listCartItems` API REST controller can be triggered via the following route: `/v1/cartitems` **Rest Request Parameters** The `listCartItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/cartitems** ```js axios({ method: 'GET', url: '/v1/cartitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "price": "Double", "title": "String", "type": "Enum", "type_idx": "Integer", "mediaAssetIds": "ID" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Cartitem` API Remove an item from the user’s cart. **Rest Route** The `deleteCartItem` API REST controller can be triggered via the following route: `/v1/cartitems/:cartItemId` **Rest Request Parameters** The `deleteCartItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | **cartItemId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/cartitems/:cartItemId** ```js axios({ method: 'DELETE', url: `/v1/cartitems/${cartItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Watchlistitem` API Add product to user’s watchlist (default or target list/folder). One (user, product, list) per item enforced. Block duplicates. **Rest Route** The `createWatchlistItem` API REST controller can be triggered via the following route: `/v1/watchlistitems` **Rest Request Parameters** The `createWatchlistItem` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | productId | ID | true | request.body?.productId | | listId | ID | false | request.body?.listId | **addedAt** : Timestamp watchlist item created. **productId** : Referenced product in the watchlist. **listId** : Owning watchlistList; null if in default watchlist. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/watchlistitems** ```js axios({ method: 'POST', url: '/v1/watchlistitems', data: { addedAt:"Date", productId:"ID", listId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Watchlistitems` API List all products in user’s watchlists. Supports listing by listId for folders. **Rest Route** The `listWatchlistItems` API REST controller can be triggered via the following route: `/v1/watchlistitems` **Rest Request Parameters** The `listWatchlistItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/watchlistitems** ```js axios({ method: 'GET', url: '/v1/watchlistitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Update Cartitemquantity` API Change the quantity for a cart item. User must own the item. **Rest Route** The `updateCartItemQuantity` API REST controller can be triggered via the following route: `/v1/cartitemquantity/:cartItemId` **Rest Request Parameters** The `updateCartItemQuantity` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | | quantity | Integer | false | request.body?.quantity | **cartItemId** : This id paremeter is used to select the required data object that will be updated **quantity** : How many units (if product allows). **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/cartitemquantity/:cartItemId** ```js axios({ method: 'PATCH', url: `/v1/cartitemquantity/${cartItemId}`, data: { quantity:"Integer", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Watchlistlist` API Create a new custom watchlist folder. Name must be unique per user; ‘Default’ is reserved for system. **Rest Route** The `createWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists` **Rest Request Parameters** The `createWatchlistList` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | name | String | true | request.body?.name | **name** : Custom folder or list name. 'Default' is reserved (non-deletable for each user). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/watchlistlists** ```js axios({ method: 'POST', url: '/v1/watchlistlists', data: { name:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Watchlistlist` API Delete a custom watchlist (folder). Items are reassigned to user’s default list. Cannot delete default list. **Rest Route** The `deleteWatchlistList` API REST controller can be triggered via the following route: `/v1/watchlistlists/:watchlistListId` **Rest Request Parameters** The `deleteWatchlistList` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistListId | ID | true | request.params?.watchlistListId | **watchlistListId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistlists/:watchlistListId** ```js axios({ method: 'DELETE', url: `/v1/watchlistlists/${watchlistListId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Watchlistitem` API Remove a product from a user’s watchlist. **Rest Route** The `deleteWatchlistItem` API REST controller can be triggered via the following route: `/v1/watchlistitems/:watchlistItemId` **Rest Request Parameters** The `deleteWatchlistItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistItemId | ID | true | request.params?.watchlistItemId | **watchlistItemId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistitems/:watchlistItemId** ```js axios({ method: 'DELETE', url: `/v1/watchlistitems/${watchlistItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Cartitem` API Add an item to the user’s cart. Only fixed-price products allowed. Duplicates not permitted. **Rest Route** The `createCartItem` API REST controller can be triggered via the following route: `/v1/cartitems` **Rest Request Parameters** The `createCartItem` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | **addedAt** : Timestamp added to cart. **quantity** : How many units (if product allows). **productId** : Product being checked out. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/cartitems** ```js axios({ method: 'POST', url: '/v1/cartitems', data: { addedAt:"Date", quantity:"Integer", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Do Userwatchlist` API userwatchlist **Rest Route** The `userwatchlist` API REST controller can be triggered via the following route: `/v1/userwatchlist` **Rest Request Parameters** The `userwatchlist` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userwatchlist** ```js axios({ method: 'GET', url: '/v1/userwatchlist', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Usercartitems` API list all cart items adde by user **Rest Route** The `listUserCartItems` API REST controller can be triggered via the following route: `/v1/usercartitems` **Rest Request Parameters** The `listUserCartItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/usercartitems** ```js axios({ method: 'GET', url: '/v1/usercartitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "shipping": "Double" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Do Userwatchlistlists` API list all watch lists created by user **Rest Route** The `userwatchlistlists` API REST controller can be triggered via the following route: `/v1/userwatchlistlists` **Rest Request Parameters** The `userwatchlistlists` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/userwatchlistlists** ```js axios({ method: 'GET', url: '/v1/userwatchlistlists', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ## ProductListing Service Handles product listings (both auction and fixed-price), image/media storage with validations, enforces immutable type, soft-delete, and public product discovery. ### ProductListing Service Data Objects **ProductListingMedia** Stores and manages images/media associated with products, including secure URL, MIME type, and size validation. Each asset can be used by multiple products. **ProductListingProduct** Represents a single product listing (fixed-price or auction) in the marketplace, with seller, category, type, price information, shipping details, media references, and dynamic auction fields. ### ProductListing Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/productlisting-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/productlisting-api` * **Production:** `https://ebaycclone.mindbricks.co/productlisting-api` ### `List Productlistingmedia` API List all media assets (admin or for media management/bulk preview). **Rest Route** The `listProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias` **Rest Request Parameters** The `listProductListingMedia` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias** ```js axios({ method: 'GET', url: '/v1/productlistingmedias', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedias", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingMedias": [ { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Productlistingproduct` API Get a single product listing. Checks isActive and public status. Includes media, category, subcategory, and seller info via joins. **Rest Route** The `getProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `getProductListingProduct` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | **productListingProductId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'GET', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Productlistingownproducts` API listing the loggedin user's products **Rest Route** The `listProductListingOwnProducts` API REST controller can be triggered via the following route: `/v1/productlistingownproducts` **Rest Request Parameters** The `listProductListingOwnProducts` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingownproducts** ```js axios({ method: 'GET', url: '/v1/productlistingownproducts', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Productlistingmedia` API Get a single media asset by ID (for admin or to display in product UI). **Rest Route** The `getProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` **Rest Request Parameters** The `getProductListingMedia` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | **productListingMediaId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'GET', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Productlistingproducts` API List public product listings. Only isActive=true records are returned. Includes category, subcategory, seller, media joins. Supports filtering. **Rest Route** The `listProductListingProducts` API REST controller can be triggered via the following route: `/v1/productlistingproducts` **Rest Request Parameters** The `listProductListingProducts` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts** ```js axios({ method: 'GET', url: '/v1/productlistingproducts', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Delete Productlistingproduct` API Soft-delete a product listing. Only owner or admin can delete. **Rest Route** The `deleteProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `deleteProductListingProduct` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | **productListingProductId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'DELETE', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Productlistingproduct` API Update a product listing. Product type cannot be changed (immutable). **Rest Route** The `updateProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` **Rest Request Parameters** The `updateProductListingProduct` api has got 21 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | | currency | String | false | request.body?.currency | | description | Text | false | request.body?.description | | condition | Enum | false | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | false | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | false | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | false | request.body?.shippingMethod | | shipping | Double | false | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | false | request.body?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | **productListingProductId** : This id paremeter is used to select the required data object that will be updated **currency** : ISO currency code (e.g. USD, EUR) **description** : Product detailed description **condition** : Condition of product: BRAND_NEW, NEW, or USED **startBid** : The opening bid value (for auction type products) **endPrice** : Optional immediate sale/upper end price for auction (if AUCTION type) **price** : Product price (required if fixed price type) **title** : Product title **startPrice** : Minimum starting price for auction (required if AUCTION type) **endBid** : The upper (max) bid value for auction products (if any) **estimatedDelivery** : Estimated delivery date for this product **shippingCurrency** : Currency code for shipping cost **mediaAssetIds** : References to associated product/media assets **shippingMethod** : Shipping option for product: STANDARD, EXPRESS, or FREE **shipping** : Shipping cost for this product **startBidDate** : Date/time when auction bidding begins **subcategoryId** : Reference to subcategory **categoryId** : Reference to parent category **endBidDate** : Date/time when auction bidding ends **currentBid** : Current highest bid for auction-type product (updated atomically on bid placement) **highestBidderId** : User ID of current highest bidder (auction-only, updated by auction microservice) **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'PATCH', url: `/v1/productlistingproducts/${productListingProductId}`, data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Productlistingproduct` API Create a new product listing (fixed or auction), conditioned on product type. Type is immutable after creation. **Rest Route** The `createProductListingProduct` API REST controller can be triggered via the following route: `/v1/productlistingproducts` **Rest Request Parameters** The `createProductListingProduct` api has got 21 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | description | Text | true | request.body?.description | | condition | Enum | true | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | true | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | type | Enum | true | request.body?.type | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | true | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | true | request.body?.shippingMethod | | shipping | Double | true | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | true | request.body?.subcategoryId | | categoryId | ID | true | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | **currency** : ISO currency code (e.g. USD, EUR) **description** : Product detailed description **condition** : Condition of product: BRAND_NEW, NEW, or USED **startBid** : The opening bid value (for auction type products) **endPrice** : Optional immediate sale/upper end price for auction (if AUCTION type) **price** : Product price (required if fixed price type) **title** : Product title **startPrice** : Minimum starting price for auction (required if AUCTION type) **type** : Product listing type, either FIXED or AUCTION (immutable after creation) **endBid** : The upper (max) bid value for auction products (if any) **estimatedDelivery** : Estimated delivery date for this product **shippingCurrency** : Currency code for shipping cost **mediaAssetIds** : References to associated product/media assets **shippingMethod** : Shipping option for product: STANDARD, EXPRESS, or FREE **shipping** : Shipping cost for this product **startBidDate** : Date/time when auction bidding begins **subcategoryId** : Reference to subcategory **categoryId** : Reference to parent category **endBidDate** : Date/time when auction bidding ends **currentBid** : Current highest bid for auction-type product (updated atomically on bid placement) **highestBidderId** : User ID of current highest bidder (auction-only, updated by auction microservice) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/productlistingproducts** ```js axios({ method: 'POST', url: '/v1/productlistingproducts', data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", type:"Enum", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Productlistingmedia` API Soft-delete a media asset (typically by admin or media owner for flagged/invalid content). **Rest Route** The `deleteProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` **Rest Request Parameters** The `deleteProductListingMedia` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | **productListingMediaId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'DELETE', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Productlistingmedia` API Create a new media asset record after validation. Used mainly by edge controller after upload. **Rest Route** The `createProductListingMedia` API REST controller can be triggered via the following route: `/v1/productlistingmedias` **Rest Request Parameters** The `createProductListingMedia` api has got 4 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | mimeType | String | true | request.body?.mimeType | | productId | ID | false | request.body?.productId | | url | String | true | request.body?.url | | size | Integer | true | request.body?.size | **mimeType** : MIME type of the uploaded media (e.g., image/jpeg) **productId** : ID of product associated with this media asset **url** : Secure, validated URL for the media asset (S3 or equivalent) **size** : Media size in bytes (for validation and quota) **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/productlistingmedias** ```js axios({ method: 'POST', url: '/v1/productlistingmedias', data: { mimeType:"String", productId:"ID", url:"String", size:"Integer", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ## OrderManagement Service Handles all marketplace orders, manual checkout flows for fixed-price/offer/auction settlements, Stripe payment processing and webhook reconciliation, explicit status updates (shipping, delivery, cancellation), and feedback eligibility via orderItems. ### OrderManagement Service Data Objects **OrderManagementOrder** Marketplace order record. Stores buyer, shipping, status, items, Stripe payment data, and manual shipment/delivery events. Only accessible to admins or the buyer/seller of order items. **OrderManagementOrderItem** Order line item representing purchase of a single product from a specific seller as part of an order. Enables feedback, delivery, and per-seller analytics. Immutable after order creation. **Sys_orderManagementOrderPayment** A payment storage object to store the payment life cyle of orders based on orderManagementOrder object. It is autocreated based on the source object's checkout config **Sys_paymentCustomer** A payment storage object to store the customer values of the payment platform **Sys_paymentMethod** A payment storage object to store the payment methods of the platform customers ### OrderManagement Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/ordermanagement-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/ordermanagement-api` * **Production:** `https://ebaycclone.mindbricks.co/ordermanagement-api` ### `List Ordermanagementorders` API List orders, filtered for buyer and/or seller, or by admin. Includes select orderItems. **Rest Route** The `listOrderManagementOrders` API REST controller can be triggered via the following route: `/v1/ordermanagementorders` **Rest Request Parameters** The `listOrderManagementOrders` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ordermanagementorders', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Ordermanagementorderitem` API Get a specific order item (for feedback/business logic). **Rest Route** The `getOrderManagementOrderItem` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems/:orderManagementOrderItemId` **Rest Request Parameters** The `getOrderManagementOrderItem` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderItemId | ID | true | request.params?.orderManagementOrderItemId | **orderManagementOrderItemId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems/:orderManagementOrderItemId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderitems/${orderManagementOrderItemId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Ordermanagementorder` API Soft-delete/cancel order by admin or eligible actor prior to shipment. Sets status to CANCELLED and cancels active payment intent if pending. Irreversible and blocks feedback. **Rest Route** The `deleteOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` **Rest Request Parameters** The `deleteOrderManagementOrder` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorder` API Get single order by ID. Only accessible to admin, buyer, or relevant sellers of items within this order. Includes all orderItems. **Rest Route** The `getOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` **Rest Request Parameters** The `getOrderManagementOrder` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | **orderManagementOrderId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Ordermanagementorderstatus` API Update order status (manual shipment, delivery, cancellation/refund). Restricted: only seller of all items can mark as shipped, only buyer can confirm delivery, only admin can set refund/cancelled. Timestamps updated as per business rule. **Rest Route** The `updateOrderManagementOrderStatus` API REST controller can be triggered via the following route: `/v1/ordermanagementorderstatus/:orderManagementOrderId` **Rest Request Parameters** The `updateOrderManagementOrderStatus` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **status** : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderstatus/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderstatus/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Complete Orderstripewebhook` API Webhook endpoint called by Stripe to reconcile payment state and update order status based on paymentIntentId and event data. No authentication required (Stripe IPs only). **Rest Route** The `completeOrderStripeWebhook` API REST controller can be triggered via the following route: `/v1/completeorderstripewebhook/:orderManagementOrderId` **Rest Request Parameters** The `completeOrderStripeWebhook` api has got 10 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **status** : Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/completeorderstripewebhook/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/completeorderstripewebhook/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderbyproductid` API get orders by productId **Rest Route** The `getOrderManagementOrderByProductId` API REST controller can be triggered via the following route: `/v1/ordermanagementorderbyproductid/:items` **Rest Request Parameters** The `getOrderManagementOrderByProductId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | items | String | true | request.params?.items | **orderManagementOrderId** : This id paremeter is used to query the required data object. **items** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderbyproductid/:items** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderbyproductid/${items}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Ordermanagementorder` API Creates an order and initiates Stripe payment. Validates that all products in the order are fixed-price, populates orderItems, saves Stripe customer/paymentMethod/paymentIntentId for reconciliation. Only accessible to buyers for own checkouts and only allows fixed-price product checkout (no auction). **Rest Route** The `createOrderManagementOrder` API REST controller can be triggered via the following route: `/v1/ordermanagementorders` **Rest Request Parameters** The `createOrderManagementOrder` api has got 14 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderNumber | String | true | request.body?.orderNumber | | items | ID | false | request.body?.items | | paymentMethodId | String | true | request.body?.paymentMethodId | | stripeCustomerId | String | true | request.body?.stripeCustomerId | | paymentIntentId | String | false | request.body?.paymentIntentId | | shippingAddress | Object | true | request.body?.shippingAddress | | summary | Object | true | request.body?.summary | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | **orderNumber** : Unique, human-friendly order number (displayed to users); enforced unique. **items** : Array of orderManagementOrderItem ids representing items in this order. **paymentMethodId** : Stripe paymentMethodId used for payment. Not stored if cash or other payment (future). **stripeCustomerId** : Stripe customerId of buyer; enables saved/paymentMethodId flows. **paymentIntentId** : Stripe paymentIntentId; enables webhook correlation and status sync. **shippingAddress** : Shipping address for the order (copy of buyer address at purchase time). **summary** : Object with total, subtotal, currency, shipping, discount breakdown as snapshot of order at time of purchase. **trackingNumber** : Optional tracking number entered by seller when marking as shipped. **estimatedDelivery** : Estimated delivery date for order; copied from fastest estimated item or seller input. **cancelledAt** : Timestamp when cancelled by buyer, seller, or admin before shipment. **paidAt** : Timestamp when payment confirmed via Stripe or manual admin update. **deliveredAt** : Timestamp when buyer confirms delivery. **shippedAt** : Timestamp when seller marks as shipped. **carrier** : Optional carrier name entered by seller when marking as shipped. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorders** ```js axios({ method: 'POST', url: '/v1/ordermanagementorders', data: { orderNumber:"String", items:"ID", paymentMethodId:"String", stripeCustomerId:"String", paymentIntentId:"String", shippingAddress:"Object", summary:"Object", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderitems` API List order items for a given order or for buyer/seller analytics. Used for feedback management. **Rest Route** The `listOrderManagementOrderItems` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems` **Rest Request Parameters** The `listOrderManagementOrderItems` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderitems', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Ownordermanagementorders` API list the loggedin user orders **Rest Route** The `listOwnOrderManagementOrders` API REST controller can be triggered via the following route: `/v1/ownordermanagementorders` **Rest Request Parameters** The `listOwnOrderManagementOrders` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ownordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ownordermanagementorders', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Lis Ordermanagementownorderitem` API list the loggedin user's order items **Rest Route** The `lisOrderManagementOwnOrderItem` API REST controller can be triggered via the following route: `/v1/lisordermanagementownorderitem` **Rest Request Parameters** The `lisOrderManagementOwnOrderItem` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/lisordermanagementownorderitem** ```js axios({ method: 'GET', url: '/v1/lisordermanagementownorderitem', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Ordermanagementorderitem` API create order item **Rest Route** The `createOrderManagementOrderItem` API REST controller can be triggered via the following route: `/v1/ordermanagementorderitems` **Rest Request Parameters** The `createOrderManagementOrderItem` api has got 8 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | shipping | Double | true | request.body?.shipping | | orderId | ID | true | request.body?.orderId | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | | price | Double | true | request.body?.price | | sellerId | ID | true | request.body?.sellerId | | title | String | true | request.body?.title | | currency | String | true | request.body?.currency | **shipping** : Shipping cost for this product (may be 0 for free shipping). **orderId** : Parent order this item belongs to; enables join and lifecycle tracking. **quantity** : Number of units purchased for this product. **productId** : ID of product purchased in this line item. **price** : Unit price for this product at purchase time. **sellerId** : UserId of seller (owner of product at purchase time). **title** : Product title at purchase time (copied for convenience/audit). **currency** : Currency code for price/shipping (ISO 4217). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderitems** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderitems', data: { shipping:"Double", orderId:"ID", quantity:"Integer", productId:"ID", price:"Double", sellerId:"ID", title:"String", currency:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpayment2` API This route is used to get the payment information by ID. **Rest Route** The `getOrderManagementOrderPayment2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `getOrderManagementOrderPayment2` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderpayments2` API This route is used to list all payments. **Rest Route** The `listOrderManagementOrderPayments2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayments2` **Rest Request Parameters** The `listOrderManagementOrderPayments2` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Create Ordermanagementorderpayment` API This route is used to create a new payment. **Rest Route** The `createOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment` **Rest Request Parameters** The `createOrderManagementOrderPayment` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderId | ID | true | request.body?.orderId | | paymentId | String | true | request.body?.paymentId | | paymentStatus | String | true | request.body?.paymentStatus | | statusLiteral | String | true | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | **orderId** : an ID value to represent the orderId which is the ID parameter of the source orderManagementOrder object **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderpayment', data: { orderId:"ID", paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Ordermanagementorderpayment` API This route is used to update an existing payment. **Rest Route** The `updateOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `updateOrderManagementOrderPayment` api has got 5 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | false | request.body?.paymentId | | paymentStatus | String | false | request.body?.paymentStatus | | statusLiteral | String | false | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | **sys_orderManagementOrderPaymentId** : This id paremeter is used to select the required data object that will be updated **paymentId** : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type **paymentStatus** : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. **statusLiteral** : A string value to represent the logical payment status which belongs to the application lifecycle itself. **redirectUrl** : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Ordermanagementorderpayment` API This route is used to delete a payment. **Rest Route** The `deleteOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `deleteOrderManagementOrderPayment` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Ordermanagementorderpayments2` API This route is used to list all payments. **Rest Route** The `listOrderManagementOrderPayments2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayments2` **Rest Request Parameters** The `listOrderManagementOrderPayments2` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Ordermanagementorderpaymentbyorderid` API This route is used to get the payment information by order id. **Rest Route** The `getOrderManagementOrderPaymentByOrderId` API REST controller can be triggered via the following route: `/v1/orderManagementOrderpaymentbyorderid/:orderId` **Rest Request Parameters** The `getOrderManagementOrderPaymentByOrderId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | orderId | String | true | request.params?.orderId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **orderId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbyorderid/:orderId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbyorderid/${orderId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpaymentbypaymentid` API This route is used to get the payment information by payment id. **Rest Route** The `getOrderManagementOrderPaymentByPaymentId` API REST controller can be triggered via the following route: `/v1/orderManagementOrderpaymentbypaymentid/:paymentId` **Rest Request Parameters** The `getOrderManagementOrderPaymentByPaymentId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | true | request.params?.paymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **paymentId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbypaymentid/:paymentId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbypaymentid/${paymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Get Ordermanagementorderpayment2` API This route is used to get the payment information by ID. **Rest Route** The `getOrderManagementOrderPayment2` API REST controller can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` **Rest Request Parameters** The `getOrderManagementOrderPayment2` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | **sys_orderManagementOrderPaymentId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Start Ordermanagementorderpayment` API Start payment for orderManagementOrder **Rest Route** The `startOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/startordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `startOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to start a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/startordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/startordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Refresh Ordermanagementorderpayment` API Refresh payment info for orderManagementOrder from Stripe **Rest Route** The `refreshOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/refreshordermanagementorderpayment/:orderManagementOrderId` **Rest Request Parameters** The `refreshOrderManagementOrderPayment` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | **orderManagementOrderId** : This id paremeter is used to select the required data object that will be updated **paymentUserParams** : The user parameters that should be defined to refresh a stripe payment process **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/refreshordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/refreshordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Callback Ordermanagementorderpayment` API Refresh payment values by gateway webhook call for orderManagementOrder **Rest Route** The `callbackOrderManagementOrderPayment` API REST controller can be triggered via the following route: `/v1/callbackordermanagementorderpayment` **Rest Request Parameters** The `callbackOrderManagementOrderPayment` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.body?.orderManagementOrderId | **orderManagementOrderId** : The order id parameter that will be read from webhook callback params **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/callbackordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/callbackordermanagementorderpayment', data: { orderManagementOrderId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` ### `Get Paymentcustomerbyuserid` API This route is used to get the payment customer information by user id. **Rest Route** The `getPaymentCustomerByUserId` API REST controller can be triggered via the following route: `/v1/paymentcustomers/:userId` **Rest Request Parameters** The `getPaymentCustomerByUserId` api has got 2 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_paymentCustomerId | ID | true | request.params?.sys_paymentCustomerId | | userId | String | true | request.params?.userId | **sys_paymentCustomerId** : This id paremeter is used to query the required data object. **userId** : This parameter will be used to select the data object that is queried **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomers/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_paymentCustomer": { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `List Paymentcustomers` API This route is used to list all payment customers. **Rest Route** The `listPaymentCustomers` API REST controller can be triggered via the following route: `/v1/paymentcustomers` **Rest Request Parameters** The `listPaymentCustomers` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers** ```js axios({ method: 'GET', url: '/v1/paymentcustomers', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentCustomers": [ { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `List Paymentcustomermethods` API This route is used to list all payment customer methods. **Rest Route** The `listPaymentCustomerMethods` API REST controller can be triggered via the following route: `/v1/paymentcustomermethods/:userId` **Rest Request Parameters** The `listPaymentCustomerMethods` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | String | true | request.params?.userId | **userId** : This parameter will be used to select the data objects that want to be listed **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomermethods/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomermethods/${userId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentMethods", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentMethods": [ { "id": "ID", "paymentMethodId": "String", "userId": "ID", "customerId": "String", "cardHolderName": "String", "cardHolderZip": "String", "platform": "String", "cardInfo": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ## Feedback Service Handles feedback for order items: one feedback per buyer/orderItem, attached to sellerId for analytical feedback/rating aggregation and reputation tracking. Enables querying feedbacks received/given for sellers and buyers. test ### Feedback Service Data Objects **Feedback** One feedback per (buyer, orderItem). Stores rating (1-5), comment, ties to seller for analytics. Created only after delivery confirmed on order item. ### Feedback Service Access urls This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/feedback-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/feedback-api` * **Production:** `https://ebaycclone.mindbricks.co/feedback-api` ### `List Feedbacks` API List feedback with filtering by buyerId (given), sellerId (received), productId, or orderItemId. Used for showing seller profile, buyer profile, or order analytics. **Rest Route** The `listFeedbacks` API REST controller can be triggered via the following route: `/v1/feedbacks` **Rest Request Parameters** The `listFeedbacks` api has got no request parameters. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/feedbacks** ```js axios({ method: 'GET', url: '/v1/feedbacks', data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedbacks", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "feedbacks": [ { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` ### `Get Feedback` API Get a single feedback by id. Accessible to public (for seller profile, product, or audit views). **Rest Route** The `getFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `getFeedback` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | **feedbackId** : This id paremeter is used to query the required data object. **REST Request** To access the api you can use the **REST** controller with the path **GET /v1/feedbacks/:feedbackId** ```js axios({ method: 'GET', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Update Feedback` API Update feedback (comment/rating) for existing feedback record (buyer only). Admin can update as override. **Rest Route** The `updateFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `updateFeedback` api has got 3 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | | rating | Integer | false | request.body?.rating | | comment | String | false | request.body?.comment | **feedbackId** : This id paremeter is used to select the required data object that will be updated **rating** : Rating (1-5 stars) submitted by buyer. Required. **comment** : Optional textual feedback comment, max ~500 chars. **REST Request** To access the api you can use the **REST** controller with the path **PATCH /v1/feedbacks/:feedbackId** ```js axios({ method: 'PATCH', url: `/v1/feedbacks/${feedbackId}`, data: { rating:"Integer", comment:"String", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Delete Feedback` API Delete (soft-delete) feedback (by buyer or admin). Only feedback owner or admin. **Rest Route** The `deleteFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks/:feedbackId` **Rest Request Parameters** The `deleteFeedback` api has got 1 request parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | **feedbackId** : This id paremeter is used to select the required data object that will be deleted **REST Request** To access the api you can use the **REST** controller with the path **DELETE /v1/feedbacks/:feedbackId** ```js axios({ method: 'DELETE', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` ### `Create Feedback` API Buyer creates feedback for a delivered order item. Only allowed once per (buyer, orderItemId). Allowed only once order item is delivered. **Rest Route** The `createFeedback` API REST controller can be triggered via the following route: `/v1/feedbacks` **Rest Request Parameters** The `createFeedback` api has got 6 request parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | rating | Integer | true | request.body?.rating | | orderId | ID | true | request.body?.orderId | | orderItemId | ID | true | request.body?.orderItemId | | sellerId | ID | true | request.body?.sellerId | | comment | String | false | request.body?.comment | | productId | ID | true | request.body?.productId | **rating** : Rating (1-5 stars) submitted by buyer. Required. **orderId** : Order containing this purchased item. Used for aggregation and validation. **orderItemId** : Purchased item (line item) in order. Feedback is per (buyer, orderItem). **sellerId** : Seller of product for analytics/aggregation. Not author; used for querying feedback about sellers. **comment** : Optional textual feedback comment, max ~500 chars. **productId** : The product listing being reviewed (snapshot at order time). **REST Request** To access the api you can use the **REST** controller with the path **POST /v1/feedbacks** ```js axios({ method: 'POST', url: '/v1/feedbacks', data: { rating:"Integer", orderId:"ID", orderItemId:"ID", sellerId:"ID", comment:"String", productId:"ID", }, params: { } }); ``` **REST Response** ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # REST API GUIDE ## ebaycclone-watchlistcart-service Handles user watchlists (with custom folders) and shopping cart preparation for checkout, strictly enforcing only fixed-price products in carts, supporting item moves/bulk operations, and robust default/folder logic.. ## Architectural Design Credit and Contact Information The architectural design of this microservice is credited to . For inquiries, feedback, or further information regarding the architecture, please direct your communication to: Email: We encourage open communication and welcome any questions or discussions related to the architectural aspects of this microservice. ## Documentation Scope Welcome to the official documentation for the WatchlistCart Service's REST API. This document is designed to provide a comprehensive guide to interfacing with our WatchlistCart Service exclusively through RESTful API endpoints. **Intended Audience** This documentation is intended for developers and integrators who are looking to interact with the WatchlistCart Service via HTTP requests for purposes such as creating, updating, deleting and querying WatchlistCart objects. **Overview** Within these pages, you will find detailed information on how to effectively utilize the REST API, including authentication methods, request and response formats, endpoint descriptions, and examples of common use cases. Beyond REST It's important to note that the WatchlistCart Service also supports alternative methods of interaction, such as gRPC and messaging via a Message Broker. These communication methods are beyond the scope of this document. For information regarding these protocols, please refer to their respective documentation. ## Authentication And Authorization To ensure secure access to the WatchlistCart service's protected endpoints, a project-wide access token is required. This token serves as the primary method for authenticating requests to our service. However, it's important to note that access control varies across different routes: **Protected API**: Certain API (routes) require specific authorization levels. Access to these routes is contingent upon the possession of a valid access token that meets the route-specific authorization criteria. Unauthorized requests to these routes will be rejected. **Public API **: The service also includes public API (routes) that are accessible without authentication. These public endpoints are designed for open access and do not require an access token. ### Token Locations When including your access token in a request, ensure it is placed in one of the following specified locations. The service will sequentially search these locations for the token, utilizing the first one it encounters. | Location | Token Name / Param Name | | ---------------------- | ---------------------------- | | Query | access_token | | Authorization Header | Bearer | | Header | ebaycclone-access-token| | Cookie | ebaycclone-access-token| Please ensure the token is correctly placed in one of these locations, using the appropriate label as indicated. The service prioritizes these locations in the order listed, processing the first token it successfully identifies. ## Api Definitions This section outlines the API endpoints available within the WatchlistCart service. Each endpoint can receive parameters through various methods, meticulously described in the following definitions. It's important to understand the flexibility in how parameters can be included in requests to effectively interact with the WatchlistCart service. This service is configured to listen for HTTP requests on port `3003`, serving both the main API interface and default administrative endpoints. The following routes are available by default: * **API Test Interface (API Face):** `/` * **Swagger Documentation:** `/swagger` * **Postman Collection Download:** `/getPostmanCollection` * **Health Checks:** `/health` and `/admin/health` * **Current Session Info:** `/currentuser` * **Favicon:** `/favicon.ico` This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/watchlistcart-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/watchlistcart-api` * **Production:** `https://ebaycclone.mindbricks.co/watchlistcart-api` **Parameter Inclusion Methods:** Parameters can be incorporated into API requests in several ways, each with its designated location. Understanding these methods is crucial for correctly constructing your requests: **Query Parameters:** Included directly in the URL's query string. **Path Parameters:** Embedded within the URL's path. **Body Parameters:** Sent within the JSON body of the request. **Session Parameters:** Automatically read from the session object. This method is used for parameters that are intrinsic to the user's session, such as userId. When using an API that involves session parameters, you can omit these from your request. The service will automatically bind them to the API layer, provided that a session is associated with your request. **Note on Session Parameters:** Session parameters represent a unique method of parameter inclusion, relying on the context of the user's session. A common example of a session parameter is userId, which the service automatically associates with your request when a session exists. This feature ensures seamless integration of user-specific data without manual input for each request. By adhering to the specified parameter inclusion methods, you can effectively utilize the WatchlistCart service's API endpoints. For detailed information on each endpoint, including required parameters and their accepted locations, refer to the individual API definitions below. ### Common Parameters The `WatchlistCart` service's business API support several common parameters designed to modify and enhance the behavior of API requests. These parameters are not individually listed in the API route definitions to avoid repetition. Instead, refer to this section to understand how to leverage these common behaviors across different routes. Note that all common parameters should be included in the query part of the URL. ### Supported Common Parameters: - **getJoins (BOOLEAN)**: Controls whether to retrieve associated objects along with the main object. By default, `getJoins` is assumed to be `true`. Set it to `false` if you prefer to receive only the main fields of an object, excluding its associations. - **excludeCQRS (BOOLEAN)**: Applicable only when `getJoins` is `true`. By default, `excludeCQRS` is set to `false`. Enabling this parameter (`true`) omits non-local associations, which are typically more resource-intensive as they require querying external services like ElasticSearch for additional information. Use this to optimize response times and resource usage. - **requestId (String)**: Identifies a request to enable tracking through the service's log chain. A random hex string of 32 characters is assigned by default. If you wish to use a custom `requestId`, simply include it in your query parameters. - **caching (BOOLEAN)**: Determines the use of caching for query API. By default, caching is enabled (`true`). To ensure the freshest data directly from the database, set this parameter to `false`, bypassing the cache. - **cacheTTL (Integer)**: Specifies the Time-To-Live (TTL) for query caching, in seconds. This is particularly useful for adjusting the default caching duration (5 minutes) for `get list` queries. Setting a custom `cacheTTL` allows you to fine-tune the cache lifespan to meet your needs. - **pageNumber (Integer)**: For paginated `get list` API's, this parameter selects which page of results to retrieve. The default is `1`, indicating the first page. To disable pagination and retrieve all results, set `pageNumber` to `0`. - **pageRowCount (Integer)**: In conjunction with paginated API's, this parameter defines the number of records per page. The default value is `25`. Adjusting `pageRowCount` allows you to control the volume of data returned in a single request. By utilizing these common parameters, you can tailor the behavior of API requests to suit your specific requirements, ensuring optimal performance and usability of the `WatchlistCart` service. ### Error Response If a request encounters an issue, whether due to a logical fault or a technical problem, the service responds with a standardized JSON error structure. The HTTP status code within this response indicates the nature of the error, utilizing commonly recognized codes for clarity: - **400 Bad Request**: The request was improperly formatted or contained invalid parameters, preventing the server from processing it. - **401 Unauthorized**: The request lacked valid authentication credentials or the credentials provided do not grant access to the requested resource. - **404 Not Found**: The requested resource was not found on the server. - **500 Internal Server Error**: The server encountered an unexpected condition that prevented it from fulfilling the request. Each error response is structured to provide meaningful insight into the problem, assisting in diagnosing and resolving issues efficiently. ```js { "result": "ERR", "status": 400, "message": "errMsg_organizationIdisNotAValidID", "errCode": 400, "date": "2024-03-19T12:13:54.124Z", "detail": "String" } ``` ### Object Structure of a Successfull Response When the `WatchlistCart` service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope not only contains the data but also includes essential metadata, such as configuration details and pagination information, to enrich the response and provide context to the client. **Key Characteristics of the Response Envelope:** - **Data Presentation**: Depending on the nature of the request, the service returns either a single data object or an array of objects encapsulated within the JSON envelope. - **Creation and Update API**: These API routes return the unmodified (pure) form of the data object(s), without any associations to other data objects. - **Delete API**: Even though the data is removed from the database, the last known state of the data object(s) is returned in its pure form. - **Get Requests**: A single data object is returned in JSON format. - **Get List Requests**: An array of data objects is provided, reflecting a collection of resources. - **Data Structure and Joins**: The complexity of the data structure in the response can vary based on the API's architectural design and the join options specified in the request. The architecture might inherently limit join operations, or they might be dynamically controlled through query parameters. - **Pure Data Forms**: In some cases, the response mirrors the exact structure found in the primary data table, without extensions. - **Extended Data Forms**: Alternatively, responses might include data extended through joins with tables within the same service or aggregated from external sources, such as ElasticSearch indices related to other services. - **Join Varieties**: The extensions might involve one-to-one joins, resulting in single object associations, or one-to-many joins, leading to an array of objects. In certain instances, the data might even feature nested inclusions from other data objects. **Design Considerations**: The structure of a API's response data is meticulously crafted during the service's architectural planning. This design ensures that responses adequately reflect the intended data relationships and service logic, providing clients with rich and meaningful information. **Brief Data**: Certain API's return a condensed version of the object data, intentionally selecting only specific fields deemed useful for that request. In such instances, the API documentation will detail the properties included in the response, guiding developers on what to expect. ### API Response Structure The API utilizes a standardized JSON envelope to encapsulate responses. This envelope is designed to consistently deliver both the requested data and essential metadata, ensuring that clients can efficiently interpret and utilize the response. **HTTP Status Codes:** - **200 OK**: This status code is returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request has been processed successfully. - **201 Created**: This status code is specific to CREATE operations, signifying that the requested resource has been successfully created. **Success Response Format:** For successful operations, the response includes a `"status": "OK"` property, signaling the successful execution of the request. The structure of a successful response is outlined below: ```json { "status":"OK", "statusCode": 200, "elapsedMs":126, "ssoTime":120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName":"products", "method":"GET", "action":"list", "appVersion":"Version", "rowCount":3 "products":[{},{},{}], "paging": { "pageNumber":1, "pageRowCount":25, "totalRowCount":3, "pageCount":1 }, "filters": [], "uiPermissions": [] } ``` - **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation performed. **Handling Errors:** For details on handling error scenarios and understanding the structure of error responses, please refer to the "Error Response" section provided earlier in this documentation. It outlines how error conditions are communicated, including the use of HTTP status codes and standardized JSON structures for error messages. ## Resources WatchlistCart service provides the following resources which are stored in its own database as a data object. Note that a resource for an api access is a data object for the service. ### WatchlistItem resource *Resource Definition* : Item in a user’s watchlist, optionally in a named folder; references product and user. *WatchlistItem Resource Properties* | Name | Type | Required | Default | Definition | | ---- | ---- | -------- | ------- | ---------- | | **userId** | ID | | | *Owner of the watchlist item.* | | **addedAt** | Date | | | *Timestamp watchlist item created.* | | **productId** | ID | | | *Referenced product in the watchlist.* | | **listId** | ID | | | *Owning watchlistList; null if in default watchlist.* | ### CartItem resource *Resource Definition* : Single product pending checkout in a user’s cart. Only fixed-price products permitted; quantity supported for multi-unit purchases (if allowed). *CartItem Resource Properties* | Name | Type | Required | Default | Definition | | ---- | ---- | -------- | ------- | ---------- | | **addedAt** | Date | | | *Timestamp added to cart.* | | **userId** | ID | | | *Cart owner.* | | **quantity** | Integer | | | *How many units (if product allows).* | | **productId** | ID | | | *Product being checked out.* | ### WatchlistList resource *Resource Definition* : A named folder/list in a user’s watchlist. Default list exists for all users. Custom lists may be created and deleted. *WatchlistList Resource Properties* | Name | Type | Required | Default | Definition | | ---- | ---- | -------- | ------- | ---------- | | **name** | String | | | *Custom folder or list name. 'Default' is reserved (non-deletable for each user).* | | **itemCount** | Integer | | | *Number of (non-deleted) items in the list/folder.* | | **userId** | ID | | | *Owner of the watchlist list/folder.* | ## Business Api ### List Watchlistlist API *API Definition* : List all lists in user’s watchlists. Supports listing by listId for folders. *API Crud Type* : list *Default access route* : *GET* `/v1/watchlistlists` The listWatchlistList api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/watchlistlists** ```js axios({ method: 'GET', url: '/v1/watchlistlists', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`watchlistLists`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistLists","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","watchlistLists":[{"id":"ID","name":"String","itemCount":"Integer","userId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For List Watchlistlist](businessApi/listWatchlistList). ### List Cartitems API *API Definition* : List all cart items for a user (pending checkout). *API Crud Type* : list *Default access route* : *GET* `/v1/cartitems` The listCartItems api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/cartitems** ```js axios({ method: 'GET', url: '/v1/cartitems', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`cartItems`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"cartItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","cartItems":[{"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID","product":[{"currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","price":"Double","title":"String","type":"Enum","type_idx":"Integer","mediaAssetIds":"ID"},{},{}]},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For List Cartitems](businessApi/listCartItems). ### Delete Cartitem API *API Definition* : Remove an item from the user’s cart. *API Crud Type* : delete *Default access route* : *DELETE* `/v1/cartitems/:cartItemId` #### Parameters The deleteCartItem api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | To access the api you can use the **REST** controller with the path **DELETE /v1/cartitems/:cartItemId** ```js axios({ method: 'DELETE', url: `/v1/cartitems/${cartItemId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`cartItem`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"cartItem","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"cartItem":{"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Delete Cartitem](businessApi/deleteCartItem). ### Create Watchlistitem API *API Definition* : Add product to user’s watchlist (default or target list/folder). One (user, product, list) per item enforced. Block duplicates. *API Crud Type* : create *Default access route* : *POST* `/v1/watchlistitems` #### Parameters The createWatchlistItem api has got 3 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | productId | ID | true | request.body?.productId | | listId | ID | false | request.body?.listId | To access the api you can use the **REST** controller with the path **POST /v1/watchlistitems** ```js axios({ method: 'POST', url: '/v1/watchlistitems', data: { addedAt:"Date", productId:"ID", listId:"ID", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`watchlistItem`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistItem","method":"POST","action":"create","appVersion":"Version","rowCount":1,"watchlistItem":{"id":"ID","userId":"ID","addedAt":"Date","productId":"ID","listId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Create Watchlistitem](businessApi/createWatchlistItem). ### List Watchlistitems API *API Definition* : List all products in user’s watchlists. Supports listing by listId for folders. *API Crud Type* : list *Default access route* : *GET* `/v1/watchlistitems` The listWatchlistItems api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/watchlistitems** ```js axios({ method: 'GET', url: '/v1/watchlistitems', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`watchlistItems`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","watchlistItems":[{"id":"ID","userId":"ID","addedAt":"Date","productId":"ID","listId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For List Watchlistitems](businessApi/listWatchlistItems). ### Update Cartitemquantity API *API Definition* : Change the quantity for a cart item. User must own the item. *API Crud Type* : update *Default access route* : *PATCH* `/v1/cartitemquantity/:cartItemId` #### Parameters The updateCartItemQuantity api has got 2 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | | quantity | Integer | false | request.body?.quantity | To access the api you can use the **REST** controller with the path **PATCH /v1/cartitemquantity/:cartItemId** ```js axios({ method: 'PATCH', url: `/v1/cartitemquantity/${cartItemId}`, data: { quantity:"Integer", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`cartItem`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"cartItem","method":"PATCH","action":"update","appVersion":"Version","rowCount":1,"cartItem":{"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Update Cartitemquantity](businessApi/updateCartItemQuantity). ### Create Watchlistlist API *API Definition* : Create a new custom watchlist folder. Name must be unique per user; ‘Default’ is reserved for system. *API Crud Type* : create *Default access route* : *POST* `/v1/watchlistlists` #### Parameters The createWatchlistList api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | name | String | true | request.body?.name | To access the api you can use the **REST** controller with the path **POST /v1/watchlistlists** ```js axios({ method: 'POST', url: '/v1/watchlistlists', data: { name:"String", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`watchlistList`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistList","method":"POST","action":"create","appVersion":"Version","rowCount":1,"watchlistList":{"id":"ID","name":"String","itemCount":"Integer","userId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Create Watchlistlist](businessApi/createWatchlistList). ### Delete Watchlistlist API *API Definition* : Delete a custom watchlist (folder). Items are reassigned to user’s default list. Cannot delete default list. *API Crud Type* : delete *Default access route* : *DELETE* `/v1/watchlistlists/:watchlistListId` #### Parameters The deleteWatchlistList api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistListId | ID | true | request.params?.watchlistListId | To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistlists/:watchlistListId** ```js axios({ method: 'DELETE', url: `/v1/watchlistlists/${watchlistListId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`watchlistList`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistList","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"watchlistList":{"id":"ID","name":"String","itemCount":"Integer","userId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Delete Watchlistlist](businessApi/deleteWatchlistList). ### Delete Watchlistitem API *API Definition* : Remove a product from a user’s watchlist. *API Crud Type* : delete *Default access route* : *DELETE* `/v1/watchlistitems/:watchlistItemId` #### Parameters The deleteWatchlistItem api has got 1 parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistItemId | ID | true | request.params?.watchlistItemId | To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistitems/:watchlistItemId** ```js axios({ method: 'DELETE', url: `/v1/watchlistitems/${watchlistItemId}`, data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`watchlistItem`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistItem","method":"DELETE","action":"delete","appVersion":"Version","rowCount":1,"watchlistItem":{"id":"ID","userId":"ID","addedAt":"Date","productId":"ID","listId":"ID","isActive":false,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Delete Watchlistitem](businessApi/deleteWatchlistItem). ### Create Cartitem API *API Definition* : Add an item to the user’s cart. Only fixed-price products allowed. Duplicates not permitted. *API Crud Type* : create *Default access route* : *POST* `/v1/cartitems` #### Parameters The createCartItem api has got 3 parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | To access the api you can use the **REST** controller with the path **POST /v1/cartitems** ```js axios({ method: 'POST', url: '/v1/cartitems', data: { addedAt:"Date", quantity:"Integer", productId:"ID", }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`cartItem`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"201","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"cartItem","method":"POST","action":"create","appVersion":"Version","rowCount":1,"cartItem":{"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"}} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Create Cartitem](businessApi/createCartItem). ### Do Userwatchlist API *API Definition* : userwatchlist *API Crud Type* : list *Default access route* : *GET* `/v1/userwatchlist` The userwatchlist api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/userwatchlist** ```js axios({ method: 'GET', url: '/v1/userwatchlist', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`watchlistItems`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","watchlistItems":[{"id":"ID","userId":"ID","addedAt":"Date","productId":"ID","listId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Do Userwatchlist](businessApi/userwatchlist). ### List Usercartitems API *API Definition* : list all cart items adde by user *API Crud Type* : list *Default access route* : *GET* `/v1/usercartitems` The listUserCartItems api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/usercartitems** ```js axios({ method: 'GET', url: '/v1/usercartitems', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`cartItems`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"cartItems","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","cartItems":[{"id":"ID","addedAt":"Date","userId":"ID","quantity":"Integer","productId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID","product":[{"currency":"String","description":"Text","condition":"Enum","condition_idx":"Integer","endPrice":"Double","price":"Double","title":"String","startPrice":"Double","type":"Enum","type_idx":"Integer","shipping":"Double"},{},{}]},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For List Usercartitems](businessApi/listUserCartItems). ### Do Userwatchlistlists API *API Definition* : list all watch lists created by user *API Crud Type* : list *Default access route* : *GET* `/v1/userwatchlistlists` The userwatchlistlists api has got no parameters. To access the api you can use the **REST** controller with the path **GET /v1/userwatchlistlists** ```js axios({ method: 'GET', url: '/v1/userwatchlistlists', data: { }, params: { } }); ``` The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`watchlistLists`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json {"status":"OK","statusCode":"200","elapsedMs":126,"ssoTime":120,"source":"db","cacheKey":"hexCode","userId":"ID","sessionId":"ID","requestId":"ID","dataName":"watchlistLists","method":"GET","action":"list","appVersion":"Version","rowCount":"\"Number\"","watchlistLists":[{"id":"ID","name":"String","itemCount":"Integer","userId":"ID","isActive":true,"recordVersion":"Integer","createdAt":"Date","updatedAt":"Date","_owner":"ID"},{},{}],"paging":{"pageNumber":"Number","pageRowCount":"NUmber","totalRowCount":"Number","pageCount":"Number"},"filters":[],"uiPermissions":[]} ``` > For a detailed description of the `` api with its internal and inter-service logic please refer to the [Business API Specification Document For Do Userwatchlistlists](businessApi/userwatchlistlists). ### Authentication Specific Routes ### Common Routes ### Route: currentuser *Route Definition*: Retrieves the currently authenticated user's session information. *Route Type*: sessionInfo *Access Route*: `GET /currentuser` #### Parameters This route does **not** require any request parameters. #### Behavior - Returns the authenticated session object associated with the current access token. - If no valid session exists, responds with a 401 Unauthorized. ```js // Sample GET /currentuser call axios.get("/currentuser", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** Returns the session object, including user-related data and token information. ``` { "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9", "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "email": "user@example.com", "fullname": "John Doe", "roleId": "user", "tenantId": "abc123", "accessToken": "jwt-token-string", ... } ``` **Error Response** **401 Unauthorized:** No active session found. ``` { "status": "ERR", "message": "No login found" } ``` **Notes** * This route is typically used by frontend or mobile applications to fetch the current session state after login. * The returned session includes key user identity fields, tenant information (if applicable), and the access token for further authenticated requests. * Always ensure a valid access token is provided in the request to retrieve the session. ### Route: permissions `*Route Definition*`: Retrieves all effective permission records assigned to the currently authenticated user. `*Route Type*`: permissionFetch *Access Route*: `GET /permissions` #### Parameters This route does **not** require any request parameters. #### Behavior - Fetches all active permission records (`givenPermissions` entries) associated with the current user session. - Returns a full array of permission objects. - Requires a valid session (`access token`) to be available. ```js // Sample GET /permissions call axios.get("/permissions", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** Returns an array of permission objects. ```json [ { "id": "perm1", "permissionName": "adminPanel.access", "roleId": "admin", "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" }, { "id": "perm2", "permissionName": "orders.manage", "roleId": null, "subjectUserId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38", "subjectUserGroupId": null, "objectId": null, "canDo": true, "tenantCodename": "store123" } ] ``` Each object reflects a single permission grant, aligned with the givenPermissions model: - `**permissionName**`: The permission the user has. - `**roleId**`: If the permission was granted through a role. -` **subjectUserId**`: If directly granted to the user. - `**subjectUserGroupId**`: If granted through a group. - `**objectId**`: If tied to a specific object (OBAC). - `**canDo**`: True or false flag to represent if permission is active or restricted. **Error Responses** * **401 Unauthorized**: No active session found. ```json { "status": "ERR", "message": "No login found" } ``` * **500 Internal Server Error**: Unexpected error fetching permissions. **Notes** * The /permissions route is available across all backend services generated by Mindbricks, not just the auth service. * Auth service: Fetches permissions freshly from the live database (givenPermissions table). * Other services: Typically use a cached or projected view of permissions stored in a common ElasticSearch store, optimized for faster authorization checks. > **Tip**: > Applications can cache permission results client-side or server-side, but should occasionally refresh by calling this endpoint, especially after login or permission-changing operations. ### Route: permissions/:permissionName *Route Definition*: Checks whether the current user has access to a specific permission, and provides a list of scoped object exceptions or inclusions. *Route Type*: permissionScopeCheck *Access Route*: `GET /permissions/:permissionName` #### Parameters | Parameter | Type | Required | Population | |------------------|--------|----------|------------------------| | permissionName | String | Yes | `request.params.permissionName` | #### Behavior - Evaluates whether the current user **has access** to the given `permissionName`. - Returns a structured object indicating: - Whether the permission is generally granted (`canDo`) - Which object IDs are explicitly included or excluded from access (`exceptions`) - Requires a valid session (`access token`). ```js // Sample GET /permissions/orders.manage axios.get("/permissions/orders.manage", { headers: { "Authorization": "Bearer your-jwt-token" } }); ``` **Success Response** ```json { "canDo": true, "exceptions": [ "a1f2e3d4-xxxx-yyyy-zzzz-object1", "b2c3d4e5-xxxx-yyyy-zzzz-object2" ] } ``` * If `canDo` is `true`, the user generally has the permission, but not for the objects listed in `exceptions` (i.e., restrictions). * If `canDo` is `false`, the user does not have the permission by default — but only for the objects in `exceptions`, they do have permission (i.e., selective overrides). * The exceptions array contains valid **UUID strings**, each corresponding to an object ID (typically from the data model targeted by the permission). ## Copyright All sources, documents and other digital materials are copyright of . ## About Us For more information please visit our website: . . . # Service Design Specification **ebaycclone-watchlistcart-service** documentation -Version:**`1.0.22`** ## Scope This document provides a structured architectural overview of the `watchlistCart` microservice, detailing its configuration, data model, authorization logic, business rules, and API design. It has been automatically generated based on the service definition within Mindbricks, ensuring that the information reflects the source of truth used during code generation and deployment. The document is intended to serve multiple audiences: * **Service architects** can use it to validate design decisions and ensure alignment with broader architectural goals. * **Developers and maintainers** will find it useful for understanding the structure and behavior of the service, facilitating easier debugging, feature extension, and integration with other systems. * **Stakeholders and reviewers** can use it to gain a clear understanding of the service's capabilities and domain logic. > **Note for Frontend Developers**: While this document is valuable for understanding business logic and data interactions, please refer to the [Service API Documentation](#) for endpoint-level specifications and integration details. > **Note for Backend Developers**: Since the code for this service is automatically generated by Mindbricks, you typically won't need to implement or modify it manually. However, this document is especially valuable when you're building other services—whether within Mindbricks or externally—that need to interact with or depend on this service. It provides a clear reference to the service's data contracts, business rules, and API structure, helping ensure compatibility and correct integration. ## `WatchlistCart` Service Settings [**Edit**](watchlistcart/serviceSettings) Handles user watchlists (with custom folders) and shopping cart preparation for checkout, strictly enforcing only fixed-price products in carts, supporting item moves/bulk operations, and robust default/folder logic.. ### Service Overview This service is configured to listen for HTTP requests on port `3003`, serving both the main API interface and default administrative endpoints. The following routes are available by default: * **API Test Interface (API Face):** `/` * **Swagger Documentation:** `/swagger` * **Postman Collection Download:** `/getPostmanCollection` * **Health Checks:** `/health` and `/admin/health` * **Current Session Info:** `/currentuser` * **Favicon:** `/favicon.ico` The service uses a **PostgreSQL** database for data storage, with the database name set to `ebaycclone-watchlistcart-service`. This service is accessible via the following environment-specific URLs: * **Preview:** `https://ebaycclone.prw.mindbricks.com/watchlistcart-api` * **Staging:** `https://ebaycclone-stage.mindbricks.co/watchlistcart-api` * **Production:** `https://ebaycclone.mindbricks.co/watchlistcart-api` ### Authentication & Security - **Login Required**: Yes This service requires user authentication for access. It supports both JWT and RSA-based authentication mechanisms, ensuring secure user sessions and data integrity. If a crud route also is configured to require login, it will check a valid JWT token in the request query/header/bearer/cookie. If the token is valid, it will extract the user information from the token and make the fetched session data available in the request context. ### Service Data Objects The service uses a **PostgreSQL** database for data storage, with the database name set to `ebaycclone-watchlistcart-service`. Data deletion is managed using a **soft delete** strategy. Instead of removing records from the database, they are flagged as inactive by setting the `isActive` field to `false`. | Object Name | Description | Public Access | |-------------|-------------|---------------| | `watchlistItem` | Item in a user’s watchlist, optionally in a named folder; references product and user. | accessPrivate | | `cartItem` | Single product pending checkout in a user’s cart. Only fixed-price products permitted; quantity supported for multi-unit purchases (if allowed). | accessPrivate | | `watchlistList` | A named folder/list in a user’s watchlist. Default list exists for all users. Custom lists may be created and deleted. | accessPrivate | ## watchlistItem Data Object ### Object Overview **Description:** Item in a user’s watchlist, optionally in a named folder; references product and user. This object represents a core data structure within the service and acts as the blueprint for database interaction, API generation, and business logic enforcement. It is defined using the `ObjectSettings` pattern, which governs its behavior, access control, caching strategy, and integration points with other systems such as Stripe and Redis. ### Core Configuration - **Soft Delete:** Enabled — Determines whether records are marked inactive (`isActive = false`) instead of being physically deleted. - **Public Access:** accessPrivate — If enabled, anonymous users may access this object’s data depending on API-level rules. ### Composite Indexes - **uniqueWatchlistPerUserProductList**: [userId, productId, listId] This composite index is defined to optimize query performance for complex queries involving multiple fields. The index also defines a conflict resolution strategy for duplicate key violations. When a new record would violate this composite index, the following action will be taken: **On Duplicate**: `throwError` An error will be thrown, preventing the insertion of conflicting data. ### Properties Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `userId` | ID | Yes | Owner of the watchlist item. | | `addedAt` | Date | Yes | Timestamp watchlist item created. | | `productId` | ID | Yes | Referenced product in the watchlist. | | `listId` | ID | No | Owning watchlistList; null if in default watchlist. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value is set. ### Default Values Default values are automatically assigned to properties when a new object is created, if no value is provided in the request body. Since default values are applied on db level, they should be literal values, not expressions.If you want to use expressions, you can use transposed parameters in any business API to set default values dynamically. - **userId**: '00000000-0000-0000-0000-000000000000' - **addedAt**: new Date() - **productId**: '00000000-0000-0000-0000-000000000000' ### Constant Properties `userId` `addedAt` `productId` Constant properties are defined to be immutable after creation, meaning they cannot be updated or changed once set. They are typically used for properties that should remain constant throughout the object's lifecycle. A property is set to be constant if the `Allow Update` option is set to `false`. ### Auto Update Properties `userId` `addedAt` `productId` `listId` An update crud API created with the option `Auto Params` enabled will automatically update these properties with the provided values in the request body. If you want to update any property in your own business logic not by user input, you can set the `Allow Auto Update` option to false. These properties will be added to the update API's body parameters and can be updated by the user if any value is provided in the request body. ### Database Indexing `userId` `productId` `listId` Properties that are indexed in the database will be optimized for query performance, allowing for faster data retrieval. Make a property indexed in the database if you want to use it frequently in query filters or sorting. ### Relation Properties `userId` `productId` `listId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. You can define relations in the data object properties, which will be used to create foreign key constraints in the database. For complex joins operations, Mindbricks supportsa BFF pattern, where you can view dynamic and static views based on Elastic Search Indexes. Use db level relations for simple one-to-one or one-to-many relationships, and use BFF views for complex joins that require multiple data objects to be joined together. - **userId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes - **productId**: ID Relation to `productListingProduct`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes - **listId**: ID Relation to `watchlistList`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: No ### Session Data Properties `userId` Session data properties are used to store data that is specific to the user session, allowing for personalized experiences and temporary data storage. If a property is configured as session data, it will be automatically mapped to the related field in the user session during CRUD operations. Note that session data properties can not be mutated by the user, but only by the system. - **userId**: ID property will be mapped to the session parameter `userId`. This property is also used to store the owner of the session data, allowing for ownership checks and access control. ## cartItem Data Object ### Object Overview **Description:** Single product pending checkout in a user’s cart. Only fixed-price products permitted; quantity supported for multi-unit purchases (if allowed). This object represents a core data structure within the service and acts as the blueprint for database interaction, API generation, and business logic enforcement. It is defined using the `ObjectSettings` pattern, which governs its behavior, access control, caching strategy, and integration points with other systems such as Stripe and Redis. ### Core Configuration - **Soft Delete:** Enabled — Determines whether records are marked inactive (`isActive = false`) instead of being physically deleted. - **Public Access:** accessPrivate — If enabled, anonymous users may access this object’s data depending on API-level rules. ### Composite Indexes - **uniqueCartPerUserProduct**: [userId, productId] This composite index is defined to optimize query performance for complex queries involving multiple fields. The index also defines a conflict resolution strategy for duplicate key violations. When a new record would violate this composite index, the following action will be taken: **On Duplicate**: `throwError` An error will be thrown, preventing the insertion of conflicting data. ### Properties Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `addedAt` | Date | Yes | Timestamp added to cart. | | `userId` | ID | Yes | Cart owner. | | `quantity` | Integer | Yes | How many units (if product allows). | | `productId` | ID | Yes | Product being checked out. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value is set. ### Default Values Default values are automatically assigned to properties when a new object is created, if no value is provided in the request body. Since default values are applied on db level, they should be literal values, not expressions.If you want to use expressions, you can use transposed parameters in any business API to set default values dynamically. - **addedAt**: new Date() - **userId**: '00000000-0000-0000-0000-000000000000' - **quantity**: 1 - **productId**: '00000000-0000-0000-0000-000000000000' ### Constant Properties `addedAt` `userId` `productId` Constant properties are defined to be immutable after creation, meaning they cannot be updated or changed once set. They are typically used for properties that should remain constant throughout the object's lifecycle. A property is set to be constant if the `Allow Update` option is set to `false`. ### Auto Update Properties `addedAt` `userId` `quantity` `productId` An update crud API created with the option `Auto Params` enabled will automatically update these properties with the provided values in the request body. If you want to update any property in your own business logic not by user input, you can set the `Allow Auto Update` option to false. These properties will be added to the update API's body parameters and can be updated by the user if any value is provided in the request body. ### Database Indexing `userId` `productId` Properties that are indexed in the database will be optimized for query performance, allowing for faster data retrieval. Make a property indexed in the database if you want to use it frequently in query filters or sorting. ### Relation Properties `userId` `productId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. You can define relations in the data object properties, which will be used to create foreign key constraints in the database. For complex joins operations, Mindbricks supportsa BFF pattern, where you can view dynamic and static views based on Elastic Search Indexes. Use db level relations for simple one-to-one or one-to-many relationships, and use BFF views for complex joins that require multiple data objects to be joined together. - **userId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes - **productId**: ID Relation to `productListingProduct`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes ### Session Data Properties `userId` Session data properties are used to store data that is specific to the user session, allowing for personalized experiences and temporary data storage. If a property is configured as session data, it will be automatically mapped to the related field in the user session during CRUD operations. Note that session data properties can not be mutated by the user, but only by the system. - **userId**: ID property will be mapped to the session parameter `userId`. This property is also used to store the owner of the session data, allowing for ownership checks and access control. ## watchlistList Data Object ### Object Overview **Description:** A named folder/list in a user’s watchlist. Default list exists for all users. Custom lists may be created and deleted. This object represents a core data structure within the service and acts as the blueprint for database interaction, API generation, and business logic enforcement. It is defined using the `ObjectSettings` pattern, which governs its behavior, access control, caching strategy, and integration points with other systems such as Stripe and Redis. ### Core Configuration - **Soft Delete:** Enabled — Determines whether records are marked inactive (`isActive = false`) instead of being physically deleted. - **Public Access:** accessPrivate — If enabled, anonymous users may access this object’s data depending on API-level rules. ### Composite Indexes - **uniqueWatchlistListPerUserAndName**: [userId, name] This composite index is defined to optimize query performance for complex queries involving multiple fields. The index also defines a conflict resolution strategy for duplicate key violations. When a new record would violate this composite index, the following action will be taken: **On Duplicate**: `throwError` An error will be thrown, preventing the insertion of conflicting data. ### Properties Schema | Property | Type | Required | Description | |----------|------|----------|-------------| | `name` | String | Yes | Custom folder or list name. 'Default' is reserved (non-deletable for each user). | | `itemCount` | Integer | Yes | Number of (non-deleted) items in the list/folder. | | `userId` | ID | Yes | Owner of the watchlist list/folder. | * Required properties are mandatory for creating objects and must be provided in the request body if no default value is set. ### Default Values Default values are automatically assigned to properties when a new object is created, if no value is provided in the request body. Since default values are applied on db level, they should be literal values, not expressions.If you want to use expressions, you can use transposed parameters in any business API to set default values dynamically. - **name**: 'default' - **userId**: '00000000-0000-0000-0000-000000000000' ### Always Create with Default Values Some of the default values are set to be always used when creating a new object, even if the property value is provided in the request body. It ensures that the property is always initialized with a default value when the object is created. - **itemCount**: Will be created with value `0` ### Constant Properties `itemCount` `userId` Constant properties are defined to be immutable after creation, meaning they cannot be updated or changed once set. They are typically used for properties that should remain constant throughout the object's lifecycle. A property is set to be constant if the `Allow Update` option is set to `false`. ### Auto Update Properties `name` `itemCount` `userId` An update crud API created with the option `Auto Params` enabled will automatically update these properties with the provided values in the request body. If you want to update any property in your own business logic not by user input, you can set the `Allow Auto Update` option to false. These properties will be added to the update API's body parameters and can be updated by the user if any value is provided in the request body. ### Elastic Search Indexing `name` Properties that are indexed in Elastic Search will be searchable via the Elastic Search API. While all properties are stored in the elastic search index of the data object, only those marked for Elastic Search indexing will be available for search queries. ### Database Indexing `name` `userId` Properties that are indexed in the database will be optimized for query performance, allowing for faster data retrieval. Make a property indexed in the database if you want to use it frequently in query filters or sorting. ### Relation Properties `userId` Mindbricks supports relations between data objects, allowing you to define how objects are linked together. You can define relations in the data object properties, which will be used to create foreign key constraints in the database. For complex joins operations, Mindbricks supportsa BFF pattern, where you can view dynamic and static views based on Elastic Search Indexes. Use db level relations for simple one-to-one or one-to-many relationships, and use BFF views for complex joins that require multiple data objects to be joined together. - **userId**: ID Relation to `user`.id The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object. On Delete: Set Null Required: Yes ### Session Data Properties `userId` Session data properties are used to store data that is specific to the user session, allowing for personalized experiences and temporary data storage. If a property is configured as session data, it will be automatically mapped to the related field in the user session during CRUD operations. Note that session data properties can not be mutated by the user, but only by the system. - **userId**: ID property will be mapped to the session parameter `userId`. This property is also used to store the owner of the session data, allowing for ownership checks and access control. ### Filter Properties `name` Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's that have "Auto Params" enabled. - **name**: String has a filter named `name` ## Business Logic watchlistCart has got 13 Business APIs to manage its internal and crud logic. For the details of each business API refer to its chapter. * [List Watchlistlist](/businessLogic/listwatchlistlist) * [List Cartitems](/businessLogic/listcartitems) * [Delete Cartitem](/businessLogic/deletecartitem) * [Create Watchlistitem](/businessLogic/createwatchlistitem) * [List Watchlistitems](/businessLogic/listwatchlistitems) * [Update Cartitemquantity](/businessLogic/updatecartitemquantity) * [Create Watchlistlist](/businessLogic/createwatchlistlist) * [Delete Watchlistlist](/businessLogic/deletewatchlistlist) * [Delete Watchlistitem](/businessLogic/deletewatchlistitem) * [Create Cartitem](/businessLogic/createcartitem) * [Do Userwatchlist](/businessLogic/userwatchlist) * [List Usercartitems](/businessLogic/listusercartitems) * [Do Userwatchlistlists](/businessLogic/userwatchlistlists) ## Edge Controllers No edge controllers defined for this service. --- ## Service Library ### Functions #### validateReservedDefaultListName.js ```js module.exports = function() { return this.name.trim().toLowerCase() !== 'default'; } ``` ### Hook Functions No hook functions defined. ### Edge Functions No edge functions defined. ### Templates No templates defined. ### Assets No assets defined. ### Public Assets No public assets defined. --- ### Event Emission --- ## Integration Patterns ## Deployment Considerations ### Environment Configuration - **HTTP Port**: `3003` - **Database Type**: MongoDB - **Global Soft Delete**: Enabled ## Implementation Guidelines ### Development Workflow 1. **Data Model Implementation**: Generate database schema from data object definitions 2. **CRUD Route Generation**: Implement auto-generated routes with custom logic 3. **Custom Logic Integration**: Implement hook functions and edge functions 4. **Authentication Integration**: Configure with project-level authentication 5. **Testing**: Unit and integration testing for all components ### Code Generation Expectations - **Database Schema**: Auto-generated from data objects and relationships - **API Routes**: REST endpoints with customizable behavior - **Validation Logic**: Input validation from property definitions - **Access Control**: Authentication and authorization middleware ### Custom Code Integration Points - **Hook Functions**: Lifecycle-specific custom logic - **Edge Functions**: Full request/response control - **Library Functions**: Reusable business logic - **Templates**: Dynamic content rendering ### Testing Strategy #### Unit Testing - Test all custom library functions - Test validation logic and business rules - Test hook function implementations #### Integration Testing - Test API endpoints with authentication scenarios - Test database operations and transactions - Test external integrations - Test event emission and Kafka integration #### Performance Testing - Load test high-traffic endpoints - Test caching effectiveness - Monitor database query performance - Test scalability under load --- ## Appendices ### Data Type Reference | Type | Description | Storage | |------|-------------|---------| | ID | Unique identifier | UUID (SQL) / ObjectID (NoSQL) | | String | Short text (≤255 chars) | VARCHAR | | Text | Long-form text | TEXT | | Integer | 32-bit whole numbers | INT | | Boolean | True/false values | BOOLEAN | | Double | 64-bit floating point | DOUBLE | | Float | 32-bit floating point | FLOAT | | Short | 16-bit integers | SMALLINT | | Object | JSON object | JSONB (PostgreSQL) / Object (MongoDB) | | Date | ISO 8601 timestamp | TIMESTAMP | | Enum | Fixed numeric values | SMALLINT with lookup | ### Enum Value Mappings #### Request Locations - `0`: Bearer token in Authorization header - `1`: Cookie value - `2`: Custom HTTP header - `3`: Query parameter - `4`: Request body property - `5`: URL path parameter - `6`: Session data - `7`: Root request object #### HTTP Methods - `0`: GET - `1`: POST - `2`: PUT - `3`: PATCH - `4`: DELETE ### Edge Function Signature ```javascript async function edgeFunction(request) { // Custom request processing // Return response object or throw error return { data: {}, status: 200, message: "Success" }; } ``` --- *This document was generated from the service architecture definition and should be kept in sync with implementation changes.* # Business API Design Specification - `Create Moderationaction` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `createModerationAction` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `createModerationAction` Business API is designed to handle a `create` operation on the `ModerationAction` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Logs an admin moderation or override action in the system for audit and traceability. Requires admin login, takes context from session, and creates an audit entry for any admin operation over any entity type. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `moderationaction-created` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `createModerationAction` Business API includes a REST controller that can be triggered via the following route: `/v1/moderationactions` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `createModerationAction` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `createModerationAction` Business API has 7 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `moderationActionId` | `ID` | `No` | `-` | `body` | `moderationActionId` | | **Description:** | This id paremeter is used to create the data object with a given specific id. Leave null for automatic id. | | | | | | | | | | | | | `adminId` | `ID` | `Yes` | `-` | `session` | `userId` | | **Description:** | ID of admin performing moderation action. | | | | | | | | | | | | | `entityId` | `ID` | `Yes` | `-` | `body` | `entityId` | | **Description:** | ID of target entity affected by moderation (user/product/etc). | | | | | | | | | | | | | `actionTimestamp` | `Date` | `Yes` | `-` | `body` | `actionTimestamp` | | **Description:** | Timestamp moderation action was performed/logged. | | | | | | | | | | | | | `entityType` | `Enum` | `Yes` | `-` | `body` | `entityType` | | **Description:** | Type of entity affected (USER, PRODUCT, FEEDBACK, MEDIA, CATEGORY, NOTIFICATION, ORDER, SEARCHINDEX). | | | | | | | | | | | | | `reason` | `String` | `Yes` | `-` | `body` | `reason` | | **Description:** | Explanation or justification for the moderation action performed. | | | | | | | | | | | | | `actionType` | `Enum` | `Yes` | `-` | `body` | `actionType` | | **Description:** | Type of moderation action (e.g., SOFT_DELETE, RESTORE, UPDATE_ROLE, MANUAL_CORRECTION, MEDIA_FLAG, INDEX_REBUILD, PAYMENT_FIX, FEEDBACK_OVERRIDE, ADMIN_NOTE). | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `createModerationAction` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { id: this.moderationActionId, adminId: this.adminId, entityId: this.entityId, actionTimestamp: this.actionTimestamp, entityType: this.entityType, reason: this.reason, actionType: this.actionType, isActive: true, _archivedAt: null, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, populates session and request objects, prepares internal structures for parameter handling and workflow execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads input parameters, normalizes missing values, applies default type casting, and stores them in the API context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager transforms parameters, computes derived values, flattens or remaps arrays/objects, and adjusts formats for downstream processing. --- ### [4] Step : checkParameters Manager executes built-in validations: required field checks, type enforcement, and basic business rules. Prevents operation if validation fails. --- ### [5] Step : checkBasicAuth Manager performs authentication and authorization checks: verifies session, user roles, permissions, and tenant restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildDataClause Manager constructs the final data object for creation, fills auto-generated fields (IDs, timestamps, owner fields), and ensures schema consistency. You can use the following settings to change some behavior of this step. `dataClause` --- ### [7] Step : mainCreateOperation Manager executes the database insert operation, updates indexes/caches, and triggers internal post-processing like linked default records. --- ### [8] Step : buildOutput Manager shapes the response: masks sensitive fields, resolves linked references, and formats output according to API contract. --- ### [9] Step : sendResponse Manager sends the response to the client and finalizes internal tasks like flushing logs or updating session state. --- ### [10] Step : raiseApiEvent Manager triggers API-level events (Kafka, WebSocket, async workflows) as the final internal step. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `createModerationAction` api has got 4 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | entityId | ID | true | request.body?.entityId | | entityType | Enum | true | request.body?.entityType | | reason | String | true | request.body?.reason | | actionType | Enum | true | request.body?.actionType | ### REST Request To access the api you can use the **REST** controller with the path **POST /v1/moderationactions** ```js axios({ method: 'POST', url: '/v1/moderationactions', data: { entityId:"ID", entityType:"Enum", reason:"String", actionType:"Enum", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`moderationAction`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Delete Moderationaction` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `deleteModerationAction` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `deleteModerationAction` Business API is designed to handle a `delete` operation on the `ModerationAction` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Soft-deletes a moderation action log record (dangerous; allowed only to superadmins or strict manual correction), primarily for audit correction or internal error cleanup. Usually, moderation logs are immutable. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `moderationaction-deleted` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `deleteModerationAction` Business API includes a REST controller that can be triggered via the following route: `/v1/moderationactions/:moderationActionId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `deleteModerationAction` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `deleteModerationAction` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `moderationActionId` | `ID` | `Yes` | `-` | `urlpath` | `moderationActionId` | | **Description:** | This id paremeter is used to select the required data object that will be deleted | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `deleteModerationAction` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.moderationActionId},{isActive:true}]} ``` ## Delete Options Use these options to set `delete` specific settings. **useSoftDelete**: false If true, the record will be marked as deleted `(isActive: false)` instead of removed. The implementation depends on the data object’s soft delete configuration. ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request/session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads and normalizes parameters, applies defaults, and stores them in the context for downstream steps. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts, computes derived values, and remaps objects or arrays as needed for later processing. --- ### [4] Step : checkParameters Manager runs built-in validations including required field checks, type enforcement, and deletion preconditions. Stops execution if validation fails. --- ### [5] Step : checkBasicAuth Manager validates session, user roles, permissions, and tenant-specific access rules to enforce basic auth restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager generates the query conditions, applies ownership and parent checks, and ensures the clause is correct for the delete operation. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the target record, applies filters from WHERE clause, and writes the instance to the context for further checks. --- ### [8] Step : checkInstance Manager performs object-level validations such as lock status, soft-delete eligibility, and multi-step approval enforcement. --- ### [9] Step : mainDeleteOperation Manager executes the delete query, updates related indexes/caches, and handles soft/hard delete logic according to configuration. You can use the following settings to change some behavior of this step. `deleteOptions` --- ### [10] Step : buildOutput Manager shapes the response payload, masks sensitive fields, and formats related cleanup results for output. --- ### [11] Step : sendResponse Manager delivers the response to the client and finalizes any temporary internal structures. --- ### [12] Step : raiseApiEvent Manager triggers asynchronous API events, notifies queues or streams, and performs final cleanup for the workflow. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `deleteModerationAction` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | ### REST Request To access the api you can use the **REST** controller with the path **DELETE /v1/moderationactions/:moderationActionId** ```js axios({ method: 'DELETE', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`moderationAction`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Get Moderationaction` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `getModerationAction` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `getModerationAction` Business API is designed to handle a `get` operation on the `ModerationAction` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Get a single moderation action log by ID. Used to review admin audit trails; accessible only to platform admins. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `moderationaction-retrived` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `getModerationAction` Business API includes a REST controller that can be triggered via the following route: `/v1/moderationactions/:moderationActionId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `getModerationAction` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `getModerationAction` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `moderationActionId` | `ID` | `Yes` | `-` | `urlpath` | `moderationActionId` | | **Description:** | This id paremeter is used to query the required data object. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `getModerationAction` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.moderationActionId},{isActive:true}]} ``` ## Get Options Use these options to set `get` specific settings. **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Extracts parameters from request and Redis, applies defaults, and writes them to context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Executes parameter transformation scripts, applies type coercion, merges derived values, and reshapes inputs for downstream milestones. --- ### [4] Step : checkParameters Validates required and custom parameters, enforcing business-specific rules and constraints. --- ### [5] Step : checkBasicAuth Performs login, role, and permission checks, and applies dynamic object-level access rules. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Builds the WHERE clause for fetching the object and applies additional scoped filters if configured. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainGetOperation Executes the database fetch, retrieves the object, and stores it in context for enrichment or further checks. You can use the following settings to change some behavior of this step. `selectClause`, `getOptions` --- ### [8] Step : checkInstance Performs instance-level validations, such as ownership, existence, or access conditions. --- ### [9] Step : buildOutput Assembles the response from the object, applies masking, formatting, and injects additional metadata if needed. --- ### [10] Step : sendResponse Delivers the response to the controller for client delivery. --- ### [11] Step : raiseApiEvent Triggers optional API-level events after workflow completion, sending messages to integrations like Kafka if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `getModerationAction` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/moderationactions/:moderationActionId** ```js axios({ method: 'GET', url: `/v1/moderationactions/${moderationActionId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`moderationAction`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `List Moderationactions` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `listModerationActions` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `listModerationActions` Business API is designed to handle a `list` operation on the `ModerationAction` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description List moderation actions for admin dashboard/audit search. Supports filtering by admin, entityType, entityId, actionType, and date. Always sorted by most recent action. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `moderationactions-listed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `listModerationActions` Business API includes a REST controller that can be triggered via the following route: `/v1/moderationactions` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `listModerationActions` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `listModerationActions` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `listModerationActions` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {isActive:true} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `listModerationActions` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/moderationactions** ```js axios({ method: 'GET', url: '/v1/moderationactions', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`moderationActions`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationActions", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "moderationActions": [ { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `Update Moderationaction` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `updateModerationAction` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `updateModerationAction` Business API is designed to handle a `update` operation on the `ModerationAction` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Allows update of explanation/note on a moderation action for correction (typically by admin or superadmin only). No entity/type/admin may be changed after creation; only 'reason' is editable for audit consistency. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `moderationaction-updated` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `updateModerationAction` Business API includes a REST controller that can be triggered via the following route: `/v1/moderationactions/:moderationActionId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `updateModerationAction` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `updateModerationAction` Business API has 2 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `moderationActionId` | `ID` | `Yes` | `-` | `urlpath` | `moderationActionId` | | **Description:** | This id paremeter is used to select the required data object that will be updated | | | | | | | | | | | | | `reason` | `String` | `No` | `-` | `body` | `reason` | | **Description:** | Explanation or justification for the moderation action performed. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `updateModerationAction` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.moderationActionId},{isActive:true}]} ``` ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. An update data clause populates all update-allowed properties of a data object, however the null properties (that are not provided by client) are ignored in db layer. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { reason: this.reason, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request and session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads parameters from the request or Redis, applies defaults, and writes them into context for downstream milestones. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts and derives any helper values or reshaped payloads into the context. --- ### [4] Step : checkParameters Manager validates required parameters, checks ID formats (UUID/ObjectId), and ensures all preconditions for update are met. --- ### [5] Step : checkBasicAuth Manager performs login verification, role, and permission checks, enforcing tenant and access rules before update. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager constructs the WHERE clause used to identify the record to update, applying ownership and parent checks if necessary. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the existing record from the database and writes it to the context for validation or enrichment. --- ### [8] Step : checkInstance Manager performs instance-level validations, including ownership, existence, lock status, or other pre-update checks. --- ### [9] Step : buildDataClause Manager prepares the data clause for the update, applying transformations or enhancements before persisting. You can use the following settings to change some behavior of this step. `dataClause` --- ### [10] Step : mainUpdateOperation Manager executes the update operation with the WHERE and data clauses. Database-level events are raised if configured. --- ### [11] Step : buildOutput Manager assembles the response object from the update result, masking fields or injecting additional metadata. --- ### [12] Step : sendResponse Manager sends the response back to the controller for delivery to the client. --- ### [13] Step : raiseApiEvent Manager triggers API-level events, sending relevant messages to Kafka or other integrations if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `updateModerationAction` api has got 2 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | moderationActionId | ID | true | request.params?.moderationActionId | | reason | String | false | request.body?.reason | ### REST Request To access the api you can use the **REST** controller with the path **PATCH /v1/moderationactions/:moderationActionId** ```js axios({ method: 'PATCH', url: `/v1/moderationactions/${moderationActionId}`, data: { reason:"String", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`moderationAction`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "moderationAction", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "moderationAction": { "id": "ID", "adminId": "ID", "entityId": "ID", "actionTimestamp": "Date", "entityType": "Enum", "entityType_idx": "Integer", "reason": "String", "actionType": "Enum", "actionType_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Create Auctionofferbid` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `createAuctionOfferBid` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `createAuctionOfferBid` Business API is designed to handle a `create` operation on the `AuctionOfferBid` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Creates a new bid for an auction product. Validates auction status, not seller, product type, bid window, and ensures min. increment. Updates product.currentBid and product.highestBidderId atomically. Triggers notification event. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `auctionofferbid-created` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `createAuctionOfferBid` Business API includes a REST controller that can be triggered via the following route: `/v1/auctionofferbids` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `createAuctionOfferBid` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `createAuctionOfferBid` Business API has 7 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `auctionOfferBidId` | `ID` | `No` | `-` | `body` | `auctionOfferBidId` | | **Description:** | This id paremeter is used to create the data object with a given specific id. Leave null for automatic id. | | | | | | | | | | | | | `userId` | `ID` | `Yes` | `-` | `session` | `userId` | | **Description:** | User placing the bid. | | | | | | | | | | | | | `bidAmount` | `Double` | `Yes` | `-` | `body` | `bidAmount` | | **Description:** | Bid amount placed by the user. | | | | | | | | | | | | | `placedAt` | `Date` | `No` | `-` | `body` | `placedAt` | | **Description:** | When the bid was placed. | | | | | | | | | | | | | `currency` | `String` | `Yes` | `-` | `body` | `currency` | | **Description:** | ISO currency for the bid (e.g., USD, EUR). | | | | | | | | | | | | | `status` | `Enum` | `Yes` | `-` | `body` | `status` | | **Description:** | Bid status: ACTIVE, WON, LOST, CANCELLED. | | | | | | | | | | | | | `productId` | `ID` | `Yes` | `-` | `body` | `productId` | | **Description:** | Product being bid on (must be AUCTION type). | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `createAuctionOfferBid` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { id: this.auctionOfferBidId, userId: this.userId, bidAmount: this.bidAmount, placedAt: this.placedAt, currency: this.currency, status: this.status, productId: this.productId, isActive: true, _archivedAt: null, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, populates session and request objects, prepares internal structures for parameter handling and workflow execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads input parameters, normalizes missing values, applies default type casting, and stores them in the API context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager transforms parameters, computes derived values, flattens or remaps arrays/objects, and adjusts formats for downstream processing. --- ### [4] Step : checkParameters Manager executes built-in validations: required field checks, type enforcement, and basic business rules. Prevents operation if validation fails. --- ### [5] Step : checkBasicAuth Manager performs authentication and authorization checks: verifies session, user roles, permissions, and tenant restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildDataClause Manager constructs the final data object for creation, fills auto-generated fields (IDs, timestamps, owner fields), and ensures schema consistency. You can use the following settings to change some behavior of this step. `dataClause` --- ### [7] Step : mainCreateOperation Manager executes the database insert operation, updates indexes/caches, and triggers internal post-processing like linked default records. --- ### [8] Step : buildOutput Manager shapes the response: masks sensitive fields, resolves linked references, and formats output according to API contract. --- ### [9] Step : sendResponse Manager sends the response to the client and finalizes internal tasks like flushing logs or updating session state. --- ### [10] Step : raiseApiEvent Manager triggers API-level events (Kafka, WebSocket, async workflows) as the final internal step. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `createAuctionOfferBid` api has got 4 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | bidAmount | Double | true | request.body?.bidAmount | | currency | String | true | request.body?.currency | | status | Enum | true | request.body?.status | | productId | ID | true | request.body?.productId | ### REST Request To access the api you can use the **REST** controller with the path **POST /v1/auctionofferbids** ```js axios({ method: 'POST', url: '/v1/auctionofferbids', data: { bidAmount:"Double", currency:"String", status:"Enum", productId:"ID", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`auctionOfferBid`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Create Auctionofferoffer` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `createAuctionOfferOffer` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `createAuctionOfferOffer` Business API is designed to handle a `create` operation on the `AuctionOfferOffer` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Creates a new offer for a fixed-price product, validating acceptOffers, type, eligibility, and product/seller/buyer active. Defaults to PENDING state. Triggers notification event. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `auctionofferoffer-created` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `createAuctionOfferOffer` Business API includes a REST controller that can be triggered via the following route: `/v1/auctionofferoffers` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `createAuctionOfferOffer` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `createAuctionOfferOffer` Business API has 13 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `auctionOfferOfferId` | `ID` | `No` | `-` | `body` | `auctionOfferOfferId` | | **Description:** | This id paremeter is used to create the data object with a given specific id. Leave null for automatic id. | | | | | | | | | | | | | `buyerId` | `ID` | `Yes` | `-` | `session` | `userId` | | **Description:** | Buyer making the offer. | | | | | | | | | | | | | `currency` | `String` | `Yes` | `-` | `body` | `currency` | | **Description:** | ISO currency (e.g., USD, EUR) for the offer. | | | | | | | | | | | | | `productId` | `ID` | `Yes` | `-` | `body` | `productId` | | **Description:** | Product the offer applies to (must be fixed-price, acceptOffers true). | | | | | | | | | | | | | `counterOfferId` | `ID` | `No` | `-` | `body` | `counterOfferId` | | **Description:** | References another offer (counter-offer chain). | | | | | | | | | | | | | `counterMessage` | `String` | `No` | `-` | `body` | `counterMessage` | | **Description:** | Message accompanying seller's counter-offer (optional). | | | | | | | | | | | | | `counterAmount` | `Double` | `No` | `-` | `body` | `counterAmount` | | **Description:** | Counter-offer amount (when offer is COUNTERED). | | | | | | | | | | | | | `offerAmount` | `Double` | `Yes` | `-` | `body` | `offerAmount` | | **Description:** | Primary offer amount from buyer. | | | | | | | | | | | | | `message` | `String` | `No` | `-` | `body` | `message` | | **Description:** | Message/special notes from buyer (optional). | | | | | | | | | | | | | `sellerId` | `ID` | `Yes` | `-` | `body` | `sellerId` | | **Description:** | Seller of the product (recipient of offer; auto-fetched from product). | | | | | | | | | | | | | `status` | `Enum` | `Yes` | `-` | `body` | `status` | | **Description:** | Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). | | | | | | | | | | | | | `expiresAt` | `Date` | `No` | `-` | `body` | `expiresAt` | | **Description:** | When this offer expires (optional). | | | | | | | | | | | | | `respondedAt` | `Date` | `No` | `-` | `body` | `respondedAt` | | **Description:** | When the seller (or buyer, for counter-offer) responded/updated the offer status. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `createAuctionOfferOffer` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { id: this.auctionOfferOfferId, buyerId: this.buyerId, currency: this.currency, productId: this.productId, counterOfferId: this.counterOfferId, counterMessage: this.counterMessage, counterAmount: this.counterAmount, offerAmount: this.offerAmount, message: this.message, // sellerId parameter is a static joined paramater // the value will be read from productListingProduct joint osurce sellerId: null, status: this.status, expiresAt: this.expiresAt, respondedAt: this.respondedAt, isActive: true, _archivedAt: null, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, populates session and request objects, prepares internal structures for parameter handling and workflow execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads input parameters, normalizes missing values, applies default type casting, and stores them in the API context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager transforms parameters, computes derived values, flattens or remaps arrays/objects, and adjusts formats for downstream processing. --- ### [4] Step : checkParameters Manager executes built-in validations: required field checks, type enforcement, and basic business rules. Prevents operation if validation fails. --- ### [5] Step : checkBasicAuth Manager performs authentication and authorization checks: verifies session, user roles, permissions, and tenant restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildDataClause Manager constructs the final data object for creation, fills auto-generated fields (IDs, timestamps, owner fields), and ensures schema consistency. You can use the following settings to change some behavior of this step. `dataClause` --- ### [7] Step : mainCreateOperation Manager executes the database insert operation, updates indexes/caches, and triggers internal post-processing like linked default records. --- ### [8] Step : buildOutput Manager shapes the response: masks sensitive fields, resolves linked references, and formats output according to API contract. --- ### [9] Step : sendResponse Manager sends the response to the client and finalizes internal tasks like flushing logs or updating session state. --- ### [10] Step : raiseApiEvent Manager triggers API-level events (Kafka, WebSocket, async workflows) as the final internal step. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `createAuctionOfferOffer` api has got 10 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | productId | ID | true | request.body?.productId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | offerAmount | Double | true | request.body?.offerAmount | | message | String | false | request.body?.message | | status | Enum | true | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | ### REST Request To access the api you can use the **REST** controller with the path **POST /v1/auctionofferoffers** ```js axios({ method: 'POST', url: '/v1/auctionofferoffers', data: { currency:"String", productId:"ID", counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", offerAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`auctionOfferOffer`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Delete Auctionofferbid` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `deleteAuctionOfferBid` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `deleteAuctionOfferBid` Business API is designed to handle a `delete` operation on the `AuctionOfferBid` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Soft-deletes a bid (for admin or self before auction ends). ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `auctionofferbid-deleted` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `deleteAuctionOfferBid` Business API includes a REST controller that can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `deleteAuctionOfferBid` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `deleteAuctionOfferBid` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `auctionOfferBidId` | `ID` | `Yes` | `-` | `urlpath` | `auctionOfferBidId` | | **Description:** | This id paremeter is used to select the required data object that will be deleted | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `deleteAuctionOfferBid` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks This Business API enforces ownership of the main data object before executing the operation. - The check is performed **after fetching the object instance**. If the current user is not the owner, the API will respond with **403 Forbidden**. Note: Ownership checks are applied **only if the objects have an owner field**. --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.auctionOfferBidId},{isActive:true}]} ``` ## Delete Options Use these options to set `delete` specific settings. **useSoftDelete**: false If true, the record will be marked as deleted `(isActive: false)` instead of removed. The implementation depends on the data object’s soft delete configuration. ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request/session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads and normalizes parameters, applies defaults, and stores them in the context for downstream steps. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts, computes derived values, and remaps objects or arrays as needed for later processing. --- ### [4] Step : checkParameters Manager runs built-in validations including required field checks, type enforcement, and deletion preconditions. Stops execution if validation fails. --- ### [5] Step : checkBasicAuth Manager validates session, user roles, permissions, and tenant-specific access rules to enforce basic auth restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager generates the query conditions, applies ownership and parent checks, and ensures the clause is correct for the delete operation. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the target record, applies filters from WHERE clause, and writes the instance to the context for further checks. --- ### [8] Step : checkInstance Manager performs object-level validations such as lock status, soft-delete eligibility, and multi-step approval enforcement. --- ### [9] Step : mainDeleteOperation Manager executes the delete query, updates related indexes/caches, and handles soft/hard delete logic according to configuration. You can use the following settings to change some behavior of this step. `deleteOptions` --- ### [10] Step : buildOutput Manager shapes the response payload, masks sensitive fields, and formats related cleanup results for output. --- ### [11] Step : sendResponse Manager delivers the response to the client and finalizes any temporary internal structures. --- ### [12] Step : raiseApiEvent Manager triggers asynchronous API events, notifies queues or streams, and performs final cleanup for the workflow. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `deleteAuctionOfferBid` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | ### REST Request To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`auctionOfferBid`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Delete Auctionofferoffer` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `deleteAuctionOfferOffer` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `deleteAuctionOfferOffer` Business API is designed to handle a `delete` operation on the `AuctionOfferOffer` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Soft-deletes an offer (allowed only in non-accepted/expired state). ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `auctionofferoffer-deleted` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `deleteAuctionOfferOffer` Business API includes a REST controller that can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `deleteAuctionOfferOffer` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `deleteAuctionOfferOffer` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `auctionOfferOfferId` | `ID` | `Yes` | `-` | `urlpath` | `auctionOfferOfferId` | | **Description:** | This id paremeter is used to select the required data object that will be deleted | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `deleteAuctionOfferOffer` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks This Business API enforces ownership of the main data object before executing the operation. - The check is performed **after fetching the object instance**. If the current user is not the owner, the API will respond with **403 Forbidden**. Note: Ownership checks are applied **only if the objects have an owner field**. --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.auctionOfferOfferId},{isActive:true}]} ``` ## Delete Options Use these options to set `delete` specific settings. **useSoftDelete**: false If true, the record will be marked as deleted `(isActive: false)` instead of removed. The implementation depends on the data object’s soft delete configuration. ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request/session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads and normalizes parameters, applies defaults, and stores them in the context for downstream steps. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts, computes derived values, and remaps objects or arrays as needed for later processing. --- ### [4] Step : checkParameters Manager runs built-in validations including required field checks, type enforcement, and deletion preconditions. Stops execution if validation fails. --- ### [5] Step : checkBasicAuth Manager validates session, user roles, permissions, and tenant-specific access rules to enforce basic auth restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager generates the query conditions, applies ownership and parent checks, and ensures the clause is correct for the delete operation. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the target record, applies filters from WHERE clause, and writes the instance to the context for further checks. --- ### [8] Step : checkInstance Manager performs object-level validations such as lock status, soft-delete eligibility, and multi-step approval enforcement. --- ### [9] Step : mainDeleteOperation Manager executes the delete query, updates related indexes/caches, and handles soft/hard delete logic according to configuration. You can use the following settings to change some behavior of this step. `deleteOptions` --- ### [10] Step : buildOutput Manager shapes the response payload, masks sensitive fields, and formats related cleanup results for output. --- ### [11] Step : sendResponse Manager delivers the response to the client and finalizes any temporary internal structures. --- ### [12] Step : raiseApiEvent Manager triggers asynchronous API events, notifies queues or streams, and performs final cleanup for the workflow. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `deleteAuctionOfferOffer` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | ### REST Request To access the api you can use the **REST** controller with the path **DELETE /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'DELETE', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`auctionOfferOffer`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Get Auctionofferbid` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `getAuctionOfferBid` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `getAuctionOfferBid` Business API is designed to handle a `get` operation on the `AuctionOfferBid` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Gets a single bid (only visible to owner/admin or for auction history). ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `auctionofferbid-retrived` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `getAuctionOfferBid` Business API includes a REST controller that can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `getAuctionOfferBid` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `getAuctionOfferBid` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `auctionOfferBidId` | `ID` | `Yes` | `-` | `urlpath` | `auctionOfferBidId` | | **Description:** | This id paremeter is used to query the required data object. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `getAuctionOfferBid` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks This Business API enforces ownership of the main data object before executing the operation. - The check is performed **after fetching the object instance**. If the current user is not the owner, the API will respond with **403 Forbidden**. Note: Ownership checks are applied **only if the objects have an owner field**. --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.auctionOfferBidId},{isActive:true}]} ``` ## Get Options Use these options to set `get` specific settings. **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Extracts parameters from request and Redis, applies defaults, and writes them to context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Executes parameter transformation scripts, applies type coercion, merges derived values, and reshapes inputs for downstream milestones. --- ### [4] Step : checkParameters Validates required and custom parameters, enforcing business-specific rules and constraints. --- ### [5] Step : checkBasicAuth Performs login, role, and permission checks, and applies dynamic object-level access rules. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Builds the WHERE clause for fetching the object and applies additional scoped filters if configured. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainGetOperation Executes the database fetch, retrieves the object, and stores it in context for enrichment or further checks. You can use the following settings to change some behavior of this step. `selectClause`, `getOptions` --- ### [8] Step : checkInstance Performs instance-level validations, such as ownership, existence, or access conditions. --- ### [9] Step : buildOutput Assembles the response from the object, applies masking, formatting, and injects additional metadata if needed. --- ### [10] Step : sendResponse Delivers the response to the controller for client delivery. --- ### [11] Step : raiseApiEvent Triggers optional API-level events after workflow completion, sending messages to integrations like Kafka if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `getAuctionOfferBid` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'GET', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`auctionOfferBid`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Get Auctionofferoffer` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `getAuctionOfferOffer` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `getAuctionOfferOffer` Business API is designed to handle a `get` operation on the `AuctionOfferOffer` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Gets a single offer (shown to buyer/seller or admin). ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `auctionofferoffer-retrived` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `getAuctionOfferOffer` Business API includes a REST controller that can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `getAuctionOfferOffer` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `getAuctionOfferOffer` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `auctionOfferOfferId` | `ID` | `Yes` | `-` | `urlpath` | `auctionOfferOfferId` | | **Description:** | This id paremeter is used to query the required data object. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `getAuctionOfferOffer` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks This Business API enforces ownership of the main data object before executing the operation. - The check is performed **after fetching the object instance**. If the current user is not the owner, the API will respond with **403 Forbidden**. Note: Ownership checks are applied **only if the objects have an owner field**. --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.auctionOfferOfferId},{isActive:true}]} ``` ## Get Options Use these options to set `get` specific settings. **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Extracts parameters from request and Redis, applies defaults, and writes them to context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Executes parameter transformation scripts, applies type coercion, merges derived values, and reshapes inputs for downstream milestones. --- ### [4] Step : checkParameters Validates required and custom parameters, enforcing business-specific rules and constraints. --- ### [5] Step : checkBasicAuth Performs login, role, and permission checks, and applies dynamic object-level access rules. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Builds the WHERE clause for fetching the object and applies additional scoped filters if configured. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainGetOperation Executes the database fetch, retrieves the object, and stores it in context for enrichment or further checks. You can use the following settings to change some behavior of this step. `selectClause`, `getOptions` --- ### [8] Step : checkInstance Performs instance-level validations, such as ownership, existence, or access conditions. --- ### [9] Step : buildOutput Assembles the response from the object, applies masking, formatting, and injects additional metadata if needed. --- ### [10] Step : sendResponse Delivers the response to the controller for client delivery. --- ### [11] Step : raiseApiEvent Triggers optional API-level events after workflow completion, sending messages to integrations like Kafka if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `getAuctionOfferOffer` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'GET', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`auctionOfferOffer`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `List Auctionofferbids` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `listAuctionOfferBids` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `listAuctionOfferBids` Business API is designed to handle a `list` operation on the `AuctionOfferBid` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Lists bids by product, user, or auction, supports history/analytics. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `auctionofferbids-listed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `listAuctionOfferBids` Business API includes a REST controller that can be triggered via the following route: `/v1/auctionofferbids` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `listAuctionOfferBids` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `listAuctionOfferBids` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `listAuctionOfferBids` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {isActive:true} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `listAuctionOfferBids` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/auctionofferbids** ```js axios({ method: 'GET', url: '/v1/auctionofferbids', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`auctionOfferBids`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBids", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferBids": [ { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `List Auctionofferoffers` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `listAuctionOfferOffers` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `listAuctionOfferOffers` Business API is designed to handle a `list` operation on the `AuctionOfferOffer` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Lists offers by product, user, status, or counterOffer chain. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `auctionofferoffers-listed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `listAuctionOfferOffers` Business API includes a REST controller that can be triggered via the following route: `/v1/auctionofferoffers` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `listAuctionOfferOffers` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `listAuctionOfferOffers` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `listAuctionOfferOffers` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {isActive:true} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `listAuctionOfferOffers` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/auctionofferoffers** ```js axios({ method: 'GET', url: '/v1/auctionofferoffers', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`auctionOfferOffers`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "auctionOfferOffers": [ { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `Update Auctionofferbid` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `updateAuctionOfferBid` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `updateAuctionOfferBid` Business API is designed to handle a `update` operation on the `AuctionOfferBid` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Updates a bid’s status (allow only status update, e.g. CANCELLED, WIN/LOSE on admin settlement). Only owner/admin, and only if auction not ended or not settled. Triggers notification event. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `auctionofferbid-updated` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `updateAuctionOfferBid` Business API includes a REST controller that can be triggered via the following route: `/v1/auctionofferbids/:auctionOfferBidId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `updateAuctionOfferBid` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `updateAuctionOfferBid` Business API has 2 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `auctionOfferBidId` | `ID` | `Yes` | `-` | `urlpath` | `auctionOfferBidId` | | **Description:** | This id paremeter is used to select the required data object that will be updated | | | | | | | | | | | | | `status` | `Enum` | `No` | `-` | `body` | `status` | | **Description:** | Bid status: ACTIVE, WON, LOST, CANCELLED. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `updateAuctionOfferBid` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks This Business API enforces ownership of the main data object before executing the operation. - The check is performed **after fetching the object instance**. If the current user is not the owner, the API will respond with **403 Forbidden**. Note: Ownership checks are applied **only if the objects have an owner field**. --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.auctionOfferBidId},{isActive:true}]} ``` ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. An update data clause populates all update-allowed properties of a data object, however the null properties (that are not provided by client) are ignored in db layer. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { status: this.status, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request and session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads parameters from the request or Redis, applies defaults, and writes them into context for downstream milestones. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts and derives any helper values or reshaped payloads into the context. --- ### [4] Step : checkParameters Manager validates required parameters, checks ID formats (UUID/ObjectId), and ensures all preconditions for update are met. --- ### [5] Step : checkBasicAuth Manager performs login verification, role, and permission checks, enforcing tenant and access rules before update. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager constructs the WHERE clause used to identify the record to update, applying ownership and parent checks if necessary. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the existing record from the database and writes it to the context for validation or enrichment. --- ### [8] Step : checkInstance Manager performs instance-level validations, including ownership, existence, lock status, or other pre-update checks. --- ### [9] Step : buildDataClause Manager prepares the data clause for the update, applying transformations or enhancements before persisting. You can use the following settings to change some behavior of this step. `dataClause` --- ### [10] Step : mainUpdateOperation Manager executes the update operation with the WHERE and data clauses. Database-level events are raised if configured. --- ### [11] Step : buildOutput Manager assembles the response object from the update result, masking fields or injecting additional metadata. --- ### [12] Step : sendResponse Manager sends the response back to the controller for delivery to the client. --- ### [13] Step : raiseApiEvent Manager triggers API-level events, sending relevant messages to Kafka or other integrations if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `updateAuctionOfferBid` api has got 2 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferBidId | ID | true | request.params?.auctionOfferBidId | | status | Enum | false | request.body?.status | ### REST Request To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferbids/:auctionOfferBidId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferbids/${auctionOfferBidId}`, data: { status:"Enum", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`auctionOfferBid`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferBid", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferBid": { "id": "ID", "userId": "ID", "bidAmount": "Double", "placedAt": "Date", "currency": "String", "status": "Enum", "status_idx": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Update Auctionofferoffer` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `updateAuctionOfferOffer` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `updateAuctionOfferOffer` Business API is designed to handle a `update` operation on the `AuctionOfferOffer` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Updates offer: accepts/declines/counters by seller, withdraws by buyer before response. Enforces status transition rules, sets respondedAt. Triggers event. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `auctionofferoffer-updated` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `updateAuctionOfferOffer` Business API includes a REST controller that can be triggered via the following route: `/v1/auctionofferoffers/:auctionOfferOfferId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `updateAuctionOfferOffer` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `updateAuctionOfferOffer` Business API has 8 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `auctionOfferOfferId` | `ID` | `Yes` | `-` | `urlpath` | `auctionOfferOfferId` | | **Description:** | This id paremeter is used to select the required data object that will be updated | | | | | | | | | | | | | `counterOfferId` | `ID` | `No` | `-` | `body` | `counterOfferId` | | **Description:** | References another offer (counter-offer chain). | | | | | | | | | | | | | `counterMessage` | `String` | `No` | `-` | `body` | `counterMessage` | | **Description:** | Message accompanying seller's counter-offer (optional). | | | | | | | | | | | | | `counterAmount` | `Double` | `No` | `-` | `body` | `counterAmount` | | **Description:** | Counter-offer amount (when offer is COUNTERED). | | | | | | | | | | | | | `message` | `String` | `No` | `-` | `body` | `message` | | **Description:** | Message/special notes from buyer (optional). | | | | | | | | | | | | | `status` | `Enum` | `No` | `-` | `body` | `status` | | **Description:** | Current offer status (e.g., PENDING, ACCEPTED, DECLINED, COUNTERED, EXPIRED, CANCELLED). | | | | | | | | | | | | | `expiresAt` | `Date` | `No` | `-` | `body` | `expiresAt` | | **Description:** | When this offer expires (optional). | | | | | | | | | | | | | `respondedAt` | `Date` | `No` | `-` | `body` | `respondedAt` | | **Description:** | When the seller (or buyer, for counter-offer) responded/updated the offer status. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `updateAuctionOfferOffer` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks This Business API enforces ownership of the main data object before executing the operation. - The check is performed **after fetching the object instance**. If the current user is not the owner, the API will respond with **403 Forbidden**. Note: Ownership checks are applied **only if the objects have an owner field**. --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.auctionOfferOfferId},{isActive:true}]} ``` ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. An update data clause populates all update-allowed properties of a data object, however the null properties (that are not provided by client) are ignored in db layer. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { counterOfferId: this.counterOfferId, counterMessage: this.counterMessage, counterAmount: this.counterAmount, message: this.message, status: this.status, expiresAt: this.expiresAt, respondedAt: this.respondedAt, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request and session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads parameters from the request or Redis, applies defaults, and writes them into context for downstream milestones. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts and derives any helper values or reshaped payloads into the context. --- ### [4] Step : checkParameters Manager validates required parameters, checks ID formats (UUID/ObjectId), and ensures all preconditions for update are met. --- ### [5] Step : checkBasicAuth Manager performs login verification, role, and permission checks, enforcing tenant and access rules before update. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager constructs the WHERE clause used to identify the record to update, applying ownership and parent checks if necessary. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the existing record from the database and writes it to the context for validation or enrichment. --- ### [8] Step : checkInstance Manager performs instance-level validations, including ownership, existence, lock status, or other pre-update checks. --- ### [9] Step : buildDataClause Manager prepares the data clause for the update, applying transformations or enhancements before persisting. You can use the following settings to change some behavior of this step. `dataClause` --- ### [10] Step : mainUpdateOperation Manager executes the update operation with the WHERE and data clauses. Database-level events are raised if configured. --- ### [11] Step : buildOutput Manager assembles the response object from the update result, masking fields or injecting additional metadata. --- ### [12] Step : sendResponse Manager sends the response back to the controller for delivery to the client. --- ### [13] Step : raiseApiEvent Manager triggers API-level events, sending relevant messages to Kafka or other integrations if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `updateAuctionOfferOffer` api has got 8 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | auctionOfferOfferId | ID | true | request.params?.auctionOfferOfferId | | counterOfferId | ID | false | request.body?.counterOfferId | | counterMessage | String | false | request.body?.counterMessage | | counterAmount | Double | false | request.body?.counterAmount | | message | String | false | request.body?.message | | status | Enum | false | request.body?.status | | expiresAt | Date | false | request.body?.expiresAt | | respondedAt | Date | false | request.body?.respondedAt | ### REST Request To access the api you can use the **REST** controller with the path **PATCH /v1/auctionofferoffers/:auctionOfferOfferId** ```js axios({ method: 'PATCH', url: `/v1/auctionofferoffers/${auctionOfferOfferId}`, data: { counterOfferId:"ID", counterMessage:"String", counterAmount:"Double", message:"String", status:"Enum", expiresAt:"Date", respondedAt:"Date", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`auctionOfferOffer`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "auctionOfferOffer", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "auctionOfferOffer": { "id": "ID", "buyerId": "ID", "currency": "String", "productId": "ID", "counterOfferId": "ID", "counterMessage": "String", "counterAmount": "Double", "offerAmount": "Double", "message": "String", "sellerId": "ID", "status": "Enum", "status_idx": "Integer", "expiresAt": "Date", "respondedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Archive Profile` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `archiveProfile` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `archiveProfile` Business API is designed to handle a `delete` operation on the `User` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description This api is used by users to archive their profiles. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `profile-archived` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `archiveProfile` Business API includes a REST controller that can be triggered via the following route: `/v1/archiveprofile/:userId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### gRPC Controller The `archiveProfile` Business API includes a gRPC controller that can be triggered via the following function: `archiveProfile()` By calling this gRPC endpoint using a gRPC client, you can execute the Business API. Note that all parameters must be provided as function arguments, regardless of their HTTP location configuration, which is relevant only for the REST controller. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `archiveProfile` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `archiveProfile` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `userId` | `ID` | `Yes` | `-` | `urlpath` | `userId` | | **Description:** | This id paremeter is used to select the required data object that will be deleted | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `archiveProfile` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.userId},{isActive:true}]} ``` ## Delete Options Use these options to set `delete` specific settings. **useSoftDelete**: If true, the record will be marked as deleted `(isActive: false)` instead of removed. The implementation depends on the data object’s soft delete configuration. ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request/session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads and normalizes parameters, applies defaults, and stores them in the context for downstream steps. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts, computes derived values, and remaps objects or arrays as needed for later processing. --- ### [4] Step : checkParameters Manager runs built-in validations including required field checks, type enforcement, and deletion preconditions. Stops execution if validation fails. --- ### [5] Step : checkBasicAuth Manager validates session, user roles, permissions, and tenant-specific access rules to enforce basic auth restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Action : protectSuperAdmin **Action Type**: `ValidationAction` Prevents deletion of the SuperAdmin account. This safeguard ensures that the SuperAdmin userId cannot be removed under any circumstances. ```js class Api { async protectSuperAdmin() { const isError = this.userId == this.auth?.superAdminId; if (isError) { throw new BadRequestError("SuperAdminCantBeDeleted"); } return isError; } } ``` --- ### [7] Step : buildWhereClause Manager generates the query conditions, applies ownership and parent checks, and ensures the clause is correct for the delete operation. You can use the following settings to change some behavior of this step. `whereClause` --- ### [8] Step : fetchInstance Manager fetches the target record, applies filters from WHERE clause, and writes the instance to the context for further checks. --- ### [9] Step : checkInstance Manager performs object-level validations such as lock status, soft-delete eligibility, and multi-step approval enforcement. --- ### [10] Step : mainDeleteOperation Manager executes the delete query, updates related indexes/caches, and handles soft/hard delete logic according to configuration. You can use the following settings to change some behavior of this step. `deleteOptions` --- ### [11] Action : deleteUserSessions **Action Type**: `FunctionCallAction` Makes a call to this.auth to delete the sessions of the deleted user. ```js class Api { async deleteUserSessions() { try { return await (async (userId) => { await this.auth.deleteUserSessions(userId); })(this.userId); } catch (err) { console.error("Error in FunctionCallAction deleteUserSessions:", err); throw err; } } } ``` --- ### [12] Step : buildOutput Manager shapes the response payload, masks sensitive fields, and formats related cleanup results for output. --- ### [13] Step : sendResponse Manager delivers the response to the client and finalizes any temporary internal structures. --- ### [14] Step : raiseApiEvent Manager triggers asynchronous API events, notifies queues or streams, and performs final cleanup for the workflow. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `archiveProfile` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | ### REST Request To access the api you can use the **REST** controller with the path **DELETE /v1/archiveprofile/:userId** ```js axios({ method: 'DELETE', url: `/v1/archiveprofile/${userId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`user`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Create User` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `createUser` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `createUser` Business API is designed to handle a `create` operation on the `User` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description This api is used by admin roles to create a new user manually from admin panels ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `user-created` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `createUser` Business API includes a REST controller that can be triggered via the following route: `/v1/users` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### gRPC Controller The `createUser` Business API includes a gRPC controller that can be triggered via the following function: `createUser()` By calling this gRPC endpoint using a gRPC client, you can execute the Business API. Note that all parameters must be provided as function arguments, regardless of their HTTP location configuration, which is relevant only for the REST controller. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `createUser` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `createUser` Business API has 7 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `userId` | `ID` | `No` | `-` | `body` | `userId` | | **Description:** | This id paremeter is used to create the data object with a given specific id. Leave null for automatic id. | | | | | | | | | | | | | `avatar` | `String` | `No` | `-` | `body` | `avatar` | | **Description:** | The avatar url of the user. If not sent, a default random one will be generated. | | | | | | | | | | | | | `email` | `String` | `Yes` | `-` | `body` | `email` | | **Description:** | A string value to represent the user's email. | | | | | | | | | | | | | `password` | `String` | `Yes` | `-` | `body` | `password` | | **Description:** | A string value to represent the user's password. It will be stored as hashed. | | | | | | | | | | | | | `fullname` | `String` | `Yes` | `-` | `body` | `fullname` | | **Description:** | A string value to represent the fullname of the user | | | | | | | | | | | | | `phone` | `String` | `No` | `-` | `body` | `phone` | | **Description:** | user's phone number | | | | | | | | | | | | | `address` | `Object` | `No` | `-` | `body` | `address` | | **Description:** | user's adress | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. * `avatar`: ```javascript this.avatar = this.avatar ? `https://gravatar.com/avatar/${LIB.common.md5(this.email ?? 'nullValue')}?s=200&d=identicon` : null ``` ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `createUser` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin]` - **Check roles** (must pass basic role checks): Users must have at least one of the following roles to execute this API: `[superAdmin`, `admin`, `saasAdmin`, `tenantAdmin`, `tenantOwner]` --- ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { id: this.userId, email: this.email, password: this.hashString(this.password), fullname: this.fullname, avatar: this.avatar, phone: this.phone, address: this.address ? (typeof this.address == 'string' ? JSON.parse(this.address) : this.address) : null, isActive: true, _archivedAt: null, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, populates session and request objects, prepares internal structures for parameter handling and workflow execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads input parameters, normalizes missing values, applies default type casting, and stores them in the API context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager transforms parameters, computes derived values, flattens or remaps arrays/objects, and adjusts formats for downstream processing. --- ### [4] Step : checkParameters Manager executes built-in validations: required field checks, type enforcement, and basic business rules. Prevents operation if validation fails. --- ### [5] Action : fetchArchivedUser **Action Type**: `FetchObjectAction` Check and get if any deleted user exists with the same email ```js class Api { async fetchArchivedUser() { // Fetch Object on childObject user const userQuery = { $and: [ { email: this.email, isActive: false }, { _archivedAt: { $gte: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000), }, }, ], }; const { convertUserQueryToSequelizeQuery } = require("common"); const scriptQuery = convertUserQueryToSequelizeQuery(userQuery); // get object from db const data = await getUserByQuery(scriptQuery); return data ? { id: data["id"], } : null; } } ``` --- ### [6] Action : checkArchivedUser **Action Type**: `ValidationAction` Prevents re-register of a user when their profile is sitll in 30days archive ```js class Api { async checkArchivedUser() { const isError = this.archivedUser?.email != null; if (isError) { throw new BadRequestError("ThisProfileIsArchivedPleaseLoginToRestore"); } return isError; } } ``` --- ### [7] Step : checkBasicAuth Manager performs authentication and authorization checks: verifies session, user roles, permissions, and tenant restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [8] Step : buildDataClause Manager constructs the final data object for creation, fills auto-generated fields (IDs, timestamps, owner fields), and ensures schema consistency. You can use the following settings to change some behavior of this step. `dataClause` --- ### [9] Step : mainCreateOperation Manager executes the database insert operation, updates indexes/caches, and triggers internal post-processing like linked default records. --- ### [10] Step : buildOutput Manager shapes the response: masks sensitive fields, resolves linked references, and formats output according to API contract. --- ### [11] Action : writeVerificationNeedsToResponse **Action Type**: `AddToResponseAction` Set if email or mobile verification needed ```js class Api { async writeVerificationNeedsToResponse() { try { this.output["emailVerificationNeeded"] = !this.user?.emailVerified; this.output["mobileVerificationNeeded"] = false; return true; } catch (error) { console.error("AddToResponseAction error:", error); throw error; } } } ``` --- ### [12] Step : sendResponse Manager sends the response to the client and finalizes internal tasks like flushing logs or updating session state. --- ### [13] Step : raiseApiEvent Manager triggers API-level events (Kafka, WebSocket, async workflows) as the final internal step. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `createUser` api has got 6 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | email | String | true | request.body?.email | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | ### REST Request To access the api you can use the **REST** controller with the path **POST /v1/users** ```js axios({ method: 'POST', url: '/v1/users', data: { avatar:"String", email:"String", password:"String", fullname:"String", phone:"String", address:"Object", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`user`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Delete User` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `deleteUser` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `deleteUser` Business API is designed to handle a `delete` operation on the `User` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description This api is used by admins to delete user profiles. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `user-deleted` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `deleteUser` Business API includes a REST controller that can be triggered via the following route: `/v1/users/:userId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### gRPC Controller The `deleteUser` Business API includes a gRPC controller that can be triggered via the following function: `deleteUser()` By calling this gRPC endpoint using a gRPC client, you can execute the Business API. Note that all parameters must be provided as function arguments, regardless of their HTTP location configuration, which is relevant only for the REST controller. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `deleteUser` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `deleteUser` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `userId` | `ID` | `Yes` | `-` | `urlpath` | `userId` | | **Description:** | This id paremeter is used to select the required data object that will be deleted | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `deleteUser` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin]` - **Check roles** (must pass basic role checks): Users must have at least one of the following roles to execute this API: `[superAdmin`, `admin]` --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.userId},{isActive:true}]} ``` ## Delete Options Use these options to set `delete` specific settings. **useSoftDelete**: If true, the record will be marked as deleted `(isActive: false)` instead of removed. The implementation depends on the data object’s soft delete configuration. ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request/session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads and normalizes parameters, applies defaults, and stores them in the context for downstream steps. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts, computes derived values, and remaps objects or arrays as needed for later processing. --- ### [4] Step : checkParameters Manager runs built-in validations including required field checks, type enforcement, and deletion preconditions. Stops execution if validation fails. --- ### [5] Step : checkBasicAuth Manager validates session, user roles, permissions, and tenant-specific access rules to enforce basic auth restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Action : protectSuperAdmin **Action Type**: `ValidationAction` Prevents deletion of the SuperAdmin account. This safeguard ensures that the SuperAdmin userId cannot be removed under any circumstances. ```js class Api { async protectSuperAdmin() { const isError = this.userId == this.auth?.superAdminId; if (isError) { throw new BadRequestError("SuperAdminCantBeDeleted"); } return isError; } } ``` --- ### [7] Step : buildWhereClause Manager generates the query conditions, applies ownership and parent checks, and ensures the clause is correct for the delete operation. You can use the following settings to change some behavior of this step. `whereClause` --- ### [8] Step : fetchInstance Manager fetches the target record, applies filters from WHERE clause, and writes the instance to the context for further checks. --- ### [9] Step : checkInstance Manager performs object-level validations such as lock status, soft-delete eligibility, and multi-step approval enforcement. --- ### [10] Step : mainDeleteOperation Manager executes the delete query, updates related indexes/caches, and handles soft/hard delete logic according to configuration. You can use the following settings to change some behavior of this step. `deleteOptions` --- ### [11] Action : deleteUserSessions **Action Type**: `FunctionCallAction` Makes a call to this.auth to delete the sessions of the deleted user. ```js class Api { async deleteUserSessions() { try { return await (async (userId) => { await this.auth.deleteUserSessions(userId); })(this.userId); } catch (err) { console.error("Error in FunctionCallAction deleteUserSessions:", err); throw err; } } } ``` --- ### [12] Step : buildOutput Manager shapes the response payload, masks sensitive fields, and formats related cleanup results for output. --- ### [13] Step : sendResponse Manager delivers the response to the client and finalizes any temporary internal structures. --- ### [14] Step : raiseApiEvent Manager triggers asynchronous API events, notifies queues or streams, and performs final cleanup for the workflow. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `deleteUser` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | ### REST Request To access the api you can use the **REST** controller with the path **DELETE /v1/users/:userId** ```js axios({ method: 'DELETE', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`user`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Get Briefuser` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `getBriefUser` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `getBriefUser` Business API is designed to handle a `get` operation on the `User` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description This route is used by public to get simple user profile information. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `briefuser-retrived` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `getBriefUser` Business API includes a REST controller that can be triggered via the following route: `/v1/briefuser/:userId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### gRPC Controller The `getBriefUser` Business API includes a gRPC controller that can be triggered via the following function: `getBriefUser()` By calling this gRPC endpoint using a gRPC client, you can execute the Business API. Note that all parameters must be provided as function arguments, regardless of their HTTP location configuration, which is relevant only for the REST controller. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `getBriefUser` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `getBriefUser` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `userId` | `ID` | `Yes` | `-` | `urlpath` | `userId` | | **Description:** | This id paremeter is used to query the required data object. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `getBriefUser` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API is **public** and can be accessed without login (`loginRequired = false`). --- ### Ownership Checks --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin]` --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `id`,`fullname`,`avatar` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.userId},{isActive:true}]} ``` ## Get Options Use these options to set `get` specific settings. **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Extracts parameters from request and Redis, applies defaults, and writes them to context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Executes parameter transformation scripts, applies type coercion, merges derived values, and reshapes inputs for downstream milestones. --- ### [4] Step : checkParameters Validates required and custom parameters, enforcing business-specific rules and constraints. --- ### [5] Step : checkBasicAuth Performs login, role, and permission checks, and applies dynamic object-level access rules. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Builds the WHERE clause for fetching the object and applies additional scoped filters if configured. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainGetOperation Executes the database fetch, retrieves the object, and stores it in context for enrichment or further checks. You can use the following settings to change some behavior of this step. `selectClause`, `getOptions` --- ### [8] Step : checkInstance Performs instance-level validations, such as ownership, existence, or access conditions. --- ### [9] Step : buildOutput Assembles the response from the object, applies masking, formatting, and injects additional metadata if needed. --- ### [10] Step : sendResponse Delivers the response to the controller for client delivery. --- ### [11] Step : raiseApiEvent Triggers optional API-level events after workflow completion, sending messages to integrations like Kafka if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `getBriefUser` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/briefuser/:userId** ```js axios({ method: 'GET', url: `/v1/briefuser/${userId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`user`** object in the respones. However, some properties may be omitted based on the object's internal logic. This route's response is constrained to a select list of properties, and therefore does not encompass all attributes of the resource. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "fullname": "String", "avatar": "String", "isActive": true } } ``` # Business API Design Specification - `Get User` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `getUser` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `getUser` Business API is designed to handle a `get` operation on the `User` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description This api is used by admin roles or the users themselves to get the user profile information. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `user-retrived` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `getUser` Business API includes a REST controller that can be triggered via the following route: `/v1/users/:userId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### gRPC Controller The `getUser` Business API includes a gRPC controller that can be triggered via the following function: `getUser()` By calling this gRPC endpoint using a gRPC client, you can execute the Business API. Note that all parameters must be provided as function arguments, regardless of their HTTP location configuration, which is relevant only for the REST controller. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `getUser` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `getUser` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `userId` | `ID` | `Yes` | `-` | `urlpath` | `userId` | | **Description:** | This id paremeter is used to query the required data object. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `getUser` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin, admin]` --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.userId},{isActive:true}]} ``` ## Get Options Use these options to set `get` specific settings. **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Extracts parameters from request and Redis, applies defaults, and writes them to context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Executes parameter transformation scripts, applies type coercion, merges derived values, and reshapes inputs for downstream milestones. --- ### [4] Step : checkParameters Validates required and custom parameters, enforcing business-specific rules and constraints. --- ### [5] Step : checkBasicAuth Performs login, role, and permission checks, and applies dynamic object-level access rules. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Builds the WHERE clause for fetching the object and applies additional scoped filters if configured. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainGetOperation Executes the database fetch, retrieves the object, and stores it in context for enrichment or further checks. You can use the following settings to change some behavior of this step. `selectClause`, `getOptions` --- ### [8] Step : checkInstance Performs instance-level validations, such as ownership, existence, or access conditions. --- ### [9] Step : buildOutput Assembles the response from the object, applies masking, formatting, and injects additional metadata if needed. --- ### [10] Step : sendResponse Delivers the response to the controller for client delivery. --- ### [11] Step : raiseApiEvent Triggers optional API-level events after workflow completion, sending messages to integrations like Kafka if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `getUser` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/users/:userId** ```js axios({ method: 'GET', url: `/v1/users/${userId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`user`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `List Users` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `listUsers` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `listUsers` Business API is designed to handle a `list` operation on the `User` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description The list of users is filtered by the tenantId. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `users-listed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `listUsers` Business API includes a REST controller that can be triggered via the following route: `/v1/users` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### gRPC Controller The `listUsers` Business API includes a gRPC controller that can be triggered via the following function: `listUsers()` By calling this gRPC endpoint using a gRPC client, you can execute the Business API. Note that all parameters must be provided as function arguments, regardless of their HTTP location configuration, which is relevant only for the REST controller. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `listUsers` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `listUsers` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `listUsers` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin, admin]` - **Check roles** (must pass basic role checks): Users must have at least one of the following roles to execute this API: `[superAdmin`, `admin]` --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {isActive:true} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). [ id asc ] **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `listUsers` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/users** ```js axios({ method: 'GET', url: '/v1/users', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`users`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `Register User` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `registerUser` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `registerUser` Business API is designed to handle a `create` operation on the `User` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description This api is used by public users to register themselves ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `user-registered` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `registerUser` Business API includes a REST controller that can be triggered via the following route: `/v1/registeruser` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### gRPC Controller The `registerUser` Business API includes a gRPC controller that can be triggered via the following function: `registerUser()` By calling this gRPC endpoint using a gRPC client, you can execute the Business API. Note that all parameters must be provided as function arguments, regardless of their HTTP location configuration, which is relevant only for the REST controller. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `registerUser` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `registerUser` Business API has 8 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `userId` | `ID` | `No` | `-` | `body` | `userId` | | **Description:** | This id paremeter is used to create the data object with a given specific id. Leave null for automatic id. | | | | | | | | | | | | | `avatar` | `String` | `No` | `-` | `body` | `avatar` | | **Description:** | The avatar url of the user. If not sent, a default random one will be generated. | | | | | | | | | | | | | `socialCode` | `String` | `No` | `-` | `body` | `socialCode` | | **Description:** | Send this social code if it is sent to you after a social login authetication of an unregistred user. The users profile data will be complemented from the autheticated social profile using this code. If you provide the social code there is no need to give full profile data of the user, just give the ones that are not included in social profiles. | | | | | | | | | | | | | `password` | `String` | `Yes` | `-` | `body` | `password` | | **Description:** | The password defined by the the user that is being registered. | | | | | | | | | | | | | `fullname` | `String` | `Yes` | `-` | `body` | `fullname` | | **Description:** | The fullname defined by the the user that is being registered. | | | | | | | | | | | | | `email` | `String` | `Yes` | `-` | `body` | `email` | | **Description:** | The email defined by the the user that is being registered. | | | | | | | | | | | | | `phone` | `String` | `No` | `-` | `body` | `phone` | | **Description:** | user's phone number | | | | | | | | | | | | | `address` | `Object` | `No` | `-` | `body` | `address` | | **Description:** | user's adress | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. * `avatar`: ```javascript this.avatar = this.socialProfile?.avatar ?? (this.avatar ? this.avatar : `https://gravatar.com/avatar/${LIB.common.md5(this.email ?? 'nullValue')}?s=200&d=identicon`) ``` * `password`: ```javascript this.password = this.socialProfile ? this.password ?? LIB.common.randomCode() : this.password ``` * `fullname`: ```javascript this.fullname = this.socialProfile?.fullname ?? this.fullname ``` * `email`: ```javascript this.email = this.socialProfile?.email ?? this.email ``` ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `registerUser` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API is **public** and can be accessed without login (`loginRequired = false`). --- ### Ownership Checks --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin]` --- ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. **Custom Data Clause Override** ```js { emailVerified: this.socialProfile?.emailVerified ?? false, roleId: this.socialProfile?.roleId ?? 'user', } ``` **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { id: this.userId, email: this.email, password: this.hashString(this.password), fullname: this.fullname, avatar: this.avatar, phone: this.phone, address: this.address ? (typeof this.address == 'string' ? JSON.parse(this.address) : this.address) : null, emailVerified: this.socialProfile?.emailVerified ?? false, roleId: this.socialProfile?.roleId ?? 'user', isActive: true, _archivedAt: null, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, populates session and request objects, prepares internal structures for parameter handling and workflow execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads input parameters, normalizes missing values, applies default type casting, and stores them in the API context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager transforms parameters, computes derived values, flattens or remaps arrays/objects, and adjusts formats for downstream processing. --- ### [4] Step : checkParameters Manager executes built-in validations: required field checks, type enforcement, and basic business rules. Prevents operation if validation fails. --- ### [5] Action : fetchArchivedUser **Action Type**: `FetchObjectAction` Check and get if any deleted user(in 30 days) exists with the same email ```js class Api { async fetchArchivedUser() { // Fetch Object on childObject user const userQuery = { $and: [ { email: this.email, isActive: false }, { _archivedAt: { $gte: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000), }, }, ], }; const { convertUserQueryToSequelizeQuery } = require("common"); const scriptQuery = convertUserQueryToSequelizeQuery(userQuery); // get object from db const data = await getUserByQuery(scriptQuery); return data ? { id: data["id"], } : null; } } ``` --- ### [6] Action : checkArchivedUser **Action Type**: `ValidationAction` Prevents re-register of a user when their profile is sitll in 30days archive ```js class Api { async checkArchivedUser() { const isError = this.archivedUser?.email != null; if (isError) { throw new BadRequestError("YourProfileIsArchivedPleaseLoginToRestore"); } return isError; } } ``` --- ### [7] Step : checkBasicAuth Manager performs authentication and authorization checks: verifies session, user roles, permissions, and tenant restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [8] Step : buildDataClause Manager constructs the final data object for creation, fills auto-generated fields (IDs, timestamps, owner fields), and ensures schema consistency. You can use the following settings to change some behavior of this step. `dataClause` --- ### [9] Step : mainCreateOperation Manager executes the database insert operation, updates indexes/caches, and triggers internal post-processing like linked default records. --- ### [10] Step : buildOutput Manager shapes the response: masks sensitive fields, resolves linked references, and formats output according to API contract. --- ### [11] Action : writeVerificationNeedsToResponse **Action Type**: `AddToResponseAction` Set if email or mobile verification needed ```js class Api { async writeVerificationNeedsToResponse() { try { this.output["emailVerificationNeeded"] = !this.user?.emailVerified; this.output["mobileVerificationNeeded"] = false; return true; } catch (error) { console.error("AddToResponseAction error:", error); throw error; } } } ``` --- ### [12] Step : sendResponse Manager sends the response to the client and finalizes internal tasks like flushing logs or updating session state. --- ### [13] Step : raiseApiEvent Manager triggers API-level events (Kafka, WebSocket, async workflows) as the final internal step. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `registerUser` api has got 6 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | avatar | String | false | request.body?.avatar | | password | String | true | request.body?.password | | fullname | String | true | request.body?.fullname | | email | String | true | request.body?.email | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | ### REST Request To access the api you can use the **REST** controller with the path **POST /v1/registeruser** ```js axios({ method: 'POST', url: '/v1/registeruser', data: { avatar:"String", password:"String", fullname:"String", email:"String", phone:"String", address:"Object", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`user`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Search Users` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `searchUsers` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `searchUsers` Business API is designed to handle a `list` operation on the `User` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description The list of users is filtered by the tenantId. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `users-searched` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `searchUsers` Business API includes a REST controller that can be triggered via the following route: `/v1/searchusers` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### gRPC Controller The `searchUsers` Business API includes a gRPC controller that can be triggered via the following function: `searchUsers()` By calling this gRPC endpoint using a gRPC client, you can execute the Business API. Note that all parameters must be provided as function arguments, regardless of their HTTP location configuration, which is relevant only for the REST controller. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `searchUsers` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `searchUsers` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `keyword` | `String` | `Yes` | `-` | `query` | `keyword` | | **Description:** | - | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `searchUsers` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin, admin]` - **Check roles** (must pass basic role checks): Users must have at least one of the following roles to execute this API: `[superAdmin`, `admin]` --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {isActive:true} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). [ id asc ] **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `searchUsers` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | keyword | String | true | request.query?.keyword | ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/searchusers** ```js axios({ method: 'GET', url: '/v1/searchusers', data: { }, params: { keyword:'"String"', } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`users`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "users", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "users": [ { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `Update Profile` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `updateProfile` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `updateProfile` Business API is designed to handle a `update` operation on the `User` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description This route is used by users to update their profiles. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `profile-updated` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `updateProfile` Business API includes a REST controller that can be triggered via the following route: `/v1/profile/:userId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### gRPC Controller The `updateProfile` Business API includes a gRPC controller that can be triggered via the following function: `updateProfile()` By calling this gRPC endpoint using a gRPC client, you can execute the Business API. Note that all parameters must be provided as function arguments, regardless of their HTTP location configuration, which is relevant only for the REST controller. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `updateProfile` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `updateProfile` Business API has 5 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `userId` | `ID` | `Yes` | `-` | `urlpath` | `userId` | | **Description:** | This id paremeter is used to select the required data object that will be updated | | | | | | | | | | | | | `fullname` | `String` | `No` | `-` | `body` | `fullname` | | **Description:** | A string value to represent the fullname of the user | | | | | | | | | | | | | `avatar` | `String` | `No` | `-` | `body` | `avatar` | | **Description:** | The avatar url of the user. A random avatar will be generated if not provided | | | | | | | | | | | | | `phone` | `String` | `No` | `-` | `body` | `phone` | | **Description:** | user's phone number | | | | | | | | | | | | | `address` | `Object` | `No` | `-` | `body` | `address` | | **Description:** | user's adress | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `updateProfile` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin]` --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.userId},{isActive:true}]} ``` ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. An update data clause populates all update-allowed properties of a data object, however the null properties (that are not provided by client) are ignored in db layer. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { fullname: this.fullname, avatar: this.avatar, phone: this.phone, address: this.address ? (typeof this.address == 'string' ? JSON.parse(this.address) : this.address) : null, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request and session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads parameters from the request or Redis, applies defaults, and writes them into context for downstream milestones. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts and derives any helper values or reshaped payloads into the context. --- ### [4] Step : checkParameters Manager validates required parameters, checks ID formats (UUID/ObjectId), and ensures all preconditions for update are met. --- ### [5] Step : checkBasicAuth Manager performs login verification, role, and permission checks, enforcing tenant and access rules before update. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager constructs the WHERE clause used to identify the record to update, applying ownership and parent checks if necessary. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the existing record from the database and writes it to the context for validation or enrichment. --- ### [8] Step : checkInstance Manager performs instance-level validations, including ownership, existence, lock status, or other pre-update checks. --- ### [9] Step : buildDataClause Manager prepares the data clause for the update, applying transformations or enhancements before persisting. You can use the following settings to change some behavior of this step. `dataClause` --- ### [10] Step : mainUpdateOperation Manager executes the update operation with the WHERE and data clauses. Database-level events are raised if configured. --- ### [11] Step : buildOutput Manager assembles the response object from the update result, masking fields or injecting additional metadata. --- ### [12] Step : sendResponse Manager sends the response back to the controller for delivery to the client. --- ### [13] Step : raiseApiEvent Manager triggers API-level events, sending relevant messages to Kafka or other integrations if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `updateProfile` api has got 5 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | ### REST Request To access the api you can use the **REST** controller with the path **PATCH /v1/profile/:userId** ```js axios({ method: 'PATCH', url: `/v1/profile/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`user`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Update User` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `updateUser` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `updateUser` Business API is designed to handle a `update` operation on the `User` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description This route is used by admins to update user profiles. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `user-updated` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `updateUser` Business API includes a REST controller that can be triggered via the following route: `/v1/users/:userId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### gRPC Controller The `updateUser` Business API includes a gRPC controller that can be triggered via the following function: `updateUser()` By calling this gRPC endpoint using a gRPC client, you can execute the Business API. Note that all parameters must be provided as function arguments, regardless of their HTTP location configuration, which is relevant only for the REST controller. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `updateUser` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `updateUser` Business API has 5 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `userId` | `ID` | `Yes` | `-` | `urlpath` | `userId` | | **Description:** | This id paremeter is used to select the required data object that will be updated | | | | | | | | | | | | | `fullname` | `String` | `No` | `-` | `body` | `fullname` | | **Description:** | A string value to represent the fullname of the user | | | | | | | | | | | | | `avatar` | `String` | `No` | `-` | `body` | `avatar` | | **Description:** | The avatar url of the user. A random avatar will be generated if not provided | | | | | | | | | | | | | `phone` | `String` | `No` | `-` | `body` | `phone` | | **Description:** | user's phone number | | | | | | | | | | | | | `address` | `Object` | `No` | `-` | `body` | `address` | | **Description:** | user's adress | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `updateUser` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin]` - **Check roles** (must pass basic role checks): Users must have at least one of the following roles to execute this API: `[superAdmin`, `saasAdmin`, `admin`, `tenantOwner`, `tenantAdmin]` --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.userId},{isActive:true}]} ``` ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. An update data clause populates all update-allowed properties of a data object, however the null properties (that are not provided by client) are ignored in db layer. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { fullname: this.fullname, avatar: this.avatar, phone: this.phone, address: this.address ? (typeof this.address == 'string' ? JSON.parse(this.address) : this.address) : null, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request and session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads parameters from the request or Redis, applies defaults, and writes them into context for downstream milestones. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts and derives any helper values or reshaped payloads into the context. --- ### [4] Step : checkParameters Manager validates required parameters, checks ID formats (UUID/ObjectId), and ensures all preconditions for update are met. --- ### [5] Step : checkBasicAuth Manager performs login verification, role, and permission checks, enforcing tenant and access rules before update. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager constructs the WHERE clause used to identify the record to update, applying ownership and parent checks if necessary. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the existing record from the database and writes it to the context for validation or enrichment. --- ### [8] Action : setRolesOrder **Action Type**: `CreateObjectAction` Sets the hiyerarchy of the roles to check user permissions on other users ```js class Api { async setRolesOrder() { // Construct base object const obj = {}; // Merge dynamic object Object.assign(obj, { superAdmin: 20, saasAdmin: 19, admin: 18, tenantOwner: 17, tenantAdmin: 16, saasUser: 15, tenantUser: 14, user: 13, }); return obj; } } ``` --- ### [9] Action : protectHigherRole **Action Type**: `ValidationAction` Prevents the update of a higher or equal user role if not themselves ```js class Api { async protectHigherRole() { const isValid = (this._r[this.session.roleId] ?? 0) > (this._r[this.user.roleId] ?? 0); if (!isValid) { throw new BadRequestError("AHigherUserRoleCantBeChanged"); } return isValid; } } ``` --- ### [10] Step : checkInstance Manager performs instance-level validations, including ownership, existence, lock status, or other pre-update checks. --- ### [11] Step : buildDataClause Manager prepares the data clause for the update, applying transformations or enhancements before persisting. You can use the following settings to change some behavior of this step. `dataClause` --- ### [12] Step : mainUpdateOperation Manager executes the update operation with the WHERE and data clauses. Database-level events are raised if configured. --- ### [13] Step : buildOutput Manager assembles the response object from the update result, masking fields or injecting additional metadata. --- ### [14] Step : sendResponse Manager sends the response back to the controller for delivery to the client. --- ### [15] Step : raiseApiEvent Manager triggers API-level events, sending relevant messages to Kafka or other integrations if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `updateUser` api has got 5 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | fullname | String | false | request.body?.fullname | | avatar | String | false | request.body?.avatar | | phone | String | false | request.body?.phone | | address | Object | false | request.body?.address | ### REST Request To access the api you can use the **REST** controller with the path **PATCH /v1/users/:userId** ```js axios({ method: 'PATCH', url: `/v1/users/${userId}`, data: { fullname:"String", avatar:"String", phone:"String", address:"Object", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`user`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Update Userpassword` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `updateUserPassword` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `updateUserPassword` Business API is designed to handle a `update` operation on the `User` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description This route is used to update the password of users in the profile page by users themselves ## API Options * **Auto Params** : `false` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `userpassword-updated` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `updateUserPassword` Business API includes a REST controller that can be triggered via the following route: `/v1/userpassword/:userId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### gRPC Controller The `updateUserPassword` Business API includes a gRPC controller that can be triggered via the following function: `updateUserPassword()` By calling this gRPC endpoint using a gRPC client, you can execute the Business API. Note that all parameters must be provided as function arguments, regardless of their HTTP location configuration, which is relevant only for the REST controller. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `updateUserPassword` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `updateUserPassword` Business API has 3 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `userId` | `ID` | `Yes` | `-` | `urlpath` | `userId` | | **Description:** | This id paremeter is used to select the required data object that will be updated | | | | | | | | | | | | | `oldPassword` | `String` | `Yes` | `-` | `body` | `oldPassword` | | **Description:** | The old password of the user that will be overridden bu the new one. Send for double check. | | | | | | | | | | | | | `newPassword` | `String` | `Yes` | `-` | `body` | `newPassword` | | **Description:** | The new password of the user to be updated | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. * `newPassword`: ```javascript this.newPassword = this.newPassword ? this.hashString(this.newPassword) : null ``` ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `updateUserPassword` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin]` --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.userId},{isActive:true}]} ``` ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. An update data clause populates all update-allowed properties of a data object, however the null properties (that are not provided by client) are ignored in db layer. **Custom Data Clause Override** ```js { password: this.newPassword, } ``` **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { // password parameter is closed to update by client request // include it in data clause unless you are sure password: this.newPassword, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request and session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads parameters from the request or Redis, applies defaults, and writes them into context for downstream milestones. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts and derives any helper values or reshaped payloads into the context. --- ### [4] Step : checkParameters Manager validates required parameters, checks ID formats (UUID/ObjectId), and ensures all preconditions for update are met. --- ### [5] Step : checkBasicAuth Manager performs login verification, role, and permission checks, enforcing tenant and access rules before update. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager constructs the WHERE clause used to identify the record to update, applying ownership and parent checks if necessary. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the existing record from the database and writes it to the context for validation or enrichment. --- ### [8] Step : checkInstance Manager performs instance-level validations, including ownership, existence, lock status, or other pre-update checks. --- ### [9] Action : checkOldPassword **Action Type**: `ValidationAction` Check if the current password mathces the old password. It is done after the instance is fetched. ```js class Api { async checkOldPassword() { if (this.checkAbsolute()) return true; const isValid = this.hashCompare(this.oldPassword, this.user.password); if (!isValid) { throw new ForbiddenError("TheOldPasswordDoesNotMatch"); } return isValid; } } ``` --- ### [10] Step : buildDataClause Manager prepares the data clause for the update, applying transformations or enhancements before persisting. You can use the following settings to change some behavior of this step. `dataClause` --- ### [11] Step : mainUpdateOperation Manager executes the update operation with the WHERE and data clauses. Database-level events are raised if configured. --- ### [12] Step : buildOutput Manager assembles the response object from the update result, masking fields or injecting additional metadata. --- ### [13] Step : sendResponse Manager sends the response back to the controller for delivery to the client. --- ### [14] Step : raiseApiEvent Manager triggers API-level events, sending relevant messages to Kafka or other integrations if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `updateUserPassword` api has got 3 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | oldPassword | String | true | request.body?.oldPassword | | newPassword | String | true | request.body?.newPassword | ### REST Request To access the api you can use the **REST** controller with the path **PATCH /v1/userpassword/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpassword/${userId}`, data: { oldPassword:"String", newPassword:"String", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`user`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Update Userpasswordbyadmin` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `updateUserPasswordByAdmin` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `updateUserPasswordByAdmin` Business API is designed to handle a `update` operation on the `User` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description This route is used to change any user password by admins only. Superadmin can chnage all passwords, admins can change only nonadmin passwords ## API Options * **Auto Params** : `false` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `userpasswordbyadmin-updated` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `updateUserPasswordByAdmin` Business API includes a REST controller that can be triggered via the following route: `/v1/userpasswordbyadmin/:userId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### gRPC Controller The `updateUserPasswordByAdmin` Business API includes a gRPC controller that can be triggered via the following function: `updateUserPasswordByAdmin()` By calling this gRPC endpoint using a gRPC client, you can execute the Business API. Note that all parameters must be provided as function arguments, regardless of their HTTP location configuration, which is relevant only for the REST controller. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `updateUserPasswordByAdmin` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `updateUserPasswordByAdmin` Business API has 2 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `userId` | `ID` | `Yes` | `-` | `urlpath` | `userId` | | **Description:** | This id paremeter is used to select the required data object that will be updated | | | | | | | | | | | | | `password` | `String` | `Yes` | `-` | `body` | `password` | | **Description:** | The new password of the user to be updated | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. * `password`: ```javascript this.password = this.password ? this.hashString(this.password) : null ``` ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `updateUserPasswordByAdmin` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin]` - **Check roles** (must pass basic role checks): Users must have at least one of the following roles to execute this API: `[superAdmin`, `admin]` --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.userId},{isActive:true}]} ``` ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. An update data clause populates all update-allowed properties of a data object, however the null properties (that are not provided by client) are ignored in db layer. **Custom Data Clause Override** ```js { password: this.password, } ``` **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { // password parameter is closed to update by client request // include it in data clause unless you are sure password: this.password, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request and session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads parameters from the request or Redis, applies defaults, and writes them into context for downstream milestones. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts and derives any helper values or reshaped payloads into the context. --- ### [4] Step : checkParameters Manager validates required parameters, checks ID formats (UUID/ObjectId), and ensures all preconditions for update are met. --- ### [5] Step : checkBasicAuth Manager performs login verification, role, and permission checks, enforcing tenant and access rules before update. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager constructs the WHERE clause used to identify the record to update, applying ownership and parent checks if necessary. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the existing record from the database and writes it to the context for validation or enrichment. --- ### [8] Step : checkInstance Manager performs instance-level validations, including ownership, existence, lock status, or other pre-update checks. --- ### [9] Action : setRolesOrder **Action Type**: `CreateObjectAction` Sets the hiyerarchy of the roles to check user permissions on other users ```js class Api { async setRolesOrder() { // Construct base object const obj = {}; // Merge dynamic object Object.assign(obj, { superAdmin: 20, saasAdmin: 19, admin: 18, tenantOwner: 17, tenantAdmin: 16, saasUser: 15, tenantUser: 14, user: 13, }); return obj; } } ``` --- ### [10] Action : protectHigherRole **Action Type**: `ValidationAction` Prevents the update of a higher or equal user role ```js class Api { async protectHigherRole() { const isValid = (this._r[this.session.roleId] ?? 0) > (this._r[this.user.roleId] ?? 0); if (!isValid) { throw new BadRequestError("AHigherUserCantBeUpdated"); } return isValid; } } ``` --- ### [11] Step : buildDataClause Manager prepares the data clause for the update, applying transformations or enhancements before persisting. You can use the following settings to change some behavior of this step. `dataClause` --- ### [12] Step : mainUpdateOperation Manager executes the update operation with the WHERE and data clauses. Database-level events are raised if configured. --- ### [13] Step : buildOutput Manager assembles the response object from the update result, masking fields or injecting additional metadata. --- ### [14] Step : sendResponse Manager sends the response back to the controller for delivery to the client. --- ### [15] Step : raiseApiEvent Manager triggers API-level events, sending relevant messages to Kafka or other integrations if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `updateUserPasswordByAdmin` api has got 2 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | password | String | true | request.body?.password | ### REST Request To access the api you can use the **REST** controller with the path **PATCH /v1/userpasswordbyadmin/:userId** ```js axios({ method: 'PATCH', url: `/v1/userpasswordbyadmin/${userId}`, data: { password:"String", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`user`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Update Userrole` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `updateUserRole` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `updateUserRole` Business API is designed to handle a `update` operation on the `User` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description This route is used by admin roles to update the user role.The default role is user when a user is registered. A user's role can be updated by superAdmin or admin ## API Options * **Auto Params** : `false` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `userrole-updated` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `updateUserRole` Business API includes a REST controller that can be triggered via the following route: `/v1/userrole/:userId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### gRPC Controller The `updateUserRole` Business API includes a gRPC controller that can be triggered via the following function: `updateUserRole()` By calling this gRPC endpoint using a gRPC client, you can execute the Business API. Note that all parameters must be provided as function arguments, regardless of their HTTP location configuration, which is relevant only for the REST controller. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `updateUserRole` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `updateUserRole` Business API has 2 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `userId` | `ID` | `Yes` | `-` | `urlpath` | `userId` | | **Description:** | This id paremeter is used to select the required data object that will be updated | | | | | | | | | | | | | `roleId` | `String` | `Yes` | `-` | `body` | `roleId` | | **Description:** | The new roleId of the user to be updated | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `updateUserRole` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin]` - **Check roles** (must pass basic role checks): Users must have at least one of the following roles to execute this API: `[superAdmin`, `admin]` --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.userId},{isActive:true}]} ``` ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. An update data clause populates all update-allowed properties of a data object, however the null properties (that are not provided by client) are ignored in db layer. **Custom Data Clause Override** ```js { roleId: this.roleId, } ``` **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { // roleId parameter is closed to update by client request // include it in data clause unless you are sure roleId: this.roleId, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request and session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads parameters from the request or Redis, applies defaults, and writes them into context for downstream milestones. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts and derives any helper values or reshaped payloads into the context. --- ### [4] Step : checkParameters Manager validates required parameters, checks ID formats (UUID/ObjectId), and ensures all preconditions for update are met. --- ### [5] Step : checkBasicAuth Manager performs login verification, role, and permission checks, enforcing tenant and access rules before update. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Action : setRolesOrder **Action Type**: `CreateObjectAction` Sets the hiyerarchy of the roles to check user permissions on other users ```js class Api { async setRolesOrder() { // Construct base object const obj = {}; // Merge dynamic object Object.assign(obj, { superAdmin: 20, saasAdmin: 19, admin: 18, tenantOwner: 17, tenantAdmin: 16, saasUser: 15, tenantUser: 0, user: 0, }); return obj; } } ``` --- ### [7] Action : preventHigherRoleSet **Action Type**: `ValidationAction` Prevents to set a user's role as higher than or equal to the setter role ```js class Api { async preventHigherRoleSet() { const isValid = (this._r[this.session.roleId] ?? 0) > (this._r[this.roleId] ?? 0); if (!isValid) { throw new BadRequestError("AHigherRoleCantBeAssigned"); } return isValid; } } ``` --- ### [8] Step : buildWhereClause Manager constructs the WHERE clause used to identify the record to update, applying ownership and parent checks if necessary. You can use the following settings to change some behavior of this step. `whereClause` --- ### [9] Step : fetchInstance Manager fetches the existing record from the database and writes it to the context for validation or enrichment. --- ### [10] Action : protectHigherRole **Action Type**: `ValidationAction` Prevents the update of a higher or equal user role ```js class Api { async protectHigherRole() { const isValid = (this._r[this.session.roleId] ?? 0) > (this._r[this.user.roleId] ?? 0); if (!isValid) { throw new BadRequestError("AHigherUserRoleCantBeChanged"); } return isValid; } } ``` --- ### [11] Step : checkInstance Manager performs instance-level validations, including ownership, existence, lock status, or other pre-update checks. --- ### [12] Step : buildDataClause Manager prepares the data clause for the update, applying transformations or enhancements before persisting. You can use the following settings to change some behavior of this step. `dataClause` --- ### [13] Step : mainUpdateOperation Manager executes the update operation with the WHERE and data clauses. Database-level events are raised if configured. --- ### [14] Step : buildOutput Manager assembles the response object from the update result, masking fields or injecting additional metadata. --- ### [15] Step : sendResponse Manager sends the response back to the controller for delivery to the client. --- ### [16] Step : raiseApiEvent Manager triggers API-level events, sending relevant messages to Kafka or other integrations if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `updateUserRole` api has got 2 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | ID | true | request.params?.userId | | roleId | String | true | request.body?.roleId | ### REST Request To access the api you can use the **REST** controller with the path **PATCH /v1/userrole/:userId** ```js axios({ method: 'PATCH', url: `/v1/userrole/${userId}`, data: { roleId:"String", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`user`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "user", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "user": { "id": "ID", "email": "String", "password": "String", "fullname": "String", "avatar": "String", "roleId": "String", "emailVerified": "Boolean", "phone": "String", "address": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Create Category` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `createCategory` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `createCategory` Business API is designed to handle a `create` operation on the `Category` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Create a new category (admin-only) for product classification. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `category-created` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `createCategory` Business API includes a REST controller that can be triggered via the following route: `/v1/categories` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `createCategory` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `createCategory` Business API has 4 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `categoryId` | `ID` | `No` | `-` | `body` | `categoryId` | | **Description:** | This id paremeter is used to create the data object with a given specific id. Leave null for automatic id. | | | | | | | | | | | | | `imageUrl` | `String` | `No` | `-` | `body` | `imageUrl` | | **Description:** | URL for category image/avatar (optional, used for homepage visuals). | | | | | | | | | | | | | `subtitle` | `String` | `No` | `-` | `body` | `subtitle` | | **Description:** | Optional short description for UI/tooltips. | | | | | | | | | | | | | `title` | `String` | `Yes` | `-` | `body` | `title` | | **Description:** | Display name of the category. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `createCategory` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { id: this.categoryId, imageUrl: this.imageUrl, subtitle: this.subtitle, title: this.title, isActive: true, _archivedAt: null, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, populates session and request objects, prepares internal structures for parameter handling and workflow execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads input parameters, normalizes missing values, applies default type casting, and stores them in the API context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager transforms parameters, computes derived values, flattens or remaps arrays/objects, and adjusts formats for downstream processing. --- ### [4] Step : checkParameters Manager executes built-in validations: required field checks, type enforcement, and basic business rules. Prevents operation if validation fails. --- ### [5] Step : checkBasicAuth Manager performs authentication and authorization checks: verifies session, user roles, permissions, and tenant restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildDataClause Manager constructs the final data object for creation, fills auto-generated fields (IDs, timestamps, owner fields), and ensures schema consistency. You can use the following settings to change some behavior of this step. `dataClause` --- ### [7] Step : mainCreateOperation Manager executes the database insert operation, updates indexes/caches, and triggers internal post-processing like linked default records. --- ### [8] Step : buildOutput Manager shapes the response: masks sensitive fields, resolves linked references, and formats output according to API contract. --- ### [9] Step : sendResponse Manager sends the response to the client and finalizes internal tasks like flushing logs or updating session state. --- ### [10] Step : raiseApiEvent Manager triggers API-level events (Kafka, WebSocket, async workflows) as the final internal step. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `createCategory` api has got 3 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | true | request.body?.title | ### REST Request To access the api you can use the **REST** controller with the path **POST /v1/categories** ```js axios({ method: 'POST', url: '/v1/categories', data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`category`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Create Subcategory` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `createSubcategory` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `createSubcategory` Business API is designed to handle a `create` operation on the `Subcategory` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Create a new subcategory under a given category (admin-only), with enum group constraint. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `subcategory-created` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `createSubcategory` Business API includes a REST controller that can be triggered via the following route: `/v1/subcategories` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `createSubcategory` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `createSubcategory` Business API has 4 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `subcategoryId` | `ID` | `No` | `-` | `body` | `subcategoryId` | | **Description:** | This id paremeter is used to create the data object with a given specific id. Leave null for automatic id. | | | | | | | | | | | | | `categoryId` | `ID` | `Yes` | `-` | `body` | `categoryId` | | **Description:** | Reference to the parent category (category.id). | | | | | | | | | | | | | `name` | `String` | `Yes` | `-` | `body` | `name` | | **Description:** | Display name of the subcategory. | | | | | | | | | | | | | `group` | `Enum` | `Yes` | `-` | `body` | `group` | | **Description:** | Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `createSubcategory` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { id: this.subcategoryId, categoryId: this.categoryId, name: this.name, group: this.group, isActive: true, _archivedAt: null, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, populates session and request objects, prepares internal structures for parameter handling and workflow execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads input parameters, normalizes missing values, applies default type casting, and stores them in the API context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager transforms parameters, computes derived values, flattens or remaps arrays/objects, and adjusts formats for downstream processing. --- ### [4] Step : checkParameters Manager executes built-in validations: required field checks, type enforcement, and basic business rules. Prevents operation if validation fails. --- ### [5] Step : checkBasicAuth Manager performs authentication and authorization checks: verifies session, user roles, permissions, and tenant restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildDataClause Manager constructs the final data object for creation, fills auto-generated fields (IDs, timestamps, owner fields), and ensures schema consistency. You can use the following settings to change some behavior of this step. `dataClause` --- ### [7] Step : mainCreateOperation Manager executes the database insert operation, updates indexes/caches, and triggers internal post-processing like linked default records. --- ### [8] Step : buildOutput Manager shapes the response: masks sensitive fields, resolves linked references, and formats output according to API contract. --- ### [9] Step : sendResponse Manager sends the response to the client and finalizes internal tasks like flushing logs or updating session state. --- ### [10] Step : raiseApiEvent Manager triggers API-level events (Kafka, WebSocket, async workflows) as the final internal step. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `createSubcategory` api has got 3 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.body?.categoryId | | name | String | true | request.body?.name | | group | Enum | true | request.body?.group | ### REST Request To access the api you can use the **REST** controller with the path **POST /v1/subcategories** ```js axios({ method: 'POST', url: '/v1/subcategories', data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`subcategory`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Delete Category` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `deleteCategory` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `deleteCategory` Business API is designed to handle a `delete` operation on the `Category` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Soft-delete a category (admin-only). ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `category-deleted` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `deleteCategory` Business API includes a REST controller that can be triggered via the following route: `/v1/categories/:categoryId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `deleteCategory` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `deleteCategory` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `categoryId` | `ID` | `Yes` | `-` | `urlpath` | `categoryId` | | **Description:** | This id paremeter is used to select the required data object that will be deleted | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `deleteCategory` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.categoryId},{isActive:true}]} ``` ## Delete Options Use these options to set `delete` specific settings. **useSoftDelete**: false If true, the record will be marked as deleted `(isActive: false)` instead of removed. The implementation depends on the data object’s soft delete configuration. ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request/session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads and normalizes parameters, applies defaults, and stores them in the context for downstream steps. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts, computes derived values, and remaps objects or arrays as needed for later processing. --- ### [4] Step : checkParameters Manager runs built-in validations including required field checks, type enforcement, and deletion preconditions. Stops execution if validation fails. --- ### [5] Step : checkBasicAuth Manager validates session, user roles, permissions, and tenant-specific access rules to enforce basic auth restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager generates the query conditions, applies ownership and parent checks, and ensures the clause is correct for the delete operation. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the target record, applies filters from WHERE clause, and writes the instance to the context for further checks. --- ### [8] Step : checkInstance Manager performs object-level validations such as lock status, soft-delete eligibility, and multi-step approval enforcement. --- ### [9] Step : mainDeleteOperation Manager executes the delete query, updates related indexes/caches, and handles soft/hard delete logic according to configuration. You can use the following settings to change some behavior of this step. `deleteOptions` --- ### [10] Step : buildOutput Manager shapes the response payload, masks sensitive fields, and formats related cleanup results for output. --- ### [11] Step : sendResponse Manager delivers the response to the client and finalizes any temporary internal structures. --- ### [12] Step : raiseApiEvent Manager triggers asynchronous API events, notifies queues or streams, and performs final cleanup for the workflow. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `deleteCategory` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | ### REST Request To access the api you can use the **REST** controller with the path **DELETE /v1/categories/:categoryId** ```js axios({ method: 'DELETE', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`category`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Delete Subcategory` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `deleteSubcategory` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `deleteSubcategory` Business API is designed to handle a `delete` operation on the `Subcategory` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Soft-delete a subcategory (admin-only). ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `subcategory-deleted` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `deleteSubcategory` Business API includes a REST controller that can be triggered via the following route: `/v1/subcategories/:subcategoryId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `deleteSubcategory` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `deleteSubcategory` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `subcategoryId` | `ID` | `Yes` | `-` | `urlpath` | `subcategoryId` | | **Description:** | This id paremeter is used to select the required data object that will be deleted | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `deleteSubcategory` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.subcategoryId},{isActive:true}]} ``` ## Delete Options Use these options to set `delete` specific settings. **useSoftDelete**: false If true, the record will be marked as deleted `(isActive: false)` instead of removed. The implementation depends on the data object’s soft delete configuration. ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request/session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads and normalizes parameters, applies defaults, and stores them in the context for downstream steps. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts, computes derived values, and remaps objects or arrays as needed for later processing. --- ### [4] Step : checkParameters Manager runs built-in validations including required field checks, type enforcement, and deletion preconditions. Stops execution if validation fails. --- ### [5] Step : checkBasicAuth Manager validates session, user roles, permissions, and tenant-specific access rules to enforce basic auth restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager generates the query conditions, applies ownership and parent checks, and ensures the clause is correct for the delete operation. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the target record, applies filters from WHERE clause, and writes the instance to the context for further checks. --- ### [8] Step : checkInstance Manager performs object-level validations such as lock status, soft-delete eligibility, and multi-step approval enforcement. --- ### [9] Step : mainDeleteOperation Manager executes the delete query, updates related indexes/caches, and handles soft/hard delete logic according to configuration. You can use the following settings to change some behavior of this step. `deleteOptions` --- ### [10] Step : buildOutput Manager shapes the response payload, masks sensitive fields, and formats related cleanup results for output. --- ### [11] Step : sendResponse Manager delivers the response to the client and finalizes any temporary internal structures. --- ### [12] Step : raiseApiEvent Manager triggers asynchronous API events, notifies queues or streams, and performs final cleanup for the workflow. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `deleteSubcategory` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | ### REST Request To access the api you can use the **REST** controller with the path **DELETE /v1/subcategories/:subcategoryId** ```js axios({ method: 'DELETE', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`subcategory`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Get Category` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `getCategory` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `getCategory` Business API is designed to handle a `get` operation on the `Category` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Get a single category by ID. Public - only active categories returned (for non-admins). ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `category-retrived` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `getCategory` Business API includes a REST controller that can be triggered via the following route: `/v1/categories/:categoryId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `getCategory` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `getCategory` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `categoryId` | `ID` | `Yes` | `-` | `urlpath` | `categoryId` | | **Description:** | This id paremeter is used to query the required data object. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `getCategory` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.categoryId},{isActive:true}]} ``` ## Get Options Use these options to set `get` specific settings. **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Extracts parameters from request and Redis, applies defaults, and writes them to context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Executes parameter transformation scripts, applies type coercion, merges derived values, and reshapes inputs for downstream milestones. --- ### [4] Step : checkParameters Validates required and custom parameters, enforcing business-specific rules and constraints. --- ### [5] Step : checkBasicAuth Performs login, role, and permission checks, and applies dynamic object-level access rules. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Builds the WHERE clause for fetching the object and applies additional scoped filters if configured. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainGetOperation Executes the database fetch, retrieves the object, and stores it in context for enrichment or further checks. You can use the following settings to change some behavior of this step. `selectClause`, `getOptions` --- ### [8] Step : checkInstance Performs instance-level validations, such as ownership, existence, or access conditions. --- ### [9] Step : buildOutput Assembles the response from the object, applies masking, formatting, and injects additional metadata if needed. --- ### [10] Step : sendResponse Delivers the response to the controller for client delivery. --- ### [11] Step : raiseApiEvent Triggers optional API-level events after workflow completion, sending messages to integrations like Kafka if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `getCategory` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/categories/:categoryId** ```js axios({ method: 'GET', url: `/v1/categories/${categoryId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`category`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Get Subcategory` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `getSubcategory` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `getSubcategory` Business API is designed to handle a `get` operation on the `Subcategory` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Get a subcategory by ID. Public - only active subcategories returned except for admin. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `subcategory-retrived` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `getSubcategory` Business API includes a REST controller that can be triggered via the following route: `/v1/subcategories/:subcategoryId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `getSubcategory` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `getSubcategory` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `subcategoryId` | `ID` | `Yes` | `-` | `urlpath` | `subcategoryId` | | **Description:** | This id paremeter is used to query the required data object. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `getSubcategory` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.subcategoryId},{isActive:true}]} ``` ## Get Options Use these options to set `get` specific settings. **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Extracts parameters from request and Redis, applies defaults, and writes them to context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Executes parameter transformation scripts, applies type coercion, merges derived values, and reshapes inputs for downstream milestones. --- ### [4] Step : checkParameters Validates required and custom parameters, enforcing business-specific rules and constraints. --- ### [5] Step : checkBasicAuth Performs login, role, and permission checks, and applies dynamic object-level access rules. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Builds the WHERE clause for fetching the object and applies additional scoped filters if configured. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainGetOperation Executes the database fetch, retrieves the object, and stores it in context for enrichment or further checks. You can use the following settings to change some behavior of this step. `selectClause`, `getOptions` --- ### [8] Step : checkInstance Performs instance-level validations, such as ownership, existence, or access conditions. --- ### [9] Step : buildOutput Assembles the response from the object, applies masking, formatting, and injects additional metadata if needed. --- ### [10] Step : sendResponse Delivers the response to the controller for client delivery. --- ### [11] Step : raiseApiEvent Triggers optional API-level events after workflow completion, sending messages to integrations like Kafka if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `getSubcategory` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/subcategories/:subcategoryId** ```js axios({ method: 'GET', url: `/v1/subcategories/${subcategoryId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`subcategory`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `List Categories` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `listCategories` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `listCategories` Business API is designed to handle a `list` operation on the `Category` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description List all categories for browsing and filtering. Only active categories shown to public/non-admin users. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `categories-listed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `listCategories` Business API includes a REST controller that can be triggered via the following route: `/v1/categories` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `listCategories` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `listCategories` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `listCategories` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {isActive:true} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `listCategories` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/categories** ```js axios({ method: 'GET', url: '/v1/categories', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`categories`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "categories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "categories": [ { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `List Subcategories` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `listSubcategories` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `listSubcategories` Business API is designed to handle a `list` operation on the `Subcategory` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description List all subcategories for browsing/filtering, with support for group enum and parent category queries. Only active subcategories shown to public/non-admin users. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `subcategories-listed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `listSubcategories` Business API includes a REST controller that can be triggered via the following route: `/v1/subcategories` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `listSubcategories` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `listSubcategories` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `listSubcategories` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {isActive:true} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `listSubcategories` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/subcategories** ```js axios({ method: 'GET', url: '/v1/subcategories', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`subcategories`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategories", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "subcategories": [ { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `Update Category` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `updateCategory` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `updateCategory` Business API is designed to handle a `update` operation on the `Category` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Update category details (admin-only). ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `category-updated` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `updateCategory` Business API includes a REST controller that can be triggered via the following route: `/v1/categories/:categoryId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `updateCategory` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `updateCategory` Business API has 4 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `categoryId` | `ID` | `Yes` | `-` | `urlpath` | `categoryId` | | **Description:** | This id paremeter is used to select the required data object that will be updated | | | | | | | | | | | | | `imageUrl` | `String` | `No` | `-` | `body` | `imageUrl` | | **Description:** | URL for category image/avatar (optional, used for homepage visuals). | | | | | | | | | | | | | `subtitle` | `String` | `No` | `-` | `body` | `subtitle` | | **Description:** | Optional short description for UI/tooltips. | | | | | | | | | | | | | `title` | `String` | `No` | `-` | `body` | `title` | | **Description:** | Display name of the category. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `updateCategory` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.categoryId},{isActive:true}]} ``` ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. An update data clause populates all update-allowed properties of a data object, however the null properties (that are not provided by client) are ignored in db layer. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { imageUrl: this.imageUrl, subtitle: this.subtitle, title: this.title, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request and session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads parameters from the request or Redis, applies defaults, and writes them into context for downstream milestones. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts and derives any helper values or reshaped payloads into the context. --- ### [4] Step : checkParameters Manager validates required parameters, checks ID formats (UUID/ObjectId), and ensures all preconditions for update are met. --- ### [5] Step : checkBasicAuth Manager performs login verification, role, and permission checks, enforcing tenant and access rules before update. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager constructs the WHERE clause used to identify the record to update, applying ownership and parent checks if necessary. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the existing record from the database and writes it to the context for validation or enrichment. --- ### [8] Step : checkInstance Manager performs instance-level validations, including ownership, existence, lock status, or other pre-update checks. --- ### [9] Step : buildDataClause Manager prepares the data clause for the update, applying transformations or enhancements before persisting. You can use the following settings to change some behavior of this step. `dataClause` --- ### [10] Step : mainUpdateOperation Manager executes the update operation with the WHERE and data clauses. Database-level events are raised if configured. --- ### [11] Step : buildOutput Manager assembles the response object from the update result, masking fields or injecting additional metadata. --- ### [12] Step : sendResponse Manager sends the response back to the controller for delivery to the client. --- ### [13] Step : raiseApiEvent Manager triggers API-level events, sending relevant messages to Kafka or other integrations if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `updateCategory` api has got 4 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | categoryId | ID | true | request.params?.categoryId | | imageUrl | String | false | request.body?.imageUrl | | subtitle | String | false | request.body?.subtitle | | title | String | false | request.body?.title | ### REST Request To access the api you can use the **REST** controller with the path **PATCH /v1/categories/:categoryId** ```js axios({ method: 'PATCH', url: `/v1/categories/${categoryId}`, data: { imageUrl:"String", subtitle:"String", title:"String", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`category`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "category", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "category": { "id": "ID", "imageUrl": "String", "subtitle": "String", "title": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Update Subcategory` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `updateSubcategory` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `updateSubcategory` Business API is designed to handle a `update` operation on the `Subcategory` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Update subcategory (admin-only), including group enum change. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `subcategory-updated` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `updateSubcategory` Business API includes a REST controller that can be triggered via the following route: `/v1/subcategories/:subcategoryId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `updateSubcategory` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `updateSubcategory` Business API has 4 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `subcategoryId` | `ID` | `Yes` | `-` | `urlpath` | `subcategoryId` | | **Description:** | This id paremeter is used to select the required data object that will be updated | | | | | | | | | | | | | `categoryId` | `ID` | `No` | `-` | `body` | `categoryId` | | **Description:** | Reference to the parent category (category.id). | | | | | | | | | | | | | `name` | `String` | `No` | `-` | `body` | `name` | | **Description:** | Display name of the subcategory. | | | | | | | | | | | | | `group` | `Enum` | `No` | `-` | `body` | `group` | | **Description:** | Classification for subcategory display; restrict to enum of MOST_POPULAR or MORE. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `updateSubcategory` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.subcategoryId},{isActive:true}]} ``` ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. An update data clause populates all update-allowed properties of a data object, however the null properties (that are not provided by client) are ignored in db layer. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { categoryId: this.categoryId, name: this.name, group: this.group, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request and session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads parameters from the request or Redis, applies defaults, and writes them into context for downstream milestones. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts and derives any helper values or reshaped payloads into the context. --- ### [4] Step : checkParameters Manager validates required parameters, checks ID formats (UUID/ObjectId), and ensures all preconditions for update are met. --- ### [5] Step : checkBasicAuth Manager performs login verification, role, and permission checks, enforcing tenant and access rules before update. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager constructs the WHERE clause used to identify the record to update, applying ownership and parent checks if necessary. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the existing record from the database and writes it to the context for validation or enrichment. --- ### [8] Step : checkInstance Manager performs instance-level validations, including ownership, existence, lock status, or other pre-update checks. --- ### [9] Step : buildDataClause Manager prepares the data clause for the update, applying transformations or enhancements before persisting. You can use the following settings to change some behavior of this step. `dataClause` --- ### [10] Step : mainUpdateOperation Manager executes the update operation with the WHERE and data clauses. Database-level events are raised if configured. --- ### [11] Step : buildOutput Manager assembles the response object from the update result, masking fields or injecting additional metadata. --- ### [12] Step : sendResponse Manager sends the response back to the controller for delivery to the client. --- ### [13] Step : raiseApiEvent Manager triggers API-level events, sending relevant messages to Kafka or other integrations if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `updateSubcategory` api has got 4 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | subcategoryId | ID | true | request.params?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | name | String | false | request.body?.name | | group | Enum | false | request.body?.group | ### REST Request To access the api you can use the **REST** controller with the path **PATCH /v1/subcategories/:subcategoryId** ```js axios({ method: 'PATCH', url: `/v1/subcategories/${subcategoryId}`, data: { categoryId:"ID", name:"String", group:"Enum", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`subcategory`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "subcategory", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "subcategory": { "id": "ID", "categoryId": "ID", "name": "String", "group": "Enum", "group_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Create Feedback` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `createFeedback` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `createFeedback` Business API is designed to handle a `create` operation on the `Feedback` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Buyer creates feedback for a delivered order item. Only allowed once per (buyer, orderItemId). Allowed only once order item is delivered. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `feedback-created` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `createFeedback` Business API includes a REST controller that can be triggered via the following route: `/v1/feedbacks` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `createFeedback` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `createFeedback` Business API has 8 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `feedbackId` | `ID` | `No` | `-` | `body` | `feedbackId` | | **Description:** | This id paremeter is used to create the data object with a given specific id. Leave null for automatic id. | | | | | | | | | | | | | `rating` | `Integer` | `Yes` | `-` | `body` | `rating` | | **Description:** | Rating (1-5 stars) submitted by buyer. Required. | | | | | | | | | | | | | `orderId` | `ID` | `Yes` | `-` | `body` | `orderId` | | **Description:** | Order containing this purchased item. Used for aggregation and validation. | | | | | | | | | | | | | `buyerId` | `ID` | `Yes` | `-` | `session` | `userId` | | **Description:** | User/buyer leaving feedback. Authenticated user, must match order item buyer. | | | | | | | | | | | | | `orderItemId` | `ID` | `Yes` | `-` | `body` | `orderItemId` | | **Description:** | Purchased item (line item) in order. Feedback is per (buyer, orderItem). | | | | | | | | | | | | | `sellerId` | `ID` | `Yes` | `-` | `body` | `sellerId` | | **Description:** | Seller of product for analytics/aggregation. Not author; used for querying feedback about sellers. | | | | | | | | | | | | | `comment` | `String` | `No` | `-` | `body` | `comment` | | **Description:** | Optional textual feedback comment, max ~500 chars. | | | | | | | | | | | | | `productId` | `ID` | `Yes` | `-` | `body` | `productId` | | **Description:** | The product listing being reviewed (snapshot at order time). | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `createFeedback` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { id: this.feedbackId, rating: this.rating, orderId: this.orderId, buyerId: this.buyerId, orderItemId: this.orderItemId, sellerId: this.sellerId, comment: this.comment, productId: this.productId, isActive: true, _archivedAt: null, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, populates session and request objects, prepares internal structures for parameter handling and workflow execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads input parameters, normalizes missing values, applies default type casting, and stores them in the API context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager transforms parameters, computes derived values, flattens or remaps arrays/objects, and adjusts formats for downstream processing. --- ### [4] Step : checkParameters Manager executes built-in validations: required field checks, type enforcement, and basic business rules. Prevents operation if validation fails. --- ### [5] Step : checkBasicAuth Manager performs authentication and authorization checks: verifies session, user roles, permissions, and tenant restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildDataClause Manager constructs the final data object for creation, fills auto-generated fields (IDs, timestamps, owner fields), and ensures schema consistency. You can use the following settings to change some behavior of this step. `dataClause` --- ### [7] Step : mainCreateOperation Manager executes the database insert operation, updates indexes/caches, and triggers internal post-processing like linked default records. --- ### [8] Step : buildOutput Manager shapes the response: masks sensitive fields, resolves linked references, and formats output according to API contract. --- ### [9] Step : sendResponse Manager sends the response to the client and finalizes internal tasks like flushing logs or updating session state. --- ### [10] Step : raiseApiEvent Manager triggers API-level events (Kafka, WebSocket, async workflows) as the final internal step. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `createFeedback` api has got 6 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | rating | Integer | true | request.body?.rating | | orderId | ID | true | request.body?.orderId | | orderItemId | ID | true | request.body?.orderItemId | | sellerId | ID | true | request.body?.sellerId | | comment | String | false | request.body?.comment | | productId | ID | true | request.body?.productId | ### REST Request To access the api you can use the **REST** controller with the path **POST /v1/feedbacks** ```js axios({ method: 'POST', url: '/v1/feedbacks', data: { rating:"Integer", orderId:"ID", orderItemId:"ID", sellerId:"ID", comment:"String", productId:"ID", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`feedback`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Delete Feedback` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `deleteFeedback` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `deleteFeedback` Business API is designed to handle a `delete` operation on the `Feedback` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Delete (soft-delete) feedback (by buyer or admin). Only feedback owner or admin. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `feedback-deleted` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `deleteFeedback` Business API includes a REST controller that can be triggered via the following route: `/v1/feedbacks/:feedbackId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `deleteFeedback` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `deleteFeedback` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `feedbackId` | `ID` | `Yes` | `-` | `urlpath` | `feedbackId` | | **Description:** | This id paremeter is used to select the required data object that will be deleted | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `deleteFeedback` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks This Business API enforces ownership of the main data object before executing the operation. - The check is performed **after fetching the object instance**. If the current user is not the owner, the API will respond with **403 Forbidden**. Note: Ownership checks are applied **only if the objects have an owner field**. --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.feedbackId},{isActive:true}]} ``` ## Delete Options Use these options to set `delete` specific settings. **useSoftDelete**: false If true, the record will be marked as deleted `(isActive: false)` instead of removed. The implementation depends on the data object’s soft delete configuration. ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request/session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads and normalizes parameters, applies defaults, and stores them in the context for downstream steps. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts, computes derived values, and remaps objects or arrays as needed for later processing. --- ### [4] Step : checkParameters Manager runs built-in validations including required field checks, type enforcement, and deletion preconditions. Stops execution if validation fails. --- ### [5] Step : checkBasicAuth Manager validates session, user roles, permissions, and tenant-specific access rules to enforce basic auth restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager generates the query conditions, applies ownership and parent checks, and ensures the clause is correct for the delete operation. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the target record, applies filters from WHERE clause, and writes the instance to the context for further checks. --- ### [8] Step : checkInstance Manager performs object-level validations such as lock status, soft-delete eligibility, and multi-step approval enforcement. --- ### [9] Step : mainDeleteOperation Manager executes the delete query, updates related indexes/caches, and handles soft/hard delete logic according to configuration. You can use the following settings to change some behavior of this step. `deleteOptions` --- ### [10] Step : buildOutput Manager shapes the response payload, masks sensitive fields, and formats related cleanup results for output. --- ### [11] Step : sendResponse Manager delivers the response to the client and finalizes any temporary internal structures. --- ### [12] Step : raiseApiEvent Manager triggers asynchronous API events, notifies queues or streams, and performs final cleanup for the workflow. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `deleteFeedback` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | ### REST Request To access the api you can use the **REST** controller with the path **DELETE /v1/feedbacks/:feedbackId** ```js axios({ method: 'DELETE', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`feedback`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Get Feedback` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `getFeedback` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `getFeedback` Business API is designed to handle a `get` operation on the `Feedback` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Get a single feedback by id. Accessible to public (for seller profile, product, or audit views). ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `feedback-retrived` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `getFeedback` Business API includes a REST controller that can be triggered via the following route: `/v1/feedbacks/:feedbackId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `getFeedback` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `getFeedback` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `feedbackId` | `ID` | `Yes` | `-` | `urlpath` | `feedbackId` | | **Description:** | This id paremeter is used to query the required data object. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `getFeedback` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks This Business API enforces ownership of the main data object before executing the operation. - The check is performed **after fetching the object instance**. If the current user is not the owner, the API will respond with **403 Forbidden**. Note: Ownership checks are applied **only if the objects have an owner field**. --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.feedbackId},{isActive:true}]} ``` ## Get Options Use these options to set `get` specific settings. **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Extracts parameters from request and Redis, applies defaults, and writes them to context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Executes parameter transformation scripts, applies type coercion, merges derived values, and reshapes inputs for downstream milestones. --- ### [4] Step : checkParameters Validates required and custom parameters, enforcing business-specific rules and constraints. --- ### [5] Step : checkBasicAuth Performs login, role, and permission checks, and applies dynamic object-level access rules. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Builds the WHERE clause for fetching the object and applies additional scoped filters if configured. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainGetOperation Executes the database fetch, retrieves the object, and stores it in context for enrichment or further checks. You can use the following settings to change some behavior of this step. `selectClause`, `getOptions` --- ### [8] Step : checkInstance Performs instance-level validations, such as ownership, existence, or access conditions. --- ### [9] Step : buildOutput Assembles the response from the object, applies masking, formatting, and injects additional metadata if needed. --- ### [10] Step : sendResponse Delivers the response to the controller for client delivery. --- ### [11] Step : raiseApiEvent Triggers optional API-level events after workflow completion, sending messages to integrations like Kafka if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `getFeedback` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/feedbacks/:feedbackId** ```js axios({ method: 'GET', url: `/v1/feedbacks/${feedbackId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`feedback`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `List Feedbacks` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `listFeedbacks` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `listFeedbacks` Business API is designed to handle a `list` operation on the `Feedback` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description List feedback with filtering by buyerId (given), sellerId (received), productId, or orderItemId. Used for showing seller profile, buyer profile, or order analytics. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `feedbacks-listed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `listFeedbacks` Business API includes a REST controller that can be triggered via the following route: `/v1/feedbacks` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `listFeedbacks` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `listFeedbacks` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `listFeedbacks` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {isActive:true} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `listFeedbacks` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/feedbacks** ```js axios({ method: 'GET', url: '/v1/feedbacks', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`feedbacks`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedbacks", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "feedbacks": [ { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `Update Feedback` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `updateFeedback` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `updateFeedback` Business API is designed to handle a `update` operation on the `Feedback` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Update feedback (comment/rating) for existing feedback record (buyer only). Admin can update as override. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `feedback-updated` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `updateFeedback` Business API includes a REST controller that can be triggered via the following route: `/v1/feedbacks/:feedbackId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `updateFeedback` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `updateFeedback` Business API has 3 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `feedbackId` | `ID` | `Yes` | `-` | `urlpath` | `feedbackId` | | **Description:** | This id paremeter is used to select the required data object that will be updated | | | | | | | | | | | | | `rating` | `Integer` | `No` | `-` | `body` | `rating` | | **Description:** | Rating (1-5 stars) submitted by buyer. Required. | | | | | | | | | | | | | `comment` | `String` | `No` | `-` | `body` | `comment` | | **Description:** | Optional textual feedback comment, max ~500 chars. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `updateFeedback` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks This Business API enforces ownership of the main data object before executing the operation. - The check is performed **after fetching the object instance**. If the current user is not the owner, the API will respond with **403 Forbidden**. Note: Ownership checks are applied **only if the objects have an owner field**. --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.feedbackId},{isActive:true}]} ``` ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. An update data clause populates all update-allowed properties of a data object, however the null properties (that are not provided by client) are ignored in db layer. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { rating: this.rating, comment: this.comment, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request and session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads parameters from the request or Redis, applies defaults, and writes them into context for downstream milestones. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts and derives any helper values or reshaped payloads into the context. --- ### [4] Step : checkParameters Manager validates required parameters, checks ID formats (UUID/ObjectId), and ensures all preconditions for update are met. --- ### [5] Step : checkBasicAuth Manager performs login verification, role, and permission checks, enforcing tenant and access rules before update. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager constructs the WHERE clause used to identify the record to update, applying ownership and parent checks if necessary. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the existing record from the database and writes it to the context for validation or enrichment. --- ### [8] Step : checkInstance Manager performs instance-level validations, including ownership, existence, lock status, or other pre-update checks. --- ### [9] Step : buildDataClause Manager prepares the data clause for the update, applying transformations or enhancements before persisting. You can use the following settings to change some behavior of this step. `dataClause` --- ### [10] Step : mainUpdateOperation Manager executes the update operation with the WHERE and data clauses. Database-level events are raised if configured. --- ### [11] Step : buildOutput Manager assembles the response object from the update result, masking fields or injecting additional metadata. --- ### [12] Step : sendResponse Manager sends the response back to the controller for delivery to the client. --- ### [13] Step : raiseApiEvent Manager triggers API-level events, sending relevant messages to Kafka or other integrations if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `updateFeedback` api has got 3 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | feedbackId | ID | true | request.params?.feedbackId | | rating | Integer | false | request.body?.rating | | comment | String | false | request.body?.comment | ### REST Request To access the api you can use the **REST** controller with the path **PATCH /v1/feedbacks/:feedbackId** ```js axios({ method: 'PATCH', url: `/v1/feedbacks/${feedbackId}`, data: { rating:"Integer", comment:"String", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`feedback`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "feedback", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "feedback": { "id": "ID", "rating": "Integer", "orderId": "ID", "buyerId": "ID", "orderItemId": "ID", "sellerId": "ID", "comment": "String", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Create Messagingmessage` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `createMessagingMessage` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `createMessagingMessage` Business API is designed to handle a `create` operation on the `MessagingMessage` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Send a new text message from the logged-in user to a recipient. Sender is set from session. Launch version supports only text content. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `messagingmessage-created` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `createMessagingMessage` Business API includes a REST controller that can be triggered via the following route: `/v1/messagingmessages` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `createMessagingMessage` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `createMessagingMessage` Business API has 6 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `messagingMessageId` | `ID` | `No` | `-` | `body` | `messagingMessageId` | | **Description:** | This id paremeter is used to create the data object with a given specific id. Leave null for automatic id. | | | | | | | | | | | | | `fromUserId` | `ID` | `Yes` | `-` | `session` | `userId` | | **Description:** | Sender (user) of this message. | | | | | | | | | | | | | `toUserId` | `ID` | `Yes` | `-` | `body` | `toUserId` | | **Description:** | Recipient (user) of this message. | | | | | | | | | | | | | `content` | `String` | `Yes` | `-` | `body` | `content` | | **Description:** | Text content of the message. No files or attachments for launch. | | | | | | | | | | | | | `isRead` | `Boolean` | `Yes` | `-` | `body` | `isRead` | | **Description:** | If true, recipient has marked this message as read. | | | | | | | | | | | | | `sentAt` | `Date` | `No` | `-` | `body` | `sentAt` | | **Description:** | Time the message was sent. If not set, will be createdAt. Used for ordering. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `createMessagingMessage` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { id: this.messagingMessageId, fromUserId: this.fromUserId, toUserId: this.toUserId, content: this.content, isRead: this.isRead, sentAt: this.sentAt, isActive: true, _archivedAt: null, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, populates session and request objects, prepares internal structures for parameter handling and workflow execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads input parameters, normalizes missing values, applies default type casting, and stores them in the API context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager transforms parameters, computes derived values, flattens or remaps arrays/objects, and adjusts formats for downstream processing. --- ### [4] Step : checkParameters Manager executes built-in validations: required field checks, type enforcement, and basic business rules. Prevents operation if validation fails. --- ### [5] Step : checkBasicAuth Manager performs authentication and authorization checks: verifies session, user roles, permissions, and tenant restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildDataClause Manager constructs the final data object for creation, fills auto-generated fields (IDs, timestamps, owner fields), and ensures schema consistency. You can use the following settings to change some behavior of this step. `dataClause` --- ### [7] Step : mainCreateOperation Manager executes the database insert operation, updates indexes/caches, and triggers internal post-processing like linked default records. --- ### [8] Step : buildOutput Manager shapes the response: masks sensitive fields, resolves linked references, and formats output according to API contract. --- ### [9] Step : sendResponse Manager sends the response to the client and finalizes internal tasks like flushing logs or updating session state. --- ### [10] Step : raiseApiEvent Manager triggers API-level events (Kafka, WebSocket, async workflows) as the final internal step. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `createMessagingMessage` api has got 3 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | toUserId | ID | true | request.body?.toUserId | | content | String | true | request.body?.content | | isRead | Boolean | true | request.body?.isRead | ### REST Request To access the api you can use the **REST** controller with the path **POST /v1/messagingmessages** ```js axios({ method: 'POST', url: '/v1/messagingmessages', data: { toUserId:"ID", content:"String", isRead:"Boolean", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`messagingMessage`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Delete Messagingmessage` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `deleteMessagingMessage` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `deleteMessagingMessage` Business API is designed to handle a `delete` operation on the `MessagingMessage` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Delete a message (soft-delete). Only sender, recipient, or admin may delete a message. Deletion only hides it for the user; not a full erase unless both delete. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `messagingmessage-deleted` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `deleteMessagingMessage` Business API includes a REST controller that can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `deleteMessagingMessage` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `deleteMessagingMessage` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `messagingMessageId` | `ID` | `Yes` | `-` | `urlpath` | `messagingMessageId` | | **Description:** | This id paremeter is used to select the required data object that will be deleted | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `deleteMessagingMessage` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.messagingMessageId},{isActive:true}]} ``` ## Delete Options Use these options to set `delete` specific settings. **useSoftDelete**: false If true, the record will be marked as deleted `(isActive: false)` instead of removed. The implementation depends on the data object’s soft delete configuration. ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request/session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads and normalizes parameters, applies defaults, and stores them in the context for downstream steps. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts, computes derived values, and remaps objects or arrays as needed for later processing. --- ### [4] Step : checkParameters Manager runs built-in validations including required field checks, type enforcement, and deletion preconditions. Stops execution if validation fails. --- ### [5] Step : checkBasicAuth Manager validates session, user roles, permissions, and tenant-specific access rules to enforce basic auth restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager generates the query conditions, applies ownership and parent checks, and ensures the clause is correct for the delete operation. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the target record, applies filters from WHERE clause, and writes the instance to the context for further checks. --- ### [8] Step : checkInstance Manager performs object-level validations such as lock status, soft-delete eligibility, and multi-step approval enforcement. --- ### [9] Step : mainDeleteOperation Manager executes the delete query, updates related indexes/caches, and handles soft/hard delete logic according to configuration. You can use the following settings to change some behavior of this step. `deleteOptions` --- ### [10] Step : buildOutput Manager shapes the response payload, masks sensitive fields, and formats related cleanup results for output. --- ### [11] Step : sendResponse Manager delivers the response to the client and finalizes any temporary internal structures. --- ### [12] Step : raiseApiEvent Manager triggers asynchronous API events, notifies queues or streams, and performs final cleanup for the workflow. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `deleteMessagingMessage` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | ### REST Request To access the api you can use the **REST** controller with the path **DELETE /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'DELETE', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`messagingMessage`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Get Messagingmessage` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `getMessagingMessage` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `getMessagingMessage` Business API is designed to handle a `get` operation on the `MessagingMessage` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Get a message by ID. Only accessible to the sender, the recipient, or an admin. Used for message detail view or reading a single message in a thread. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `messagingmessage-retrived` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `getMessagingMessage` Business API includes a REST controller that can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `getMessagingMessage` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `getMessagingMessage` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `messagingMessageId` | `ID` | `Yes` | `-` | `urlpath` | `messagingMessageId` | | **Description:** | This id paremeter is used to query the required data object. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `getMessagingMessage` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.messagingMessageId},{isActive:true}]} ``` ## Get Options Use these options to set `get` specific settings. **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Extracts parameters from request and Redis, applies defaults, and writes them to context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Executes parameter transformation scripts, applies type coercion, merges derived values, and reshapes inputs for downstream milestones. --- ### [4] Step : checkParameters Validates required and custom parameters, enforcing business-specific rules and constraints. --- ### [5] Step : checkBasicAuth Performs login, role, and permission checks, and applies dynamic object-level access rules. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Builds the WHERE clause for fetching the object and applies additional scoped filters if configured. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainGetOperation Executes the database fetch, retrieves the object, and stores it in context for enrichment or further checks. You can use the following settings to change some behavior of this step. `selectClause`, `getOptions` --- ### [8] Step : checkInstance Performs instance-level validations, such as ownership, existence, or access conditions. --- ### [9] Step : buildOutput Assembles the response from the object, applies masking, formatting, and injects additional metadata if needed. --- ### [10] Step : sendResponse Delivers the response to the controller for client delivery. --- ### [11] Step : raiseApiEvent Triggers optional API-level events after workflow completion, sending messages to integrations like Kafka if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `getMessagingMessage` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'GET', url: `/v1/messagingmessages/${messagingMessageId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`messagingMessage`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `List Messagingmessages` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `listMessagingMessages` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `listMessagingMessages` Business API is designed to handle a `list` operation on the `MessagingMessage` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description List all messages in the conversation between the logged-in user and another party, ordered by sentAt descending. Can filter unread with isRead. Returns only messages visible to user (isActive). ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `messagingmessages-listed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `listMessagingMessages` Business API includes a REST controller that can be triggered via the following route: `/v1/messagingmessages` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `listMessagingMessages` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `listMessagingMessages` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `listMessagingMessages` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {isActive:true} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `listMessagingMessages` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/messagingmessages** ```js axios({ method: 'GET', url: '/v1/messagingmessages', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`messagingMessages`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessages", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "messagingMessages": [ { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `Update Messagingmessage` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `updateMessagingMessage` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `updateMessagingMessage` Business API is designed to handle a `update` operation on the `MessagingMessage` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Update a message (mark as read/unread). Only the recipient or admin can change isRead. No content edits. Sender, content, sentAt are immutable. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `messagingmessage-updated` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `updateMessagingMessage` Business API includes a REST controller that can be triggered via the following route: `/v1/messagingmessages/:messagingMessageId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `updateMessagingMessage` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `updateMessagingMessage` Business API has 2 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `messagingMessageId` | `ID` | `Yes` | `-` | `urlpath` | `messagingMessageId` | | **Description:** | This id paremeter is used to select the required data object that will be updated | | | | | | | | | | | | | `isRead` | `Boolean` | `No` | `-` | `body` | `isRead` | | **Description:** | If true, recipient has marked this message as read. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `updateMessagingMessage` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.messagingMessageId},{isActive:true}]} ``` ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. An update data clause populates all update-allowed properties of a data object, however the null properties (that are not provided by client) are ignored in db layer. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { isRead: this.isRead, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request and session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads parameters from the request or Redis, applies defaults, and writes them into context for downstream milestones. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts and derives any helper values or reshaped payloads into the context. --- ### [4] Step : checkParameters Manager validates required parameters, checks ID formats (UUID/ObjectId), and ensures all preconditions for update are met. --- ### [5] Step : checkBasicAuth Manager performs login verification, role, and permission checks, enforcing tenant and access rules before update. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager constructs the WHERE clause used to identify the record to update, applying ownership and parent checks if necessary. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the existing record from the database and writes it to the context for validation or enrichment. --- ### [8] Step : checkInstance Manager performs instance-level validations, including ownership, existence, lock status, or other pre-update checks. --- ### [9] Step : buildDataClause Manager prepares the data clause for the update, applying transformations or enhancements before persisting. You can use the following settings to change some behavior of this step. `dataClause` --- ### [10] Step : mainUpdateOperation Manager executes the update operation with the WHERE and data clauses. Database-level events are raised if configured. --- ### [11] Step : buildOutput Manager assembles the response object from the update result, masking fields or injecting additional metadata. --- ### [12] Step : sendResponse Manager sends the response back to the controller for delivery to the client. --- ### [13] Step : raiseApiEvent Manager triggers API-level events, sending relevant messages to Kafka or other integrations if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `updateMessagingMessage` api has got 2 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | messagingMessageId | ID | true | request.params?.messagingMessageId | | isRead | Boolean | false | request.body?.isRead | ### REST Request To access the api you can use the **REST** controller with the path **PATCH /v1/messagingmessages/:messagingMessageId** ```js axios({ method: 'PATCH', url: `/v1/messagingmessages/${messagingMessageId}`, data: { isRead:"Boolean", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`messagingMessage`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "messagingMessage", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "messagingMessage": { "id": "ID", "fromUserId": "ID", "toUserId": "ID", "content": "String", "isRead": "Boolean", "sentAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Create Notification` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `createNotification` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `createNotification` Business API is designed to handle a `create` operation on the `Notification` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Creates a notification entry in response to a system/business event. Only allowed for system/event processes and admins (not standard user/action). Typically event-driven, receives userId, notificationType, payload, and channel. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `notification-created` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `createNotification` Business API includes a REST controller that can be triggered via the following route: `/v1/notifications` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `createNotification` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `createNotification` Business API has 6 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `notificationId` | `ID` | `No` | `-` | `body` | `notificationId` | | **Description:** | This id paremeter is used to create the data object with a given specific id. Leave null for automatic id. | | | | | | | | | | | | | `notificationType` | `Enum` | `Yes` | `-` | `body` | `notificationType` | | **Description:** | Type of event triggering notification (e.g., BID_UPDATED, ORDER_SHIPPED, MESSAGE_RECEIVED, etc.). Used for display/icon and query filter. | | | | | | | | | | | | | `userId` | `ID` | `Yes` | `-` | `body` | `userId` | | **Description:** | User receiving the notification (recipient). | | | | | | | | | | | | | `channel` | `Enum` | `Yes` | `-` | `body` | `channel` | | **Description:** | Channel by which notification is delivered: IN_APP or EMAIL. | | | | | | | | | | | | | `payload` | `Object` | `Yes` | `-` | `body` | `payload` | | **Description:** | Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. | | | | | | | | | | | | | `isRead` | `Boolean` | `Yes` | `-` | `body` | `isRead` | | **Description:** | Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `createNotification` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { id: this.notificationId, notificationType: this.notificationType, userId: this.userId, channel: this.channel, payload: this.payload ? (typeof this.payload == 'string' ? JSON.parse(this.payload) : this.payload) : null, isRead: this.isRead, isActive: true, _archivedAt: null, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, populates session and request objects, prepares internal structures for parameter handling and workflow execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads input parameters, normalizes missing values, applies default type casting, and stores them in the API context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager transforms parameters, computes derived values, flattens or remaps arrays/objects, and adjusts formats for downstream processing. --- ### [4] Step : checkParameters Manager executes built-in validations: required field checks, type enforcement, and basic business rules. Prevents operation if validation fails. --- ### [5] Step : checkBasicAuth Manager performs authentication and authorization checks: verifies session, user roles, permissions, and tenant restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildDataClause Manager constructs the final data object for creation, fills auto-generated fields (IDs, timestamps, owner fields), and ensures schema consistency. You can use the following settings to change some behavior of this step. `dataClause` --- ### [7] Step : mainCreateOperation Manager executes the database insert operation, updates indexes/caches, and triggers internal post-processing like linked default records. --- ### [8] Step : buildOutput Manager shapes the response: masks sensitive fields, resolves linked references, and formats output according to API contract. --- ### [9] Step : sendResponse Manager sends the response to the client and finalizes internal tasks like flushing logs or updating session state. --- ### [10] Step : raiseApiEvent Manager triggers API-level events (Kafka, WebSocket, async workflows) as the final internal step. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `createNotification` api has got 5 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationType | Enum | true | request.body?.notificationType | | userId | ID | true | request.body?.userId | | channel | Enum | true | request.body?.channel | | payload | Object | true | request.body?.payload | | isRead | Boolean | true | request.body?.isRead | ### REST Request To access the api you can use the **REST** controller with the path **POST /v1/notifications** ```js axios({ method: 'POST', url: '/v1/notifications', data: { notificationType:"Enum", userId:"ID", channel:"Enum", payload:"Object", isRead:"Boolean", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`notification`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Delete Notification` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `deleteNotification` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `deleteNotification` Business API is designed to handle a `delete` operation on the `Notification` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Soft-delete a notification record. Only receiver or admin may delete. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `notification-deleted` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `deleteNotification` Business API includes a REST controller that can be triggered via the following route: `/v1/notifications/:notificationId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `deleteNotification` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `deleteNotification` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `notificationId` | `ID` | `Yes` | `-` | `urlpath` | `notificationId` | | **Description:** | This id paremeter is used to select the required data object that will be deleted | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `deleteNotification` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.notificationId},{isActive:true}]} ``` ## Delete Options Use these options to set `delete` specific settings. **useSoftDelete**: false If true, the record will be marked as deleted `(isActive: false)` instead of removed. The implementation depends on the data object’s soft delete configuration. ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request/session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads and normalizes parameters, applies defaults, and stores them in the context for downstream steps. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts, computes derived values, and remaps objects or arrays as needed for later processing. --- ### [4] Step : checkParameters Manager runs built-in validations including required field checks, type enforcement, and deletion preconditions. Stops execution if validation fails. --- ### [5] Step : checkBasicAuth Manager validates session, user roles, permissions, and tenant-specific access rules to enforce basic auth restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager generates the query conditions, applies ownership and parent checks, and ensures the clause is correct for the delete operation. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the target record, applies filters from WHERE clause, and writes the instance to the context for further checks. --- ### [8] Step : checkInstance Manager performs object-level validations such as lock status, soft-delete eligibility, and multi-step approval enforcement. --- ### [9] Step : mainDeleteOperation Manager executes the delete query, updates related indexes/caches, and handles soft/hard delete logic according to configuration. You can use the following settings to change some behavior of this step. `deleteOptions` --- ### [10] Step : buildOutput Manager shapes the response payload, masks sensitive fields, and formats related cleanup results for output. --- ### [11] Step : sendResponse Manager delivers the response to the client and finalizes any temporary internal structures. --- ### [12] Step : raiseApiEvent Manager triggers asynchronous API events, notifies queues or streams, and performs final cleanup for the workflow. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `deleteNotification` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | ### REST Request To access the api you can use the **REST** controller with the path **DELETE /v1/notifications/:notificationId** ```js axios({ method: 'DELETE', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`notification`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Get Notification` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `getNotification` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `getNotification` Business API is designed to handle a `get` operation on the `Notification` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Retrieves a notification for the receiver or admin. Used to populate content on detail/expanded view. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `notification-retrived` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `getNotification` Business API includes a REST controller that can be triggered via the following route: `/v1/notifications/:notificationId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `getNotification` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `getNotification` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `notificationId` | `ID` | `Yes` | `-` | `urlpath` | `notificationId` | | **Description:** | This id paremeter is used to query the required data object. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `getNotification` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.notificationId},{isActive:true}]} ``` ## Get Options Use these options to set `get` specific settings. **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Extracts parameters from request and Redis, applies defaults, and writes them to context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Executes parameter transformation scripts, applies type coercion, merges derived values, and reshapes inputs for downstream milestones. --- ### [4] Step : checkParameters Validates required and custom parameters, enforcing business-specific rules and constraints. --- ### [5] Step : checkBasicAuth Performs login, role, and permission checks, and applies dynamic object-level access rules. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Builds the WHERE clause for fetching the object and applies additional scoped filters if configured. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainGetOperation Executes the database fetch, retrieves the object, and stores it in context for enrichment or further checks. You can use the following settings to change some behavior of this step. `selectClause`, `getOptions` --- ### [8] Step : checkInstance Performs instance-level validations, such as ownership, existence, or access conditions. --- ### [9] Step : buildOutput Assembles the response from the object, applies masking, formatting, and injects additional metadata if needed. --- ### [10] Step : sendResponse Delivers the response to the controller for client delivery. --- ### [11] Step : raiseApiEvent Triggers optional API-level events after workflow completion, sending messages to integrations like Kafka if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `getNotification` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/notifications/:notificationId** ```js axios({ method: 'GET', url: `/v1/notifications/${notificationId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`notification`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `List Notifications` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `listNotifications` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `listNotifications` Business API is designed to handle a `list` operation on the `Notification` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Returns filtered list of notifications for a user, with optional filters: notificationType, isRead, channel. Always sorted by createdAt (descending) for in-app notifications. Only retrieval allowed for owner/admin. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `notifications-listed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `listNotifications` Business API includes a REST controller that can be triggered via the following route: `/v1/notifications` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `listNotifications` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `listNotifications` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `listNotifications` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {isActive:true} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `listNotifications` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/notifications** ```js axios({ method: 'GET', url: '/v1/notifications', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`notifications`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notifications", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "notifications": [ { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `Update Notification` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `updateNotification` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `updateNotification` Business API is designed to handle a `update` operation on the `Notification` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Updates a notification (mark as read/unread, payload patch for e.g. admin fix). Only receiver (userId) or admins may update. isRead is primary update scenario; others very limited. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `notification-updated` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `updateNotification` Business API includes a REST controller that can be triggered via the following route: `/v1/notifications/:notificationId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `updateNotification` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `updateNotification` Business API has 3 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `notificationId` | `ID` | `Yes` | `-` | `urlpath` | `notificationId` | | **Description:** | This id paremeter is used to select the required data object that will be updated | | | | | | | | | | | | | `payload` | `Object` | `No` | `-` | `body` | `payload` | | **Description:** | Event payload; stores event-specific/structured details for frontend rendering. Structure varies by notificationType. | | | | | | | | | | | | | `isRead` | `Boolean` | `No` | `-` | `body` | `isRead` | | **Description:** | Marks if user has read/seen notification (IN_APP only; always true for EMAIL channel) | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `updateNotification` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.notificationId},{isActive:true}]} ``` ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. An update data clause populates all update-allowed properties of a data object, however the null properties (that are not provided by client) are ignored in db layer. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { payload: this.payload ? (typeof this.payload == 'string' ? JSON.parse(this.payload) : this.payload) : null, isRead: this.isRead, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request and session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads parameters from the request or Redis, applies defaults, and writes them into context for downstream milestones. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts and derives any helper values or reshaped payloads into the context. --- ### [4] Step : checkParameters Manager validates required parameters, checks ID formats (UUID/ObjectId), and ensures all preconditions for update are met. --- ### [5] Step : checkBasicAuth Manager performs login verification, role, and permission checks, enforcing tenant and access rules before update. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager constructs the WHERE clause used to identify the record to update, applying ownership and parent checks if necessary. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the existing record from the database and writes it to the context for validation or enrichment. --- ### [8] Step : checkInstance Manager performs instance-level validations, including ownership, existence, lock status, or other pre-update checks. --- ### [9] Step : buildDataClause Manager prepares the data clause for the update, applying transformations or enhancements before persisting. You can use the following settings to change some behavior of this step. `dataClause` --- ### [10] Step : mainUpdateOperation Manager executes the update operation with the WHERE and data clauses. Database-level events are raised if configured. --- ### [11] Step : buildOutput Manager assembles the response object from the update result, masking fields or injecting additional metadata. --- ### [12] Step : sendResponse Manager sends the response back to the controller for delivery to the client. --- ### [13] Step : raiseApiEvent Manager triggers API-level events, sending relevant messages to Kafka or other integrations if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `updateNotification` api has got 3 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | notificationId | ID | true | request.params?.notificationId | | payload | Object | false | request.body?.payload | | isRead | Boolean | false | request.body?.isRead | ### REST Request To access the api you can use the **REST** controller with the path **PATCH /v1/notifications/:notificationId** ```js axios({ method: 'PATCH', url: `/v1/notifications/${notificationId}`, data: { payload:"Object", isRead:"Boolean", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`notification`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "notification", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "notification": { "id": "ID", "notificationType": "Enum", "notificationType_idx": "Integer", "userId": "ID", "channel": "Enum", "channel_idx": "Integer", "payload": "Object", "isRead": "Boolean", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Callback Ordermanagementorderpayment` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `callbackOrderManagementOrderPayment` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `callbackOrderManagementOrderPayment` Business API is designed to handle a `update` operation on the `OrderManagementOrder` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Refresh payment values by gateway webhook call for orderManagementOrder ## API Options * **Auto Params** : `false` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `ordermanagementorderpayment-calledback` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `callbackOrderManagementOrderPayment` Business API includes a REST controller that can be triggered via the following route: `/v1/callbackordermanagementorderpayment` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `callbackOrderManagementOrderPayment` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `callbackOrderManagementOrderPayment` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `orderManagementOrderId` | `ID` | `Yes` | `-` | `body` | `orderManagementOrderId` | | **Description:** | The order id parameter that will be read from webhook callback params | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. * `orderManagementOrderId`: ```javascript this.orderManagementOrderId = this.paymentCallbackParams?.orderId ``` ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `callbackOrderManagementOrderPayment` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API is **public** and can be accessed without login (`loginRequired = false`). --- ### Ownership Checks --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin]` --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.orderManagementOrderId},{isActive:true}]} ``` ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. An update data clause populates all update-allowed properties of a data object, however the null properties (that are not provided by client) are ignored in db layer. **Custom Data Clause Override** ```js { status: this.status, updatedAt: new Date(), _paymentConfirmation: this._paymentConfirmation, } ``` **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { status: this.status, updatedAt: new Date(), // _paymentConfirmation parameter is closed to update by client request // include it in data clause unless you are sure _paymentConfirmation: this._paymentConfirmation, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request and session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads parameters from the request or Redis, applies defaults, and writes them into context for downstream milestones. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Action : verifyPaymentWebhook **Action Type**: `VerifyWebhookAction` Verify a providers webhook call with the secret signature and read the params, write the callback parameters to the context. Only stripe webhooks is supported for now. ```js class Api { // Code for VerifyWebhookAction async verifyPaymentWebhook() { const secretKey = null; const stripeGateway = this.checkoutManager.paymentGate; const result = await stripeGateway.webhookController(this.request); if (result.statusLiteral == "unhandled") { throw new BadRequestError( `Unhandled stripe webhook event [${result.eventType}]`, ); } return result; } } ``` --- ### [4] Step : transposeParameters Manager executes parameter transform scripts and derives any helper values or reshaped payloads into the context. --- ### [5] Step : checkParameters Manager validates required parameters, checks ID formats (UUID/ObjectId), and ensures all preconditions for update are met. --- ### [6] Step : checkBasicAuth Manager performs login verification, role, and permission checks, enforcing tenant and access rules before update. You can use the following settings to change some behavior of this step. `authOptions` --- ### [7] Step : buildWhereClause Manager constructs the WHERE clause used to identify the record to update, applying ownership and parent checks if necessary. You can use the following settings to change some behavior of this step. `whereClause` --- ### [8] Step : fetchInstance Manager fetches the existing record from the database and writes it to the context for validation or enrichment. --- ### [9] Step : checkInstance Manager performs instance-level validations, including ownership, existence, lock status, or other pre-update checks. --- ### [10] Action : doPaymentCallback **Action Type**: `CheckoutAction` Refresh payment by Stripe platform webhook, the payment operation data in the gateway server will be given by webhook call and the application payment tickets and order status will be refreshed according to the server. ```js class Api { getOrderId() { return this.orderManagementOrderId; } getPaymentStatusTopic(actionType) { switch (actionType) { case "started": return "ebaycclone-ordermanagement-service-ordermanagementorderpaymentstatus-started"; case "updated": return "ebaycclone-ordermanagement-service-ordermanagementorderpaymentstatus-updated"; case "succeeded": return "ebaycclone-ordermanagement-service-ordermanagementorderpaymentstatus-succeeded"; case "failed": return "ebaycclone-ordermanagement-service-ordermanagementorderpaymentstatus-failed"; } } async checkoutUpdated(statusLiteral) { switch (statusLiteral) { case "started": await this.checkoutStarted(); break; case "canceled": await this.checkoutCanceled(); break; case "failed": await this.checkoutFailed(); break; case "success": await this.checkoutDone(); break; default: await this.checkoutFailed(); break; } } async checkoutStarted() { this.status = "PENDING_PAYMENT"; this._paymentConfirmation = "processing"; this.raisePaymentStatusEvent("started"); } async checkoutCanceled() { this.status = "CANCELLED"; this._paymentConfirmation = "canceled"; this.raisePaymentStatusEvent("failed"); } async checkoutFailed() { this.status = "CANCELLED"; this._paymentConfirmation = "canceled"; this.raisePaymentStatusEvent("failed"); } async checkoutDone() { this.status = "PAID"; this._paymentConfirmation = "paid"; this.raisePaymentStatusEvent("succeeded"); } getCheckoutParameters(userParams) { const description = `Order #${this.orderManagementOrder.orderNumber} for buyerId ${this.orderManagementOrder.buyerId}`; return { userId: this.session._USERID, fullname: this.session.fullname, email: this.session.email, description, amount: this.orderManagementOrder.summary.total, currency: this.orderManagementOrder.summary.currency, orderId: this.orderManagementOrder.id, metadata: { order: "OrderManagement-OrderManagementOrder-order", orderId: this.orderManagementOrder.id, checkoutName: "orderManagementOrder", }, storeCard: userParams?.storeCard, paymentUserParams: userParams, bodyParams: this.bodyParams, }; } async doPaymentCallback() { // Handle Checkout Action try { if (!this.checkoutManager) { throw new Error( "This dboject is not an order object. So auto-checkout process can not be started.", ); } this.paymentResult = await this.checkoutManager.processCheckoutCallbackResult( this.paymentCallbackParams, ); } catch (err) { if (err instanceof PaymentGateError) { this.paymentResult = err.serializeError(); //**errorLog } else throw err; } return this.paymentResult; } } ``` --- ### [11] Step : buildDataClause Manager prepares the data clause for the update, applying transformations or enhancements before persisting. You can use the following settings to change some behavior of this step. `dataClause` --- ### [12] Step : mainUpdateOperation Manager executes the update operation with the WHERE and data clauses. Database-level events are raised if configured. --- ### [13] Step : buildOutput Manager assembles the response object from the update result, masking fields or injecting additional metadata. --- ### [14] Step : sendResponse Manager sends the response back to the controller for delivery to the client. --- ### [15] Step : raiseApiEvent Manager triggers API-level events, sending relevant messages to Kafka or other integrations if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `callbackOrderManagementOrderPayment` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.body?.orderManagementOrderId | ### REST Request To access the api you can use the **REST** controller with the path **POST /v1/callbackordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/callbackordermanagementorderpayment', data: { orderManagementOrderId:"ID", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrder`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` # Business API Design Specification - `Complete Orderstripewebhook` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `completeOrderStripeWebhook` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `completeOrderStripeWebhook` Business API is designed to handle a `update` operation on the `OrderManagementOrder` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Webhook endpoint called by Stripe to reconcile payment state and update order status based on paymentIntentId and event data. No authentication required (Stripe IPs only). ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `orderstripewebhook-completed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `completeOrderStripeWebhook` Business API includes a REST controller that can be triggered via the following route: `/v1/completeorderstripewebhook/:orderManagementOrderId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `completeOrderStripeWebhook` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `completeOrderStripeWebhook` Business API has 10 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `orderManagementOrderId` | `ID` | `Yes` | `-` | `urlpath` | `orderManagementOrderId` | | **Description:** | This id paremeter is used to select the required data object that will be updated | | | | | | | | | | | | | `status` | `Enum` | `No` | `-` | `body` | `status` | | **Description:** | Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED | | | | | | | | | | | | | `paymentIntentId` | `String` | `No` | `-` | `body` | `paymentIntentId` | | **Description:** | Stripe paymentIntentId; enables webhook correlation and status sync. | | | | | | | | | | | | | `trackingNumber` | `String` | `No` | `-` | `body` | `trackingNumber` | | **Description:** | Optional tracking number entered by seller when marking as shipped. | | | | | | | | | | | | | `estimatedDelivery` | `Date` | `No` | `-` | `body` | `estimatedDelivery` | | **Description:** | Estimated delivery date for order; copied from fastest estimated item or seller input. | | | | | | | | | | | | | `cancelledAt` | `Date` | `No` | `-` | `body` | `cancelledAt` | | **Description:** | Timestamp when cancelled by buyer, seller, or admin before shipment. | | | | | | | | | | | | | `paidAt` | `Date` | `No` | `-` | `body` | `paidAt` | | **Description:** | Timestamp when payment confirmed via Stripe or manual admin update. | | | | | | | | | | | | | `deliveredAt` | `Date` | `No` | `-` | `body` | `deliveredAt` | | **Description:** | Timestamp when buyer confirms delivery. | | | | | | | | | | | | | `shippedAt` | `Date` | `No` | `-` | `body` | `shippedAt` | | **Description:** | Timestamp when seller marks as shipped. | | | | | | | | | | | | | `carrier` | `String` | `No` | `-` | `body` | `carrier` | | **Description:** | Optional carrier name entered by seller when marking as shipped. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `completeOrderStripeWebhook` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks This Business API enforces ownership of the main data object before executing the operation. - The check is performed **after fetching the object instance**. If the current user is not the owner, the API will respond with **403 Forbidden**. Note: Ownership checks are applied **only if the objects have an owner field**. --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.orderManagementOrderId},{isActive:true}]} ``` ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. An update data clause populates all update-allowed properties of a data object, however the null properties (that are not provided by client) are ignored in db layer. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { status: this.status, paymentIntentId: this.paymentIntentId, trackingNumber: this.trackingNumber, estimatedDelivery: this.estimatedDelivery, cancelledAt: this.cancelledAt, paidAt: this.paidAt, deliveredAt: this.deliveredAt, shippedAt: this.shippedAt, carrier: this.carrier, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request and session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads parameters from the request or Redis, applies defaults, and writes them into context for downstream milestones. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts and derives any helper values or reshaped payloads into the context. --- ### [4] Step : checkParameters Manager validates required parameters, checks ID formats (UUID/ObjectId), and ensures all preconditions for update are met. --- ### [5] Step : checkBasicAuth Manager performs login verification, role, and permission checks, enforcing tenant and access rules before update. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager constructs the WHERE clause used to identify the record to update, applying ownership and parent checks if necessary. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the existing record from the database and writes it to the context for validation or enrichment. --- ### [8] Step : checkInstance Manager performs instance-level validations, including ownership, existence, lock status, or other pre-update checks. --- ### [9] Step : buildDataClause Manager prepares the data clause for the update, applying transformations or enhancements before persisting. You can use the following settings to change some behavior of this step. `dataClause` --- ### [10] Step : mainUpdateOperation Manager executes the update operation with the WHERE and data clauses. Database-level events are raised if configured. --- ### [11] Step : buildOutput Manager assembles the response object from the update result, masking fields or injecting additional metadata. --- ### [12] Step : sendResponse Manager sends the response back to the controller for delivery to the client. --- ### [13] Step : raiseApiEvent Manager triggers API-level events, sending relevant messages to Kafka or other integrations if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `completeOrderStripeWebhook` api has got 10 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | ### REST Request To access the api you can use the **REST** controller with the path **PATCH /v1/completeorderstripewebhook/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/completeorderstripewebhook/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrder`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Create Ordermanagementorder` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `createOrderManagementOrder` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `createOrderManagementOrder` Business API is designed to handle a `create` operation on the `OrderManagementOrder` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Creates an order and initiates Stripe payment. Validates that all products in the order are fixed-price, populates orderItems, saves Stripe customer/paymentMethod/paymentIntentId for reconciliation. Only accessible to buyers for own checkouts and only allows fixed-price product checkout (no auction). ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `ordermanagementorder-created` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `createOrderManagementOrder` Business API includes a REST controller that can be triggered via the following route: `/v1/ordermanagementorders` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `createOrderManagementOrder` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `createOrderManagementOrder` Business API has 16 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `orderManagementOrderId` | `ID` | `No` | `-` | `body` | `orderManagementOrderId` | | **Description:** | This id paremeter is used to create the data object with a given specific id. Leave null for automatic id. | | | | | | | | | | | | | `orderNumber` | `String` | `Yes` | `-` | `body` | `orderNumber` | | **Description:** | Unique, human-friendly order number (displayed to users); enforced unique. | | | | | | | | | | | | | `items` | `ID` | `No` | `-` | `body` | `items` | | **Description:** | Array of orderManagementOrderItem ids representing items in this order. | | | | | | | | | | | | | `buyerId` | `ID` | `Yes` | `-` | `session` | `userId` | | **Description:** | User ID of the buyer placing the order. | | | | | | | | | | | | | `paymentMethodId` | `String` | `Yes` | `-` | `body` | `paymentMethodId` | | **Description:** | Stripe paymentMethodId used for payment. Not stored if cash or other payment (future). | | | | | | | | | | | | | `stripeCustomerId` | `String` | `Yes` | `-` | `body` | `stripeCustomerId` | | **Description:** | Stripe customerId of buyer; enables saved/paymentMethodId flows. | | | | | | | | | | | | | `paymentIntentId` | `String` | `No` | `-` | `body` | `paymentIntentId` | | **Description:** | Stripe paymentIntentId; enables webhook correlation and status sync. | | | | | | | | | | | | | `shippingAddress` | `Object` | `Yes` | `-` | `body` | `shippingAddress` | | **Description:** | Shipping address for the order (copy of buyer address at purchase time). | | | | | | | | | | | | | `summary` | `Object` | `Yes` | `-` | `body` | `summary` | | **Description:** | Object with total, subtotal, currency, shipping, discount breakdown as snapshot of order at time of purchase. | | | | | | | | | | | | | `trackingNumber` | `String` | `No` | `-` | `body` | `trackingNumber` | | **Description:** | Optional tracking number entered by seller when marking as shipped. | | | | | | | | | | | | | `estimatedDelivery` | `Date` | `No` | `-` | `body` | `estimatedDelivery` | | **Description:** | Estimated delivery date for order; copied from fastest estimated item or seller input. | | | | | | | | | | | | | `cancelledAt` | `Date` | `No` | `-` | `body` | `cancelledAt` | | **Description:** | Timestamp when cancelled by buyer, seller, or admin before shipment. | | | | | | | | | | | | | `paidAt` | `Date` | `No` | `-` | `body` | `paidAt` | | **Description:** | Timestamp when payment confirmed via Stripe or manual admin update. | | | | | | | | | | | | | `deliveredAt` | `Date` | `No` | `-` | `body` | `deliveredAt` | | **Description:** | Timestamp when buyer confirms delivery. | | | | | | | | | | | | | `shippedAt` | `Date` | `No` | `-` | `body` | `shippedAt` | | **Description:** | Timestamp when seller marks as shipped. | | | | | | | | | | | | | `carrier` | `String` | `No` | `-` | `body` | `carrier` | | **Description:** | Optional carrier name entered by seller when marking as shipped. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `createOrderManagementOrder` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { id: this.orderManagementOrderId, orderNumber: this.orderNumber, items: this.items, buyerId: this.buyerId, paymentMethodId: this.paymentMethodId, stripeCustomerId: this.stripeCustomerId, paymentIntentId: this.paymentIntentId, shippingAddress: this.shippingAddress ? (typeof this.shippingAddress == 'string' ? JSON.parse(this.shippingAddress) : this.shippingAddress) : null, summary: this.summary ? (typeof this.summary == 'string' ? JSON.parse(this.summary) : this.summary) : null, trackingNumber: this.trackingNumber, estimatedDelivery: this.estimatedDelivery, cancelledAt: this.cancelledAt, paidAt: this.paidAt, deliveredAt: this.deliveredAt, shippedAt: this.shippedAt, carrier: this.carrier, isActive: true, _archivedAt: null, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, populates session and request objects, prepares internal structures for parameter handling and workflow execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads input parameters, normalizes missing values, applies default type casting, and stores them in the API context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager transforms parameters, computes derived values, flattens or remaps arrays/objects, and adjusts formats for downstream processing. --- ### [4] Step : checkParameters Manager executes built-in validations: required field checks, type enforcement, and basic business rules. Prevents operation if validation fails. --- ### [5] Step : checkBasicAuth Manager performs authentication and authorization checks: verifies session, user roles, permissions, and tenant restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildDataClause Manager constructs the final data object for creation, fills auto-generated fields (IDs, timestamps, owner fields), and ensures schema consistency. You can use the following settings to change some behavior of this step. `dataClause` --- ### [7] Step : mainCreateOperation Manager executes the database insert operation, updates indexes/caches, and triggers internal post-processing like linked default records. --- ### [8] Step : buildOutput Manager shapes the response: masks sensitive fields, resolves linked references, and formats output according to API contract. --- ### [9] Step : sendResponse Manager sends the response to the client and finalizes internal tasks like flushing logs or updating session state. --- ### [10] Step : raiseApiEvent Manager triggers API-level events (Kafka, WebSocket, async workflows) as the final internal step. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `createOrderManagementOrder` api has got 14 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderNumber | String | true | request.body?.orderNumber | | items | ID | false | request.body?.items | | paymentMethodId | String | true | request.body?.paymentMethodId | | stripeCustomerId | String | true | request.body?.stripeCustomerId | | paymentIntentId | String | false | request.body?.paymentIntentId | | shippingAddress | Object | true | request.body?.shippingAddress | | summary | Object | true | request.body?.summary | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | ### REST Request To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorders** ```js axios({ method: 'POST', url: '/v1/ordermanagementorders', data: { orderNumber:"String", items:"ID", paymentMethodId:"String", stripeCustomerId:"String", paymentIntentId:"String", shippingAddress:"Object", summary:"Object", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrder`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Create Ordermanagementorderitem` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `createOrderManagementOrderItem` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `createOrderManagementOrderItem` Business API is designed to handle a `create` operation on the `OrderManagementOrderItem` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description create order item ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `ordermanagementorderitem-created` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `createOrderManagementOrderItem` Business API includes a REST controller that can be triggered via the following route: `/v1/ordermanagementorderitems` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `createOrderManagementOrderItem` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `createOrderManagementOrderItem` Business API has 9 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `orderManagementOrderItemId` | `ID` | `No` | `-` | `body` | `orderManagementOrderItemId` | | **Description:** | This id paremeter is used to create the data object with a given specific id. Leave null for automatic id. | | | | | | | | | | | | | `shipping` | `Double` | `Yes` | `-` | `body` | `shipping` | | **Description:** | Shipping cost for this product (may be 0 for free shipping). | | | | | | | | | | | | | `orderId` | `ID` | `Yes` | `-` | `body` | `orderId` | | **Description:** | Parent order this item belongs to; enables join and lifecycle tracking. | | | | | | | | | | | | | `quantity` | `Integer` | `Yes` | `-` | `body` | `quantity` | | **Description:** | Number of units purchased for this product. | | | | | | | | | | | | | `productId` | `ID` | `Yes` | `-` | `body` | `productId` | | **Description:** | ID of product purchased in this line item. | | | | | | | | | | | | | `price` | `Double` | `Yes` | `-` | `body` | `price` | | **Description:** | Unit price for this product at purchase time. | | | | | | | | | | | | | `sellerId` | `ID` | `Yes` | `-` | `body` | `sellerId` | | **Description:** | UserId of seller (owner of product at purchase time). | | | | | | | | | | | | | `title` | `String` | `Yes` | `-` | `body` | `title` | | **Description:** | Product title at purchase time (copied for convenience/audit). | | | | | | | | | | | | | `currency` | `String` | `Yes` | `-` | `body` | `currency` | | **Description:** | Currency code for price/shipping (ISO 4217). | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `createOrderManagementOrderItem` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { id: this.orderManagementOrderItemId, shipping: this.shipping, orderId: this.orderId, quantity: this.quantity, productId: this.productId, price: this.price, sellerId: this.sellerId, title: this.title, currency: this.currency, isActive: true, _archivedAt: null, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, populates session and request objects, prepares internal structures for parameter handling and workflow execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads input parameters, normalizes missing values, applies default type casting, and stores them in the API context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager transforms parameters, computes derived values, flattens or remaps arrays/objects, and adjusts formats for downstream processing. --- ### [4] Step : checkParameters Manager executes built-in validations: required field checks, type enforcement, and basic business rules. Prevents operation if validation fails. --- ### [5] Step : checkBasicAuth Manager performs authentication and authorization checks: verifies session, user roles, permissions, and tenant restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildDataClause Manager constructs the final data object for creation, fills auto-generated fields (IDs, timestamps, owner fields), and ensures schema consistency. You can use the following settings to change some behavior of this step. `dataClause` --- ### [7] Step : mainCreateOperation Manager executes the database insert operation, updates indexes/caches, and triggers internal post-processing like linked default records. --- ### [8] Step : buildOutput Manager shapes the response: masks sensitive fields, resolves linked references, and formats output according to API contract. --- ### [9] Step : sendResponse Manager sends the response to the client and finalizes internal tasks like flushing logs or updating session state. --- ### [10] Step : raiseApiEvent Manager triggers API-level events (Kafka, WebSocket, async workflows) as the final internal step. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `createOrderManagementOrderItem` api has got 8 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | shipping | Double | true | request.body?.shipping | | orderId | ID | true | request.body?.orderId | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | | price | Double | true | request.body?.price | | sellerId | ID | true | request.body?.sellerId | | title | String | true | request.body?.title | | currency | String | true | request.body?.currency | ### REST Request To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderitems** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderitems', data: { shipping:"Double", orderId:"ID", quantity:"Integer", productId:"ID", price:"Double", sellerId:"ID", title:"String", currency:"String", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrderItem`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Create Ordermanagementorderpayment` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `createOrderManagementOrderPayment` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `createOrderManagementOrderPayment` Business API is designed to handle a `create` operation on the `Sys_orderManagementOrderPayment` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description This route is used to create a new payment. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `ordermanagementorderpayment-created` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `createOrderManagementOrderPayment` Business API includes a REST controller that can be triggered via the following route: `/v1/ordermanagementorderpayment` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `createOrderManagementOrderPayment` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `createOrderManagementOrderPayment` Business API has 7 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `sys_orderManagementOrderPaymentId` | `ID` | `No` | `-` | `body` | `sys_orderManagementOrderPaymentId` | | **Description:** | This id paremeter is used to create the data object with a given specific id. Leave null for automatic id. | | | | | | | | | | | | | `ownerId` | `ID` | `No` | `-` | `session` | `userId` | | **Description:** | An ID value to represent owner user who created the order | | | | | | | | | | | | | `orderId` | `ID` | `Yes` | `-` | `body` | `orderId` | | **Description:** | an ID value to represent the orderId which is the ID parameter of the source orderManagementOrder object | | | | | | | | | | | | | `paymentId` | `String` | `Yes` | `-` | `body` | `paymentId` | | **Description:** | A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type | | | | | | | | | | | | | `paymentStatus` | `String` | `Yes` | `-` | `body` | `paymentStatus` | | **Description:** | A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. | | | | | | | | | | | | | `statusLiteral` | `String` | `Yes` | `-` | `body` | `statusLiteral` | | **Description:** | A string value to represent the logical payment status which belongs to the application lifecycle itself. | | | | | | | | | | | | | `redirectUrl` | `String` | `No` | `-` | `body` | `redirectUrl` | | **Description:** | A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `createOrderManagementOrderPayment` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin]` --- ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { id: this.sys_orderManagementOrderPaymentId, ownerId: this.ownerId, orderId: this.orderId, paymentId: this.paymentId, paymentStatus: this.paymentStatus, statusLiteral: this.statusLiteral, redirectUrl: this.redirectUrl, isActive: true, _archivedAt: null, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, populates session and request objects, prepares internal structures for parameter handling and workflow execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads input parameters, normalizes missing values, applies default type casting, and stores them in the API context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager transforms parameters, computes derived values, flattens or remaps arrays/objects, and adjusts formats for downstream processing. --- ### [4] Step : checkParameters Manager executes built-in validations: required field checks, type enforcement, and basic business rules. Prevents operation if validation fails. --- ### [5] Step : checkBasicAuth Manager performs authentication and authorization checks: verifies session, user roles, permissions, and tenant restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildDataClause Manager constructs the final data object for creation, fills auto-generated fields (IDs, timestamps, owner fields), and ensures schema consistency. You can use the following settings to change some behavior of this step. `dataClause` --- ### [7] Step : mainCreateOperation Manager executes the database insert operation, updates indexes/caches, and triggers internal post-processing like linked default records. --- ### [8] Step : buildOutput Manager shapes the response: masks sensitive fields, resolves linked references, and formats output according to API contract. --- ### [9] Step : sendResponse Manager sends the response to the client and finalizes internal tasks like flushing logs or updating session state. --- ### [10] Step : raiseApiEvent Manager triggers API-level events (Kafka, WebSocket, async workflows) as the final internal step. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `createOrderManagementOrderPayment` api has got 5 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderId | ID | true | request.body?.orderId | | paymentId | String | true | request.body?.paymentId | | paymentStatus | String | true | request.body?.paymentStatus | | statusLiteral | String | true | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | ### REST Request To access the api you can use the **REST** controller with the path **POST /v1/ordermanagementorderpayment** ```js axios({ method: 'POST', url: '/v1/ordermanagementorderpayment', data: { orderId:"ID", paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`sys_orderManagementOrderPayment`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Delete Ordermanagementorder` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `deleteOrderManagementOrder` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `deleteOrderManagementOrder` Business API is designed to handle a `delete` operation on the `OrderManagementOrder` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Soft-delete/cancel order by admin or eligible actor prior to shipment. Sets status to CANCELLED and cancels active payment intent if pending. Irreversible and blocks feedback. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `ordermanagementorder-deleted` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `deleteOrderManagementOrder` Business API includes a REST controller that can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `deleteOrderManagementOrder` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `deleteOrderManagementOrder` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `orderManagementOrderId` | `ID` | `Yes` | `-` | `urlpath` | `orderManagementOrderId` | | **Description:** | This id paremeter is used to select the required data object that will be deleted | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `deleteOrderManagementOrder` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks This Business API enforces ownership of the main data object before executing the operation. - The check is performed **after fetching the object instance**. If the current user is not the owner, the API will respond with **403 Forbidden**. Note: Ownership checks are applied **only if the objects have an owner field**. --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.orderManagementOrderId},{isActive:true}]} ``` ## Delete Options Use these options to set `delete` specific settings. **useSoftDelete**: false If true, the record will be marked as deleted `(isActive: false)` instead of removed. The implementation depends on the data object’s soft delete configuration. ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request/session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads and normalizes parameters, applies defaults, and stores them in the context for downstream steps. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts, computes derived values, and remaps objects or arrays as needed for later processing. --- ### [4] Step : checkParameters Manager runs built-in validations including required field checks, type enforcement, and deletion preconditions. Stops execution if validation fails. --- ### [5] Step : checkBasicAuth Manager validates session, user roles, permissions, and tenant-specific access rules to enforce basic auth restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager generates the query conditions, applies ownership and parent checks, and ensures the clause is correct for the delete operation. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the target record, applies filters from WHERE clause, and writes the instance to the context for further checks. --- ### [8] Step : checkInstance Manager performs object-level validations such as lock status, soft-delete eligibility, and multi-step approval enforcement. --- ### [9] Step : mainDeleteOperation Manager executes the delete query, updates related indexes/caches, and handles soft/hard delete logic according to configuration. You can use the following settings to change some behavior of this step. `deleteOptions` --- ### [10] Step : buildOutput Manager shapes the response payload, masks sensitive fields, and formats related cleanup results for output. --- ### [11] Step : sendResponse Manager delivers the response to the client and finalizes any temporary internal structures. --- ### [12] Step : raiseApiEvent Manager triggers asynchronous API events, notifies queues or streams, and performs final cleanup for the workflow. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `deleteOrderManagementOrder` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | ### REST Request To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrder`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Delete Ordermanagementorderpayment` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `deleteOrderManagementOrderPayment` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `deleteOrderManagementOrderPayment` Business API is designed to handle a `delete` operation on the `Sys_orderManagementOrderPayment` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description This route is used to delete a payment. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `ordermanagementorderpayment-deleted` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `deleteOrderManagementOrderPayment` Business API includes a REST controller that can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `deleteOrderManagementOrderPayment` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `deleteOrderManagementOrderPayment` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `sys_orderManagementOrderPaymentId` | `ID` | `Yes` | `-` | `urlpath` | `sys_orderManagementOrderPaymentId` | | **Description:** | This id paremeter is used to select the required data object that will be deleted | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `deleteOrderManagementOrderPayment` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin]` --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.sys_orderManagementOrderPaymentId},{isActive:true}]} ``` ## Delete Options Use these options to set `delete` specific settings. **useSoftDelete**: If true, the record will be marked as deleted `(isActive: false)` instead of removed. The implementation depends on the data object’s soft delete configuration. ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request/session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads and normalizes parameters, applies defaults, and stores them in the context for downstream steps. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts, computes derived values, and remaps objects or arrays as needed for later processing. --- ### [4] Step : checkParameters Manager runs built-in validations including required field checks, type enforcement, and deletion preconditions. Stops execution if validation fails. --- ### [5] Step : checkBasicAuth Manager validates session, user roles, permissions, and tenant-specific access rules to enforce basic auth restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager generates the query conditions, applies ownership and parent checks, and ensures the clause is correct for the delete operation. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the target record, applies filters from WHERE clause, and writes the instance to the context for further checks. --- ### [8] Step : checkInstance Manager performs object-level validations such as lock status, soft-delete eligibility, and multi-step approval enforcement. --- ### [9] Step : mainDeleteOperation Manager executes the delete query, updates related indexes/caches, and handles soft/hard delete logic according to configuration. You can use the following settings to change some behavior of this step. `deleteOptions` --- ### [10] Step : buildOutput Manager shapes the response payload, masks sensitive fields, and formats related cleanup results for output. --- ### [11] Step : sendResponse Manager delivers the response to the client and finalizes any temporary internal structures. --- ### [12] Step : raiseApiEvent Manager triggers asynchronous API events, notifies queues or streams, and performs final cleanup for the workflow. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `deleteOrderManagementOrderPayment` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | ### REST Request To access the api you can use the **REST** controller with the path **DELETE /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'DELETE', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`sys_orderManagementOrderPayment`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Get Ordermanagementorder` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `getOrderManagementOrder` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `getOrderManagementOrder` Business API is designed to handle a `get` operation on the `OrderManagementOrder` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Get single order by ID. Only accessible to admin, buyer, or relevant sellers of items within this order. Includes all orderItems. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `ordermanagementorder-retrived` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `getOrderManagementOrder` Business API includes a REST controller that can be triggered via the following route: `/v1/ordermanagementorders/:orderManagementOrderId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `getOrderManagementOrder` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `getOrderManagementOrder` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `orderManagementOrderId` | `ID` | `Yes` | `-` | `urlpath` | `orderManagementOrderId` | | **Description:** | This id paremeter is used to query the required data object. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `getOrderManagementOrder` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks This Business API enforces ownership of the main data object before executing the operation. - The check is performed **after fetching the object instance**. If the current user is not the owner, the API will respond with **403 Forbidden**. Note: Ownership checks are applied **only if the objects have an owner field**. --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.orderManagementOrderId},{isActive:true}]} ``` ## Get Options Use these options to set `get` specific settings. **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Extracts parameters from request and Redis, applies defaults, and writes them to context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Executes parameter transformation scripts, applies type coercion, merges derived values, and reshapes inputs for downstream milestones. --- ### [4] Step : checkParameters Validates required and custom parameters, enforcing business-specific rules and constraints. --- ### [5] Step : checkBasicAuth Performs login, role, and permission checks, and applies dynamic object-level access rules. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Builds the WHERE clause for fetching the object and applies additional scoped filters if configured. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainGetOperation Executes the database fetch, retrieves the object, and stores it in context for enrichment or further checks. You can use the following settings to change some behavior of this step. `selectClause`, `getOptions` --- ### [8] Step : checkInstance Performs instance-level validations, such as ownership, existence, or access conditions. --- ### [9] Step : buildOutput Assembles the response from the object, applies masking, formatting, and injects additional metadata if needed. --- ### [10] Step : sendResponse Delivers the response to the controller for client delivery. --- ### [11] Step : raiseApiEvent Triggers optional API-level events after workflow completion, sending messages to integrations like Kafka if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `getOrderManagementOrder` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders/:orderManagementOrderId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorders/${orderManagementOrderId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrder`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Get Ordermanagementorderbyproductid` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `getOrderManagementOrderByProductId` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `getOrderManagementOrderByProductId` Business API is designed to handle a `get` operation on the `OrderManagementOrder` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description get orders by productId ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `ordermanagementorderbyproductid-retrived` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `getOrderManagementOrderByProductId` Business API includes a REST controller that can be triggered via the following route: `/v1/ordermanagementorderbyproductid/:items` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `getOrderManagementOrderByProductId` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `getOrderManagementOrderByProductId` Business API has 2 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `orderManagementOrderId` | `ID` | `Yes` | `-` | `urlpath` | `orderManagementOrderId` | | **Description:** | This id paremeter is used to query the required data object. | | | | | | | | | | | | | `items` | `String` | `Yes` | `-` | `urlpath` | `items` | | **Description:** | This parameter will be used to select the data object that is queried | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `getOrderManagementOrderByProductId` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks This Business API enforces ownership of the main data object before executing the operation. - The check is performed **after fetching the object instance**. If the current user is not the owner, the API will respond with **403 Forbidden**. Note: Ownership checks are applied **only if the objects have an owner field**. --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. The business api configuration has a `selectBy` setting: '['']` **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{items:{"$contains":this.items}},{isActive:true}]} ``` ## Get Options Use these options to set `get` specific settings. **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Extracts parameters from request and Redis, applies defaults, and writes them to context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Executes parameter transformation scripts, applies type coercion, merges derived values, and reshapes inputs for downstream milestones. --- ### [4] Step : checkParameters Validates required and custom parameters, enforcing business-specific rules and constraints. --- ### [5] Step : checkBasicAuth Performs login, role, and permission checks, and applies dynamic object-level access rules. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Builds the WHERE clause for fetching the object and applies additional scoped filters if configured. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainGetOperation Executes the database fetch, retrieves the object, and stores it in context for enrichment or further checks. You can use the following settings to change some behavior of this step. `selectClause`, `getOptions` --- ### [8] Step : checkInstance Performs instance-level validations, such as ownership, existence, or access conditions. --- ### [9] Step : buildOutput Assembles the response from the object, applies masking, formatting, and injects additional metadata if needed. --- ### [10] Step : sendResponse Delivers the response to the controller for client delivery. --- ### [11] Step : raiseApiEvent Triggers optional API-level events after workflow completion, sending messages to integrations like Kafka if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `getOrderManagementOrderByProductId` api has got 2 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | items | String | true | request.params?.items | ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderbyproductid/:items** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderbyproductid/${items}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrder`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Get Ordermanagementorderitem` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `getOrderManagementOrderItem` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `getOrderManagementOrderItem` Business API is designed to handle a `get` operation on the `OrderManagementOrderItem` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Get a specific order item (for feedback/business logic). ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `ordermanagementorderitem-retrived` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `getOrderManagementOrderItem` Business API includes a REST controller that can be triggered via the following route: `/v1/ordermanagementorderitems/:orderManagementOrderItemId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `getOrderManagementOrderItem` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `getOrderManagementOrderItem` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `orderManagementOrderItemId` | `ID` | `Yes` | `-` | `urlpath` | `orderManagementOrderItemId` | | **Description:** | This id paremeter is used to query the required data object. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `getOrderManagementOrderItem` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.orderManagementOrderItemId},{isActive:true}]} ``` ## Get Options Use these options to set `get` specific settings. **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Extracts parameters from request and Redis, applies defaults, and writes them to context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Executes parameter transformation scripts, applies type coercion, merges derived values, and reshapes inputs for downstream milestones. --- ### [4] Step : checkParameters Validates required and custom parameters, enforcing business-specific rules and constraints. --- ### [5] Step : checkBasicAuth Performs login, role, and permission checks, and applies dynamic object-level access rules. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Builds the WHERE clause for fetching the object and applies additional scoped filters if configured. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainGetOperation Executes the database fetch, retrieves the object, and stores it in context for enrichment or further checks. You can use the following settings to change some behavior of this step. `selectClause`, `getOptions` --- ### [8] Step : checkInstance Performs instance-level validations, such as ownership, existence, or access conditions. --- ### [9] Step : buildOutput Assembles the response from the object, applies masking, formatting, and injects additional metadata if needed. --- ### [10] Step : sendResponse Delivers the response to the controller for client delivery. --- ### [11] Step : raiseApiEvent Triggers optional API-level events after workflow completion, sending messages to integrations like Kafka if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `getOrderManagementOrderItem` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderItemId | ID | true | request.params?.orderManagementOrderItemId | ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems/:orderManagementOrderItemId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderitems/${orderManagementOrderItemId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrderItem`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItem", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "orderManagementOrderItem": { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Get Ordermanagementorderpayment2` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `getOrderManagementOrderPayment2` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `getOrderManagementOrderPayment2` Business API is designed to handle a `get` operation on the `Sys_orderManagementOrderPayment` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description This route is used to get the payment information by ID. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `ordermanagementorderpayment2-retrived` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `getOrderManagementOrderPayment2` Business API includes a REST controller that can be triggered via the following route: `/v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `getOrderManagementOrderPayment2` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `getOrderManagementOrderPayment2` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `sys_orderManagementOrderPaymentId` | `ID` | `Yes` | `-` | `urlpath` | `sys_orderManagementOrderPaymentId` | | **Description:** | This id paremeter is used to query the required data object. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `getOrderManagementOrderPayment2` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin]` --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.sys_orderManagementOrderPaymentId},{isActive:true}]} ``` ## Get Options Use these options to set `get` specific settings. **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Extracts parameters from request and Redis, applies defaults, and writes them to context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Executes parameter transformation scripts, applies type coercion, merges derived values, and reshapes inputs for downstream milestones. --- ### [4] Step : checkParameters Validates required and custom parameters, enforcing business-specific rules and constraints. --- ### [5] Step : checkBasicAuth Performs login, role, and permission checks, and applies dynamic object-level access rules. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Builds the WHERE clause for fetching the object and applies additional scoped filters if configured. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainGetOperation Executes the database fetch, retrieves the object, and stores it in context for enrichment or further checks. You can use the following settings to change some behavior of this step. `selectClause`, `getOptions` --- ### [8] Step : checkInstance Performs instance-level validations, such as ownership, existence, or access conditions. --- ### [9] Step : buildOutput Assembles the response from the object, applies masking, formatting, and injects additional metadata if needed. --- ### [10] Step : sendResponse Delivers the response to the controller for client delivery. --- ### [11] Step : raiseApiEvent Triggers optional API-level events after workflow completion, sending messages to integrations like Kafka if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `getOrderManagementOrderPayment2` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayment2/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'GET', url: `/v1/ordermanagementorderpayment2/${sys_orderManagementOrderPaymentId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`sys_orderManagementOrderPayment`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Get Ordermanagementorderpaymentbyorderid` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `getOrderManagementOrderPaymentByOrderId` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `getOrderManagementOrderPaymentByOrderId` Business API is designed to handle a `get` operation on the `Sys_orderManagementOrderPayment` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description This route is used to get the payment information by order id. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `ordermanagementorderpaymentbyorderid-retrived` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `getOrderManagementOrderPaymentByOrderId` Business API includes a REST controller that can be triggered via the following route: `/v1/orderManagementOrderpaymentbyorderid/:orderId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `getOrderManagementOrderPaymentByOrderId` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `getOrderManagementOrderPaymentByOrderId` Business API has 2 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `sys_orderManagementOrderPaymentId` | `ID` | `Yes` | `-` | `urlpath` | `sys_orderManagementOrderPaymentId` | | **Description:** | This id paremeter is used to query the required data object. | | | | | | | | | | | | | `orderId` | `String` | `Yes` | `-` | `urlpath` | `orderId` | | **Description:** | This parameter will be used to select the data object that is queried | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `getOrderManagementOrderPaymentByOrderId` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin]` --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. The business api configuration has a `selectBy` setting: '['']` **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{orderId:{"$eq":this.orderId}},{isActive:true}]} ``` ## Get Options Use these options to set `get` specific settings. **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Extracts parameters from request and Redis, applies defaults, and writes them to context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Executes parameter transformation scripts, applies type coercion, merges derived values, and reshapes inputs for downstream milestones. --- ### [4] Step : checkParameters Validates required and custom parameters, enforcing business-specific rules and constraints. --- ### [5] Step : checkBasicAuth Performs login, role, and permission checks, and applies dynamic object-level access rules. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Builds the WHERE clause for fetching the object and applies additional scoped filters if configured. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainGetOperation Executes the database fetch, retrieves the object, and stores it in context for enrichment or further checks. You can use the following settings to change some behavior of this step. `selectClause`, `getOptions` --- ### [8] Step : checkInstance Performs instance-level validations, such as ownership, existence, or access conditions. --- ### [9] Step : buildOutput Assembles the response from the object, applies masking, formatting, and injects additional metadata if needed. --- ### [10] Step : sendResponse Delivers the response to the controller for client delivery. --- ### [11] Step : raiseApiEvent Triggers optional API-level events after workflow completion, sending messages to integrations like Kafka if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `getOrderManagementOrderPaymentByOrderId` api has got 2 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | orderId | String | true | request.params?.orderId | ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbyorderid/:orderId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbyorderid/${orderId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`sys_orderManagementOrderPayment`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Get Ordermanagementorderpaymentbypaymentid` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `getOrderManagementOrderPaymentByPaymentId` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `getOrderManagementOrderPaymentByPaymentId` Business API is designed to handle a `get` operation on the `Sys_orderManagementOrderPayment` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description This route is used to get the payment information by payment id. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `ordermanagementorderpaymentbypaymentid-retrived` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `getOrderManagementOrderPaymentByPaymentId` Business API includes a REST controller that can be triggered via the following route: `/v1/orderManagementOrderpaymentbypaymentid/:paymentId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `getOrderManagementOrderPaymentByPaymentId` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `getOrderManagementOrderPaymentByPaymentId` Business API has 2 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `sys_orderManagementOrderPaymentId` | `ID` | `Yes` | `-` | `urlpath` | `sys_orderManagementOrderPaymentId` | | **Description:** | This id paremeter is used to query the required data object. | | | | | | | | | | | | | `paymentId` | `String` | `Yes` | `-` | `urlpath` | `paymentId` | | **Description:** | This parameter will be used to select the data object that is queried | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `getOrderManagementOrderPaymentByPaymentId` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin]` --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. The business api configuration has a `selectBy` setting: '['']` **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{paymentId:{"$eq":this.paymentId}},{isActive:true}]} ``` ## Get Options Use these options to set `get` specific settings. **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Extracts parameters from request and Redis, applies defaults, and writes them to context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Executes parameter transformation scripts, applies type coercion, merges derived values, and reshapes inputs for downstream milestones. --- ### [4] Step : checkParameters Validates required and custom parameters, enforcing business-specific rules and constraints. --- ### [5] Step : checkBasicAuth Performs login, role, and permission checks, and applies dynamic object-level access rules. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Builds the WHERE clause for fetching the object and applies additional scoped filters if configured. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainGetOperation Executes the database fetch, retrieves the object, and stores it in context for enrichment or further checks. You can use the following settings to change some behavior of this step. `selectClause`, `getOptions` --- ### [8] Step : checkInstance Performs instance-level validations, such as ownership, existence, or access conditions. --- ### [9] Step : buildOutput Assembles the response from the object, applies masking, formatting, and injects additional metadata if needed. --- ### [10] Step : sendResponse Delivers the response to the controller for client delivery. --- ### [11] Step : raiseApiEvent Triggers optional API-level events after workflow completion, sending messages to integrations like Kafka if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `getOrderManagementOrderPaymentByPaymentId` api has got 2 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | true | request.params?.paymentId | ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/orderManagementOrderpaymentbypaymentid/:paymentId** ```js axios({ method: 'GET', url: `/v1/orderManagementOrderpaymentbypaymentid/${paymentId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`sys_orderManagementOrderPayment`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Get Paymentcustomerbyuserid` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `getPaymentCustomerByUserId` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `getPaymentCustomerByUserId` Business API is designed to handle a `get` operation on the `Sys_paymentCustomer` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description This route is used to get the payment customer information by user id. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `paymentcustomerbyuserid-retrived` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `getPaymentCustomerByUserId` Business API includes a REST controller that can be triggered via the following route: `/v1/paymentcustomers/:userId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `getPaymentCustomerByUserId` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `getPaymentCustomerByUserId` Business API has 2 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `sys_paymentCustomerId` | `ID` | `Yes` | `-` | `urlpath` | `sys_paymentCustomerId` | | **Description:** | This id paremeter is used to query the required data object. | | | | | | | | | | | | | `userId` | `String` | `Yes` | `-` | `urlpath` | `userId` | | **Description:** | This parameter will be used to select the data object that is queried | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `getPaymentCustomerByUserId` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin]` --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. The business api configuration has a `selectBy` setting: '['']` **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{userId:{"$eq":this.userId}},{isActive:true}]} ``` ## Get Options Use these options to set `get` specific settings. **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Extracts parameters from request and Redis, applies defaults, and writes them to context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Executes parameter transformation scripts, applies type coercion, merges derived values, and reshapes inputs for downstream milestones. --- ### [4] Step : checkParameters Validates required and custom parameters, enforcing business-specific rules and constraints. --- ### [5] Step : checkBasicAuth Performs login, role, and permission checks, and applies dynamic object-level access rules. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Builds the WHERE clause for fetching the object and applies additional scoped filters if configured. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainGetOperation Executes the database fetch, retrieves the object, and stores it in context for enrichment or further checks. You can use the following settings to change some behavior of this step. `selectClause`, `getOptions` --- ### [8] Step : checkInstance Performs instance-level validations, such as ownership, existence, or access conditions. --- ### [9] Step : buildOutput Assembles the response from the object, applies masking, formatting, and injects additional metadata if needed. --- ### [10] Step : sendResponse Delivers the response to the controller for client delivery. --- ### [11] Step : raiseApiEvent Triggers optional API-level events after workflow completion, sending messages to integrations like Kafka if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `getPaymentCustomerByUserId` api has got 2 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_paymentCustomerId | ID | true | request.params?.sys_paymentCustomerId | | userId | String | true | request.params?.userId | ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomers/${userId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`sys_paymentCustomer`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomer", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "sys_paymentCustomer": { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Lis Ordermanagementownorderitem` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `lisOrderManagementOwnOrderItem` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `lisOrderManagementOwnOrderItem` Business API is designed to handle a `list` operation on the `OrderManagementOrderItem` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description list the loggedin user's order items ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `ordermanagementownorderitem-lissed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `lisOrderManagementOwnOrderItem` Business API includes a REST controller that can be triggered via the following route: `/v1/lisordermanagementownorderitem` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `lisOrderManagementOwnOrderItem` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `lisOrderManagementOwnOrderItem` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `lisOrderManagementOwnOrderItem` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has a `fullWhereClause` setting : ```js {sellerId:this.session.userId} ``` **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{sellerId:this.session.userId},{isActive:true}]} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `lisOrderManagementOwnOrderItem` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/lisordermanagementownorderitem** ```js axios({ method: 'GET', url: '/v1/lisordermanagementownorderitem', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrderItems`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `List Ordermanagementorderitems` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `listOrderManagementOrderItems` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `listOrderManagementOrderItems` Business API is designed to handle a `list` operation on the `OrderManagementOrderItem` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description List order items for a given order or for buyer/seller analytics. Used for feedback management. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `ordermanagementorderitems-listed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `listOrderManagementOrderItems` Business API includes a REST controller that can be triggered via the following route: `/v1/ordermanagementorderitems` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `listOrderManagementOrderItems` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `listOrderManagementOrderItems` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `listOrderManagementOrderItems` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {isActive:true} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `listOrderManagementOrderItems` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderitems** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderitems', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrderItems`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrderItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrderItems": [ { "id": "ID", "shipping": "Double", "orderId": "ID", "quantity": "Integer", "productId": "ID", "price": "Double", "sellerId": "ID", "title": "String", "currency": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `List Ordermanagementorderpayments2` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `listOrderManagementOrderPayments2` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `listOrderManagementOrderPayments2` Business API is designed to handle a `list` operation on the `Sys_orderManagementOrderPayment` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description This route is used to list all payments. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `ordermanagementorderpayments2-listed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `listOrderManagementOrderPayments2` Business API includes a REST controller that can be triggered via the following route: `/v1/ordermanagementorderpayments2` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `listOrderManagementOrderPayments2` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `listOrderManagementOrderPayments2` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `listOrderManagementOrderPayments2` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin]` --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {isActive:true} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `listOrderManagementOrderPayments2` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorderpayments2** ```js axios({ method: 'GET', url: '/v1/ordermanagementorderpayments2', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`sys_orderManagementOrderPayments`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayments", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_orderManagementOrderPayments": [ { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `List Ordermanagementorders` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `listOrderManagementOrders` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `listOrderManagementOrders` Business API is designed to handle a `list` operation on the `OrderManagementOrder` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description List orders, filtered for buyer and/or seller, or by admin. Includes select orderItems. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `ordermanagementorders-listed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `listOrderManagementOrders` Business API includes a REST controller that can be triggered via the following route: `/v1/ordermanagementorders` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `listOrderManagementOrders` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `listOrderManagementOrders` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `listOrderManagementOrders` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {isActive:true} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `listOrderManagementOrders` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/ordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ordermanagementorders', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrders`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `List Ownordermanagementorders` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `listOwnOrderManagementOrders` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `listOwnOrderManagementOrders` Business API is designed to handle a `list` operation on the `OrderManagementOrder` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description list the loggedin user orders ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `ownordermanagementorders-listed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `listOwnOrderManagementOrders` Business API includes a REST controller that can be triggered via the following route: `/v1/ownordermanagementorders` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `listOwnOrderManagementOrders` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `listOwnOrderManagementOrders` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `listOwnOrderManagementOrders` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has a `fullWhereClause` setting : ```js {buyerId:this.session.userId} ``` **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{buyerId:this.session.userId},{isActive:true}]} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `listOwnOrderManagementOrders` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/ownordermanagementorders** ```js axios({ method: 'GET', url: '/v1/ownordermanagementorders', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrders`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrders", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "orderManagementOrders": [ { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `List Paymentcustomermethods` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `listPaymentCustomerMethods` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `listPaymentCustomerMethods` Business API is designed to handle a `list` operation on the `Sys_paymentMethod` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description This route is used to list all payment customer methods. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `paymentcustomermethods-listed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `listPaymentCustomerMethods` Business API includes a REST controller that can be triggered via the following route: `/v1/paymentcustomermethods/:userId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `listPaymentCustomerMethods` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `listPaymentCustomerMethods` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `userId` | `String` | `Yes` | `-` | `urlpath` | `userId` | | **Description:** | This parameter will be used to select the data objects that want to be listed | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `listPaymentCustomerMethods` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin]` --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. The business api configuration has a `selectBy` setting: '['']` **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{userId:{"$eq":this.userId}},{isActive:true}]} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `listPaymentCustomerMethods` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | userId | String | true | request.params?.userId | ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomermethods/:userId** ```js axios({ method: 'GET', url: `/v1/paymentcustomermethods/${userId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`sys_paymentMethods`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentMethods", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentMethods": [ { "id": "ID", "paymentMethodId": "String", "userId": "ID", "customerId": "String", "cardHolderName": "String", "cardHolderZip": "String", "platform": "String", "cardInfo": "Object", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `List Paymentcustomers` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `listPaymentCustomers` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `listPaymentCustomers` Business API is designed to handle a `list` operation on the `Sys_paymentCustomer` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description This route is used to list all payment customers. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `paymentcustomers-listed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `listPaymentCustomers` Business API includes a REST controller that can be triggered via the following route: `/v1/paymentcustomers` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `listPaymentCustomers` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `listPaymentCustomers` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `listPaymentCustomers` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin]` --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {isActive:true} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `listPaymentCustomers` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/paymentcustomers** ```js axios({ method: 'GET', url: '/v1/paymentcustomers', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`sys_paymentCustomers`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_paymentCustomers", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "sys_paymentCustomers": [ { "id": "ID", "userId": "ID", "customerId": "String", "platform": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `Refresh Ordermanagementorderpayment` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `refreshOrderManagementOrderPayment` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `refreshOrderManagementOrderPayment` Business API is designed to handle a `update` operation on the `OrderManagementOrder` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Refresh payment info for orderManagementOrder from Stripe ## API Options * **Auto Params** : `false` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `ordermanagementorderpayment-refreshed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `refreshOrderManagementOrderPayment` Business API includes a REST controller that can be triggered via the following route: `/v1/refreshordermanagementorderpayment/:orderManagementOrderId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `refreshOrderManagementOrderPayment` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `refreshOrderManagementOrderPayment` Business API has 2 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `orderManagementOrderId` | `ID` | `Yes` | `-` | `urlpath` | `orderManagementOrderId` | | **Description:** | This id paremeter is used to select the required data object that will be updated | | | | | | | | | | | | | `paymentUserParams` | `Object` | `No` | `-` | `body` | `paymentUserParams` | | **Description:** | The user parameters that should be defined to refresh a stripe payment process | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `refreshOrderManagementOrderPayment` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks This Business API enforces ownership of the main data object before executing the operation. - The check is performed **after fetching the object instance**. If the current user is not the owner, the API will respond with **403 Forbidden**. Note: Ownership checks are applied **only if the objects have an owner field**. --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin]` --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.orderManagementOrderId},{isActive:true}]} ``` ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. An update data clause populates all update-allowed properties of a data object, however the null properties (that are not provided by client) are ignored in db layer. **Custom Data Clause Override** ```js { status: this.status, updatedAt: new Date(), _paymentConfirmation: this._paymentConfirmation, } ``` **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { status: this.status, updatedAt: new Date(), // _paymentConfirmation parameter is closed to update by client request // include it in data clause unless you are sure _paymentConfirmation: this._paymentConfirmation, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request and session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads parameters from the request or Redis, applies defaults, and writes them into context for downstream milestones. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts and derives any helper values or reshaped payloads into the context. --- ### [4] Step : checkParameters Manager validates required parameters, checks ID formats (UUID/ObjectId), and ensures all preconditions for update are met. --- ### [5] Step : checkBasicAuth Manager performs login verification, role, and permission checks, enforcing tenant and access rules before update. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager constructs the WHERE clause used to identify the record to update, applying ownership and parent checks if necessary. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the existing record from the database and writes it to the context for validation or enrichment. --- ### [8] Step : checkInstance Manager performs instance-level validations, including ownership, existence, lock status, or other pre-update checks. --- ### [9] Action : doRefreshPayment **Action Type**: `CheckoutAction` Refresh payment from Stripe platform, the payment operation data in the gateway server will be fetched and the application payment tickets and order status will be refreshed according to the server. This api may be used if you dont want to use a webhook. ```js class Api { getOrderId() { return this.orderManagementOrderId; } getPaymentStatusTopic(actionType) { switch (actionType) { case "started": return "ebaycclone-ordermanagement-service-ordermanagementorderpaymentstatus-started"; case "updated": return "ebaycclone-ordermanagement-service-ordermanagementorderpaymentstatus-updated"; case "succeeded": return "ebaycclone-ordermanagement-service-ordermanagementorderpaymentstatus-succeeded"; case "failed": return "ebaycclone-ordermanagement-service-ordermanagementorderpaymentstatus-failed"; } } async checkoutUpdated(statusLiteral) { switch (statusLiteral) { case "started": await this.checkoutStarted(); break; case "canceled": await this.checkoutCanceled(); break; case "failed": await this.checkoutFailed(); break; case "success": await this.checkoutDone(); break; default: await this.checkoutFailed(); break; } } async checkoutStarted() { this.status = "PENDING_PAYMENT"; this._paymentConfirmation = "processing"; this.raisePaymentStatusEvent("started"); } async checkoutCanceled() { this.status = "CANCELLED"; this._paymentConfirmation = "canceled"; this.raisePaymentStatusEvent("failed"); } async checkoutFailed() { this.status = "CANCELLED"; this._paymentConfirmation = "canceled"; this.raisePaymentStatusEvent("failed"); } async checkoutDone() { this.status = "PAID"; this._paymentConfirmation = "paid"; this.raisePaymentStatusEvent("succeeded"); } getCheckoutParameters(userParams) { const description = `Order #${this.orderManagementOrder.orderNumber} for buyerId ${this.orderManagementOrder.buyerId}`; return { userId: this.session._USERID, fullname: this.session.fullname, email: this.session.email, description, amount: this.orderManagementOrder.summary.total, currency: this.orderManagementOrder.summary.currency, orderId: this.orderManagementOrder.id, metadata: { order: "OrderManagement-OrderManagementOrder-order", orderId: this.orderManagementOrder.id, checkoutName: "orderManagementOrder", }, storeCard: userParams?.storeCard, paymentUserParams: userParams, bodyParams: this.bodyParams, }; } async doRefreshPayment() { // Handle Checkout Action try { if (!this.checkoutManager) { throw new Error( "This dboject is not an order object. So auto-checkout process can not be started.", ); } this.paymentResult = await this.checkoutManager.refreshCheckout( this.paymentUserParams, ); } catch (err) { if (err instanceof PaymentGateError) { this.paymentResult = err.serializeError(); //**errorLog } else throw err; } return this.paymentResult; } } ``` --- ### [10] Step : buildDataClause Manager prepares the data clause for the update, applying transformations or enhancements before persisting. You can use the following settings to change some behavior of this step. `dataClause` --- ### [11] Step : mainUpdateOperation Manager executes the update operation with the WHERE and data clauses. Database-level events are raised if configured. --- ### [12] Step : buildOutput Manager assembles the response object from the update result, masking fields or injecting additional metadata. --- ### [13] Step : sendResponse Manager sends the response back to the controller for delivery to the client. --- ### [14] Step : raiseApiEvent Manager triggers API-level events, sending relevant messages to Kafka or other integrations if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `refreshOrderManagementOrderPayment` api has got 2 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | ### REST Request To access the api you can use the **REST** controller with the path **PATCH /v1/refreshordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/refreshordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrder`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` # Business API Design Specification - `Start Ordermanagementorderpayment` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `startOrderManagementOrderPayment` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `startOrderManagementOrderPayment` Business API is designed to handle a `update` operation on the `OrderManagementOrder` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Start payment for orderManagementOrder ## API Options * **Auto Params** : `false` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `ordermanagementorderpayment-started` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `startOrderManagementOrderPayment` Business API includes a REST controller that can be triggered via the following route: `/v1/startordermanagementorderpayment/:orderManagementOrderId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `startOrderManagementOrderPayment` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `startOrderManagementOrderPayment` Business API has 2 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `orderManagementOrderId` | `ID` | `Yes` | `-` | `urlpath` | `orderManagementOrderId` | | **Description:** | This id paremeter is used to select the required data object that will be updated | | | | | | | | | | | | | `paymentUserParams` | `Object` | `No` | `-` | `body` | `paymentUserParams` | | **Description:** | The user parameters that should be defined to start a stripe payment process | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `startOrderManagementOrderPayment` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks This Business API enforces ownership of the main data object before executing the operation. - The check is performed **after fetching the object instance**. If the current user is not the owner, the API will respond with **403 Forbidden**. Note: Ownership checks are applied **only if the objects have an owner field**. --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin]` --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.orderManagementOrderId},{isActive:true}]} ``` ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. An update data clause populates all update-allowed properties of a data object, however the null properties (that are not provided by client) are ignored in db layer. **Custom Data Clause Override** ```js { status: this.status, updatedAt: new Date(), _paymentConfirmation: this._paymentConfirmation, } ``` **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { status: this.status, updatedAt: new Date(), // _paymentConfirmation parameter is closed to update by client request // include it in data clause unless you are sure _paymentConfirmation: this._paymentConfirmation, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request and session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads parameters from the request or Redis, applies defaults, and writes them into context for downstream milestones. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts and derives any helper values or reshaped payloads into the context. --- ### [4] Step : checkParameters Manager validates required parameters, checks ID formats (UUID/ObjectId), and ensures all preconditions for update are met. --- ### [5] Step : checkBasicAuth Manager performs login verification, role, and permission checks, enforcing tenant and access rules before update. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager constructs the WHERE clause used to identify the record to update, applying ownership and parent checks if necessary. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the existing record from the database and writes it to the context for validation or enrichment. --- ### [8] Step : checkInstance Manager performs instance-level validations, including ownership, existence, lock status, or other pre-update checks. --- ### [9] Action : doStartPayment **Action Type**: `CheckoutAction` Start a payment on Stripe platform ```js class Api { getOrderId() { return this.orderManagementOrderId; } getPaymentStatusTopic(actionType) { switch (actionType) { case "started": return "ebaycclone-ordermanagement-service-ordermanagementorderpaymentstatus-started"; case "updated": return "ebaycclone-ordermanagement-service-ordermanagementorderpaymentstatus-updated"; case "succeeded": return "ebaycclone-ordermanagement-service-ordermanagementorderpaymentstatus-succeeded"; case "failed": return "ebaycclone-ordermanagement-service-ordermanagementorderpaymentstatus-failed"; } } async checkoutUpdated(statusLiteral) { switch (statusLiteral) { case "started": await this.checkoutStarted(); break; case "canceled": await this.checkoutCanceled(); break; case "failed": await this.checkoutFailed(); break; case "success": await this.checkoutDone(); break; default: await this.checkoutFailed(); break; } } async checkoutStarted() { this.status = "PENDING_PAYMENT"; this._paymentConfirmation = "processing"; this.raisePaymentStatusEvent("started"); } async checkoutCanceled() { this.status = "CANCELLED"; this._paymentConfirmation = "canceled"; this.raisePaymentStatusEvent("failed"); } async checkoutFailed() { this.status = "CANCELLED"; this._paymentConfirmation = "canceled"; this.raisePaymentStatusEvent("failed"); } async checkoutDone() { this.status = "PAID"; this._paymentConfirmation = "paid"; this.raisePaymentStatusEvent("succeeded"); } getCheckoutParameters(userParams) { const description = `Order #${this.orderManagementOrder.orderNumber} for buyerId ${this.orderManagementOrder.buyerId}`; return { userId: this.session._USERID, fullname: this.session.fullname, email: this.session.email, description, amount: this.orderManagementOrder.summary.total, currency: this.orderManagementOrder.summary.currency, orderId: this.orderManagementOrder.id, metadata: { order: "OrderManagement-OrderManagementOrder-order", orderId: this.orderManagementOrder.id, checkoutName: "orderManagementOrder", }, storeCard: userParams?.storeCard, paymentUserParams: userParams, bodyParams: this.bodyParams, }; } async doStartPayment() { // Handle Checkout Action try { if (!this.checkoutManager) { throw new Error( "This dboject is not an order object. So auto-checkout process can not be started.", ); } this.paymentResult = await this.checkoutManager.startCheckout( this.paymentUserParams, ); } catch (err) { if (err instanceof PaymentGateError) { this.paymentResult = err.serializeError(); //**errorLog } else throw err; } return this.paymentResult; } } ``` --- ### [10] Step : buildDataClause Manager prepares the data clause for the update, applying transformations or enhancements before persisting. You can use the following settings to change some behavior of this step. `dataClause` --- ### [11] Step : mainUpdateOperation Manager executes the update operation with the WHERE and data clauses. Database-level events are raised if configured. --- ### [12] Step : buildOutput Manager assembles the response object from the update result, masking fields or injecting additional metadata. --- ### [13] Step : sendResponse Manager sends the response back to the controller for delivery to the client. --- ### [14] Step : raiseApiEvent Manager triggers API-level events, sending relevant messages to Kafka or other integrations if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `startOrderManagementOrderPayment` api has got 2 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | paymentUserParams | Object | false | request.body?.paymentUserParams | ### REST Request To access the api you can use the **REST** controller with the path **PATCH /v1/startordermanagementorderpayment/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/startordermanagementorderpayment/${orderManagementOrderId}`, data: { paymentUserParams:"Object", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrder`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, "paymentResult": { "paymentTicketId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "Enum", "paymentIntentInfo": "Object", "statusLiteral": "String", "amount": "Double", "currency": "String", "success": true, "description": "String", "metadata": "Object", "paymentUserParams": "Object" } } ``` # Business API Design Specification - `Update Ordermanagementorderpayment` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `updateOrderManagementOrderPayment` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `updateOrderManagementOrderPayment` Business API is designed to handle a `update` operation on the `Sys_orderManagementOrderPayment` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description This route is used to update an existing payment. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `ordermanagementorderpayment-updated` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `updateOrderManagementOrderPayment` Business API includes a REST controller that can be triggered via the following route: `/v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `updateOrderManagementOrderPayment` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `updateOrderManagementOrderPayment` Business API has 6 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `sys_orderManagementOrderPaymentId` | `ID` | `Yes` | `-` | `urlpath` | `sys_orderManagementOrderPaymentId` | | **Description:** | This id paremeter is used to select the required data object that will be updated | | | | | | | | | | | | | `ownerId` | `ID` | `No` | `-` | `session` | `userId` | | **Description:** | An ID value to represent owner user who created the order | | | | | | | | | | | | | `paymentId` | `String` | `No` | `-` | `body` | `paymentId` | | **Description:** | A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type | | | | | | | | | | | | | `paymentStatus` | `String` | `No` | `-` | `body` | `paymentStatus` | | **Description:** | A string value to represent the payment status which belongs to the lifecyle of a Stripe payment. | | | | | | | | | | | | | `statusLiteral` | `String` | `No` | `-` | `body` | `statusLiteral` | | **Description:** | A string value to represent the logical payment status which belongs to the application lifecycle itself. | | | | | | | | | | | | | `redirectUrl` | `String` | `No` | `-` | `body` | `redirectUrl` | | **Description:** | A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `updateOrderManagementOrderPayment` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings - **Absolute roles** (bypass all auth checks): Users with any of the following roles will bypass all authentication and authorization checks, including ownership, membership, and standard role/permission checks: `[superAdmin]` --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.sys_orderManagementOrderPaymentId},{isActive:true}]} ``` ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. An update data clause populates all update-allowed properties of a data object, however the null properties (that are not provided by client) are ignored in db layer. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { ownerId: this.ownerId, paymentId: this.paymentId, paymentStatus: this.paymentStatus, statusLiteral: this.statusLiteral, redirectUrl: this.redirectUrl, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request and session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads parameters from the request or Redis, applies defaults, and writes them into context for downstream milestones. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts and derives any helper values or reshaped payloads into the context. --- ### [4] Step : checkParameters Manager validates required parameters, checks ID formats (UUID/ObjectId), and ensures all preconditions for update are met. --- ### [5] Step : checkBasicAuth Manager performs login verification, role, and permission checks, enforcing tenant and access rules before update. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager constructs the WHERE clause used to identify the record to update, applying ownership and parent checks if necessary. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the existing record from the database and writes it to the context for validation or enrichment. --- ### [8] Step : checkInstance Manager performs instance-level validations, including ownership, existence, lock status, or other pre-update checks. --- ### [9] Step : buildDataClause Manager prepares the data clause for the update, applying transformations or enhancements before persisting. You can use the following settings to change some behavior of this step. `dataClause` --- ### [10] Step : mainUpdateOperation Manager executes the update operation with the WHERE and data clauses. Database-level events are raised if configured. --- ### [11] Step : buildOutput Manager assembles the response object from the update result, masking fields or injecting additional metadata. --- ### [12] Step : sendResponse Manager sends the response back to the controller for delivery to the client. --- ### [13] Step : raiseApiEvent Manager triggers API-level events, sending relevant messages to Kafka or other integrations if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `updateOrderManagementOrderPayment` api has got 5 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | sys_orderManagementOrderPaymentId | ID | true | request.params?.sys_orderManagementOrderPaymentId | | paymentId | String | false | request.body?.paymentId | | paymentStatus | String | false | request.body?.paymentStatus | | statusLiteral | String | false | request.body?.statusLiteral | | redirectUrl | String | false | request.body?.redirectUrl | ### REST Request To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderpayment/:sys_orderManagementOrderPaymentId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderpayment/${sys_orderManagementOrderPaymentId}`, data: { paymentId:"String", paymentStatus:"String", statusLiteral:"String", redirectUrl:"String", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`sys_orderManagementOrderPayment`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "sys_orderManagementOrderPayment", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "sys_orderManagementOrderPayment": { "id": "ID", "ownerId": "ID", "orderId": "ID", "paymentId": "String", "paymentStatus": "String", "statusLiteral": "String", "redirectUrl": "String", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Update Ordermanagementorderstatus` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `updateOrderManagementOrderStatus` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `updateOrderManagementOrderStatus` Business API is designed to handle a `update` operation on the `OrderManagementOrder` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Update order status (manual shipment, delivery, cancellation/refund). Restricted: only seller of all items can mark as shipped, only buyer can confirm delivery, only admin can set refund/cancelled. Timestamps updated as per business rule. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `ordermanagementorderstatus-updated` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `updateOrderManagementOrderStatus` Business API includes a REST controller that can be triggered via the following route: `/v1/ordermanagementorderstatus/:orderManagementOrderId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `updateOrderManagementOrderStatus` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `updateOrderManagementOrderStatus` Business API has 10 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `orderManagementOrderId` | `ID` | `Yes` | `-` | `urlpath` | `orderManagementOrderId` | | **Description:** | This id paremeter is used to select the required data object that will be updated | | | | | | | | | | | | | `status` | `Enum` | `No` | `-` | `body` | `status` | | **Description:** | Order lifecycle: PENDING_PAYMENT, PAID, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED | | | | | | | | | | | | | `paymentIntentId` | `String` | `No` | `-` | `body` | `paymentIntentId` | | **Description:** | Stripe paymentIntentId; enables webhook correlation and status sync. | | | | | | | | | | | | | `trackingNumber` | `String` | `No` | `-` | `body` | `trackingNumber` | | **Description:** | Optional tracking number entered by seller when marking as shipped. | | | | | | | | | | | | | `estimatedDelivery` | `Date` | `No` | `-` | `body` | `estimatedDelivery` | | **Description:** | Estimated delivery date for order; copied from fastest estimated item or seller input. | | | | | | | | | | | | | `cancelledAt` | `Date` | `No` | `-` | `body` | `cancelledAt` | | **Description:** | Timestamp when cancelled by buyer, seller, or admin before shipment. | | | | | | | | | | | | | `paidAt` | `Date` | `No` | `-` | `body` | `paidAt` | | **Description:** | Timestamp when payment confirmed via Stripe or manual admin update. | | | | | | | | | | | | | `deliveredAt` | `Date` | `No` | `-` | `body` | `deliveredAt` | | **Description:** | Timestamp when buyer confirms delivery. | | | | | | | | | | | | | `shippedAt` | `Date` | `No` | `-` | `body` | `shippedAt` | | **Description:** | Timestamp when seller marks as shipped. | | | | | | | | | | | | | `carrier` | `String` | `No` | `-` | `body` | `carrier` | | **Description:** | Optional carrier name entered by seller when marking as shipped. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `updateOrderManagementOrderStatus` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks This Business API enforces ownership of the main data object before executing the operation. - The check is performed **after fetching the object instance**. If the current user is not the owner, the API will respond with **403 Forbidden**. Note: Ownership checks are applied **only if the objects have an owner field**. --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.orderManagementOrderId},{isActive:true}]} ``` ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. An update data clause populates all update-allowed properties of a data object, however the null properties (that are not provided by client) are ignored in db layer. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { status: this.status, paymentIntentId: this.paymentIntentId, trackingNumber: this.trackingNumber, estimatedDelivery: this.estimatedDelivery, cancelledAt: this.cancelledAt, paidAt: this.paidAt, deliveredAt: this.deliveredAt, shippedAt: this.shippedAt, carrier: this.carrier, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request and session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads parameters from the request or Redis, applies defaults, and writes them into context for downstream milestones. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts and derives any helper values or reshaped payloads into the context. --- ### [4] Step : checkParameters Manager validates required parameters, checks ID formats (UUID/ObjectId), and ensures all preconditions for update are met. --- ### [5] Step : checkBasicAuth Manager performs login verification, role, and permission checks, enforcing tenant and access rules before update. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager constructs the WHERE clause used to identify the record to update, applying ownership and parent checks if necessary. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the existing record from the database and writes it to the context for validation or enrichment. --- ### [8] Step : checkInstance Manager performs instance-level validations, including ownership, existence, lock status, or other pre-update checks. --- ### [9] Step : buildDataClause Manager prepares the data clause for the update, applying transformations or enhancements before persisting. You can use the following settings to change some behavior of this step. `dataClause` --- ### [10] Step : mainUpdateOperation Manager executes the update operation with the WHERE and data clauses. Database-level events are raised if configured. --- ### [11] Step : buildOutput Manager assembles the response object from the update result, masking fields or injecting additional metadata. --- ### [12] Step : sendResponse Manager sends the response back to the controller for delivery to the client. --- ### [13] Step : raiseApiEvent Manager triggers API-level events, sending relevant messages to Kafka or other integrations if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `updateOrderManagementOrderStatus` api has got 10 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | orderManagementOrderId | ID | true | request.params?.orderManagementOrderId | | status | Enum | false | request.body?.status | | paymentIntentId | String | false | request.body?.paymentIntentId | | trackingNumber | String | false | request.body?.trackingNumber | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | cancelledAt | Date | false | request.body?.cancelledAt | | paidAt | Date | false | request.body?.paidAt | | deliveredAt | Date | false | request.body?.deliveredAt | | shippedAt | Date | false | request.body?.shippedAt | | carrier | String | false | request.body?.carrier | ### REST Request To access the api you can use the **REST** controller with the path **PATCH /v1/ordermanagementorderstatus/:orderManagementOrderId** ```js axios({ method: 'PATCH', url: `/v1/ordermanagementorderstatus/${orderManagementOrderId}`, data: { status:"Enum", paymentIntentId:"String", trackingNumber:"String", estimatedDelivery:"Date", cancelledAt:"Date", paidAt:"Date", deliveredAt:"Date", shippedAt:"Date", carrier:"String", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`orderManagementOrder`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "orderManagementOrder", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "orderManagementOrder": { "id": "ID", "orderNumber": "String", "items": "ID", "buyerId": "ID", "status": "Enum", "status_idx": "Integer", "paymentMethodId": "String", "stripeCustomerId": "String", "paymentIntentId": "String", "shippingAddress": "Object", "summary": "Object", "trackingNumber": "String", "estimatedDelivery": "Date", "cancelledAt": "Date", "paidAt": "Date", "deliveredAt": "Date", "shippedAt": "Date", "carrier": "String", "_paymentConfirmation": "Enum", "_paymentConfirmation_idx": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Create Productlistingmedia` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `createProductListingMedia` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `createProductListingMedia` Business API is designed to handle a `create` operation on the `ProductListingMedia` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Create a new media asset record after validation. Used mainly by edge controller after upload. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `productlistingmedia-created` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `createProductListingMedia` Business API includes a REST controller that can be triggered via the following route: `/v1/productlistingmedias` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `createProductListingMedia` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `createProductListingMedia` Business API has 5 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `productListingMediaId` | `ID` | `No` | `-` | `body` | `productListingMediaId` | | **Description:** | This id paremeter is used to create the data object with a given specific id. Leave null for automatic id. | | | | | | | | | | | | | `mimeType` | `String` | `Yes` | `-` | `body` | `mimeType` | | **Description:** | MIME type of the uploaded media (e.g., image/jpeg) | | | | | | | | | | | | | `productId` | `ID` | `No` | `-` | `body` | `productId` | | **Description:** | ID of product associated with this media asset | | | | | | | | | | | | | `url` | `String` | `Yes` | `-` | `body` | `url` | | **Description:** | Secure, validated URL for the media asset (S3 or equivalent) | | | | | | | | | | | | | `size` | `Integer` | `Yes` | `-` | `body` | `size` | | **Description:** | Media size in bytes (for validation and quota) | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `createProductListingMedia` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { id: this.productListingMediaId, mimeType: this.mimeType, productId: this.productId, url: this.url, size: this.size, isActive: true, _archivedAt: null, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, populates session and request objects, prepares internal structures for parameter handling and workflow execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads input parameters, normalizes missing values, applies default type casting, and stores them in the API context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager transforms parameters, computes derived values, flattens or remaps arrays/objects, and adjusts formats for downstream processing. --- ### [4] Step : checkParameters Manager executes built-in validations: required field checks, type enforcement, and basic business rules. Prevents operation if validation fails. --- ### [5] Step : checkBasicAuth Manager performs authentication and authorization checks: verifies session, user roles, permissions, and tenant restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildDataClause Manager constructs the final data object for creation, fills auto-generated fields (IDs, timestamps, owner fields), and ensures schema consistency. You can use the following settings to change some behavior of this step. `dataClause` --- ### [7] Step : mainCreateOperation Manager executes the database insert operation, updates indexes/caches, and triggers internal post-processing like linked default records. --- ### [8] Step : buildOutput Manager shapes the response: masks sensitive fields, resolves linked references, and formats output according to API contract. --- ### [9] Step : sendResponse Manager sends the response to the client and finalizes internal tasks like flushing logs or updating session state. --- ### [10] Step : raiseApiEvent Manager triggers API-level events (Kafka, WebSocket, async workflows) as the final internal step. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `createProductListingMedia` api has got 4 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | mimeType | String | true | request.body?.mimeType | | productId | ID | false | request.body?.productId | | url | String | true | request.body?.url | | size | Integer | true | request.body?.size | ### REST Request To access the api you can use the **REST** controller with the path **POST /v1/productlistingmedias** ```js axios({ method: 'POST', url: '/v1/productlistingmedias', data: { mimeType:"String", productId:"ID", url:"String", size:"Integer", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`productListingMedia`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Create Productlistingproduct` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `createProductListingProduct` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `createProductListingProduct` Business API is designed to handle a `create` operation on the `ProductListingProduct` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Create a new product listing (fixed or auction), conditioned on product type. Type is immutable after creation. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `productlistingproduct-created` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `createProductListingProduct` Business API includes a REST controller that can be triggered via the following route: `/v1/productlistingproducts` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `createProductListingProduct` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `createProductListingProduct` Business API has 23 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `productListingProductId` | `ID` | `No` | `-` | `body` | `productListingProductId` | | **Description:** | This id paremeter is used to create the data object with a given specific id. Leave null for automatic id. | | | | | | | | | | | | | `currency` | `String` | `Yes` | `-` | `body` | `currency` | | **Description:** | ISO currency code (e.g. USD, EUR) | | | | | | | | | | | | | `description` | `Text` | `Yes` | `-` | `body` | `description` | | **Description:** | Product detailed description | | | | | | | | | | | | | `condition` | `Enum` | `Yes` | `-` | `body` | `condition` | | **Description:** | Condition of product: BRAND_NEW, NEW, or USED | | | | | | | | | | | | | `startBid` | `Double` | `No` | `-` | `body` | `startBid` | | **Description:** | The opening bid value (for auction type products) | | | | | | | | | | | | | `endPrice` | `Double` | `No` | `-` | `body` | `endPrice` | | **Description:** | Optional immediate sale/upper end price for auction (if AUCTION type) | | | | | | | | | | | | | `price` | `Double` | `No` | `-` | `body` | `price` | | **Description:** | Product price (required if fixed price type) | | | | | | | | | | | | | `title` | `String` | `Yes` | `-` | `body` | `title` | | **Description:** | Product title | | | | | | | | | | | | | `startPrice` | `Double` | `No` | `-` | `body` | `startPrice` | | **Description:** | Minimum starting price for auction (required if AUCTION type) | | | | | | | | | | | | | `type` | `Enum` | `Yes` | `-` | `body` | `type` | | **Description:** | Product listing type, either FIXED or AUCTION (immutable after creation) | | | | | | | | | | | | | `endBid` | `Double` | `No` | `-` | `body` | `endBid` | | **Description:** | The upper (max) bid value for auction products (if any) | | | | | | | | | | | | | `estimatedDelivery` | `Date` | `No` | `-` | `body` | `estimatedDelivery` | | **Description:** | Estimated delivery date for this product | | | | | | | | | | | | | `shippingCurrency` | `String` | `Yes` | `-` | `body` | `shippingCurrency` | | **Description:** | Currency code for shipping cost | | | | | | | | | | | | | `sellerId` | `ID` | `Yes` | `-` | `session` | `userId` | | **Description:** | Reference to user who listed the product | | | | | | | | | | | | | `mediaAssetIds` | `ID` | `No` | `-` | `body` | `mediaAssetIds` | | **Description:** | References to associated product/media assets | | | | | | | | | | | | | `shippingMethod` | `Enum` | `Yes` | `-` | `body` | `shippingMethod` | | **Description:** | Shipping option for product: STANDARD, EXPRESS, or FREE | | | | | | | | | | | | | `shipping` | `Double` | `Yes` | `-` | `body` | `shipping` | | **Description:** | Shipping cost for this product | | | | | | | | | | | | | `startBidDate` | `Date` | `No` | `-` | `body` | `startBidDate` | | **Description:** | Date/time when auction bidding begins | | | | | | | | | | | | | `subcategoryId` | `ID` | `Yes` | `-` | `body` | `subcategoryId` | | **Description:** | Reference to subcategory | | | | | | | | | | | | | `categoryId` | `ID` | `Yes` | `-` | `body` | `categoryId` | | **Description:** | Reference to parent category | | | | | | | | | | | | | `endBidDate` | `Date` | `No` | `-` | `body` | `endBidDate` | | **Description:** | Date/time when auction bidding ends | | | | | | | | | | | | | `currentBid` | `Double` | `No` | `-` | `body` | `currentBid` | | **Description:** | Current highest bid for auction-type product (updated atomically on bid placement) | | | | | | | | | | | | | `highestBidderId` | `ID` | `No` | `-` | `body` | `highestBidderId` | | **Description:** | User ID of current highest bidder (auction-only, updated by auction microservice) | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `createProductListingProduct` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { id: this.productListingProductId, currency: this.currency, description: this.description, condition: this.condition, startBid: this.startBid, endPrice: this.endPrice, price: this.price, title: this.title, startPrice: this.startPrice, type: this.type, endBid: this.endBid, estimatedDelivery: this.estimatedDelivery, shippingCurrency: this.shippingCurrency, sellerId: this.sellerId, mediaAssetIds: this.mediaAssetIds, shippingMethod: this.shippingMethod, shipping: this.shipping, startBidDate: this.startBidDate, subcategoryId: this.subcategoryId, categoryId: this.categoryId, endBidDate: this.endBidDate, currentBid: this.currentBid, highestBidderId: this.highestBidderId, isActive: true, _archivedAt: null, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, populates session and request objects, prepares internal structures for parameter handling and workflow execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads input parameters, normalizes missing values, applies default type casting, and stores them in the API context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager transforms parameters, computes derived values, flattens or remaps arrays/objects, and adjusts formats for downstream processing. --- ### [4] Step : checkParameters Manager executes built-in validations: required field checks, type enforcement, and basic business rules. Prevents operation if validation fails. --- ### [5] Step : checkBasicAuth Manager performs authentication and authorization checks: verifies session, user roles, permissions, and tenant restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildDataClause Manager constructs the final data object for creation, fills auto-generated fields (IDs, timestamps, owner fields), and ensures schema consistency. You can use the following settings to change some behavior of this step. `dataClause` --- ### [7] Step : mainCreateOperation Manager executes the database insert operation, updates indexes/caches, and triggers internal post-processing like linked default records. --- ### [8] Step : buildOutput Manager shapes the response: masks sensitive fields, resolves linked references, and formats output according to API contract. --- ### [9] Step : sendResponse Manager sends the response to the client and finalizes internal tasks like flushing logs or updating session state. --- ### [10] Step : raiseApiEvent Manager triggers API-level events (Kafka, WebSocket, async workflows) as the final internal step. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `createProductListingProduct` api has got 21 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | currency | String | true | request.body?.currency | | description | Text | true | request.body?.description | | condition | Enum | true | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | true | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | type | Enum | true | request.body?.type | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | true | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | true | request.body?.shippingMethod | | shipping | Double | true | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | true | request.body?.subcategoryId | | categoryId | ID | true | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | ### REST Request To access the api you can use the **REST** controller with the path **POST /v1/productlistingproducts** ```js axios({ method: 'POST', url: '/v1/productlistingproducts', data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", type:"Enum", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`productListingProduct`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Delete Productlistingmedia` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `deleteProductListingMedia` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `deleteProductListingMedia` Business API is designed to handle a `delete` operation on the `ProductListingMedia` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Soft-delete a media asset (typically by admin or media owner for flagged/invalid content). ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `productlistingmedia-deleted` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `deleteProductListingMedia` Business API includes a REST controller that can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `deleteProductListingMedia` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `deleteProductListingMedia` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `productListingMediaId` | `ID` | `Yes` | `-` | `urlpath` | `productListingMediaId` | | **Description:** | This id paremeter is used to select the required data object that will be deleted | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `deleteProductListingMedia` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.productListingMediaId},{isActive:true}]} ``` ## Delete Options Use these options to set `delete` specific settings. **useSoftDelete**: false If true, the record will be marked as deleted `(isActive: false)` instead of removed. The implementation depends on the data object’s soft delete configuration. ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request/session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads and normalizes parameters, applies defaults, and stores them in the context for downstream steps. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts, computes derived values, and remaps objects or arrays as needed for later processing. --- ### [4] Step : checkParameters Manager runs built-in validations including required field checks, type enforcement, and deletion preconditions. Stops execution if validation fails. --- ### [5] Step : checkBasicAuth Manager validates session, user roles, permissions, and tenant-specific access rules to enforce basic auth restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager generates the query conditions, applies ownership and parent checks, and ensures the clause is correct for the delete operation. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the target record, applies filters from WHERE clause, and writes the instance to the context for further checks. --- ### [8] Step : checkInstance Manager performs object-level validations such as lock status, soft-delete eligibility, and multi-step approval enforcement. --- ### [9] Step : mainDeleteOperation Manager executes the delete query, updates related indexes/caches, and handles soft/hard delete logic according to configuration. You can use the following settings to change some behavior of this step. `deleteOptions` --- ### [10] Step : buildOutput Manager shapes the response payload, masks sensitive fields, and formats related cleanup results for output. --- ### [11] Step : sendResponse Manager delivers the response to the client and finalizes any temporary internal structures. --- ### [12] Step : raiseApiEvent Manager triggers asynchronous API events, notifies queues or streams, and performs final cleanup for the workflow. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `deleteProductListingMedia` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | ### REST Request To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'DELETE', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`productListingMedia`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Delete Productlistingproduct` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `deleteProductListingProduct` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `deleteProductListingProduct` Business API is designed to handle a `delete` operation on the `ProductListingProduct` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Soft-delete a product listing. Only owner or admin can delete. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `productlistingproduct-deleted` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `deleteProductListingProduct` Business API includes a REST controller that can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `deleteProductListingProduct` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `deleteProductListingProduct` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `productListingProductId` | `ID` | `Yes` | `-` | `urlpath` | `productListingProductId` | | **Description:** | This id paremeter is used to select the required data object that will be deleted | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `deleteProductListingProduct` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks This Business API enforces ownership of the main data object before executing the operation. - The check is performed **after fetching the object instance**. If the current user is not the owner, the API will respond with **403 Forbidden**. Note: Ownership checks are applied **only if the objects have an owner field**. --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.productListingProductId},{isActive:true}]} ``` ## Delete Options Use these options to set `delete` specific settings. **useSoftDelete**: false If true, the record will be marked as deleted `(isActive: false)` instead of removed. The implementation depends on the data object’s soft delete configuration. ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request/session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads and normalizes parameters, applies defaults, and stores them in the context for downstream steps. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts, computes derived values, and remaps objects or arrays as needed for later processing. --- ### [4] Step : checkParameters Manager runs built-in validations including required field checks, type enforcement, and deletion preconditions. Stops execution if validation fails. --- ### [5] Step : checkBasicAuth Manager validates session, user roles, permissions, and tenant-specific access rules to enforce basic auth restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager generates the query conditions, applies ownership and parent checks, and ensures the clause is correct for the delete operation. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the target record, applies filters from WHERE clause, and writes the instance to the context for further checks. --- ### [8] Step : checkInstance Manager performs object-level validations such as lock status, soft-delete eligibility, and multi-step approval enforcement. --- ### [9] Step : mainDeleteOperation Manager executes the delete query, updates related indexes/caches, and handles soft/hard delete logic according to configuration. You can use the following settings to change some behavior of this step. `deleteOptions` --- ### [10] Step : buildOutput Manager shapes the response payload, masks sensitive fields, and formats related cleanup results for output. --- ### [11] Step : sendResponse Manager delivers the response to the client and finalizes any temporary internal structures. --- ### [12] Step : raiseApiEvent Manager triggers asynchronous API events, notifies queues or streams, and performs final cleanup for the workflow. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `deleteProductListingProduct` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | ### REST Request To access the api you can use the **REST** controller with the path **DELETE /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'DELETE', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`productListingProduct`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Get Productlistingmedia` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `getProductListingMedia` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `getProductListingMedia` Business API is designed to handle a `get` operation on the `ProductListingMedia` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Get a single media asset by ID (for admin or to display in product UI). ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `productlistingmedia-retrived` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `getProductListingMedia` Business API includes a REST controller that can be triggered via the following route: `/v1/productlistingmedias/:productListingMediaId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `getProductListingMedia` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `getProductListingMedia` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `productListingMediaId` | `ID` | `Yes` | `-` | `urlpath` | `productListingMediaId` | | **Description:** | This id paremeter is used to query the required data object. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `getProductListingMedia` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.productListingMediaId},{isActive:true}]} ``` ## Get Options Use these options to set `get` specific settings. **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Extracts parameters from request and Redis, applies defaults, and writes them to context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Executes parameter transformation scripts, applies type coercion, merges derived values, and reshapes inputs for downstream milestones. --- ### [4] Step : checkParameters Validates required and custom parameters, enforcing business-specific rules and constraints. --- ### [5] Step : checkBasicAuth Performs login, role, and permission checks, and applies dynamic object-level access rules. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Builds the WHERE clause for fetching the object and applies additional scoped filters if configured. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainGetOperation Executes the database fetch, retrieves the object, and stores it in context for enrichment or further checks. You can use the following settings to change some behavior of this step. `selectClause`, `getOptions` --- ### [8] Step : checkInstance Performs instance-level validations, such as ownership, existence, or access conditions. --- ### [9] Step : buildOutput Assembles the response from the object, applies masking, formatting, and injects additional metadata if needed. --- ### [10] Step : sendResponse Delivers the response to the controller for client delivery. --- ### [11] Step : raiseApiEvent Triggers optional API-level events after workflow completion, sending messages to integrations like Kafka if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `getProductListingMedia` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingMediaId | ID | true | request.params?.productListingMediaId | ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias/:productListingMediaId** ```js axios({ method: 'GET', url: `/v1/productlistingmedias/${productListingMediaId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`productListingMedia`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedia", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingMedia": { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Get Productlistingproduct` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `getProductListingProduct` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `getProductListingProduct` Business API is designed to handle a `get` operation on the `ProductListingProduct` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Get a single product listing. Checks isActive and public status. Includes media, category, subcategory, and seller info via joins. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `productlistingproduct-retrived` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `getProductListingProduct` Business API includes a REST controller that can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `getProductListingProduct` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `getProductListingProduct` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `productListingProductId` | `ID` | `Yes` | `-` | `urlpath` | `productListingProductId` | | **Description:** | This id paremeter is used to query the required data object. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `getProductListingProduct` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks This Business API enforces ownership of the main data object before executing the operation. - The check is performed **after fetching the object instance**. If the current user is not the owner, the API will respond with **403 Forbidden**. Note: Ownership checks are applied **only if the objects have an owner field**. --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.productListingProductId},{isActive:true}]} ``` ## Get Options Use these options to set `get` specific settings. **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Extracts parameters from request and Redis, applies defaults, and writes them to context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Executes parameter transformation scripts, applies type coercion, merges derived values, and reshapes inputs for downstream milestones. --- ### [4] Step : checkParameters Validates required and custom parameters, enforcing business-specific rules and constraints. --- ### [5] Step : checkBasicAuth Performs login, role, and permission checks, and applies dynamic object-level access rules. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Builds the WHERE clause for fetching the object and applies additional scoped filters if configured. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainGetOperation Executes the database fetch, retrieves the object, and stores it in context for enrichment or further checks. You can use the following settings to change some behavior of this step. `selectClause`, `getOptions` --- ### [8] Step : checkInstance Performs instance-level validations, such as ownership, existence, or access conditions. --- ### [9] Step : buildOutput Assembles the response from the object, applies masking, formatting, and injects additional metadata if needed. --- ### [10] Step : sendResponse Delivers the response to the controller for client delivery. --- ### [11] Step : raiseApiEvent Triggers optional API-level events after workflow completion, sending messages to integrations like Kafka if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `getProductListingProduct` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'GET', url: `/v1/productlistingproducts/${productListingProductId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`productListingProduct`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `List Productlistingmedia` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `listProductListingMedia` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `listProductListingMedia` Business API is designed to handle a `list` operation on the `ProductListingMedia` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description List all media assets (admin or for media management/bulk preview). ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `productlistingmedia-listed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `listProductListingMedia` Business API includes a REST controller that can be triggered via the following route: `/v1/productlistingmedias` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `listProductListingMedia` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `listProductListingMedia` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `listProductListingMedia` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {isActive:true} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `listProductListingMedia` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/productlistingmedias** ```js axios({ method: 'GET', url: '/v1/productlistingmedias', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`productListingMedias`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingMedias", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingMedias": [ { "id": "ID", "mimeType": "String", "productId": "ID", "url": "String", "size": "Integer", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `List Productlistingownproducts` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `listProductListingOwnProducts` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `listProductListingOwnProducts` Business API is designed to handle a `list` operation on the `ProductListingProduct` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description listing the loggedin user's products ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `productlistingownproducts-listed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `listProductListingOwnProducts` Business API includes a REST controller that can be triggered via the following route: `/v1/productlistingownproducts` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `listProductListingOwnProducts` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `listProductListingOwnProducts` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `listProductListingOwnProducts` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has a `fullWhereClause` setting : ```js {sellerId:this.session.userId} ``` **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{sellerId:this.session.userId},{isActive:true}]} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `listProductListingOwnProducts` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/productlistingownproducts** ```js axios({ method: 'GET', url: '/v1/productlistingownproducts', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`productListingProducts`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `List Productlistingproducts` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `listProductListingProducts` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `listProductListingProducts` Business API is designed to handle a `list` operation on the `ProductListingProduct` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description List public product listings. Only isActive=true records are returned. Includes category, subcategory, seller, media joins. Supports filtering. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `productlistingproducts-listed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `listProductListingProducts` Business API includes a REST controller that can be triggered via the following route: `/v1/productlistingproducts` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `listProductListingProducts` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `listProductListingProducts` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `listProductListingProducts` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {isActive:true} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `listProductListingProducts` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/productlistingproducts** ```js axios({ method: 'GET', url: '/v1/productlistingproducts', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`productListingProducts`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProducts", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "productListingProducts": [ { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `Update Productlistingproduct` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `updateProductListingProduct` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `updateProductListingProduct` Business API is designed to handle a `update` operation on the `ProductListingProduct` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Update a product listing. Product type cannot be changed (immutable). ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `productlistingproduct-updated` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `updateProductListingProduct` Business API includes a REST controller that can be triggered via the following route: `/v1/productlistingproducts/:productListingProductId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `updateProductListingProduct` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `updateProductListingProduct` Business API has 21 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `productListingProductId` | `ID` | `Yes` | `-` | `urlpath` | `productListingProductId` | | **Description:** | This id paremeter is used to select the required data object that will be updated | | | | | | | | | | | | | `currency` | `String` | `No` | `-` | `body` | `currency` | | **Description:** | ISO currency code (e.g. USD, EUR) | | | | | | | | | | | | | `description` | `Text` | `No` | `-` | `body` | `description` | | **Description:** | Product detailed description | | | | | | | | | | | | | `condition` | `Enum` | `No` | `-` | `body` | `condition` | | **Description:** | Condition of product: BRAND_NEW, NEW, or USED | | | | | | | | | | | | | `startBid` | `Double` | `No` | `-` | `body` | `startBid` | | **Description:** | The opening bid value (for auction type products) | | | | | | | | | | | | | `endPrice` | `Double` | `No` | `-` | `body` | `endPrice` | | **Description:** | Optional immediate sale/upper end price for auction (if AUCTION type) | | | | | | | | | | | | | `price` | `Double` | `No` | `-` | `body` | `price` | | **Description:** | Product price (required if fixed price type) | | | | | | | | | | | | | `title` | `String` | `No` | `-` | `body` | `title` | | **Description:** | Product title | | | | | | | | | | | | | `startPrice` | `Double` | `No` | `-` | `body` | `startPrice` | | **Description:** | Minimum starting price for auction (required if AUCTION type) | | | | | | | | | | | | | `endBid` | `Double` | `No` | `-` | `body` | `endBid` | | **Description:** | The upper (max) bid value for auction products (if any) | | | | | | | | | | | | | `estimatedDelivery` | `Date` | `No` | `-` | `body` | `estimatedDelivery` | | **Description:** | Estimated delivery date for this product | | | | | | | | | | | | | `shippingCurrency` | `String` | `No` | `-` | `body` | `shippingCurrency` | | **Description:** | Currency code for shipping cost | | | | | | | | | | | | | `mediaAssetIds` | `ID` | `No` | `-` | `body` | `mediaAssetIds` | | **Description:** | References to associated product/media assets | | | | | | | | | | | | | `shippingMethod` | `Enum` | `No` | `-` | `body` | `shippingMethod` | | **Description:** | Shipping option for product: STANDARD, EXPRESS, or FREE | | | | | | | | | | | | | `shipping` | `Double` | `No` | `-` | `body` | `shipping` | | **Description:** | Shipping cost for this product | | | | | | | | | | | | | `startBidDate` | `Date` | `No` | `-` | `body` | `startBidDate` | | **Description:** | Date/time when auction bidding begins | | | | | | | | | | | | | `subcategoryId` | `ID` | `No` | `-` | `body` | `subcategoryId` | | **Description:** | Reference to subcategory | | | | | | | | | | | | | `categoryId` | `ID` | `No` | `-` | `body` | `categoryId` | | **Description:** | Reference to parent category | | | | | | | | | | | | | `endBidDate` | `Date` | `No` | `-` | `body` | `endBidDate` | | **Description:** | Date/time when auction bidding ends | | | | | | | | | | | | | `currentBid` | `Double` | `No` | `-` | `body` | `currentBid` | | **Description:** | Current highest bid for auction-type product (updated atomically on bid placement) | | | | | | | | | | | | | `highestBidderId` | `ID` | `No` | `-` | `body` | `highestBidderId` | | **Description:** | User ID of current highest bidder (auction-only, updated by auction microservice) | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `updateProductListingProduct` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks This Business API enforces ownership of the main data object before executing the operation. - The check is performed **after fetching the object instance**. If the current user is not the owner, the API will respond with **403 Forbidden**. Note: Ownership checks are applied **only if the objects have an owner field**. --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.productListingProductId},{isActive:true}]} ``` ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. An update data clause populates all update-allowed properties of a data object, however the null properties (that are not provided by client) are ignored in db layer. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { currency: this.currency, description: this.description, condition: this.condition, startBid: this.startBid, endPrice: this.endPrice, price: this.price, title: this.title, startPrice: this.startPrice, endBid: this.endBid, estimatedDelivery: this.estimatedDelivery, shippingCurrency: this.shippingCurrency, mediaAssetIds: this.mediaAssetIds ? this.mediaAssetIds : ( this.mediaAssetIds_remove ? sequelize.fn('array_remove', sequelize.col('mediaAssetIds'), this.mediaAssetIds_remove) : (this.mediaAssetIds_append ? sequelize.fn('array_append', sequelize.col('mediaAssetIds'), this.mediaAssetIds_append) : undefined)) , shippingMethod: this.shippingMethod, shipping: this.shipping, startBidDate: this.startBidDate, subcategoryId: this.subcategoryId, categoryId: this.categoryId, endBidDate: this.endBidDate, currentBid: this.currentBid, highestBidderId: this.highestBidderId, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request and session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads parameters from the request or Redis, applies defaults, and writes them into context for downstream milestones. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts and derives any helper values or reshaped payloads into the context. --- ### [4] Step : checkParameters Manager validates required parameters, checks ID formats (UUID/ObjectId), and ensures all preconditions for update are met. --- ### [5] Step : checkBasicAuth Manager performs login verification, role, and permission checks, enforcing tenant and access rules before update. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager constructs the WHERE clause used to identify the record to update, applying ownership and parent checks if necessary. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the existing record from the database and writes it to the context for validation or enrichment. --- ### [8] Step : checkInstance Manager performs instance-level validations, including ownership, existence, lock status, or other pre-update checks. --- ### [9] Step : buildDataClause Manager prepares the data clause for the update, applying transformations or enhancements before persisting. You can use the following settings to change some behavior of this step. `dataClause` --- ### [10] Step : mainUpdateOperation Manager executes the update operation with the WHERE and data clauses. Database-level events are raised if configured. --- ### [11] Step : buildOutput Manager assembles the response object from the update result, masking fields or injecting additional metadata. --- ### [12] Step : sendResponse Manager sends the response back to the controller for delivery to the client. --- ### [13] Step : raiseApiEvent Manager triggers API-level events, sending relevant messages to Kafka or other integrations if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `updateProductListingProduct` api has got 21 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | productListingProductId | ID | true | request.params?.productListingProductId | | currency | String | false | request.body?.currency | | description | Text | false | request.body?.description | | condition | Enum | false | request.body?.condition | | startBid | Double | false | request.body?.startBid | | endPrice | Double | false | request.body?.endPrice | | price | Double | false | request.body?.price | | title | String | false | request.body?.title | | startPrice | Double | false | request.body?.startPrice | | endBid | Double | false | request.body?.endBid | | estimatedDelivery | Date | false | request.body?.estimatedDelivery | | shippingCurrency | String | false | request.body?.shippingCurrency | | mediaAssetIds | ID | false | request.body?.mediaAssetIds | | shippingMethod | Enum | false | request.body?.shippingMethod | | shipping | Double | false | request.body?.shipping | | startBidDate | Date | false | request.body?.startBidDate | | subcategoryId | ID | false | request.body?.subcategoryId | | categoryId | ID | false | request.body?.categoryId | | endBidDate | Date | false | request.body?.endBidDate | | currentBid | Double | false | request.body?.currentBid | | highestBidderId | ID | false | request.body?.highestBidderId | ### REST Request To access the api you can use the **REST** controller with the path **PATCH /v1/productlistingproducts/:productListingProductId** ```js axios({ method: 'PATCH', url: `/v1/productlistingproducts/${productListingProductId}`, data: { currency:"String", description:"Text", condition:"Enum", startBid:"Double", endPrice:"Double", price:"Double", title:"String", startPrice:"Double", endBid:"Double", estimatedDelivery:"Date", shippingCurrency:"String", mediaAssetIds:"ID", shippingMethod:"Enum", shipping:"Double", startBidDate:"Date", subcategoryId:"ID", categoryId:"ID", endBidDate:"Date", currentBid:"Double", highestBidderId:"ID", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`productListingProduct`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "productListingProduct", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "productListingProduct": { "id": "ID", "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "startBid": "Double", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "endBid": "Double", "estimatedDelivery": "Date", "shippingCurrency": "String", "sellerId": "ID", "mediaAssetIds": "ID", "shippingMethod": "Enum", "shippingMethod_idx": "Integer", "shipping": "Double", "startBidDate": "Date", "subcategoryId": "ID", "categoryId": "ID", "endBidDate": "Date", "currentBid": "Double", "highestBidderId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Create Searchindex` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `createSearchIndex` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `createSearchIndex` Business API is designed to handle a `create` operation on the `SearchIndex` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Create a new searchIndex record (internal, used by event triggers and admin tools only). Typically called when a new product/seller/category/subcategory is created. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `searchindex-created` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `createSearchIndex` Business API includes a REST controller that can be triggered via the following route: `/v1/searchindexs` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `createSearchIndex` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `createSearchIndex` Business API has 5 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `searchIndexId` | `ID` | `No` | `-` | `body` | `searchIndexId` | | **Description:** | This id paremeter is used to create the data object with a given specific id. Leave null for automatic id. | | | | | | | | | | | | | `documentType` | `Enum` | `Yes` | `-` | `body` | `documentType` | | **Description:** | Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY | | | | | | | | | | | | | `document` | `Object` | `Yes` | `-` | `body` | `document` | | **Description:** | Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. | | | | | | | | | | | | | `referenceId` | `ID` | `Yes` | `-` | `body` | `referenceId` | | **Description:** | ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. | | | | | | | | | | | | | `indexedAt` | `Date` | `Yes` | `-` | `body` | `indexedAt` | | **Description:** | Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `createSearchIndex` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { id: this.searchIndexId, documentType: this.documentType, document: this.document ? (typeof this.document == 'string' ? JSON.parse(this.document) : this.document) : null, referenceId: this.referenceId, indexedAt: this.indexedAt, isActive: true, _archivedAt: null, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, populates session and request objects, prepares internal structures for parameter handling and workflow execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads input parameters, normalizes missing values, applies default type casting, and stores them in the API context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager transforms parameters, computes derived values, flattens or remaps arrays/objects, and adjusts formats for downstream processing. --- ### [4] Step : checkParameters Manager executes built-in validations: required field checks, type enforcement, and basic business rules. Prevents operation if validation fails. --- ### [5] Step : checkBasicAuth Manager performs authentication and authorization checks: verifies session, user roles, permissions, and tenant restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildDataClause Manager constructs the final data object for creation, fills auto-generated fields (IDs, timestamps, owner fields), and ensures schema consistency. You can use the following settings to change some behavior of this step. `dataClause` --- ### [7] Step : mainCreateOperation Manager executes the database insert operation, updates indexes/caches, and triggers internal post-processing like linked default records. --- ### [8] Step : buildOutput Manager shapes the response: masks sensitive fields, resolves linked references, and formats output according to API contract. --- ### [9] Step : sendResponse Manager sends the response to the client and finalizes internal tasks like flushing logs or updating session state. --- ### [10] Step : raiseApiEvent Manager triggers API-level events (Kafka, WebSocket, async workflows) as the final internal step. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `createSearchIndex` api has got 4 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | documentType | Enum | true | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | true | request.body?.indexedAt | ### REST Request To access the api you can use the **REST** controller with the path **POST /v1/searchindexs** ```js axios({ method: 'POST', url: '/v1/searchindexs', data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`searchIndex`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Delete Searchindex` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `deleteSearchIndex` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `deleteSearchIndex` Business API is designed to handle a `delete` operation on the `SearchIndex` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Soft-delete a searchIndex record (by id or by (documentType, referenceId)). Typical use: in response to entity soft-delete; internal/automation/admin only. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `searchindex-deleted` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `deleteSearchIndex` Business API includes a REST controller that can be triggered via the following route: `/v1/searchindexs/:searchIndexId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `deleteSearchIndex` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `deleteSearchIndex` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `searchIndexId` | `ID` | `Yes` | `-` | `urlpath` | `searchIndexId` | | **Description:** | This id paremeter is used to select the required data object that will be deleted | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `deleteSearchIndex` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.searchIndexId},{isActive:true}]} ``` ## Delete Options Use these options to set `delete` specific settings. **useSoftDelete**: false If true, the record will be marked as deleted `(isActive: false)` instead of removed. The implementation depends on the data object’s soft delete configuration. ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request/session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads and normalizes parameters, applies defaults, and stores them in the context for downstream steps. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts, computes derived values, and remaps objects or arrays as needed for later processing. --- ### [4] Step : checkParameters Manager runs built-in validations including required field checks, type enforcement, and deletion preconditions. Stops execution if validation fails. --- ### [5] Step : checkBasicAuth Manager validates session, user roles, permissions, and tenant-specific access rules to enforce basic auth restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager generates the query conditions, applies ownership and parent checks, and ensures the clause is correct for the delete operation. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the target record, applies filters from WHERE clause, and writes the instance to the context for further checks. --- ### [8] Step : checkInstance Manager performs object-level validations such as lock status, soft-delete eligibility, and multi-step approval enforcement. --- ### [9] Step : mainDeleteOperation Manager executes the delete query, updates related indexes/caches, and handles soft/hard delete logic according to configuration. You can use the following settings to change some behavior of this step. `deleteOptions` --- ### [10] Step : buildOutput Manager shapes the response payload, masks sensitive fields, and formats related cleanup results for output. --- ### [11] Step : sendResponse Manager delivers the response to the client and finalizes any temporary internal structures. --- ### [12] Step : raiseApiEvent Manager triggers asynchronous API events, notifies queues or streams, and performs final cleanup for the workflow. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `deleteSearchIndex` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | ### REST Request To access the api you can use the **REST** controller with the path **DELETE /v1/searchindexs/:searchIndexId** ```js axios({ method: 'DELETE', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`searchIndex`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Get Searchindex` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `getSearchIndex` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `getSearchIndex` Business API is designed to handle a `get` operation on the `SearchIndex` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Get a single denormalized index record (by id, or documentType+referenceId). Used by BFF for full entity search. Always excludes inactive records unless forced (admin only path). ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `searchindex-retrived` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `getSearchIndex` Business API includes a REST controller that can be triggered via the following route: `/v1/searchindexs/:searchIndexId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `getSearchIndex` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `getSearchIndex` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `searchIndexId` | `ID` | `Yes` | `-` | `urlpath` | `searchIndexId` | | **Description:** | This id paremeter is used to query the required data object. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `getSearchIndex` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.searchIndexId},{isActive:true}]} ``` ## Get Options Use these options to set `get` specific settings. **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Extracts parameters from request and Redis, applies defaults, and writes them to context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Executes parameter transformation scripts, applies type coercion, merges derived values, and reshapes inputs for downstream milestones. --- ### [4] Step : checkParameters Validates required and custom parameters, enforcing business-specific rules and constraints. --- ### [5] Step : checkBasicAuth Performs login, role, and permission checks, and applies dynamic object-level access rules. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Builds the WHERE clause for fetching the object and applies additional scoped filters if configured. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainGetOperation Executes the database fetch, retrieves the object, and stores it in context for enrichment or further checks. You can use the following settings to change some behavior of this step. `selectClause`, `getOptions` --- ### [8] Step : checkInstance Performs instance-level validations, such as ownership, existence, or access conditions. --- ### [9] Step : buildOutput Assembles the response from the object, applies masking, formatting, and injects additional metadata if needed. --- ### [10] Step : sendResponse Delivers the response to the controller for client delivery. --- ### [11] Step : raiseApiEvent Triggers optional API-level events after workflow completion, sending messages to integrations like Kafka if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `getSearchIndex` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/searchindexs/:searchIndexId** ```js axios({ method: 'GET', url: `/v1/searchindexs/${searchIndexId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`searchIndex`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "GET", "action": "get", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `List Searchindexes` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `listSearchIndexes` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `listSearchIndexes` Business API is designed to handle a `list` operation on the `SearchIndex` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description List/search search index entries by type or referenceId (used by BFF/global search). Always excludes inactive (soft-deleted) records. Supports filtering and full-text search filters by documentType/referenceId for admin/maintenance use. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `searchindexes-listed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `listSearchIndexes` Business API includes a REST controller that can be triggered via the following route: `/v1/searchindexes` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `listSearchIndexes` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `listSearchIndexes` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `listSearchIndexes` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {isActive:true} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `listSearchIndexes` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/searchindexes** ```js axios({ method: 'GET', url: '/v1/searchindexes', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`searchIndices`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndices", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "searchIndices": [ { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `Update Searchindex` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `updateSearchIndex` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `updateSearchIndex` Business API is designed to handle a `update` operation on the `SearchIndex` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Update an existing searchIndex record (by (documentType, referenceId) or id). Used in response to events (entity edit, data change); internal/automation/admin only. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `searchindex-updated` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `updateSearchIndex` Business API includes a REST controller that can be triggered via the following route: `/v1/searchindexs/:searchIndexId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `updateSearchIndex` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `updateSearchIndex` Business API has 5 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `searchIndexId` | `ID` | `Yes` | `-` | `urlpath` | `searchIndexId` | | **Description:** | This id paremeter is used to select the required data object that will be updated | | | | | | | | | | | | | `documentType` | `Enum` | `No` | `-` | `body` | `documentType` | | **Description:** | Type of the indexed document: PRODUCT, SELLER, CATEGORY, SUBCATEGORY | | | | | | | | | | | | | `document` | `Object` | `Yes` | `-` | `body` | `document` | | **Description:** | Denormalized snapshot of the entity data, optimized for full-text search. May contain different keys depending on documentType. | | | | | | | | | | | | | `referenceId` | `ID` | `Yes` | `-` | `body` | `referenceId` | | **Description:** | ID of the underlying source entity (product, seller, category, subcategory) for reverse-mapping/database triggers. | | | | | | | | | | | | | `indexedAt` | `Date` | `No` | `-` | `body` | `indexedAt` | | **Description:** | Timestamp when the record was (last) indexed. Used for maintenance, debugging, rebuild tracing. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `updateSearchIndex` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.searchIndexId},{isActive:true}]} ``` ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. An update data clause populates all update-allowed properties of a data object, however the null properties (that are not provided by client) are ignored in db layer. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { documentType: this.documentType, document: this.document ? (typeof this.document == 'string' ? JSON.parse(this.document) : this.document) : null, referenceId: this.referenceId, indexedAt: this.indexedAt, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request and session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads parameters from the request or Redis, applies defaults, and writes them into context for downstream milestones. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts and derives any helper values or reshaped payloads into the context. --- ### [4] Step : checkParameters Manager validates required parameters, checks ID formats (UUID/ObjectId), and ensures all preconditions for update are met. --- ### [5] Step : checkBasicAuth Manager performs login verification, role, and permission checks, enforcing tenant and access rules before update. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager constructs the WHERE clause used to identify the record to update, applying ownership and parent checks if necessary. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the existing record from the database and writes it to the context for validation or enrichment. --- ### [8] Step : checkInstance Manager performs instance-level validations, including ownership, existence, lock status, or other pre-update checks. --- ### [9] Step : buildDataClause Manager prepares the data clause for the update, applying transformations or enhancements before persisting. You can use the following settings to change some behavior of this step. `dataClause` --- ### [10] Step : mainUpdateOperation Manager executes the update operation with the WHERE and data clauses. Database-level events are raised if configured. --- ### [11] Step : buildOutput Manager assembles the response object from the update result, masking fields or injecting additional metadata. --- ### [12] Step : sendResponse Manager sends the response back to the controller for delivery to the client. --- ### [13] Step : raiseApiEvent Manager triggers API-level events, sending relevant messages to Kafka or other integrations if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `updateSearchIndex` api has got 5 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | searchIndexId | ID | true | request.params?.searchIndexId | | documentType | Enum | false | request.body?.documentType | | document | Object | true | request.body?.document | | referenceId | ID | true | request.body?.referenceId | | indexedAt | Date | false | request.body?.indexedAt | ### REST Request To access the api you can use the **REST** controller with the path **PATCH /v1/searchindexs/:searchIndexId** ```js axios({ method: 'PATCH', url: `/v1/searchindexs/${searchIndexId}`, data: { documentType:"Enum", document:"Object", referenceId:"ID", indexedAt:"Date", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`searchIndex`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "searchIndex", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "searchIndex": { "id": "ID", "documentType": "Enum", "documentType_idx": "Integer", "document": "Object", "referenceId": "ID", "indexedAt": "Date", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Create Cartitem` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `createCartItem` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `createCartItem` Business API is designed to handle a `create` operation on the `CartItem` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Add an item to the user’s cart. Only fixed-price products allowed. Duplicates not permitted. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `cartitem-created` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `createCartItem` Business API includes a REST controller that can be triggered via the following route: `/v1/cartitems` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `createCartItem` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `createCartItem` Business API has 5 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `cartItemId` | `ID` | `No` | `-` | `body` | `cartItemId` | | **Description:** | This id paremeter is used to create the data object with a given specific id. Leave null for automatic id. | | | | | | | | | | | | | `addedAt` | `Date` | `Yes` | `-` | `body` | `addedAt` | | **Description:** | Timestamp added to cart. | | | | | | | | | | | | | `userId` | `ID` | `Yes` | `-` | `session` | `userId` | | **Description:** | Cart owner. | | | | | | | | | | | | | `quantity` | `Integer` | `Yes` | `-` | `body` | `quantity` | | **Description:** | How many units (if product allows). | | | | | | | | | | | | | `productId` | `ID` | `Yes` | `-` | `body` | `productId` | | **Description:** | Product being checked out. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `createCartItem` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { id: this.cartItemId, addedAt: this.addedAt, userId: this.userId, quantity: this.quantity, productId: this.productId, isActive: true, _archivedAt: null, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, populates session and request objects, prepares internal structures for parameter handling and workflow execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads input parameters, normalizes missing values, applies default type casting, and stores them in the API context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager transforms parameters, computes derived values, flattens or remaps arrays/objects, and adjusts formats for downstream processing. --- ### [4] Step : checkParameters Manager executes built-in validations: required field checks, type enforcement, and basic business rules. Prevents operation if validation fails. --- ### [5] Step : checkBasicAuth Manager performs authentication and authorization checks: verifies session, user roles, permissions, and tenant restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildDataClause Manager constructs the final data object for creation, fills auto-generated fields (IDs, timestamps, owner fields), and ensures schema consistency. You can use the following settings to change some behavior of this step. `dataClause` --- ### [7] Step : mainCreateOperation Manager executes the database insert operation, updates indexes/caches, and triggers internal post-processing like linked default records. --- ### [8] Step : buildOutput Manager shapes the response: masks sensitive fields, resolves linked references, and formats output according to API contract. --- ### [9] Step : sendResponse Manager sends the response to the client and finalizes internal tasks like flushing logs or updating session state. --- ### [10] Step : raiseApiEvent Manager triggers API-level events (Kafka, WebSocket, async workflows) as the final internal step. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `createCartItem` api has got 3 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | quantity | Integer | true | request.body?.quantity | | productId | ID | true | request.body?.productId | ### REST Request To access the api you can use the **REST** controller with the path **POST /v1/cartitems** ```js axios({ method: 'POST', url: '/v1/cartitems', data: { addedAt:"Date", quantity:"Integer", productId:"ID", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`cartItem`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Create Watchlistitem` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `createWatchlistItem` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `createWatchlistItem` Business API is designed to handle a `create` operation on the `WatchlistItem` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Add product to user’s watchlist (default or target list/folder). One (user, product, list) per item enforced. Block duplicates. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `watchlistitem-created` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `createWatchlistItem` Business API includes a REST controller that can be triggered via the following route: `/v1/watchlistitems` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `createWatchlistItem` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `createWatchlistItem` Business API has 5 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `watchlistItemId` | `ID` | `No` | `-` | `body` | `watchlistItemId` | | **Description:** | This id paremeter is used to create the data object with a given specific id. Leave null for automatic id. | | | | | | | | | | | | | `userId` | `ID` | `Yes` | `-` | `session` | `userId` | | **Description:** | Owner of the watchlist item. | | | | | | | | | | | | | `addedAt` | `Date` | `Yes` | `-` | `body` | `addedAt` | | **Description:** | Timestamp watchlist item created. | | | | | | | | | | | | | `productId` | `ID` | `Yes` | `-` | `body` | `productId` | | **Description:** | Referenced product in the watchlist. | | | | | | | | | | | | | `listId` | `ID` | `No` | `-` | `body` | `listId` | | **Description:** | Owning watchlistList; null if in default watchlist. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `createWatchlistItem` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { id: this.watchlistItemId, userId: this.userId, addedAt: this.addedAt, productId: this.productId, listId: this.listId, isActive: true, _archivedAt: null, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, populates session and request objects, prepares internal structures for parameter handling and workflow execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads input parameters, normalizes missing values, applies default type casting, and stores them in the API context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager transforms parameters, computes derived values, flattens or remaps arrays/objects, and adjusts formats for downstream processing. --- ### [4] Step : checkParameters Manager executes built-in validations: required field checks, type enforcement, and basic business rules. Prevents operation if validation fails. --- ### [5] Step : checkBasicAuth Manager performs authentication and authorization checks: verifies session, user roles, permissions, and tenant restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildDataClause Manager constructs the final data object for creation, fills auto-generated fields (IDs, timestamps, owner fields), and ensures schema consistency. You can use the following settings to change some behavior of this step. `dataClause` --- ### [7] Step : mainCreateOperation Manager executes the database insert operation, updates indexes/caches, and triggers internal post-processing like linked default records. --- ### [8] Step : buildOutput Manager shapes the response: masks sensitive fields, resolves linked references, and formats output according to API contract. --- ### [9] Step : sendResponse Manager sends the response to the client and finalizes internal tasks like flushing logs or updating session state. --- ### [10] Step : raiseApiEvent Manager triggers API-level events (Kafka, WebSocket, async workflows) as the final internal step. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `createWatchlistItem` api has got 3 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | addedAt | Date | true | request.body?.addedAt | | productId | ID | true | request.body?.productId | | listId | ID | false | request.body?.listId | ### REST Request To access the api you can use the **REST** controller with the path **POST /v1/watchlistitems** ```js axios({ method: 'POST', url: '/v1/watchlistitems', data: { addedAt:"Date", productId:"ID", listId:"ID", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`watchlistItem`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Create Watchlistlist` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `createWatchlistList` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `createWatchlistList` Business API is designed to handle a `create` operation on the `WatchlistList` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Create a new custom watchlist folder. Name must be unique per user; ‘Default’ is reserved for system. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `watchlistlist-created` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `createWatchlistList` Business API includes a REST controller that can be triggered via the following route: `/v1/watchlistlists` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `createWatchlistList` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `createWatchlistList` Business API has 3 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `watchlistListId` | `ID` | `No` | `-` | `body` | `watchlistListId` | | **Description:** | This id paremeter is used to create the data object with a given specific id. Leave null for automatic id. | | | | | | | | | | | | | `name` | `String` | `Yes` | `-` | `body` | `name` | | **Description:** | Custom folder or list name. 'Default' is reserved (non-deletable for each user). | | | | | | | | | | | | | `userId` | `ID` | `Yes` | `-` | `session` | `userId` | | **Description:** | Owner of the watchlist list/folder. | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `createWatchlistList` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { id: this.watchlistListId, name: this.name, userId: this.userId, isActive: true, _archivedAt: null, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, populates session and request objects, prepares internal structures for parameter handling and workflow execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads input parameters, normalizes missing values, applies default type casting, and stores them in the API context. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager transforms parameters, computes derived values, flattens or remaps arrays/objects, and adjusts formats for downstream processing. --- ### [4] Step : checkParameters Manager executes built-in validations: required field checks, type enforcement, and basic business rules. Prevents operation if validation fails. --- ### [5] Step : checkBasicAuth Manager performs authentication and authorization checks: verifies session, user roles, permissions, and tenant restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildDataClause Manager constructs the final data object for creation, fills auto-generated fields (IDs, timestamps, owner fields), and ensures schema consistency. You can use the following settings to change some behavior of this step. `dataClause` --- ### [7] Step : mainCreateOperation Manager executes the database insert operation, updates indexes/caches, and triggers internal post-processing like linked default records. --- ### [8] Step : buildOutput Manager shapes the response: masks sensitive fields, resolves linked references, and formats output according to API contract. --- ### [9] Step : sendResponse Manager sends the response to the client and finalizes internal tasks like flushing logs or updating session state. --- ### [10] Step : raiseApiEvent Manager triggers API-level events (Kafka, WebSocket, async workflows) as the final internal step. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `createWatchlistList` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | name | String | true | request.body?.name | ### REST Request To access the api you can use the **REST** controller with the path **POST /v1/watchlistlists** ```js axios({ method: 'POST', url: '/v1/watchlistlists', data: { name:"String", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`watchlistList`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "201", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "POST", "action": "create", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Delete Cartitem` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `deleteCartItem` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `deleteCartItem` Business API is designed to handle a `delete` operation on the `CartItem` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Remove an item from the user’s cart. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `cartitem-deleted` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `deleteCartItem` Business API includes a REST controller that can be triggered via the following route: `/v1/cartitems/:cartItemId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `deleteCartItem` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `deleteCartItem` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `cartItemId` | `ID` | `Yes` | `-` | `urlpath` | `cartItemId` | | **Description:** | This id paremeter is used to select the required data object that will be deleted | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `deleteCartItem` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks This Business API enforces ownership of the main data object before executing the operation. - The check is performed **after fetching the object instance**. If the current user is not the owner, the API will respond with **403 Forbidden**. Note: Ownership checks are applied **only if the objects have an owner field**. --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.cartItemId},{isActive:true}]} ``` ## Delete Options Use these options to set `delete` specific settings. **useSoftDelete**: false If true, the record will be marked as deleted `(isActive: false)` instead of removed. The implementation depends on the data object’s soft delete configuration. ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request/session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads and normalizes parameters, applies defaults, and stores them in the context for downstream steps. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts, computes derived values, and remaps objects or arrays as needed for later processing. --- ### [4] Step : checkParameters Manager runs built-in validations including required field checks, type enforcement, and deletion preconditions. Stops execution if validation fails. --- ### [5] Step : checkBasicAuth Manager validates session, user roles, permissions, and tenant-specific access rules to enforce basic auth restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager generates the query conditions, applies ownership and parent checks, and ensures the clause is correct for the delete operation. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the target record, applies filters from WHERE clause, and writes the instance to the context for further checks. --- ### [8] Step : checkInstance Manager performs object-level validations such as lock status, soft-delete eligibility, and multi-step approval enforcement. --- ### [9] Step : mainDeleteOperation Manager executes the delete query, updates related indexes/caches, and handles soft/hard delete logic according to configuration. You can use the following settings to change some behavior of this step. `deleteOptions` --- ### [10] Step : buildOutput Manager shapes the response payload, masks sensitive fields, and formats related cleanup results for output. --- ### [11] Step : sendResponse Manager delivers the response to the client and finalizes any temporary internal structures. --- ### [12] Step : raiseApiEvent Manager triggers asynchronous API events, notifies queues or streams, and performs final cleanup for the workflow. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `deleteCartItem` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | ### REST Request To access the api you can use the **REST** controller with the path **DELETE /v1/cartitems/:cartItemId** ```js axios({ method: 'DELETE', url: `/v1/cartitems/${cartItemId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`cartItem`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Delete Watchlistitem` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `deleteWatchlistItem` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `deleteWatchlistItem` Business API is designed to handle a `delete` operation on the `WatchlistItem` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Remove a product from a user’s watchlist. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `watchlistitem-deleted` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `deleteWatchlistItem` Business API includes a REST controller that can be triggered via the following route: `/v1/watchlistitems/:watchlistItemId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `deleteWatchlistItem` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `deleteWatchlistItem` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `watchlistItemId` | `ID` | `Yes` | `-` | `urlpath` | `watchlistItemId` | | **Description:** | This id paremeter is used to select the required data object that will be deleted | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `deleteWatchlistItem` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks This Business API enforces ownership of the main data object before executing the operation. - The check is performed **after fetching the object instance**. If the current user is not the owner, the API will respond with **403 Forbidden**. Note: Ownership checks are applied **only if the objects have an owner field**. --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.watchlistItemId},{isActive:true}]} ``` ## Delete Options Use these options to set `delete` specific settings. **useSoftDelete**: false If true, the record will be marked as deleted `(isActive: false)` instead of removed. The implementation depends on the data object’s soft delete configuration. ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request/session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads and normalizes parameters, applies defaults, and stores them in the context for downstream steps. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts, computes derived values, and remaps objects or arrays as needed for later processing. --- ### [4] Step : checkParameters Manager runs built-in validations including required field checks, type enforcement, and deletion preconditions. Stops execution if validation fails. --- ### [5] Step : checkBasicAuth Manager validates session, user roles, permissions, and tenant-specific access rules to enforce basic auth restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager generates the query conditions, applies ownership and parent checks, and ensures the clause is correct for the delete operation. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the target record, applies filters from WHERE clause, and writes the instance to the context for further checks. --- ### [8] Step : checkInstance Manager performs object-level validations such as lock status, soft-delete eligibility, and multi-step approval enforcement. --- ### [9] Step : mainDeleteOperation Manager executes the delete query, updates related indexes/caches, and handles soft/hard delete logic according to configuration. You can use the following settings to change some behavior of this step. `deleteOptions` --- ### [10] Step : buildOutput Manager shapes the response payload, masks sensitive fields, and formats related cleanup results for output. --- ### [11] Step : sendResponse Manager delivers the response to the client and finalizes any temporary internal structures. --- ### [12] Step : raiseApiEvent Manager triggers asynchronous API events, notifies queues or streams, and performs final cleanup for the workflow. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `deleteWatchlistItem` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistItemId | ID | true | request.params?.watchlistItemId | ### REST Request To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistitems/:watchlistItemId** ```js axios({ method: 'DELETE', url: `/v1/watchlistitems/${watchlistItemId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`watchlistItem`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItem", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistItem": { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Delete Watchlistlist` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `deleteWatchlistList` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `deleteWatchlistList` Business API is designed to handle a `delete` operation on the `WatchlistList` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Delete a custom watchlist (folder). Items are reassigned to user’s default list. Cannot delete default list. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `watchlistlist-deleted` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `deleteWatchlistList` Business API includes a REST controller that can be triggered via the following route: `/v1/watchlistlists/:watchlistListId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `deleteWatchlistList` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `deleteWatchlistList` Business API has 1 parameter that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `watchlistListId` | `ID` | `Yes` | `-` | `urlpath` | `watchlistListId` | | **Description:** | This id paremeter is used to select the required data object that will be deleted | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `deleteWatchlistList` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks This Business API enforces ownership of the main data object before executing the operation. - The check is performed **after fetching the object instance**. If the current user is not the owner, the API will respond with **403 Forbidden**. Note: Ownership checks are applied **only if the objects have an owner field**. --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.watchlistListId},{isActive:true}]} ``` ## Delete Options Use these options to set `delete` specific settings. **useSoftDelete**: false If true, the record will be marked as deleted `(isActive: false)` instead of removed. The implementation depends on the data object’s soft delete configuration. ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request/session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads and normalizes parameters, applies defaults, and stores them in the context for downstream steps. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts, computes derived values, and remaps objects or arrays as needed for later processing. --- ### [4] Step : checkParameters Manager runs built-in validations including required field checks, type enforcement, and deletion preconditions. Stops execution if validation fails. --- ### [5] Step : checkBasicAuth Manager validates session, user roles, permissions, and tenant-specific access rules to enforce basic auth restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager generates the query conditions, applies ownership and parent checks, and ensures the clause is correct for the delete operation. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the target record, applies filters from WHERE clause, and writes the instance to the context for further checks. --- ### [8] Step : checkInstance Manager performs object-level validations such as lock status, soft-delete eligibility, and multi-step approval enforcement. --- ### [9] Step : mainDeleteOperation Manager executes the delete query, updates related indexes/caches, and handles soft/hard delete logic according to configuration. You can use the following settings to change some behavior of this step. `deleteOptions` --- ### [10] Step : buildOutput Manager shapes the response payload, masks sensitive fields, and formats related cleanup results for output. --- ### [11] Step : sendResponse Manager delivers the response to the client and finalizes any temporary internal structures. --- ### [12] Step : raiseApiEvent Manager triggers asynchronous API events, notifies queues or streams, and performs final cleanup for the workflow. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `deleteWatchlistList` api has got 1 client parameter | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | watchlistListId | ID | true | request.params?.watchlistListId | ### REST Request To access the api you can use the **REST** controller with the path **DELETE /v1/watchlistlists/:watchlistListId** ```js axios({ method: 'DELETE', url: `/v1/watchlistlists/${watchlistListId}`, data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`watchlistList`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistList", "method": "DELETE", "action": "delete", "appVersion": "Version", "rowCount": 1, "watchlistList": { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": false, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `List Cartitems` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `listCartItems` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `listCartItems` Business API is designed to handle a `list` operation on the `CartItem` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description List all cart items for a user (pending checkout). ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `cartitems-listed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `listCartItems` Business API includes a REST controller that can be triggered via the following route: `/v1/cartitems` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `listCartItems` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `listCartItems` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `listCartItems` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {isActive:true} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `listCartItems` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/cartitems** ```js axios({ method: 'GET', url: '/v1/cartitems', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`cartItems`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "price": "Double", "title": "String", "type": "Enum", "type_idx": "Integer", "mediaAssetIds": "ID" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `List Usercartitems` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `listUserCartItems` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `listUserCartItems` Business API is designed to handle a `list` operation on the `CartItem` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description list all cart items adde by user ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `usercartitems-listed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `listUserCartItems` Business API includes a REST controller that can be triggered via the following route: `/v1/usercartitems` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `listUserCartItems` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `listUserCartItems` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `listUserCartItems` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has a `fullWhereClause` setting : ```js {userId:this.session.userId} ``` **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{userId:this.session.userId},{isActive:true}]} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `listUserCartItems` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/usercartitems** ```js axios({ method: 'GET', url: '/v1/usercartitems', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`cartItems`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "cartItems": [ { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID", "product": [ { "currency": "String", "description": "Text", "condition": "Enum", "condition_idx": "Integer", "endPrice": "Double", "price": "Double", "title": "String", "startPrice": "Double", "type": "Enum", "type_idx": "Integer", "shipping": "Double" }, {}, {} ] }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `List Watchlistitems` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `listWatchlistItems` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `listWatchlistItems` Business API is designed to handle a `list` operation on the `WatchlistItem` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description List all products in user’s watchlists. Supports listing by listId for folders. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `watchlistitems-listed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `listWatchlistItems` Business API includes a REST controller that can be triggered via the following route: `/v1/watchlistitems` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `listWatchlistItems` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `listWatchlistItems` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `listWatchlistItems` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {isActive:true} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `listWatchlistItems` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/watchlistitems** ```js axios({ method: 'GET', url: '/v1/watchlistitems', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`watchlistItems`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `List Watchlistlist` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `listWatchlistList` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `listWatchlistList` Business API is designed to handle a `list` operation on the `WatchlistList` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description List all lists in user’s watchlists. Supports listing by listId for folders. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `watchlistlist-listed` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `listWatchlistList` Business API includes a REST controller that can be triggered via the following route: `/v1/watchlistlists` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `listWatchlistList` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `listWatchlistList` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `listWatchlistList` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {isActive:true} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `listWatchlistList` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/watchlistlists** ```js axios({ method: 'GET', url: '/v1/watchlistlists', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`watchlistLists`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `Update Cartitemquantity` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `updateCartItemQuantity` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `updateCartItemQuantity` Business API is designed to handle a `update` operation on the `CartItem` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description Change the quantity for a cart item. User must own the item. ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `cartitemquantity-updated` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `updateCartItemQuantity` Business API includes a REST controller that can be triggered via the following route: `/v1/cartitemquantity/:cartItemId` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `updateCartItemQuantity` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `updateCartItemQuantity` Business API has 2 parameters that must be sent from the controller. Note that all parameters, except session and Redis parameters, should be provided by the client. Business API parameters can be: * **Auto-generated by Mindbricks** — inferred from the CRUD type and the property definitions of the main data object when the `autoParameters` option is enabled. * **Custom parameters added by the architect** — these can supplement or override the auto-generated parameters. ### Parameter Details | Name | Type | Required | Default | Location | Data Path | | ----------------------------------------------- | --------------------- | -------------------------------------- | -------------------------------------------------------------------- | --------------------------- | ------------------------------ | | | | | | | | | `cartItemId` | `ID` | `Yes` | `-` | `urlpath` | `cartItemId` | | **Description:** | This id paremeter is used to select the required data object that will be updated | | | | | | | | | | | | | `quantity` | `Integer` | `No` | `-` | `body` | `quantity` | | **Description:** | How many units (if product allows). | | | | | | | | | | | | ### Parameter Transformations Some parameters are post-processed using **transform scripts** after being read from the request but before validation or workflow execution. Only parameters with a `transform` script are listed below. *No parameters are transformed in this API.* ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `updateCartItemQuantity` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks This Business API enforces ownership of the main data object before executing the operation. - The check is performed **after fetching the object instance**. If the current user is not the owner, the API will respond with **403 Forbidden**. Note: Ownership checks are applied **only if the objects have an owner field**. --- ### Role and Permission Settings --- ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has no `fullWhereClause` setting. **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{id:this.cartItemId},{isActive:true}]} ``` ## Data Clause Defines custom field-value assignments used to modify or augment the default payload for `create` and `update` operations. These settings override values derived from the session or parameters if explicitly provided.", Note that a default data clause is always prepared by Mindbricks using data property settings, however any property in the data clause can be override by Data Clause Settings. An update data clause populates all update-allowed properties of a data object, however the null properties (that are not provided by client) are ignored in db layer. **Custom Data Clause Override** *No custom data clause override configured* **Actual Data Clause** The business api will use the following data clause. Note that any calculated value will be added to the data clause in the api manager. ```js { quantity: this.quantity, } ``` ## Business Logic Workflow ### [1] Step : startBusinessApi Manager initializes context, prepares request and session objects, and sets up internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Manager reads parameters from the request or Redis, applies defaults, and writes them into context for downstream milestones. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Manager executes parameter transform scripts and derives any helper values or reshaped payloads into the context. --- ### [4] Step : checkParameters Manager validates required parameters, checks ID formats (UUID/ObjectId), and ensures all preconditions for update are met. --- ### [5] Step : checkBasicAuth Manager performs login verification, role, and permission checks, enforcing tenant and access rules before update. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Manager constructs the WHERE clause used to identify the record to update, applying ownership and parent checks if necessary. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : fetchInstance Manager fetches the existing record from the database and writes it to the context for validation or enrichment. --- ### [8] Step : checkInstance Manager performs instance-level validations, including ownership, existence, lock status, or other pre-update checks. --- ### [9] Step : buildDataClause Manager prepares the data clause for the update, applying transformations or enhancements before persisting. You can use the following settings to change some behavior of this step. `dataClause` --- ### [10] Step : mainUpdateOperation Manager executes the update operation with the WHERE and data clauses. Database-level events are raised if configured. --- ### [11] Step : buildOutput Manager assembles the response object from the update result, masking fields or injecting additional metadata. --- ### [12] Step : sendResponse Manager sends the response back to the controller for delivery to the client. --- ### [13] Step : raiseApiEvent Manager triggers API-level events, sending relevant messages to Kafka or other integrations if configured. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `updateCartItemQuantity` api has got 2 client parameters | Parameter | Type | Required | Population | | ---------------------- | ---------------------- | -------- | ---------------------------- | | cartItemId | ID | true | request.params?.cartItemId | | quantity | Integer | false | request.body?.quantity | ### REST Request To access the api you can use the **REST** controller with the path **PATCH /v1/cartitemquantity/:cartItemId** ```js axios({ method: 'PATCH', url: `/v1/cartitemquantity/${cartItemId}`, data: { quantity:"Integer", }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`cartItem`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "cartItem", "method": "PATCH", "action": "update", "appVersion": "Version", "rowCount": 1, "cartItem": { "id": "ID", "addedAt": "Date", "userId": "ID", "quantity": "Integer", "productId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" } } ``` # Business API Design Specification - `Do Userwatchlist` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `userwatchlist` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `userwatchlist` Business API is designed to handle a `list` operation on the `WatchlistItem` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description userwatchlist ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `userwatchlist-done` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `userwatchlist` Business API includes a REST controller that can be triggered via the following route: `/v1/userwatchlist` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `userwatchlist` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `userwatchlist` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `userwatchlist` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has a `fullWhereClause` setting : ```js {userId:this.session.userId} ``` **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{userId:this.session.userId},{isActive:true}]} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `userwatchlist` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/userwatchlist** ```js axios({ method: 'GET', url: '/v1/userwatchlist', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`watchlistItems`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistItems", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistItems": [ { "id": "ID", "userId": "ID", "addedAt": "Date", "productId": "ID", "listId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ``` # Business API Design Specification - `Do Userwatchlistlists` A Business API is a set of logical actions centered around a main data object. These actions can range from simple CRUD operations to complex workflows that implement intricate business logic. While the term “API” traditionally refers to an interface that allows software systems to interact, in Mindbricks a Business API represents a broader concept. It encapsulates a business workflow around a data object, going beyond basic CRUD operations to include rich, internally coordinated actions that can be fully designed and customized. This document provides an in-depth explanation of the architectural design of the `userwatchlistlists` Business API. It is intended to guide backend architects and developers in maintaining the current design. Additionally, frontend developers and frontend AI agents can use this document to understand how to properly consume this API on the client side. ## Main Data Object and CRUD Operation The `userwatchlistlists` Business API is designed to handle a `list` operation on the `WatchlistList` data object. This operation is performed under the specified conditions and may include additional, coordinated actions as part of the workflow. ## API Description list all watch lists created by user ## API Options * **Auto Params** : `true` Determines whether input parameters should be auto-generated from the schema of the associated data object. Set to `false` if you want to define all input parameters manually. * **Raise Api Event** : `true` Indicates whether the Business API should emit an API-level event after successful execution. This is typically used for audit trails, analytics, or external integrations. The event will be emitted to the `userwatchlistlists-done` Kafka Topic Note that the DB-Level events for `create`, `update` and `delete` operations will always be raised for internal reasons. * **Active Check** : `` Controls how the system checks if a record is active (not soft-deleted or inactive). Uses the `ApiCheckOption` to determine whether this is checked during the query or after fetching the instance. * **Read From Entity Cache** : `false` If enabled, the API will attempt to read the target object from the Redis entity cache before querying the database. This can improve performance for frequently accessed records. ## API Controllers A Mindbricks Business API can be accessed through multiple interfaces, including REST, gRPC, WebSocket, Kafka, or Cron. The controllers listed below map the business workflow to a specific interface, enabling consistent interaction regardless of the communication channel. ### REST Controller The `userwatchlistlists` Business API includes a REST controller that can be triggered via the following route: `/v1/userwatchlistlists` By sending a request to this route using the service API address, you can execute this Business API. Parameters can be provided in multiple HTTP locations, including the URL path, URL query, request body, and request headers. Detailed information about these parameters is provided in the **Parameters** section. ### MCP Tool REST controllers also expose the Business API as a tool in the MCP, making it accessible to AI agents. This `userwatchlistlists` Business API will be registered as a tool on the MCP server within the service binding. ## API Parameters The `userwatchlistlists` Business API does not require any parameters to be provided from the controllers. ## AUTH Configuration The **authentication and authorization configuration** defines the core access rules for the `userwatchlistlists` Business API. These checks are applied **after parameter validation** and before executing the main business logic. While these settings cover the most common scenarios, more **fine-grained or conditional access control**—such as permissions based on object context, nested memberships, or custom workflows—should be implemented using explicit actions like `PermissionCheckAction`, `MembershipCheckAction`, or `ObjectPermissionCheckAction`. ### Login Requirement This API **requires login** (`loginRequired = true`). Requests from non-logged-in users will return a **401 Unauthorized** error. Login is necessary **but not sufficient**, as additional role, permission, or other authorization checks may still apply. --- ### Ownership Checks --- ### Role and Permission Settings --- ## Select Clause Specifies which fields will be selected from the main data object during a `get` or `list` operation. Leave blank to select all properties. This applies only to `get` and `list` type APIs.", `` ## Where Clause Defines the criteria used to locate the target record(s) for the main operation. This is expressed as a query object and applies to `get`, `list`, `update`, and `delete` APIs. All API types except `list` are expected to affect a single record. *If nothing is configured for (get, update, delete) the id fields will be the select criteria.* **Select By**: A list of fields that must be matched exactly as part of the WHERE clause. This is not a filter — it is a required selection rule. In single-record APIs (`get`, `update`, `delete`), it defines how a unique record is located. In `list` APIs, it scopes the results to only entries matching the given values. Note that `selectBy` fields will be ignored if `fullWhereClause` is set. *The business api configuration has no `selectBy` setting.* **Full Where Clause** An MScript query expression that overrides all default WHERE clause logic. Use this for fully customized queries. When `fullWhereClause` is set, `selectBy` is ignored, however additional selects will still be applied to final where clause. The business api configuration has a `fullWhereClause` setting : ```js {userId:this.session.userId} ``` **Additional Clauses** A list of conditionally applied MScript query fragments. These clauses are appended only if their conditions evaluate to true. If no condition is set it will be applied to the where clause directly. The business api configuration has no additionalClauses setting. **Actual Where Clause** This where clause is built using whereClause configuration (if set) and default business logic. ```js {$and:[{userId:this.session.userId},{isActive:true}]} ``` ## List Options Defines list-specific options including filtering logic, default sorting, and result customization for APIs that return multiple records. **List Sort By** Sort order definitions for the result set. Multiple fields can be provided with direction (asc/desc). Specific sort order is not configure, natural order (ascending id) will be used. **List Group By** Grouping definitions for the result set. This is typically used for visual or report-based grouping. *The list is not grouped.* **setAsRead**: An optional array of field-value mappings that will be updated after the read operation. Useful for marking items as read or viewed. No `setAsread` field-value pair is configured. **Permission Filter** Optional filter that applies permission constraints dynamically based on session or object roles. So that the list items are filtered by the user's OBAC or ABAC permissions. *Permission filter is not active at the moment. Follow Mindbricks updates to be able to use it.* ## Pagination Options Contains settings to configure pagination behavior for `list` APIs. Includes options like page size, offset, cursor support, and total count inclusion. ## Business Logic Workflow ### [1] Step : startBusinessApi Initializes context with request and session objects. Prepares internal structures for parameter handling and milestone execution. You can use the following settings to change some behavior of this step. `apiOptions`, `restSettings`, `grpcSettings`, `kafkaSettings`, `socketSettings`, `cronSettings` --- ### [2] Step : readParameters Reads request and Redis parameters, applies defaults, and writes them to context for downstream processing. You can use the following settings to change some behavior of this step. `customParameters`, `redisParameters` --- ### [3] Step : transposeParameters Transforms and normalizes parameters, derives dependent values, and reshapes inputs for the main list query. --- ### [4] Step : checkParameters Executes validation logic on required and custom parameters, enforcing business rules and cross-field consistency. --- ### [5] Step : checkBasicAuth Performs role-based access checks and applies dynamic membership or session-based restrictions. You can use the following settings to change some behavior of this step. `authOptions` --- ### [6] Step : buildWhereClause Constructs the main query WHERE clause and applies optional filters or scoped access controls. You can use the following settings to change some behavior of this step. `whereClause` --- ### [7] Step : mainListOperation Executes the paginated database query, retrieves the list, and stores results in context for enrichment. You can use the following settings to change some behavior of this step. `selectClause`, `listOptions`, `paginationOptions` --- ### [8] Step : buildOutput Assembles the list response, sanitizes sensitive fields, applies transformations, and injects extra context if needed. --- ### [9] Step : sendResponse Sends the paginated list to the client through the controller. --- ### [10] Step : raiseApiEvent Triggers optional post-workflow events, such as Kafka messages, logs, or system notifications. --- ## Rest Usage ### Rest Client Parameters Client parameters are the api parameters that are visible to client and will be populated by the client. Note that some api parameters are not visible to client because they are populated by internal system, session, calculation or joint sources. The `userwatchlistlists` api has got no visible parameters. ### REST Request To access the api you can use the **REST** controller with the path **GET /v1/userwatchlistlists** ```js axios({ method: 'GET', url: '/v1/userwatchlistlists', data: { }, params: { } }); ``` ### REST Response The API response is encapsulated within a JSON envelope. Successful operations return an HTTP status code of 200 for get, list, update, or delete requests, and 201 for create requests. Each successful response includes a `"status": "OK"` property. For error handling, refer to the "Error Response" section. Following JSON represents the most comprehensive form of the **`watchlistLists`** object in the respones. However, some properties may be omitted based on the object's internal logic. ```json { "status": "OK", "statusCode": "200", "elapsedMs": 126, "ssoTime": 120, "source": "db", "cacheKey": "hexCode", "userId": "ID", "sessionId": "ID", "requestId": "ID", "dataName": "watchlistLists", "method": "GET", "action": "list", "appVersion": "Version", "rowCount": "\"Number\"", "watchlistLists": [ { "id": "ID", "name": "String", "itemCount": "Integer", "userId": "ID", "isActive": true, "recordVersion": "Integer", "createdAt": "Date", "updatedAt": "Date", "_owner": "ID" }, {}, {} ], "paging": { "pageNumber": "Number", "pageRowCount": "NUmber", "totalRowCount": "Number", "pageCount": "Number" }, "filters": [], "uiPermissions": [] } ```