{ "openapi": "3.1.0", "info": { "title": "EaaS Platform API & Model Context Protocol (MCP) Reference", "version": "1.0.0", "description": "Comprehensive REST and MCP specification for the E-commerce-as-a-Service (EaaS) Multi-Tenant Platform. Enables external websites (Shopify, WooCommerce, custom frontends) to ingest catalogs and sync transactions into the Merchant Admin Panel, and provides Super Admin platform orchestration.", "contact": { "name": "EaaS Developer Platform", "url": "https://eaas-platform.local" } }, "servers": [ { "url": "/api", "description": "Current Environment API Server" } ], "security": [ { "TenantHeader": [] } ], "paths": { "/v1/version": { "get": { "summary": "Platform Health & Version Info", "description": "Returns runtime environment details, API version, and engine status.", "tags": ["Platform"], "responses": { "200": { "description": "Platform version details" } } } }, "/v1/storefront/products": { "get": { "summary": "List Catalog Products", "description": "Retrieve active catalog products for the current tenant store.", "tags": ["Storefront"], "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search term across product titles and descriptions" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Paginated product list" } } } }, "/v1/storefront/products/{slug}": { "get": { "summary": "Get Product Details by Slug", "description": "Retrieve comprehensive product metadata and SKU variant matrix for the storefront.", "tags": ["Storefront"], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product details with active variants" }, "404": { "description": "Product not found in this tenant store" } } } }, "/v1/storefront/cart": { "post": { "summary": "Create Cart", "description": "Initialize a new shopping cart session identified by a unique UUID.", "tags": ["Cart & Checkout"], "responses": { "201": { "description": "Cart initialized with UUID" } } } }, "/v1/storefront/cart/{cartId}": { "get": { "summary": "Get Cart Contents", "description": "Retrieve cart line items, subtotal, tax, and estimated totals.", "tags": ["Cart & Checkout"], "parameters": [ { "name": "cartId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Cart contents" } } } }, "/v1/storefront/cart/{cartId}/items": { "post": { "summary": "Add Item to Cart", "description": "Add a product SKU variant to the cart session with real-time stock verification.", "tags": ["Cart & Checkout"], "parameters": [ { "name": "cartId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["product_variant_id", "quantity"], "properties": { "product_variant_id": { "type": "integer" }, "quantity": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "200": { "description": "Item added to cart" }, "422": { "description": "Insufficient inventory or invalid variant" } } } }, "/v1/storefront/cart/{cartId}/coupon": { "post": { "summary": "Apply Coupon to Cart", "description": "Applies a percentage, fixed amount, or free shipping coupon to the cart and recalculates totals.", "tags": ["Cart & Checkout"], "parameters": [ { "name": "cartId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["code"], "properties": { "code": { "type": "string", "example": "SAVE20" } } } } } }, "responses": { "200": { "description": "Coupon applied and cart discounted" }, "422": { "description": "Invalid, expired, or unmet minimum subtotal" } } }, "delete": { "summary": "Remove Coupon from Cart", "description": "Removes any active coupon and restores standard pricing.", "tags": ["Cart & Checkout"], "parameters": [ { "name": "cartId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Coupon removed and cart recalculated" } } } }, "/v1/storefront/checkout": { "post": { "summary": "Submit Order Checkout", "description": "Process atomic order placement with DB row locking, inventory deduction, and idempotency protection.", "tags": ["Cart & Checkout"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["cart_id", "customer_name", "customer_email"], "properties": { "cart_id": { "type": "string", "format": "uuid" }, "customer_name": { "type": "string" }, "customer_email": { "type": "string", "format": "email" }, "customer_phone": { "type": "string" }, "shipping_address": { "type": "object" }, "billing_address": { "type": "object" }, "payment_method": { "type": "string", "default": "stripe" }, "idempotency_key": { "type": "string" } } } } } }, "responses": { "201": { "description": "Order placed successfully" }, "422": { "description": "Inventory check failed or empty cart" } } } }, "/v1/external/sync/products": { "post": { "summary": "Sync External Website Products (REST)", "description": "Allows external websites (Shopify, WooCommerce, custom Next.js storefronts) to stream products and variant matrices directly into their EaaS Merchant Panel.", "tags": ["External Website & MCP Integration"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["products"], "properties": { "source": { "type": "string", "example": "woocommerce", "description": "External platform identifier" }, "products": { "type": "array", "items": { "type": "object", "required": ["title"], "properties": { "external_id": { "type": "string", "example": "woo_prod_8941" }, "title": { "type": "string", "example": "Organic Cotton Crewneck" }, "slug": { "type": "string", "example": "organic-cotton-crewneck" }, "description": { "type": "string" }, "price": { "type": "number", "example": 45.00 }, "inventory_quantity": { "type": "integer", "example": 80 }, "featured_image_url": { "type": "string", "format": "uri" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "example": "CREW-BLK-M" }, "title": { "type": "string", "example": "Black / Medium" }, "price": { "type": "number", "example": 45.00 }, "inventory_quantity": { "type": "integer", "example": 40 } } } } } } } } } } } }, "responses": { "200": { "description": "External products synced and tagged in Merchant Admin Panel" } } } }, "/v1/external/sync/orders": { "post": { "summary": "Sync External Website Orders (REST)", "description": "Ingest external website orders and customer details so sales and analytics reflect immediately in the Merchant Dashboard.", "tags": ["External Website & MCP Integration"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["orders"], "properties": { "source": { "type": "string", "example": "shopify" }, "orders": { "type": "array", "items": { "type": "object", "required": ["total"], "properties": { "external_id": { "type": "string", "example": "ext_ord_1029" }, "order_number": { "type": "string", "example": "SH-1029" }, "customer_name": { "type": "string", "example": "Alice Smith" }, "customer_email": { "type": "string", "format": "email", "example": "alice@external.com" }, "total": { "type": "number", "example": 120.00 }, "status": { "type": "string", "example": "completed" }, "payment_status": { "type": "string", "example": "paid" }, "items": { "type": "array", "items": { "type": "object", "properties": { "product_title": { "type": "string", "example": "Classic Tee" }, "sku": { "type": "string", "example": "TEE-WHT-L" }, "quantity": { "type": "integer", "example": 2 }, "unit_price": { "type": "number", "example": 60.00 } } } } } } } } } } } }, "responses": { "200": { "description": "External orders synced to merchant panel" } } } }, "/v1/external/integrations": { "get": { "summary": "Get External Integration Telemetry", "description": "Returns counts of synced products vs native products, last sync timestamps, and MCP server connection details.", "tags": ["External Website & MCP Integration"], "responses": { "200": { "description": "Integration telemetry summary" } } } }, "/mcp": { "post": { "summary": "Model Context Protocol (MCP) JSON-RPC Endpoint", "description": "Standard Model Context Protocol web endpoint. Supports tools: `sync_external_products`, `sync_external_orders`, `get_store_metrics`, and `list_store_products`.", "tags": ["Model Context Protocol (MCP)"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["jsonrpc", "method"], "properties": { "jsonrpc": { "type": "string", "example": "2.0" }, "method": { "type": "string", "example": "tools/call" }, "params": { "type": "object", "properties": { "name": { "type": "string", "example": "sync_external_products" }, "arguments": { "type": "object" } } }, "id": { "type": "integer", "example": 1 } } } } } }, "responses": { "200": { "description": "MCP JSON-RPC response" } } } }, "/v1/admin/dashboard": { "get": { "summary": "Merchant Dashboard Metrics", "description": "Executive metrics for the active tenant store, including GMV, total orders, low stock items, and external sync counts.", "tags": ["Merchant Admin"], "responses": { "200": { "description": "Store KPIs and recent orders" } } } }, "/v1/admin/products": { "get": { "summary": "List Merchant Products", "description": "Paginated products list for merchant management.", "tags": ["Merchant Admin"], "responses": { "200": { "description": "Merchant catalog list" } } }, "post": { "summary": "Create Product with Variant Matrix", "description": "Create a new catalog item with SKU options.", "tags": ["Merchant Admin"], "responses": { "201": { "description": "Product created" } } } }, "/v1/admin/orders": { "get": { "summary": "List Merchant Orders", "description": "Retrieve store orders with customer and item details.", "tags": ["Merchant Admin"], "responses": { "200": { "description": "Orders list" } } } }, "/v1/admin/orders/{id}/status": { "patch": { "summary": "Update Order Status", "description": "Modify order or payment status.", "tags": ["Merchant Admin"], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["pending", "paid", "processing", "completed", "cancelled"] }, "payment_status": { "type": "string", "enum": ["pending", "paid", "failed", "refunded"] }, "fulfillment_status": { "type": "string", "enum": ["unfulfilled", "partially_fulfilled", "fulfilled"] } } } } } }, "responses": { "200": { "description": "Order status updated" } } } }, "/v1/admin/coupons": { "get": { "summary": "List Store Coupons", "description": "Retrieve active and expired merchant coupons and redemption counts.", "tags": ["Merchant Admin"], "responses": { "200": { "description": "Coupons list" } } }, "post": { "summary": "Create Store Coupon", "description": "Create a new discount coupon with percentage, fixed amount, or free shipping rules.", "tags": ["Merchant Admin"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["code", "type", "value"], "properties": { "code": { "type": "string", "example": "SPRING30" }, "type": { "type": "string", "enum": ["percentage", "fixed_amount", "free_shipping"], "example": "percentage" }, "value": { "type": "number", "example": 30.00 }, "min_order_subtotal": { "type": "number", "example": 60.00 }, "max_discount_amount": { "type": "number", "example": 50.00 }, "usage_limit": { "type": "integer", "example": 100 } } } } } }, "responses": { "201": { "description": "Coupon created" } } } }, "/v1/admin/coupons/{id}": { "delete": { "summary": "Delete Coupon", "description": "Remove an existing coupon from the store.", "tags": ["Merchant Admin"], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Coupon deleted" } } } }, "/v1/super-admin/dashboard": { "get": { "summary": "Super Admin Global Telemetry", "description": "Platform-wide executive metrics across all tenant stores: Global GMV, Total Orders, Store Count, and Store Summaries.", "tags": ["Super Admin"], "responses": { "200": { "description": "Global platform telemetry" } } } }, "/v1/super-admin/tenants": { "get": { "summary": "List Tenant Stores", "description": "Paginated list of all merchant stores with GMV and product counts.", "tags": ["Super Admin"], "responses": { "200": { "description": "Tenants list" } } }, "post": { "summary": "Provision New Tenant Store", "description": "Provision a new isolated merchant store tenant.", "tags": ["Super Admin"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "example": "Apex Footwear" }, "slug": { "type": "string", "example": "apex-footwear" }, "domain": { "type": "string", "example": "shop.apexfootwear.com" }, "currency": { "type": "string", "example": "USD" } } } } } }, "responses": { "201": { "description": "Tenant store created" } } } }, "/v1/super-admin/tenants/{id}/status": { "patch": { "summary": "Toggle Tenant Store Status", "description": "Activate or suspend a merchant store tenant.", "tags": ["Super Admin"], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Tenant status updated" } } } }, "/v1/storefront/sitemap.xml": { "get": { "summary": "Dynamic XML Sitemap Index", "description": "Standard XML sitemap with Google Image metadata and alternate language hreflang links.", "tags": ["Marketing, SEO & AI Discovery"], "responses": { "200": { "description": "XML sitemap content", "content": { "application/xml": {} } } } } }, "/v1/storefront/sitemap-products.xml": { "get": { "summary": "Products XML Sitemap", "description": "Dedicated product catalog sitemap for search crawlers.", "tags": ["Marketing, SEO & AI Discovery"], "responses": { "200": { "description": "Products XML sitemap", "content": { "application/xml": {} } } } } }, "/v1/storefront/sitemap-pages.xml": { "get": { "summary": "Static & Discovery Pages XML Sitemap", "description": "Dedicated pages sitemap listing homepage, catalog, policies, and AI discovery endpoints.", "tags": ["Marketing, SEO & AI Discovery"], "responses": { "200": { "description": "Pages XML sitemap", "content": { "application/xml": {} } } } } }, "/v1/storefront/robots.txt": { "get": { "summary": "Dynamic Crawler Directives (robots.txt)", "description": "Crawler permissions tailored for Googlebot, Bingbot, and AI engines (GPTBot, PerplexityBot, ClaudeBot, Applebot-Extended) with Sitemap and LLMs-Txt declarations.", "tags": ["Marketing, SEO & AI Discovery"], "responses": { "200": { "description": "Plain text crawler rules", "content": { "text/plain": {} } } } } }, "/v1/storefront/llms.txt": { "get": { "summary": "Standard LLMs.txt Context (AI Discovery)", "description": "Open standard /llms.txt Markdown feed for AI search engines (Perplexity, ChatGPT Search, Claude, Gemini) containing brand identity, active products, discount codes, policies, and MCP agent instructions.", "tags": ["Marketing, SEO & AI Discovery"], "responses": { "200": { "description": "Markdown formatted LLM context", "content": { "text/markdown": {} } } } } }, "/v1/storefront/llms-full.txt": { "get": { "summary": "Deep RAG Knowledge Base (/llms-full.txt)", "description": "Comprehensive unstructured and structured knowledge base for full Large Language Model RAG ingestion.", "tags": ["Marketing, SEO & AI Discovery"], "responses": { "200": { "description": "Full Markdown knowledge dataset", "content": { "text/markdown": {} } } } } }, "/v1/storefront/geo.json": { "get": { "summary": "Geographic Operations & Delivery Coverage (GeoJSON)", "description": "RFC 7946 GeoJSON FeatureCollection specifying store headquarters/fulfillment point coordinates and polygon operational delivery zones.", "tags": ["Marketing, SEO & AI Discovery"], "responses": { "200": { "description": "GeoJSON FeatureCollection", "content": { "application/geo+json": {} } } } } }, "/v1/storefront/ai-catalog.json": { "get": { "summary": "Answer Engine Optimization Facts Feed (AEO)", "description": "High-density factual JSON payload optimized for zero-shot question answering by Google AI Overviews, Perplexity, and conversational commerce agents.", "tags": ["Marketing, SEO & AI Discovery"], "responses": { "200": { "description": "AEO JSON fact sheet", "content": { "application/json": {} } } } } } }, "components": { "securitySchemes": { "TenantHeader": { "type": "apiKey", "in": "header", "name": "X-Tenant-ID", "description": "Tenant Store Identifier (slug or ID). Can alternatively be resolved via custom domain or Host header." }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Sanctum Token" } } } }