{"openapi":"3.0.3","info":{"title":"iNeed Mobile API","description":"API móvil para la plataforma iNeed - Marketplace multi-tienda","version":"1.0.0","contact":{"name":"iNeed Support","email":"soporte@ineed.market"}},"servers":[{"url":"https://ineed.market","description":"Servidor de producción"},{"url":"http://localhost:3000","description":"Servidor de desarrollo"}],"tags":[{"name":"Auth","description":"Autenticación y registro"},{"name":"Profile","description":"Perfil de usuario"},{"name":"Products","description":"Catálogo de productos"},{"name":"Cart","description":"Carrito de compras"},{"name":"Orders","description":"Historial de pedidos"},{"name":"Favorites","description":"Favoritos y wishlist"},{"name":"Addresses","description":"Direcciones de entrega"},{"name":"Search","description":"Búsqueda avanzada"},{"name":"Notifications","description":"Notificaciones push"},{"name":"Reviews","description":"Reseñas y valoraciones"},{"name":"Chat","description":"Chat en tiempo real"},{"name":"Location","description":"Geolocalización"},{"name":"Share","description":"Compartir social"},{"name":"Coupons","description":"Cupones y descuentos"},{"name":"Loyalty","description":"Programa de lealtad"},{"name":"Stats","description":"Estadísticas del usuario"},{"name":"Payments","description":"Pagos y transacciones"},{"name":"Support","description":"Soporte al cliente"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"SessionAuth":{"type":"apiKey","in":"cookie","name":"next-auth.session-token"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"User":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"phone":{"type":"string"},"image":{"type":"string"},"role":{"type":"string","enum":["cliente","tienda","transporte","repartidor","admin"]},"countryCode":{"type":"string"},"referralCode":{"type":"string"}}},"Product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"price":{"type":"number"},"images":{"type":"array","items":{"type":"string"}},"stock":{"type":"integer"},"category":{"type":"string"},"store":{"$ref":"#/components/schemas/Store"}}},"Store":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"image":{"type":"string"},"address":{"type":"string"},"type":{"type":"string"},"avgRating":{"type":"number"},"reviewCount":{"type":"integer"}}},"Order":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"total":{"type":"number"},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderItem"}},"createdAt":{"type":"string","format":"date-time"}}},"OrderItem":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string"},"price":{"type":"number"},"quantity":{"type":"integer"}}},"Review":{"type":"object","properties":{"id":{"type":"string"},"rating":{"type":"integer","minimum":1,"maximum":5},"comment":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"user":{"$ref":"#/components/schemas/User"}}},"Coupon":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["porcentaje","fijo"]},"value":{"type":"number"},"minPurchase":{"type":"number"},"maxDiscount":{"type":"number"},"expiresAt":{"type":"string","format":"date-time"}}},"LoyaltyPoints":{"type":"object","properties":{"current":{"type":"integer"},"total":{"type":"integer"},"redeemed":{"type":"integer"},"level":{"type":"string","enum":["bronce","plata","oro","platino","diamante"]}}},"LoyaltyReward":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"type":{"type":"string"},"pointsCost":{"type":"integer"},"value":{"type":"number"},"minLevel":{"type":"string"}}},"Address":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"address":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"isDefault":{"type":"boolean"}}},"Conversation":{"type":"object","properties":{"id":{"type":"string"},"customerId":{"type":"string"},"providerId":{"type":"string"},"unreadCount":{"type":"integer"},"lastMessage":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"}}},"Message":{"type":"object","properties":{"id":{"type":"string"},"message":{"type":"string"},"senderId":{"type":"string"},"isRead":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}}}},"paths":{"/api/mobile/auth/login":{"post":{"tags":["Auth"],"summary":"Iniciar sesión","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":6}}}}}},"responses":{"200":{"description":"Login exitoso"},"401":{"description":"Credenciales inválidas"}}}},"/api/mobile/auth/register":{"post":{"tags":["Auth"],"summary":"Registrar nuevo usuario","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password","name"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":6},"name":{"type":"string"},"phone":{"type":"string"},"referralCode":{"type":"string"}}}}}},"responses":{"201":{"description":"Usuario creado"},"400":{"description":"Datos inválidos"}}}},"/api/mobile/auth/logout":{"post":{"tags":["Auth"],"summary":"Cerrar sesión","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Sesión cerrada"}}}},"/api/mobile/profile":{"get":{"tags":["Profile"],"summary":"Obtener perfil del usuario","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Perfil del usuario","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}}}},"put":{"tags":["Profile"],"summary":"Actualizar perfil","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"image":{"type":"string"}}}}}},"responses":{"200":{"description":"Perfil actualizado"}}}},"/api/mobile/addresses":{"get":{"tags":["Addresses"],"summary":"Listar direcciones del usuario","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Lista de direcciones","content":{"application/json":{"schema":{"type":"object","properties":{"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}}}}}}}}},"post":{"tags":["Addresses"],"summary":"Agregar dirección","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Address"}}}},"responses":{"201":{"description":"Dirección creada"}}}},"/api/mobile/orders":{"get":{"tags":["Orders"],"summary":"Historial de pedidos","security":[{"BearerAuth":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"status","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Lista de pedidos","content":{"application/json":{"schema":{"type":"object","properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}}},"/api/mobile/favorites":{"get":{"tags":["Favorites"],"summary":"Listar favoritos","security":[{"BearerAuth":[]}],"parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["stores","services","products"]}}],"responses":{"200":{"description":"Lista de favoritos"}}},"post":{"tags":["Favorites"],"summary":"Agregar a favoritos","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","targetId"],"properties":{"type":{"type":"string","enum":["store","service","product"]},"targetId":{"type":"string"}}}}}},"responses":{"200":{"description":"Agregado a favoritos"}}}},"/api/mobile/search":{"get":{"tags":["Search"],"summary":"Búsqueda avanzada","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string","enum":["all","products","stores","services"]}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"minPrice","in":"query","schema":{"type":"number"}},{"name":"maxPrice","in":"query","schema":{"type":"number"}},{"name":"lat","in":"query","schema":{"type":"number"}},{"name":"lng","in":"query","schema":{"type":"number"}},{"name":"radius","in":"query","schema":{"type":"number"}},{"name":"sort","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Resultados de búsqueda"}}}},"/api/mobile/reviews":{"get":{"tags":["Reviews"],"summary":"Listar reseñas","security":[{"BearerAuth":[]}],"parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["product","store","rider"]}},{"name":"targetId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Lista de reseñas"}}},"post":{"tags":["Reviews"],"summary":"Crear reseña","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","targetId","orderId","rating"],"properties":{"type":{"type":"string","enum":["product","store","rider"]},"targetId":{"type":"string"},"orderId":{"type":"string"},"rating":{"type":"integer","minimum":1,"maximum":5},"comment":{"type":"string"}}}}}},"responses":{"200":{"description":"Reseña creada"}}}},"/api/mobile/reviews/pending":{"get":{"tags":["Reviews"],"summary":"Pedidos pendientes de reseña","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Lista de pedidos pendientes"}}}},"/api/mobile/chat":{"get":{"tags":["Chat"],"summary":"Listar conversaciones","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Lista de conversaciones","content":{"application/json":{"schema":{"type":"object","properties":{"conversations":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}}}}}}}}},"post":{"tags":["Chat"],"summary":"Crear conversación","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["providerId"],"properties":{"providerId":{"type":"string"},"initialMessage":{"type":"string"}}}}}},"responses":{"201":{"description":"Conversación creada"}}}},"/api/mobile/chat/{conversationId}":{"get":{"tags":["Chat"],"summary":"Obtener mensajes de conversación","security":[{"BearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Mensajes de la conversación","content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}},"post":{"tags":["Chat"],"summary":"Enviar mensaje","security":[{"BearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string"},"attachmentUrl":{"type":"string"}}}}}},"responses":{"200":{"description":"Mensaje enviado"}}}},"/api/mobile/chat/unread":{"get":{"tags":["Chat"],"summary":"Contar mensajes no leídos","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Conteo de mensajes no leídos","content":{"application/json":{"schema":{"type":"object","properties":{"unreadCount":{"type":"integer"}}}}}}}}},"/api/mobile/location":{"get":{"tags":["Location"],"summary":"Obtener ubicación guardada","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Ubicación del usuario"}}},"post":{"tags":["Location"],"summary":"Guardar ubicación","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number"},"longitude":{"type":"number"},"accuracy":{"type":"number"},"heading":{"type":"number"},"speed":{"type":"number"}}}}}},"responses":{"200":{"description":"Ubicación guardada"}}}},"/api/mobile/location/nearby":{"get":{"tags":["Location"],"summary":"Buscar establecimientos cercanos","parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number"}},{"name":"lng","in":"query","required":true,"schema":{"type":"number"}},{"name":"radius","in":"query","schema":{"type":"number","default":10}},{"name":"type","in":"query","schema":{"type":"string","enum":["stores","services","transport","all"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Establecimientos cercanos"}}}},"/api/mobile/location/distance":{"get":{"tags":["Location"],"summary":"Calcular distancia entre puntos","parameters":[{"name":"fromLat","in":"query","required":true,"schema":{"type":"number"}},{"name":"fromLng","in":"query","required":true,"schema":{"type":"number"}},{"name":"toLat","in":"query","required":true,"schema":{"type":"number"}},{"name":"toLng","in":"query","required":true,"schema":{"type":"number"}},{"name":"mode","in":"query","schema":{"type":"string","enum":["walking","cycling","driving","motorcycle"]}}],"responses":{"200":{"description":"Distancia y tiempo estimado","content":{"application/json":{"schema":{"type":"object","properties":{"distance":{"type":"number"},"duration":{"type":"number"},"mode":{"type":"string"}}}}}}}}},"/api/mobile/share":{"post":{"tags":["Share"],"summary":"Generar enlace para compartir","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","targetId"],"properties":{"type":{"type":"string","enum":["product","store","service"]},"targetId":{"type":"string"}}}}}},"responses":{"200":{"description":"Enlaces para compartir","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"whatsapp":{"type":"string"},"facebook":{"type":"string"},"twitter":{"type":"string"}}}}}}}}},"/api/mobile/share/referral":{"get":{"tags":["Share"],"summary":"Obtener código de referido","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Información de referidos","content":{"application/json":{"schema":{"type":"object","properties":{"referralCode":{"type":"string"},"referralUrl":{"type":"string"},"referredCount":{"type":"integer"}}}}}}}}},"/api/mobile/coupons":{"get":{"tags":["Coupons"],"summary":"Listar cupones disponibles","security":[{"BearerAuth":[]}],"parameters":[{"name":"storeId","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Lista de cupones","content":{"application/json":{"schema":{"type":"object","properties":{"coupons":{"type":"array","items":{"$ref":"#/components/schemas/Coupon"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}}},"/api/mobile/coupons/validate":{"post":{"tags":["Coupons"],"summary":"Validar y calcular descuento de cupón","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"storeId":{"type":"string"},"subtotal":{"type":"number"}}}}}},"responses":{"200":{"description":"Resultado de validación","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"coupon":{"$ref":"#/components/schemas/Coupon"},"discount":{"type":"number"},"errors":{"type":"array","items":{"type":"string"}}}}}}}}}},"/api/mobile/coupons/history":{"get":{"tags":["Coupons"],"summary":"Historial de cupones usados","security":[{"BearerAuth":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Historial de cupones","content":{"application/json":{"schema":{"type":"object","properties":{"history":{"type":"array"},"stats":{"type":"object","properties":{"totalUsed":{"type":"integer"},"totalSaved":{"type":"number"}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}}},"/api/mobile/loyalty":{"get":{"tags":["Loyalty"],"summary":"Información del programa de lealtad","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Estado de lealtad del usuario","content":{"application/json":{"schema":{"type":"object","properties":{"points":{"$ref":"#/components/schemas/LoyaltyPoints"},"level":{"type":"object","properties":{"current":{"type":"string"},"next":{"type":"string"},"pointsToNext":{"type":"integer"},"progress":{"type":"integer"},"benefits":{"type":"array","items":{"type":"string"}}}},"recentActivity":{"type":"array"},"availableRewardsCount":{"type":"integer"}}}}}}}}},"/api/mobile/loyalty/history":{"get":{"tags":["Loyalty"],"summary":"Historial de transacciones de puntos","security":[{"BearerAuth":[]}],"parameters":[{"name":"type","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Historial de transacciones"}}}},"/api/mobile/loyalty/rewards":{"get":{"tags":["Loyalty"],"summary":"Recompensas disponibles","security":[{"BearerAuth":[]}],"parameters":[{"name":"type","in":"query","schema":{"type":"string"}},{"name":"affordable","in":"query","schema":{"type":"boolean"}},{"name":"page","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Lista de recompensas","content":{"application/json":{"schema":{"type":"object","properties":{"rewards":{"type":"array","items":{"$ref":"#/components/schemas/LoyaltyReward"}},"userInfo":{"type":"object","properties":{"currentPoints":{"type":"integer"},"level":{"type":"string"}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}}},"/api/mobile/loyalty/redeem":{"get":{"tags":["Loyalty"],"summary":"Listar canjes del usuario","security":[{"BearerAuth":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["activo","usado","expirado","all"]}},{"name":"page","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Lista de canjes"}}},"post":{"tags":["Loyalty"],"summary":"Canjear recompensa","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rewardId"],"properties":{"rewardId":{"type":"string"}}}}}},"responses":{"200":{"description":"Canje exitoso","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"redemption":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}},"newBalance":{"type":"integer"},"message":{"type":"string"}}}}}},"400":{"description":"Error de validación"}}}},"/api/mobile/stats":{"get":{"tags":["Stats"],"summary":"Estadísticas generales del usuario","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Estadísticas del usuario","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"object","properties":{"totalOrders":{"type":"integer"},"totalSpent":{"type":"number"},"avgOrderValue":{"type":"number"}}},"savings":{"type":"object"},"activity":{"type":"object"},"loyalty":{"type":"object"},"membership":{"type":"object"}}}}}}}}},"/api/mobile/stats/spending":{"get":{"tags":["Stats"],"summary":"Análisis de gastos","security":[{"BearerAuth":[]}],"parameters":[{"name":"period","in":"query","schema":{"type":"string","enum":["30days","3months","6months","1year"]}}],"responses":{"200":{"description":"Análisis de gastos","content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"string"},"summary":{"type":"object"},"timeSeries":{"type":"array"},"byStoreType":{"type":"array"},"topStores":{"type":"array"},"topCategories":{"type":"array"}}}}}}}}},"/api/mobile/stats/activity":{"get":{"tags":["Stats"],"summary":"Historial de actividad","security":[{"BearerAuth":[]}],"parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["order","review","booking","transport","coupon","loyalty"]}},{"name":"page","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Lista de actividad","content":{"application/json":{"schema":{"type":"object","properties":{"activities":{"type":"array"},"summary":{"type":"object"},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}}},"/api/mobile/notifications":{"get":{"tags":["Notifications"],"summary":"Listar notificaciones","security":[{"BearerAuth":[]}],"parameters":[{"name":"unreadOnly","in":"query","schema":{"type":"boolean"}},{"name":"page","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Lista de notificaciones"}}}},"/api/mobile/notifications/register":{"post":{"tags":["Notifications"],"summary":"Registrar token de dispositivo","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","platform"],"properties":{"token":{"type":"string"},"platform":{"type":"string","enum":["ios","android","web"]},"deviceId":{"type":"string"}}}}}},"responses":{"200":{"description":"Token registrado"}}}}}}