Saltar al contenido principal

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 Productos), 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/eliminar 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. Crear estado en el panel de administración
   (por ejemplo, "Nueva Llegada")
   ↓
2. Asignar estado a productos
   (Seleccionar productos en el administrador)
   ↓
3. Obtener estados a través del SDK
   (ProductStatuses.getProductStatuses())
   ↓
4. Mostrar etiquetas de estado en productos
   (Renderizar etiquetas en listados de productos)
   ↓
5. Filtrar productos por estado
   (Products.getProducts({ statusId }))

¿Por qué usar el módulo ProductStatuses?​

BeneficioDescripción
Filtrado FlexibleFiltrar productos por múltiples criterios personalizados
Etiquetas DinámicasMostrar etiquetas visuales sin codificación dura
Fácil GestiónAñadir/eliminar estados en el panel de administración
Etiquetas ReutilizablesAplicar el mismo estado a muchos productos
Multi-IdiomaNombres de estado localizados por idioma
Estilo PersonalizadoDefinir 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:

Panel de Administración de OneEntry → Catálogo → Estados de Productos → Crear Estado → Establecer Nombre/Marcador → Guardar

Proceso de Creación:

  • Proporcionar un Nombre - Designación del estado (requerido)
  • Proporcionar un Marcador - Identificador único (requerido, solo letras/números latinos/'_'/'-' )
  • Hacer 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 Estados​

Los estados se asignan a productos en el panel de administración:

Panel de Administración de OneEntry → Productos → Editar Producto → Asignar Estados → Guardar

En el 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] - IDs de Estado

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 edición y eliminación, además de reordenamiento por arrastrar y soltar

Validación del 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 de producto:

CaracterísticaProductStatusesAtributos
PropósitoEtiquetas/insignias/filtrosPropiedades del producto
Ejemplos"Nuevo", "En Oferta", "Destacado"Color, Tamaño, Material
Valores múltiplesSí (múltiples estados)Sí (múltiples atributos)
FiltradoSimple (por ID de estado)Complejo (rangos, valores)
Caso de usoEtiquetas de marketingEspecificaciones del producto

Mejor práctica: Usa estados para etiquetas de marketing, atributos para propiedades del producto.

📊 Tabla de Referencia Rápida​

MétodoDescripciónCaso de Uso
getProductStatuses()Obtener todos los estados de productoListar todos los estados disponibles
getProductsByStatusMarker()Obtener estado de producto por marcadorObtener estado por identificador
validateMarker()Verificar si el marcador existeValidar 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, En 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 o marcador de estado 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 etiquetas 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 etiquetas de producto basadas en el array statusIds del producto.

🎓 Mejores Prácticas​

  • Usa marcadores descriptivos - nueva_llegada, no estado1
  • Define colores de manera consistente - Usa la paleta de colores de la marca
  • Limita los estados activos - No abrumes a los usuarios con demasiadas etiquetas
  • Mantén los nombres de estado cortos - "En 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 etiquetas 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 habilita 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(
  "tu-url-de-proyecto", {
    "token": "tu-token-de-aplicación"
  }
);

🔗 Documentación Relacionada​