Introducción

Gestiona productos de comercio electrónico con catálogos dinámicos, filtrado y búsqueda.

🎯 ¿Qué hace este módulo?

El módulo Products (Catálogo) es un módulo independiente que te permite crear, recuperar, filtrar y gestionar productos en tu tienda en línea o colecciones multimedia. Proporciona herramientas muy flexibles para crear catálogos de productos o galerías multimedia con potentes funciones de búsqueda, filtros y organización.

El Catálogo permite crear, subir, editar y filtrar catálogos a través de una interfaz intuitiva. Más allá del comercio electrónico, admite aplicaciones alternativas como galerías multimedia, demostrando su versatilidad como herramienta de gestión de contenido.

Piénsalo como tu almacén digital: gestionas tu inventario de productos en el panel de administración de OneEntry (Catálogo > Productos), y tu aplicación obtiene productos dinámicamente con potentes funciones de búsqueda, filtros y ordenación.

📖 Explicación Simple

Imagina que estás construyendo una tienda en línea que vende:

👟 Zapatillas - con tamaños, colores, precios
📱 Electrónica - con especificaciones, imágenes, reseñas
👕 Ropa - con tamaños, materiales, variantes
📚 Libros - con autores, precios, descripciones

✅ En lugar de codificar cada producto, tú:

Agregas productos en el panel de administración de OneEntry (con todos los detalles)
Obtienes productos dinámicamente usando este módulo
Filtras por categoría, rango de precios, disponibilidad
Buscas productos por nombre o descripción
Ordenas por precio, fecha, popularidad
Actualizas precios/inventario sin necesidad de redeplegar

Ejemplo del mundo real:

❌ Sin el Módulo de Productos (codificado):
- Agregar nuevo producto → Cambiar código → Desplegar
- Cambiar precio → Cambio de código → Desplegar
- 1000 productos = archivo de código masivo

✅ Con el Módulo de Productos (dinámico):
- Agregar nuevo producto → Actualizar en admin → En vivo instantáneamente
- Cambiar precio → Actualizar en admin → En vivo instantáneamente
- 10,000 productos = llamadas a API simples

✨ Conceptos Clave

¿Qué es un Producto?

Un producto es un artículo que vendes, que contiene:

Información básica - Nombre, descripción, SKU, precio
Imágenes - Fotos del producto, galería
Variantes - Tamaños, colores, opciones (por ejemplo, "Camiseta roja tamaño M")
Inventario - Cantidad en stock, disponibilidad
Atributos personalizados - Cualquier campo que definas (marca, material, peso, etc.)
SEO - Título meta, descripción, palabras clave
Estado - Activo, borrador, fuera de stock
Localización - Soporte multilingüe

Estructura del Producto

Los productos pueden tener diferentes estructuras:

Tipo	Descripción	Ejemplo
Producto Simple	Artículo único, sin variantes	Libro, Póster
Producto con Variantes	Múltiples opciones (tamaño, color)	Camiseta (S/M/L, Rojo/Azul)
Producto Digital	Artículos descargables	E-book, Software
Paquete	Grupo de productos	Paquete de Inicio, Set de Regalo

Organización del Producto

Los productos se organizan a través de varias características clave:

Categorías - Organiza en secciones (Las categorías son páginas del tipo Catálogo creadas en el módulo Páginas)
Estados de Producto - Crea condiciones de filtrado adicionales más allá de los filtros de atributos existentes
Enlaces de Producto - Establece conexiones entre productos basadas en criterios de atributos
Filtros de Producto - Búsqueda rápida utilizando criterios de filtro especificados
Atributos personalizados - Marca, Tamaño, Color, Material, etc.

Ejemplo de jerarquía:

📁 Electrónica
  ├─ 📱 Smartphones
  │   ├─ iPhone 15 Pro
  │   └─ Samsung Galaxy S24
  └─ 💻 Laptops
      ├─ MacBook Pro
      └─ Dell XPS

📁 Ropa
  ├─ 👕 Camisetas
  └─ 👖 Jeans

📋 Lo Que Necesitas Saber

Arquitectura del Catálogo

Importante: Las categorías del catálogo son páginas del tipo Catálogo creadas a través del módulo Páginas. Debes crear las categorías del catálogo primero antes de agregar productos.

Características del Catálogo:

Pestaña de Productos - Espacio de trabajo principal para crear y gestionar elementos del catálogo
Filtros de Producto - Búsqueda rápida utilizando criterios especificados
Enlaces de Producto - Conectar productos basados en criterios de atributos (por ejemplo, todos los teléfonos negros)
Estados de Producto - Condiciones de filtrado adicionales para la organización
Carga del Catálogo - Importación masiva de datos del catálogo
Configuraciones - Opciones de configuración con campos de entrada numérica

Formas de Obtener Productos

Método	Cuándo Usar	Ejemplo
getProducts()	Listar productos con filtros/búsqueda	Página del catálogo
getProductsByPageId()	Productos de una categoría específica (por ID)	Página de categoría
getProductsByPageUrl()	Productos de una categoría específica (por URL)	Página de categoría por URL
getProductById()	Obtener un solo producto por ID	Página de detalles del producto
getRelatedProductsById()	Obtener productos relacionados/similares	Sección "También te puede gustar"
searchProduct()	Buscar productos por consulta	Funcionalidad de búsqueda

Paginación Explicada Simplemente

Cuando tienes 1000 productos, no los cargas todos a la vez:

Fórmula de desplazamiento: offset = (pageNumber - 1) * limit

Opciones de Ordenación

Ordena productos por diferentes campos:

sortKey	Qué Hace	Ejemplo de Uso
price	Ordenar por precio	Mostrar los más baratos primero
date	Ordenar por fecha de creación	Mostrar los productos más nuevos
title	Ordenar alfabéticamente	Lista de productos de A a Z
position	Orden personalizado (por defecto)	Orden seleccionado por el administrador
id	Ordenar por ID	Ordenación técnica

Orden de clasificación:

ASC (Ascendente) - De bajo a alto (A→Z, 0→9, barato→caro)
DESC (Descendente) - De alto a bajo (Z→A, 9→0, caro→barato)

Filtrando Productos

Usa filtros para reducir los resultados:

Marcadores de condición:

Marcador	Significado	Ejemplo
eq	Igual (coincidencia exacta)	Precio = $50
neq	No igual	Estado ≠ "agotado"
in	Contiene (uno de)	Color en ["rojo", "azul"]
nin	No contiene	Categoría no en ["archivada"]
mth	Mayor que	Precio > $100
lth	Menor que	Precio < $50
exs	Existe (tiene valor)	Tiene descuento
nexs	No existe (vacío)	Sin descuento

Estado y Enlaces de Producto

Estados de Producto crean condiciones de filtrado adicionales más allá de los filtros de atributos existentes para una organización de productos más sofisticada.

Enlaces de Producto permiten establecer conexiones entre productos basadas en criterios de atributos. Por ejemplo, puedes vincular todos los productos con el mismo atributo de color (por ejemplo, todos los teléfonos negros juntos).

📊 Tabla de Referencia Rápida - Métodos Comunes

Método	Descripción	Caso de Uso
getProducts()	Obtener todos los productos con filtrado/ordenación	Página principal del catálogo
getProductById()	Obtener un solo producto por ID	Página de detalles del producto
getProductsByPageId()	Obtener productos de categoría por ID	Página de categoría
getProductsByPageUrl()	Obtener productos de categoría por URL	Página de categoría por URL
getRelatedProductsById()	Obtener productos relacionados/similares	Sección "También te puede gustar"
searchProduct()	Buscar productos por consulta	Funcionalidad de búsqueda
getProductsCount()	Obtener el total de productos	Información de paginación
getProductsCountByPageId()	Obtener el conteo de productos por ID de categoría	Paginación de categoría
getProductsCountByPageUrl()	Obtener el conteo de productos por URL de categoría	Paginación de categoría
getProductBlockById()	Obtener bloque de producto por ID	Bloques de contenido del producto
getProductsEmptyPage()	Obtener estructura de página vacía de productos	Manejo de estado vacío
getProductsPriceByPageUrl()	Obtener precios de productos por URL de página	Filtrado de precios

❓ Preguntas Comunes (FAQ)

¿Puedo filtrar por múltiples criterios a la vez?

¡Sí! Combina múltiples filtros en un array.

¿Cómo manejo las variantes de producto (tamaños, colores)?

Las variantes de producto se almacenan en attributeValues.

¿Cómo implemento el botón "Cargar Más"?

Usa el desplazamiento para cargar más productos.

¿Puedo mostrar productos de múltiples categorías?

Sí, usa el marcador de condición category in.

¿Cómo implemento la sección "Nuevas Llegadas"?

Ordena por fecha de creación o usa la categoría principal para ordenar manualmente.

💡 Notas Importantes

Configuración de Categorías del Catálogo

Importante: Antes de agregar productos, debes crear categorías del catálogo a través del módulo Páginas. Las categorías del catálogo son páginas del tipo Catálogo.

Flujo de trabajo:

Ve al módulo Páginas en el panel de administración
Crea páginas con el tipo "Catálogo"
Estas páginas se convierten en tus categorías de productos
Agrega productos a estas categorías a través de Catálogo > Productos

Características del Catálogo

El módulo Catálogo proporciona herramientas integrales:

Pestaña de Productos - Espacio de trabajo principal para crear/gestionar elementos del catálogo
Filtros de Producto - Permiten búsquedas rápidas utilizando criterios especificados
Enlaces de Producto - Conectar productos relacionados basados en atributos
Estados de Producto - Crear condiciones de filtrado personalizadas
Carga del Catálogo - Importación masiva de productos
Configuraciones - Configurar el comportamiento del catálogo

Más Allá del Comercio Electrónico

El Catálogo no se limita a productos: puede ser utilizado para:

Galerías Multimedia - Fotos, videos, colecciones de arte
Elementos de Portafolio - Trabajos de diseño, estudios de caso
Bibliotecas de Documentos - Recursos, descargas
Catálogos de Eventos - Conferencias, seminarios web
Colecciones de Recetas - Comida, bebidas, cocina

Optimización del Rendimiento

Cachea productos de acceso frecuente para reducir llamadas a la API y mejorar los tiempos de carga.

Siempre Filtra Productos Activos

En producción, siempre muestra solo productos activos filtrando con statusId: 1.

Maneja Imágenes Faltantes

Proporciona imágenes de respaldo para productos sin imágenes para mantener una interfaz de usuario consistente.

🎓 Mejores Prácticas

Siempre usa paginación (límite + desplazamiento)
Filtra por statusId: 1 en producción
Cachea listas de productos para reducir llamadas a la API
Maneja "fuera de stock" de manera adecuada
Proporciona imágenes de respaldo
Usa marcadores para productos destacados (no IDs)
Implementa búsqueda con debouncing
Agrega estados de carga en la interfaz de usuario

Más información sobre el Catálogo en el panel de administración de OneEntry: https://doc.oneentry.cloudhttps://doc.oneentry.cloud/docs/category/catalog

Definición del módulo Products


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

Este módulo acepta un conjunto de parámetros de usuario llamados userQuery. Si los parámetros no se pasan al método, se aplicará el valor predeterminado. Algunos métodos aceptan el cuerpo como un parámetro para filtrar. Si no deseas configurar la ordenación, pasa un array vacío o no pases nada.

Parámetros:


const userQuery = {
    offset: 0,
    limit: 30,
    sortOrder: 'DESC',
    sortKey: 'id',
}

Esquema

offset: número
Parámetro de paginación. Predeterminado 0
ejemplo: 0

limit: número
parámetro de paginación. Predeterminado 30
ejemplo: 30

sortKey: cadena
Campo para ordenar (predeterminado no establecido - ordenando por posición, valores posibles: id, título, fecha, precio, posición)
Valores disponibles: id, posición, título, fecha, precio

sortOrder: cadena
orden de clasificación DESC | ASC (predeterminado DESC)
ejemplo: "DESC"

Por defecto, puedes recuperar 10 objetos. Esto se debe al límite de registro en la configuración de permisos del módulo.
Para que la paginación funcione correctamente, necesitas configurar Permisos del módulo de acuerdo a tus necesidades en la sección correspondiente.

"conditionMarker" por el cual se filtran los valores (no establecido por defecto), valores posibles:

'in' - Contiene,
'nin' - No contiene,
'eq' - Igual,
'neq' - No igual,
'mth' - Mayor que,
'lth' - Menor que,
'exs' - Existe,
'nexs' - No existe

🔗 Documentación Relacionada

Panel de Administración de OneEntry - Catálogo - Documentación oficial del panel de administración
Módulo de Páginas - Crear categorías de catálogo (páginas de tipo Catálogo)
Módulo AttributesSets - Campos y atributos personalizados de productos
Módulo de Plantillas - Plantillas de visualización de productos
Módulo de Bloques - Bloques de contenido de producto reutilizables
Módulo de Pedidos - Manejar pedidos de productos

Introducción

🎯 ¿Qué hace este módulo?​

📖 Explicación Simple​

✨ Conceptos Clave​

¿Qué es un Producto?​

Estructura del Producto​

Organización del Producto​

📋 Lo Que Necesitas Saber​

Arquitectura del Catálogo​

Formas de Obtener Productos​

Paginación Explicada Simplemente​

Opciones de Ordenación​

Filtrando Productos​

Estado y Enlaces de Producto​

📊 Tabla de Referencia Rápida - Métodos Comunes​

❓ Preguntas Comunes (FAQ)​

¿Puedo filtrar por múltiples criterios a la vez?​

¿Cómo manejo las variantes de producto (tamaños, colores)?​

¿Cómo implemento el botón "Cargar Más"?​

¿Puedo mostrar productos de múltiples categorías?​

¿Cómo implemento la sección "Nuevas Llegadas"?​

💡 Notas Importantes​

Configuración de Categorías del Catálogo​

Características del Catálogo​

Más Allá del Comercio Electrónico​

Optimización del Rendimiento​

Siempre Filtra Productos Activos​

Maneja Imágenes Faltantes​

🎓 Mejores Prácticas​

Definición del módulo Products​

🔗 Documentación Relacionada​