{"openapi":"3.0.0","info":{"title":"RetailCenter - External API Documentation","version":"1.0.0","description":"RetailCenter - External API documentation for third-party integrations. This API requires authentication via API Key (x-api-key or X-API-KEY header). User-specific operations (orders, payments, profile) require BOTH API key AND Bearer token. If your API key has IP whitelisting enabled, you must include the x-forwarded-for header with your client's IP address. Contact your administrator to obtain an API key.","contact":{"name":"API Support","email":"hr@retailcenter.io"}},"servers":[{"url":"http://localhost:5001/api","description":"Development server"},{"url":"https://prod.v2.api.retailcenter.io/api","description":"Production server"}],"tags":[{"name":"Cart","description":"Shopping cart management endpoints"},{"name":"Orders","description":"Order creation and retrieval endpoints (requires API key + Bearer token)"},{"name":"Payments","description":"Payment processing endpoints (requires API key + Bearer token)"},{"name":"Products","description":"Product listing and details endpoints"},{"name":"Authentication","description":"User authentication endpoints (login, OTP, token refresh)"},{"name":"Users","description":"User profile and management endpoints"}],"security":[{"apiKeyAuth":[]},{"apiKeyAuth":[]},{"apiKeyAuth":[]},{"apiKeyAuth":[]},{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API Key for authentication. Can be provided as `x-api-key` or `X-API-KEY` header.\nContact your administrator to obtain an API key.\n\n**Note:** If your API key has IP whitelisting enabled, you must also include the `x-forwarded-for` header\nwith your client's IP address for the request to be allowed.\n"},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token for user authentication. Required for user-specific operations (orders, payments, profile).\nObtain this token by logging in via `/external/users/login` or `/external/users/verify-otp`.\n\n**Format:** `Authorization: Bearer <token>`\n"}},"parameters":{"XForwardedFor":{"name":"x-forwarded-for","in":"header","required":false,"schema":{"type":"string"},"description":"Client IP address. Required if your API key has IP whitelisting enabled.\nCan be provided as `x-forwarded-for` or `X-FORWARDED-FOR` header.\nThis header is used to validate that requests are coming from allowed IP addresses.\nExample: `x-forwarded-for: 192.168.1.100`\n"}},"schemas":{"CreateOrderRequest":{"type":"object","description":"Request body schema for creating an order via POST /external/orders","required":["orderItems","paymentMethod","shippingAddress","totalPrice"],"properties":{"userId":{"type":"string","description":"User ID (optional if provided in query params)"},"phone":{"type":"string","description":"User phone number (optional if userId provided)"},"orderItems":{"type":"array","items":{"type":"object","required":["product","qty"],"properties":{"product":{"type":"string","description":"Product ID"},"qty":{"type":"integer","minimum":1,"description":"Quantity"},"price":{"type":"number","description":"Product price"},"name":{"type":"string","description":"Product name"},"image":{"type":"string","description":"Product image URL"}}},"description":"Array of order items"},"shippingAddress":{"type":"object","required":["name","phone","address","city","pinCode"],"properties":{"name":{"type":"string","description":"Recipient name"},"phone":{"type":"string","description":"Recipient phone number"},"address":{"type":"string","description":"Street address"},"city":{"type":"string","description":"City"},"pinCode":{"type":"string","description":"Pincode"},"country":{"type":"string","default":"India","description":"Country"}}},"paymentMethod":{"type":"string","enum":["Razorpay","Wallet","Cash","Card"],"description":"Payment method"},"taxPrice":{"type":"number","default":0,"description":"Tax amount"},"shippingPrice":{"type":"number","default":0,"description":"Shipping charges"},"totalPrice":{"type":"number","description":"Total order amount"},"orderType":{"type":"string","enum":["online","offline"],"default":"online","description":"Order type"}}},"CreateOrderShipmentsRequest":{"type":"object","description":"Request body schema for creating an order with shipments via POST /external/orders/shipments","required":["shipments","paymentMethod","totalPrice"],"properties":{"userId":{"type":"string","description":"User ID (optional if provided in query params)"},"phone":{"type":"string","description":"User phone number (optional if userId provided)"},"shipments":{"type":"array","items":{"type":"object","required":["orderItems","shippingAddress"],"properties":{"orderItems":{"type":"array","items":{"type":"object","required":["product","qty"],"properties":{"product":{"type":"string","description":"Product ID"},"qty":{"type":"integer","minimum":1,"description":"Quantity"},"price":{"type":"number","description":"Product price"},"name":{"type":"string","description":"Product name"},"image":{"type":"string","description":"Product image URL"}}}},"shippingAddress":{"type":"object","required":["name","phone","address","city","pinCode"],"properties":{"name":{"type":"string","description":"Recipient name"},"phone":{"type":"string","description":"Recipient phone number"},"address":{"type":"string","description":"Street address"},"city":{"type":"string","description":"City"},"pinCode":{"type":"string","description":"Pincode"},"country":{"type":"string","default":"India","description":"Country"}}}}}},"paymentMethod":{"type":"string","enum":["Razorpay","Wallet","Cash","Card"],"description":"Payment method"},"taxPrice":{"type":"number","default":0,"description":"Tax amount"},"shippingPrice":{"type":"number","default":0,"description":"Shipping charges"},"totalPrice":{"type":"number","description":"Total order amount"},"orderType":{"type":"string","enum":["online","offline"],"default":"online","description":"Order type"}}},"AuthResponse":{"type":"object","description":"Response schema for authentication endpoints (login, verify-otp, refresh)","properties":{"success":{"type":"boolean","default":true},"_id":{"type":"string","description":"User ID"},"name":{"type":"string","description":"User name"},"email":{"type":"string","format":"email","description":"User email"},"phone":{"type":"string","description":"User phone number"},"role":{"type":"string","description":"User role"},"address":{"type":"string","description":"User address"},"city":{"type":"string","description":"City"},"state":{"type":"string","description":"State"},"pinCode":{"type":"string","description":"Pincode"},"company":{"type":"string","description":"Company name"},"companyId":{"type":"string","description":"Company ID (internal reference)"},"store":{"type":"string","description":"Store ID (internal reference)"},"marketplaces":{"type":"array","items":{"type":"string"},"description":"Array of marketplace IDs (internal references)"},"rewardPoints":{"type":"number","description":"Total reward points"},"token":{"type":"string","description":"Bearer access token (deprecated, use accessToken). **Sensitive: Store securely, never log or expose.**"},"accessToken":{"type":"string","description":"Bearer access token for authentication. **Sensitive: Store securely, never log or expose.**"},"refreshToken":{"type":"string","description":"Refresh token for token renewal. **Sensitive: Store securely, never log or expose.**"},"tokenType":{"type":"string","default":"Bearer","description":"Token type"},"expiresIn":{"type":"number","description":"Access token expiration time in seconds"},"refreshExpiresIn":{"type":"number","description":"Refresh token expiration time in seconds"},"accessTokenExpiresAt":{"type":"string","format":"date-time","description":"Access token expiration timestamp"},"refreshTokenExpiresAt":{"type":"string","format":"date-time","description":"Refresh token expiration timestamp"},"sessionId":{"type":"string","description":"Session ID"},"issuedAt":{"type":"string","format":"date-time","description":"Token issuance timestamp"}}},"UserProfile":{"type":"object","description":"Response schema for GET /external/users/profile endpoint","properties":{"_id":{"type":"string","description":"User ID"},"name":{"type":"string","description":"User name"},"email":{"type":"string","format":"email","description":"User email"},"phone":{"type":"string","description":"User phone number"},"role":{"type":"string","description":"User role"},"address":{"type":"string","description":"User address"},"city":{"type":"string","description":"City"},"state":{"type":"string","description":"State"},"pinCode":{"type":"string","description":"Pincode"},"company":{"type":"string","description":"Company name"},"companyId":{"type":"string","description":"Company ID (internal reference)"},"store":{"type":"string","description":"Store ID (internal reference)"},"marketplaces":{"type":"array","items":{"type":"string"},"description":"Array of marketplace IDs (internal references)"},"rewardPoints":{"type":"number","description":"Total reward points"}}},"ProductResponse":{"type":"object","description":"Simplified product response schema (does not expose internal database structure)","properties":{"_id":{"type":"string","description":"Product ID"},"name":{"type":"string","description":"Product name"},"description":{"type":"string","description":"Product description"},"price":{"type":"number","description":"Product price"},"mrp":{"type":"number","description":"Maximum retail price"},"images":{"type":"array","items":{"type":"string"},"description":"Product images"},"category":{"type":"string","description":"Product category"},"subCategory":{"type":"string","description":"Product subcategory"},"brand":{"type":"string","description":"Product brand"},"countInStock":{"type":"number","description":"Stock availability"},"rating":{"type":"number","description":"Product rating"},"numReviews":{"type":"number","description":"Number of reviews"}}},"CartItemResponse":{"type":"object","description":"Simplified cart item response schema","properties":{"_id":{"type":"string","description":"Cart item ID"},"name":{"type":"string","description":"Product name"},"qty":{"type":"integer","description":"Quantity"},"image":{"type":"string","description":"Product image URL"},"price":{"type":"number","description":"Product price"},"mrp":{"type":"number","description":"Maximum retail price"},"category":{"type":"string","description":"Product category"},"product":{"type":"string","description":"Product ID"}}},"OrderResponse":{"type":"object","description":"Simplified order response schema (does not expose internal database structure)","properties":{"_id":{"type":"string","description":"Order ID"},"orderItems":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Product name"},"qty":{"type":"integer","description":"Quantity"},"image":{"type":"string","description":"Product image URL"},"price":{"type":"number","description":"Product price"},"mrp":{"type":"number","description":"Maximum retail price"},"product":{"type":"string","description":"Product ID"}}}},"shippingAddress":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"address":{"type":"string"},"city":{"type":"string"},"pinCode":{"type":"string"},"country":{"type":"string"}}},"paymentMethod":{"type":"string","enum":["Razorpay","Wallet","Cash","Card"],"description":"Payment method"},"taxPrice":{"type":"number","description":"Tax amount"},"shippingPrice":{"type":"number","description":"Shipping charges"},"totalPrice":{"type":"number","description":"Total order amount"},"isPaid":{"type":"boolean","description":"Whether order is paid"},"isDelivered":{"type":"boolean","description":"Whether order is delivered"},"status":{"type":"string","enum":["processing","shipped","delivered","cancelled","returned"],"description":"Order status"},"orderType":{"type":"string","enum":["online","offline"],"description":"Order type"},"createdAt":{"type":"string","format":"date-time","description":"Order creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Order update timestamp"}}},"Error":{"type":"object","description":"Error response schema used by all external endpoints","properties":{"success":{"type":"boolean","default":false},"message":{"type":"string"},"errorType":{"type":"string"},"statusCode":{"type":"integer"},"timestamp":{"type":"string","format":"date-time"},"path":{"type":"string"}}}}},"paths":{"/external/cart":{"post":{"summary":"Add items to cart","description":"Add or update cart items. Requires user context (userId or phone in body/query).","tags":["Cart"],"security":[{"apiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XForwardedFor"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cartItems"],"properties":{"userId":{"type":"string","description":"User ID (optional if provided in query params)"},"phone":{"type":"string","description":"User phone number (optional if userId provided)"},"cartItems":{"type":"array","items":{"type":"object","required":["product","qty"],"properties":{"product":{"type":"string","description":"Product ID"},"qty":{"type":"integer","minimum":1,"description":"Quantity"},"price":{"type":"number","description":"Product price (optional)"},"name":{"type":"string","description":"Product name (optional)"},"image":{"type":"string","description":"Product image URL (optional)"}}}}}}}}},"responses":{"200":{"description":"Cart items added successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"Get cart items","description":"Retrieve all items in the user's cart. Requires user context (userId or phone in query params).","tags":["Cart"],"security":[{"apiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XForwardedFor"},{"in":"query","name":"userId","schema":{"type":"string"},"description":"User ID"},{"in":"query","name":"phone","schema":{"type":"string"},"description":"User phone number"}],"responses":{"200":{"description":"Cart items retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"cartItems":{"type":"array","items":{"$ref":"#/components/schemas/CartItemResponse"}}}}}},"401":{"description":"Not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Cart not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/external/cart/{cartItemId}":{"delete":{"summary":"Delete cart item","description":"Remove a specific item from the cart by cartItemId.","tags":["Cart"],"security":[{"apiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XForwardedFor"},{"in":"path","name":"cartItemId","required":true,"schema":{"type":"string"},"description":"Cart item ID to delete"},{"in":"query","name":"userId","schema":{"type":"string"},"description":"User ID"},{"in":"query","name":"phone","schema":{"type":"string"},"description":"User phone number"}],"responses":{"200":{"description":"Cart item deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"401":{"description":"Not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Cart item not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/external/cart/{cartItemId}/update":{"put":{"summary":"Update cart item","description":"Update quantity or other properties of a specific cart item.","tags":["Cart"],"security":[{"apiKeyAuth":[]}],"parameters":[{"in":"path","name":"cartItemId","required":true,"schema":{"type":"string"},"description":"Cart item ID to update"},{"in":"query","name":"userId","schema":{"type":"string"},"description":"User ID"},{"in":"query","name":"phone","schema":{"type":"string"},"description":"User phone number"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"qty":{"type":"integer","minimum":1,"description":"Updated quantity"}}}}}},"responses":{"200":{"description":"Cart item updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Cart item not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/external/orders":{"post":{"summary":"Create a new order","description":"Create a new order with the provided order items.\n\n**Authentication:** Requires BOTH API key AND Bearer token (user must be logged in).\nThe order will be associated with the authenticated user from the Bearer token.\n","tags":["Orders"],"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XForwardedFor"},{"in":"header","name":"Authorization","required":true,"schema":{"type":"string"},"description":"Bearer token (e.g., \"Bearer <token>\")"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderRequest"}}}},"responses":{"201":{"description":"Order created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/external/orders/shipments":{"post":{"summary":"Create order with shipments","description":"Create an order with multiple shipments.\n\n**Authentication:** Requires BOTH API key AND Bearer token (user must be logged in).\nThe order will be associated with the authenticated user from the Bearer token.\n","tags":["Orders"],"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XForwardedFor"},{"in":"header","name":"Authorization","required":true,"schema":{"type":"string"},"description":"Bearer token (e.g., \"Bearer <token>\")"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderShipmentsRequest"}}}},"responses":{"201":{"description":"Order with shipments created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/external/orders/{id}":{"get":{"summary":"Get order by ID","description":"Retrieve detailed information about a specific order by its ID.\n\n**Authentication:** Requires BOTH API key AND Bearer token.\nUsers can only view their own orders.\n","tags":["Orders"],"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XForwardedFor"},{"in":"header","name":"Authorization","required":true,"schema":{"type":"string"},"description":"Bearer token (e.g., \"Bearer <token>\")"},{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Order ID"}],"responses":{"200":{"description":"Order details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"401":{"description":"Not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/external/orders/history":{"get":{"summary":"Get order history for logged-in user","description":"Retrieve order history for the authenticated user (determined from Bearer token).\n\n**Authentication:** Requires BOTH API key AND Bearer token.\nReturns orders for the user authenticated via Bearer token.\n","tags":["Orders"],"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XForwardedFor"},{"in":"header","name":"Authorization","required":true,"schema":{"type":"string"},"description":"Bearer token (e.g., \"Bearer <token>\")"},{"in":"query","name":"page","schema":{"type":"integer","default":1},"description":"Page number for pagination"},{"in":"query","name":"limit","schema":{"type":"integer","default":10},"description":"Number of orders per page"}],"responses":{"200":{"description":"List of orders for the authenticated user","content":{"application/json":{"schema":{"type":"object","properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/OrderResponse"}},"page":{"type":"integer"},"pages":{"type":"integer"},"total":{"type":"integer"}}}}}},"401":{"description":"API key or Bearer token required/invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/external/orders/user/{userId}/history":{"get":{"summary":"Get order history for a user (legacy)","description":"Legacy endpoint for backward compatibility. Retrieve order history for a specific user by user ID.\n\n**Authentication:** Requires BOTH API key AND Bearer token.\n**Note:** The userId in the path must match the authenticated user from the Bearer token.\n","tags":["Orders"],"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XForwardedFor"},{"in":"header","name":"Authorization","required":true,"schema":{"type":"string"},"description":"Bearer token (e.g., \"Bearer <token>\")"},{"in":"path","name":"userId","required":true,"schema":{"type":"string"},"description":"User ID"}],"responses":{"200":{"description":"List of orders for the user","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OrderResponse"}}}}},"401":{"description":"Not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/external/payments/create-order":{"post":{"summary":"Create payment order","description":"Create a Razorpay payment order for an existing order.\n\n**Authentication:** Requires BOTH API key AND Bearer token (user must be logged in).\n","tags":["Payments"],"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XForwardedFor"},{"in":"header","name":"Authorization","required":true,"schema":{"type":"string"},"description":"Bearer token (e.g., \"Bearer <token>\")"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["orderId","amount"],"properties":{"orderId":{"type":"string","description":"Order ID to create payment for"},"amount":{"type":"number","description":"Payment amount"},"currency":{"type":"string","default":"INR","description":"Currency code"}}}}}},"responses":{"200":{"description":"Payment order created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"razorpayOrderId":{"type":"string"}}}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/external/payments/marketplace/{marketplaceId}/create-order":{"post":{"summary":"Create payment order for marketplace","description":"Create a Razorpay payment order for a marketplace-specific order.\n\n**Authentication:** Requires BOTH API key AND Bearer token (user must be logged in).\n","tags":["Payments"],"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XForwardedFor"},{"in":"header","name":"Authorization","required":true,"schema":{"type":"string"},"description":"Bearer token (e.g., \"Bearer <token>\")"},{"in":"path","name":"marketplaceId","required":true,"schema":{"type":"string"},"description":"Marketplace ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["orderId","amount"],"properties":{"orderId":{"type":"string","description":"Order ID to create payment for"},"amount":{"type":"number","description":"Payment amount"},"currency":{"type":"string","default":"INR","description":"Currency code"}}}}}},"responses":{"200":{"description":"Payment order created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"razorpayOrderId":{"type":"string"}}}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/external/payments/get-razorpay-key":{"get":{"summary":"Get Razorpay public key","description":"Retrieve the Razorpay public key for a store.\n\n**Authentication:** Requires BOTH API key AND Bearer token (user must be logged in).\n","tags":["Payments"],"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XForwardedFor"},{"in":"header","name":"Authorization","required":true,"schema":{"type":"string"},"description":"Bearer token (e.g., \"Bearer <token>\")"},{"in":"query","name":"storeId","required":true,"schema":{"type":"string"},"description":"Store ID"}],"responses":{"200":{"description":"Razorpay key retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","description":"Razorpay public key"}}}}}},"400":{"description":"Invalid input - Store ID required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Store not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/external/payments/marketplace/{marketplaceId}/get-razorpay-key":{"get":{"summary":"Get Razorpay public key for marketplace","description":"Retrieve the Razorpay public key for a marketplace.\n\n**Authentication:** Requires BOTH API key AND Bearer token (user must be logged in).\n","tags":["Payments"],"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XForwardedFor"},{"in":"header","name":"Authorization","required":true,"schema":{"type":"string"},"description":"Bearer token (e.g., \"Bearer <token>\")"},{"in":"path","name":"marketplaceId","required":true,"schema":{"type":"string"},"description":"Marketplace ID"}],"responses":{"200":{"description":"Razorpay key retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","description":"Razorpay public key"}}}}}},"400":{"description":"Invalid input - Marketplace ID required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Marketplace not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/external/payments/pay-order":{"post":{"summary":"Process payment for order","description":"Process and verify a payment for an order (typically called as a webhook/callback from Razorpay).","tags":["Payments"],"security":[{"apiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XForwardedFor"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["orderId","paymentId","signature"],"properties":{"orderId":{"type":"string","description":"Order ID"},"paymentId":{"type":"string","description":"Razorpay payment ID"},"signature":{"type":"string","format":"password","description":"Razorpay payment signature for verification. **Sensitive: Used only for verification, never log or store.**"}}}}}},"responses":{"200":{"description":"Payment processed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"order":{"$ref":"#/components/schemas/OrderResponse"}}}}}},"400":{"description":"Invalid payment data or signature verification failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/external/payments/pay-order-wallet":{"post":{"summary":"Pay order using wallet","description":"Process payment for an order using the user's wallet balance.\n\n**Authentication:** Requires BOTH API key AND Bearer token (user must be logged in).\n","tags":["Payments"],"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XForwardedFor"},{"in":"header","name":"Authorization","required":true,"schema":{"type":"string"},"description":"Bearer token (e.g., \"Bearer <token>\")"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["orderId"],"properties":{"orderId":{"type":"string","description":"Order ID to pay for"}}}}}},"responses":{"200":{"description":"Payment processed successfully using wallet","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"order":{"$ref":"#/components/schemas/OrderResponse"}}}}}},"400":{"description":"Insufficient wallet balance or invalid order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/external/products":{"get":{"summary":"Get list of published products","description":"Retrieve a paginated list of published products with optional filtering by keyword, price range, and pagination.","tags":["Products"],"security":[{"apiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XForwardedFor"},{"in":"query","name":"keyword","schema":{"type":"string"},"description":"Search keyword for product name or description"},{"in":"query","name":"price","schema":{"type":"number"},"description":"Price filter (upper limit)"},{"in":"query","name":"pageNumber","schema":{"type":"integer","default":1},"description":"Page number for pagination"},{"in":"query","name":"pageSize","schema":{"type":"integer","default":60},"description":"Number of products per page"}],"responses":{"200":{"description":"List of published products","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/ProductResponse"}},"page":{"type":"integer"},"pages":{"type":"integer"},"total":{"type":"integer"}}}}}},"401":{"description":"Not authorized - API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/external/products/store/{storeId}":{"get":{"summary":"Get published products for a specific store","description":"Retrieve published products filtered by store ID.","tags":["Products"],"security":[{"apiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XForwardedFor"},{"in":"path","name":"storeId","required":true,"schema":{"type":"string"},"description":"Store ID"}],"responses":{"200":{"description":"List of published products for the store","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProductResponse"}}}}},"401":{"description":"Not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Store not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/external/products/{id}":{"get":{"summary":"Get product by ID","description":"Retrieve detailed information about a specific product by its ID.","tags":["Products"],"security":[{"apiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XForwardedFor"},{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Product ID"}],"responses":{"200":{"description":"Product details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductResponse"}}}},"401":{"description":"Not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/external/users/login":{"post":{"summary":"User login (password-based)","description":"Authenticate a user using email/phone and password. Returns Bearer token for subsequent API calls.\n\n**Note:** This endpoint reuses the same logic as `/api/users/login` but requires API key authentication.\n","tags":["Authentication"],"security":[{"apiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XForwardedFor"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["password"],"properties":{"email":{"type":"string","description":"User email address"},"phone":{"type":"string","description":"User phone number"},"identifier":{"type":"string","description":"Email or phone identifier"},"login":{"type":"string","description":"Email or phone identifier"},"username":{"type":"string","description":"Username"},"password":{"type":"string","format":"password","description":"User password"}}}}}},"responses":{"200":{"description":"Login successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"400":{"description":"Invalid input - email/phone and password required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid credentials or API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/external/users/send-otp":{"post":{"summary":"Send OTP to user's phone","description":"Send a one-time password (OTP) to the user's phone number for OTP-based login.\nThe OTP is valid for 10 minutes.\n","tags":["Authentication"],"security":[{"apiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XForwardedFor"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string","description":"User phone number"}}}}}},"responses":{"200":{"description":"OTP sent successfully (or user not found - security best practice)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"deliveredVia":{"type":"string","enum":["sms","development"],"description":"How OTP was delivered"},"otp":{"type":"string","description":"OTP code (only in development mode)"}}}}}},"400":{"description":"Invalid input - phone number required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/external/users/verify-otp":{"post":{"summary":"Verify OTP and login","description":"Verify the OTP sent to the user's phone and complete login. Returns Bearer token for subsequent API calls.\n","tags":["Authentication"],"security":[{"apiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XForwardedFor"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone","otp"],"properties":{"phone":{"type":"string","description":"User phone number"},"otp":{"type":"string","description":"OTP code received via SMS"}}}}}},"responses":{"200":{"description":"OTP verified and login successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"400":{"description":"Invalid input - phone and OTP required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired OTP, or API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/external/users/refresh":{"post":{"summary":"Refresh access token","description":"Refresh the access token using a valid refresh token. Returns a new access token and refresh token.\n","tags":["Authentication"],"security":[{"apiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XForwardedFor"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["refreshToken"],"properties":{"refreshToken":{"type":"string","description":"Valid refresh token"}}}}}},"responses":{"200":{"description":"Token refreshed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"Invalid or expired refresh token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/external/users/profile":{"get":{"summary":"Get user profile","description":"Get the authenticated user's profile information. Requires both API key AND Bearer token.\n","tags":["Users"],"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XForwardedFor"},{"in":"header","name":"Authorization","required":true,"schema":{"type":"string"},"description":"Bearer token (e.g., \"Bearer <token>\")"}],"responses":{"200":{"description":"User profile retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserProfile"}}}},"401":{"description":"API key or Bearer token required/invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}