Saltar al contenido principal

Introducción

Obtén etiquetas de estado de producto ("Nuevo", "En venta", "Agotado") para etiquetar y filtrar elementos del catálogo.

Más información sobre los estados de producto en el panel de administración de OneEntry: https://doc.oneentry.cloud/docs/category/catalog

🎯 ¿Qué hace este módulo?​

El módulo ProductStatuses proporciona condiciones de filtrado adicionales para los elementos del catálogo junto con filtros basados en atributos. Los estados de producto te permiten crear etiquetas personalizadas - como "Nueva llegada", "Más vendido", "En venta", "Agotado" - para etiquetar, organizar y filtrar productos en tu catálogo de comercio electrónico.

Definís las etiquetas de estado en el panel de administración de OneEntry (Catálogo > Estados de Producto), las asignas a los productos y usas este módulo para obtener los estados y filtrar productos por ellos. El SDK es de solo lectura: no puedes crear estados a través de él.

🚀 Inicio Rápido​

Inicializa el módulo desde defineOneEntry:


const { ProductStatuses } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Obtén todos los estados y lee sus campos:

// Fetch every product status, localized to English.
const statuses = await ProductStatuses.getProductStatuses("en_US");

statuses.forEach((status) => {
  console.log(status.identifier, status.localizeInfos.title, status.isDefault);
});

// Or fetch a single status by its marker.
const sale = await ProductStatuses.getProductsByStatusMarker("sale", "en_US");
console.log(sale.localizeInfos.title); // "Sale"

✨ Conceptos Clave​

¿Qué es un Estado de Producto?​

Un Estado de Producto (IProductStatusEntity) es una etiqueta/etiqueta personalizada para productos:

  • Nombre del Estado (localizeInfos) - Nombre de visualización localizado (por ejemplo, "Nueva llegada", "En venta")
  • Marcador de Estado (identifier) - Identificador único utilizado para filtrar
  • Indicador por defecto (isDefault) - Si este es el estado por defecto
  • Posición (position) - Orden de visualización

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 marker
   (Products.getProducts([{ statusMarker }], langCode))

📋 Lo Que Necesitas Saber​

Los estados 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 (Catálogo > Estados de Producto). Cada estado necesita un Nombre (requerido) y un Marcador único (requerido).

Restricciones del Marcador:

  • Solo letras latinas (a-z, A-Z) y números (0-9)
  • Se permiten guiones bajos (_) y guiones (-)
  • Sin espacios ni caracteres especiales
  • Debe ser único entre todos los estados

El SDK es para obtener estados y filtrar productos, no para crear estados.

Un estado por producto​

Un producto hace referencia como máximo a un estado. El objeto del producto lleva statusIdentifier (el marcador de estado, o null):

const product = await Products.getProductById(123);
console.log(product.statusIdentifier); // "in_stock" - status marker, or null

Filtrando por estado​

Para filtrar productos por estado, usa el método getProducts(body, langCode, userQuery) del módulo Products. Pasa un campo statusMarker dentro del array del cuerpo IFilterParams para obtener productos con un estado específico.

Validando un marcador​

validateMarker(marker) devuelve true si el marcador existe y false en caso contrario. Dado que el SDK no puede crear estados, úsalo para verificar un marcador antes de hacer referencia a él en tu código.

Estado vs atributos​

ProductStatuses son diferentes de los atributos de producto:

CaracterísticaProductStatusesAtributos
PropósitoEtiquetas/insignias/filtrosPropiedades del producto
Ejemplos"Nuevo", "En venta", "Destacado"Color, Tamaño, Material
Por productoUn estadoMuchos atributos
FiltradoSimple (por marcador 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 un estado de producto por marcadorObtener estado por identificador
validateMarker()Comprobar si existe un marcadorValidar marcador antes de usarlo

❓ 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 venta, Destacado) para filtrar y etiquetar, 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?​

No. Un producto hace referencia como máximo a un estado, expuesto como statusIdentifier (el marcador de estado) en el objeto del producto.

¿Cómo filtro productos por estado?​

Usa el método getProducts(body, langCode, userQuery) del módulo Products. Pasa un campo statusMarker dentro del array del cuerpo IFilterParams para obtener productos con un estado específico.

¿Cómo compruebo si existe un marcador de estado?​

Usa validateMarker() - devuelve true si el marcador existe y false en caso contrario. El SDK no puede crear estados; los marcadores se definen en el panel de administración siguiendo 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 al campo position, que determina el orden de visualización en tu aplicación.

¿Cómo añado estilos personalizados a las insignias de estado?​

Obtén todos los estados, luego asigna marcadores de estado a clases CSS o estilos en línea en tu código frontend. Aplica estos estilos al renderizar una insignia de producto basada en el statusIdentifier del producto.

🎓 Mejores Prácticas​

  • Usa marcadores descriptivos - nueva_llegada, no estado1.
  • Valida antes de hacer referencia - llama a validateMarker() antes de codificar un marcador.
  • Renderiza la insignia de estado - muestra la insignia del statusIdentifier del producto en las listas.
  • Cachea los estados - rara vez cambian, así que cachea para mejorar el rendimiento.

🔗 Documentación Relacionada​