{ "openapi": "3.0.0", "info": { "title": "Ebda Store API", "version": "1.0.0", "description": "\n# Ebda Store API Documentation\n\nMulti-tenant e-commerce platform API for managing stores, products, orders, and more.\n\n## Authentication\n\nMost endpoints require authentication using JWT Bearer tokens. Include the token in the Authorization header:\n\n```\nAuthorization: Bearer \n```\n\n## Rate Limiting\n\nAPI requests are rate limited to 100 requests per 15-minute window per IP address.\n\n## Error Responses\n\nAll errors follow this format:\n\n```json\n{\n \"success\": false,\n \"error\": {\n \"code\": \"ERROR_CODE\",\n \"message\": \"Human readable message\"\n }\n}\n```\n\n## Common Error Codes\n\n| Code | HTTP Status | Description |\n|------|-------------|-------------|\n| UNAUTHORIZED | 401 | Missing or invalid authentication token |\n| FORBIDDEN | 403 | Insufficient permissions |\n| NOT_FOUND | 404 | Resource not found |\n| VALIDATION_ERROR | 400 | Invalid request data |\n| RATE_LIMITED | 429 | Too many requests |\n ", "contact": { "name": "Ebda Store", "email": "ahlan@ebda.app", "url": "https://ebda.app" }, "license": { "name": "Proprietary", "url": "https://ebda.app/terms" } }, "servers": [ { "url": "http://localhost:4000/api/v1", "description": "Development server" }, { "url": "https://api.ebda.app/api/v1", "description": "Production server" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Enter your JWT access token" } }, "schemas": { "Error": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "example": "Invalid request data" } } } } }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "limit": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 100 }, "totalPages": { "type": "integer", "example": 5 } } }, "User": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "role": { "type": "string", "enum": [ "customer", "store_admin", "super_admin" ] }, "isVerified": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } }, "Store": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "nameAr": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "logo": { "type": "string", "format": "uri" }, "domain": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "suspended", "pending" ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "Product": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "nameAr": { "type": "string", "nullable": true }, "slug": { "type": "string" }, "description": { "type": "string", "nullable": true }, "descriptionAr": { "type": "string", "nullable": true }, "price": { "type": "integer", "description": "Price in piastres (1 EGP = 100 piastres)" }, "compareAtPrice": { "type": "integer", "nullable": true }, "sku": { "type": "string", "nullable": true }, "badgeLabel": { "type": "string", "nullable": true, "maxLength": 32 }, "badgeLabelAr": { "type": "string", "nullable": true, "maxLength": 32 }, "searchTerms": { "type": "string", "nullable": true, "maxLength": 500, "description": "Extra words shoppers type (dialect / Franco / English); comma-separated, cleaned to \"a, b, c\". Searched, never displayed. null clears." }, "inventory": { "type": "integer" }, "status": { "type": "string", "enum": [ "active", "draft", "archived" ] }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/ProductImage" } }, "category": { "$ref": "#/components/schemas/Category" }, "createdAt": { "type": "string", "format": "date-time" } } }, "ProductImage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "alt": { "type": "string" }, "position": { "type": "integer" } } }, "Category": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "nameAr": { "type": "string", "nullable": true }, "slug": { "type": "string" }, "description": { "type": "string", "nullable": true }, "descriptionAr": { "type": "string", "nullable": true }, "image": { "type": "string", "format": "uri", "nullable": true } } }, "Order": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orderNumber": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "confirmed", "processing", "shipped", "delivered", "cancelled", "refunded" ] }, "subtotal": { "type": "integer" }, "tax": { "type": "integer" }, "shipping": { "type": "integer" }, "total": { "type": "integer" }, "shippingAddress": { "type": "object" }, "billingAddress": { "type": "object" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } }, "customer": { "$ref": "#/components/schemas/User" }, "createdAt": { "type": "string", "format": "date-time" } } }, "OrderItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "productId": { "type": "string", "format": "uuid" }, "productName": { "type": "string" }, "sku": { "type": "string" }, "quantity": { "type": "integer" }, "price": { "type": "integer" }, "total": { "type": "integer" } } }, "Cart": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CartItem" } }, "itemCount": { "type": "integer" }, "subtotal": { "type": "integer" } } }, "CartItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "productId": { "type": "string", "format": "uuid" }, "quantity": { "type": "integer" }, "product": { "$ref": "#/components/schemas/Product" } } }, "Review": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "title": { "type": "string" }, "comment": { "type": "string" }, "isVerified": { "type": "boolean" }, "isApproved": { "type": "boolean" }, "helpfulCount": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } } }, "Return": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "returnNumber": { "type": "string" }, "type": { "type": "string", "enum": [ "return", "exchange", "refund" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "shipped", "received", "inspecting", "completed", "cancelled" ] }, "reason": { "type": "string" }, "refundAmount": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ReturnItem" } }, "createdAt": { "type": "string", "format": "date-time" } } }, "ReturnItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "productId": { "type": "string", "format": "uuid" }, "productName": { "type": "string" }, "quantity": { "type": "integer" }, "reason": { "type": "string" }, "condition": { "type": "string" }, "orderItem": { "type": "object", "nullable": true, "properties": { "bundleGroupId": { "type": "string", "format": "uuid", "nullable": true }, "bundleName": { "type": "string", "nullable": true }, "bundleNameAr": { "type": "string", "nullable": true } } } } }, "DashboardStats": { "type": "object", "properties": { "totalOrders": { "type": "integer" }, "totalRevenue": { "type": "integer" }, "totalProducts": { "type": "integer" }, "totalCustomers": { "type": "integer", "description": "Distinct customers in the period, keyed like the Customers page (user, else shipping email, else phone)" }, "allTimeCustomers": { "type": "integer" }, "ordersChange": { "type": "number", "format": "float" }, "revenueChange": { "type": "number", "format": "float" }, "conversionRate": { "type": "number", "format": "float", "nullable": true, "description": "Orders per product view (%), null when no views were recorded" }, "totalProfit": { "type": "integer", "nullable": true, "description": "Piastres; null when sold lines have no cost price" }, "profitItemsMissingCost": { "type": "integer" }, "profitRevenueMissingCost": { "type": "integer" } } } }, "responses": { "UnauthorizedError": { "description": "Access token is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Authentication required" } } } } }, "ForbiddenError": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "Access denied" } } } } }, "NotFoundError": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Resource not found" } } } } }, "ValidationError": { "description": "Invalid request data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Invalid request data" } } } } } } }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Authentication", "description": "User authentication endpoints" }, { "name": "Stores", "description": "Store management endpoints" }, { "name": "Products", "description": "Product management endpoints" }, { "name": "Categories", "description": "Category management endpoints" }, { "name": "Cart", "description": "Shopping cart endpoints" }, { "name": "Orders", "description": "Order management endpoints" }, { "name": "Reviews", "description": "Product review endpoints" }, { "name": "Returns", "description": "Return/exchange management endpoints" }, { "name": "Analytics", "description": "Store analytics endpoints" }, { "name": "Payments", "description": "Payment processing endpoints" }, { "name": "Uploads", "description": "File upload endpoints" }, { "name": "AI", "description": "Ebda Store assistant endpoints" }, { "name": "Admin", "description": "Super admin management endpoints" } ], "paths": { "/stores": { "get": { "summary": "List all stores", "description": "Get paginated list of all stores (admin only)", "tags": [ "Stores" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1 } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "List of stores", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "stores": { "type": "array", "items": { "$ref": "#/components/schemas/Store" } }, "meta": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" } } }, "post": { "summary": "Create a new store", "description": "Create a new store (admin only)", "tags": [ "Stores" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "My Store" }, "slug": { "type": "string", "pattern": "^[a-z0-9-]+$", "example": "my-store" }, "domain": { "type": "string", "example": "mystore.com" }, "settings": { "type": "object" } } } } } }, "responses": { "201": { "description": "Store created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "store": { "$ref": "#/components/schemas/Store" } } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/stores/{storeId}/products": { "get": { "summary": "List products", "description": "Get paginated list of products for a store", "tags": [ "Products" ], "security": [], "parameters": [ { "in": "path", "name": "storeId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1 } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 20 } }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "active", "draft", "archived" ] } }, { "in": "query", "name": "category", "schema": { "type": "string" } }, { "in": "query", "name": "search", "schema": { "type": "string" } }, { "in": "query", "name": "featured", "description": "Omit for all products; 'true' or 'false' filters. Any other value is a 400.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of products", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "meta": { "$ref": "#/components/schemas/Pagination" } } } } } } } } } } }, "/auth/register": { "post": { "summary": "Register a new user", "description": "Create a new user account with email verification", "tags": [ "Authentication" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" }, "password": { "type": "string", "minLength": 8, "example": "securePassword123" }, "firstName": { "type": "string", "example": "John" }, "lastName": { "type": "string", "example": "Doe" } } } } } }, "responses": { "200": { "description": "Verification email sent. Identical for new and existing emails (T1-4 enumeration close) — no user, tokens, cookies or csrfToken are issued; the session starts at /auth/login after verification.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "emailVerificationSent": { "type": "boolean", "example": true } } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" } } } }, "/auth/login": { "post": { "summary": "Login user", "description": "Authenticate user and return JWT tokens", "tags": [ "Authentication" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" } } } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "accessToken": { "type": "string" }, "refreshToken": { "type": "string" } } } } } } } }, "401": { "description": "Invalid credentials" } } } } } }