Introducción
🎯 ¿Qué hace este módulo?
El módulo ProductStatuses permite condiciones de filtrado adicionales para los elementos del catálogo junto con los filtros basados en atributos existentes. Product Statuses te permite crear etiquetas y filtros personalizados para productos, como "Nueva Llegada", "Más Vendido", "En Oferta", "Agotado", para organizar y filtrar productos en tu catálogo de comercio electrónico.
Los estados sirven como mecanismos de filtrado suplementarios para los elementos del catálogo, trabajando en conjunto con el filtrado basado en atributos para proporcionar opciones de organización y categorización más granulares para la gestión de productos.
Piénsalo como tu sistema de etiquetado de productos: defines las etiquetas de estado en el panel de administración de OneEntry (Catálogo > Estados de Producto), las asignas a los productos y las usas para filtrar, etiquetar y categorizar productos de manera dinámica.
📖 Explicación Simple
Cada tienda de comercio electrónico necesita resaltar productos especiales:
- 🆕 Nueva Llegada - Productos recién añadidos
- 🔥 Más Vendido - Artículos populares
- 💰 En Oferta - Productos con descuento
- ⭐ Destacado - Productos resaltados
- 📦 Agotado - Artículos no disponibles
- 🎁 Edición Limitada - Productos exclusivos
- 🚚 Envío Gratis - Productos con entrega gratuita
Problemas:
- 🔒 Inflexible - Necesita cambios de código para añadir nuevos estados
- 📊 Difícil de gestionar - Múltiples campos booleanos
- 🔄 Sin reutilización - No se puede reutilizar la lógica de estado
- 🎨 Inconsistente - Diferentes estilos de etiquetas en todas partes
La solución de ProductStatuses:
Beneficios:
- 🔒 Flexible - Añadir/quitar estados en el panel de administración
- 📊 Fácil de gestionar - Definiciones de estado centralizadas
- 🔄 Reutilizable - Mismo estado para muchos productos
- 🎨 Consistente - Renderizado uniforme de etiquetas
✨ Conceptos Clave
¿Qué es un Estado de Producto?
Un Estado de Producto es una etiqueta/etiqueta personalizada para productos:
- Nombre del Estado - Nombre a mostrar (por ejemplo, "Nueva Llegada", "En Oferta")
- Marcador de Estado - Identificador único para filtrado
- Color/Estilo - Representación visual (configurada en el administrador)
- Asociación de Producto - Qué productos tienen este estado
- Filtrado - Consultar productos por estado
Flujo de Trabajo del Estado de Producto
1. Create status in admin panel
(e.g., "New Arrival")
↓
2. Assign status to products
(Select products in admin)
↓
3. Fetch statuses via SDK
(ProductStatuses.getProductStatuses())
↓
4. Display status badges on products
(Render badges in product listings)
↓
5. Filter products by status
(Products.getProducts({ statusId }))
¿Por qué usar el módulo ProductStatuses?
| Beneficio | Descripción |
|---|---|
| Filtrado Flexible | Filtrar productos por múltiples criterios personalizados |
| Etiquetas Dinámicas | Mostrar etiquetas visuales sin codificación dura |
| Gestión Fácil | Añadir/quitar estados en el panel de administración |
| Etiquetas Reutilizables | Aplicar el mismo estado a muchos productos |
| Multi-Idioma | Nombres de estado localizados por idioma |
| Estilo Personalizado | Definir colores y estilos por estado |
📋 Lo Que Necesitas Saber
Los Estados de Producto se Crean en el Panel de Administración
No puedes crear estados a través del SDK - se crean en el panel de administración de OneEntry:
OneEntry Admin Panel → Catalog → Product Statuses → Create Status → Set Name/Marker → Save
Proceso de Creación:
- Proporcionar un Nombre - Designación del estado (requerido)
- Proporcionar un Marcador - Identificador único (requerido, solo letras/números latinos/'_'/'-' )
- Haz clic en "Crear" para finalizar
Restricciones del Marcador:
- Solo letras latinas (a-z, A-Z)
- Números (0-9)
- Símbolos de guion bajo (_) y guion (-)
- No se permiten caracteres especiales ni espacios
Gestión de Estados:
- Ver Lista - Tabla con columnas de Nombre, Marcador y Acciones
- Editar Estado - Modificar campos de Nombre y Marcador
- Eliminar Estado - Eliminar estados no utilizados
- Reordenar - Arrastrar y soltar para cambiar el orden de visualización (afecta el campo
sortOrder)
El SDK es para obtener estados y filtrar productos, no para crear estados.
Asignación de Estado
Los estados se asignan a los productos en el panel de administración:
OneEntry Admin Panel → Products → Edit Product → Assign Statuses → Save
En SDK: Los productos tienen un array statusIds con los IDs de estado asignados:
const product = await Products.getProductById(123);
console.log(product.statusIds); // [1, 2] - Status IDs
Filtrado por Estado
Usa el ID de estado para filtrar productos
Soporte Multi-Idioma
Los nombres de estado se localizan automáticamente
💡 Notas Importantes
Los Estados se Crean en el Panel de Administración
Recuerda: El SDK es para obtener estados, no para crearlos.
Para crear/editar estados: Usa el Panel de Administración de OneEntry.
Interfaz de Lista de Estados
El panel de administración muestra todos los estados en una tabla con tres columnas:
- Nombre - Designación del estado
- Marcador - Identificador único
- Acciones - Operaciones de editar y eliminar, además de reordenamiento por arrastrar y soltar
Validación de Marcador
Importante: El método validateMarker() ayuda a verificar si un marcador ya existe antes de crearlo/utilizarlo.
Restricciones del Marcador:
- Solo caracteres alfanuméricos latinos (a-z, A-Z, 0-9)
- Se permiten guiones bajos (_) y guiones (-)
- No se permiten espacios ni caracteres especiales
- Debe ser único entre todos los estados
Múltiples Estados por Producto
Los productos pueden tener múltiples estados simultáneamente (por ejemplo, "Nueva Llegada" + "En Oferta")
Estado vs Atributos
ProductStatuses son diferentes de los atributos del producto:
| Característica | ProductStatuses | Atributos |
|---|---|---|
| Propósito | Etiquetas/insignias/filtros | Propiedades del producto |
| Ejemplos | "Nuevo", "Oferta", "Destacado" | Color, Tamaño, Material |
| Valores múltiples | Sí (múltiples estados) | Sí (múltiples atributos) |
| Filtrado | Simple (por ID de estado) | Complejo (rangos, valores) |
| Caso de uso | Etiquetas de marketing | Especificaciones del producto |
Mejor práctica: Usa estados para etiquetas de marketing, atributos para propiedades del producto.
📊 Tabla de Referencia Rápida
| Método | Descripción | Caso de Uso |
|---|---|---|
| getProductStatuses() | Obtener todos los estados de producto | Listar todos los estados disponibles |
| getProductsByStatusMarker() | Obtener estado de producto por marcador | Obtener estado por identificador |
| validateMarker() | Verificar si el marcador existe | Validar marcador antes de usar |
❓ Preguntas Comunes (FAQ)
¿Cuál es la diferencia entre los estados de producto y los atributos de producto?
Los estados de producto son etiquetas de marketing (Nuevo, Oferta, Destacado) para filtrado y etiquetado, mientras que los atributos son especificaciones del producto (Color, Tamaño, Material). Usa estados para etiquetas promocionales y atributos para propiedades del producto.
¿Puede un producto tener múltiples estados a la vez?
¡Sí! Los productos pueden tener múltiples estados simultáneamente. Por ejemplo, un producto puede ser tanto "Nueva Llegada" como "En Oferta" al mismo tiempo. El array statusIds en el objeto del producto contiene todos los IDs de estado asignados.
¿Cómo filtro productos por estado?
Usa los métodos del módulo Products con filtros de estado. Pasa el ID de estado o marcador en tu consulta para obtener productos con estados específicos. También puedes combinar múltiples filtros de estado.
¿Cómo valido un marcador antes de crear un estado?
Usa el método validateMarker() para verificar si un marcador ya existe. Esto ayuda a prevenir marcadores duplicados y asegura que tu marcador siga las convenciones de nomenclatura (solo letras latinas, números, guiones bajos, guiones).
¿Puedo cambiar el orden de los estados mostrados?
¡Sí! En el panel de administración, puedes arrastrar y soltar estados para reordenarlos. Esto afecta el campo sortOrder y determina la prioridad de visualización en tu aplicación.
¿Cómo añado estilo personalizado a las insignias de estado?
Obtén todos los estados, crea un mapeo de marcadores de estado a clases CSS o estilos en línea en tu código frontend. Aplica estos estilos al renderizar las insignias de producto según el array statusIds del producto.
🎓 Mejores Prácticas
- Usa marcadores descriptivos -
nueva_llegada, noestado1 - Define colores de manera consistente - Usa la paleta de colores de la marca
- Limita los estados activos - No abrumes a los usuarios con demasiadas insignias
- Mantén los nombres de estado cortos - "Oferta" es mejor que "Productos en Oferta"
- Usa estado para filtrar - Haz que los estados sean filtrables en la interfaz de usuario
- Cachea los estados - Rara vez cambian, cachea para mejorar el rendimiento
- Muestra múltiples estados - Muestra todas las insignias relevantes en los productos
- Usa estado para ordenar - Ordena primero por estado "Destacado"
Más información sobre los estados de producto en el panel de administración de OneEntry: https://doc.oneentry.cloudhttps://doc.oneentry.cloud/docs/catalog/product-statuses/
Definición del módulo ProductStatuses
El módulo ProductStatuses gestiona estados que sirven como filtros adicionales junto con las condiciones definidas por atributos. Product Statuses permite condiciones de filtrado adicionales para los elementos del catálogo en la Plataforma OneEntry, trabajando en conjunto con el filtrado basado en atributos.
const { ProductStatuses } = defineOneEntry( "your-project-url", { "token": "your-app-token" });
🔗 Documentación Relacionada
- Panel de Administración de OneEntry - Estados de Producto - Documentación oficial del panel de administración
- Módulo de Productos - Gestionar productos con estados
- Módulo de Atributos - Atributos de producto vs estados
- Módulo de GeneralTypes - Tipos y categorías de productos
- Módulo de Locales - Nombres de estado en múltiples idiomas