Introducción

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

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

---

🎯 ¿Qué hace este módulo?

El módulo de Products (Catálogo) te permite recuperar, filtrar, buscar y ordenar productos en tu tienda en línea o colecciones multimedia. Gestionas el catálogo en el panel de administración de OneEntry (Catálogo > Productos); tu aplicación obtiene productos de forma dinámica, por lo que cambiar un precio o atributo en el administrador se refleja de inmediato sin necesidad de redeployar.

Más allá del comercio electrónico, el Catálogo también se adapta a galerías multimedia, portafolios, bibliotecas de documentos y otras colecciones de contenido.

🚀 Inicio Rápido

Inicializa el módulo desde defineOneEntry:

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

Obtén una página de productos y lee sus campos:

// Fetch the first 20 products (empty body = no filters).
const { items, total } = await Products.getProducts([], "en_US", { limit: 20 });

console.log(`Loaded ${items.length} of ${total} products`);

items.forEach((product) => {
  console.log(product.id, product.localizeInfos.title, product.price);
});

La mayoría de los métodos de listado comparten la misma estructura: un filtro body opcional, un langCode y un userQuery opcional (paginación/ordenación). Consulta Parámetros a continuación para el conjunto completo.

✨ Conceptos Clave

¿Qué es un Producto?

Un producto es una entidad de catálogo (IProductsEntity) compuesta por:

• Información básica - localizeInfos (título, etc.), sku, precio
• Imágenes - fotos del producto / galería (almacenadas como atributos)
• Atributos personalizados - cualquier campo que definas (attributeValues): marca, material, tamaño, color, variantes, stock, …
• Localización - contenido por idioma

No hay tipos de productos fijos en el SDK: cualquier estructura (variantes, opciones, descargas, paquetes) se modela con los atributos personalizados que configures para el catálogo.

Organización de Productos

Los productos se organizan a través de varias características del catálogo:

• Categorías - secciones del catálogo (páginas del tipo Catálogo, creadas en el módulo de Páginas)
• Estados de Producto - condiciones de filtrado adicionales más allá de los filtros de atributos (por ejemplo, "en stock", "en oferta")
• Enlaces de Producto - conecta productos por criterios de atributo (por ejemplo, todos los teléfonos negros juntos)
• Filtros de Producto - búsqueda rápida por criterios de filtro especificados
• Atributos personalizados - marca, tamaño, color, material, …

Ejemplo de jerarquía:

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

📁 Clothing
  ├─ 👕 T-Shirts
  └─ 👖 Jeans

📋 Lo Que Necesitas Saber

Arquitectura del Catálogo

Las categorías del catálogo son páginas del tipo Catálogo creadas a través del módulo de Páginas: créalas antes de agregar productos:

1. Abre el módulo de Páginas en el panel de administración.
2. Crea páginas con el tipo Catálogo: estas se convierten en tus categorías de productos.
3. Agrega productos a esas categorías a través de Catálogo > Productos.

El catálogo de administración también proporciona Carga Masiva de Catálogo, Filtros de Producto, Enlaces de Producto, Estados de Producto y Configuraciones por catálogo.

Paginación

No cargues todo de una vez: navega a través de los resultados con limit y offset:

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

Límite predeterminado: puedes recuperar 10 objetos por defecto. Para paginar más, configura Permisos del Módulo según tus necesidades.

Ordenación

Pasa sortKey y sortOrder en userQuery:

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

Orden de clasificación: ASC (bajo→alto) o DESC (alto→bajo, predeterminado).

Filtrado

El filtrado se realiza a través del body de la solicitud (un array de IFilterParams), no userQuery. Cada condición combina un attributeMarker, un conditionMarker (eq, neq, in, nin, mth, lth, exs, nexs) y un conditionValue. Combina varias condiciones en el array para filtrar por múltiples criterios a la vez. La referencia completa de condiciones está en Parámetros a continuación.

---

📊 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 la categoría por ID de página	Página de categoría
getProductsByPageUrl()	Obtener productos de la categoría por URL de página	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
getProductsByIds()	Obtener productos por una lista de IDs	Carrito, lista de deseos, comparación
getProductsByVectorSearch()	Búsqueda semántica (vector) de productos	Búsqueda impulsada por IA

Parámetros

Este módulo acepta un conjunto de parámetros de usuario llamados userQuery. Si no se pasa un parámetro, se aplica su valor predeterminado. Algunos métodos también aceptan un body para filtrado: pasa un array vacío (o nada) cuando no necesites filtros.

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

Nota: la estructura de userQuery depende del método. Los campos anteriores son la base común (IProductsQueryBase), utilizada por getProducts, getProductsByPageId, getProductsByPageUrl y getProductsEmptyPage. Otros métodos difieren: getRelatedProductsById también acepta statusMarker y templateMarker; getProductsPriceByPageUrl también acepta statusMarker (sin sortKey); getProductsByIds acepta solo signPrice. El filtrado (attributeMarker / conditionMarker / conditionValue) se realiza a través del body de la solicitud, no de userQuery — consulta a continuación.

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, title, date, price, position)
Valores disponibles: id, position, title, date, price

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

signPrice: cadena
Marcador de almacenamiento de pedidos para fijar el precio. Si se establece el parámetro, el precio se fija por un tiempo determinado (ver la sección Fijación del precio a continuación).
ejemplo: "orders"

Campos específicos del método: statusMarker (getRelatedProductsById, getProductsPriceByPageUrl) y templateMarker (getRelatedProductsById) — string | null, predeterminado null.

Usa condiciones para encontrar datos específicos de productos:

attributeMarker: El identificador de texto del atributo indexado por el cual se filtran los valores. conditionMarker: El tipo de condición que se aplicará al valor del atributo.

Marcador	Significado	Ejemplo
eq	Igual	statusId = 1 (solo activos)
neq	No igual	category ≠ "archived"
in	Contiene (uno de)	category in ["electronics", "books"]
nin	No contiene	brand not in ["fake_brand"]
mth	Mayor que	price > 100
lth	Menor que	stock < 10
exs	Existe (tiene valor)	Tiene descripción
nexs	No existe	Sin imagen

conditionValue: El valor con el que comparar.

---

Fijación del precio (signPrice)

Cuando obtienes productos, puedes pasar un parámetro signPrice opcional dentro de userQuery (también es un argumento en los métodos de recomendación del módulo de Blocks). Acepta el marcador de un almacenamiento de pedidos y solicita al servidor que bloquee el precio devuelto por un tiempo limitado.

signPrice — tipo string

Marcador de almacenamiento de pedidos para fijar el precio. Si se establece el parámetro, el precio se fija por un tiempo determinado.

Por qué usarlo. Los precios pueden cambiar mientras un cliente está comprando: comienza un descuento o un administrador edita el precio. signPrice garantiza que el precio mostrado en el catálogo o carrito sea exactamente el precio cobrado al finalizar la compra, por lo que no puede variar entre la navegación y el pedido.

Cómo funciona:

1. Obtén productos con signPrice establecido en tu marcador de almacenamiento de pedidos (por ejemplo, "orders").
2. Cada producto devuelto ahora lleva un campo signedPrice: un token firmado que codifica el precio bloqueado.
3. Envía ese token signedPrice de vuelta cuando crees el pedido, para que el servidor respete el precio fijado.

const { items } = await Products.getProducts([], "en_US", {
  signPrice: "orders"
});
const signedPrice = items[0].signedPrice;

➡️ El token devuelto es consumido por createOrder(). Consulta dónde tomarlo y cómo pasarlo en la sección Precio fijo del producto (signedPrice) del módulo de Orders.

---

❓ Preguntas Comunes (FAQ)

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

Sí: pasa varias condiciones en el array del body; se combinan juntas:

const { items } = await Products.getProducts(
  [
    { attributeMarker: "price", conditionMarker: "mth", conditionValue: 100 },
    { attributeMarker: "brand", conditionMarker: "in", conditionValue: ["apple", "samsung"] },
  ],
  "en_US",
);

---

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

Las variantes se almacenan en attributeValues del producto: léelas del objeto de producto obtenido. La estructura es la que sea que hayas configurado para el catálogo.

---

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

Aumenta offset por limit en cada clic y agrega los nuevos items a tu lista (usa total para saber cuándo detenerte).

---

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

Sí: filtra con el atributo category y el marcador de condición in, pasando la lista de valores de categoría.

---

¿Cómo implemento una sección de "Nuevos Llegados"?

Ordena por fecha de creación: userQuery: { sortKey: "date", sortOrder: "DESC" }.

---

🎓 Mejores Prácticas

• Siempre pagina (limit + offset) — nunca obtengas todo el catálogo de una vez.
• Cachea listas de productos para categorías de acceso frecuente para reducir llamadas a la API.
• Usa signPrice cuando los precios se integren en un carrito/checkout para que el precio no pueda variar.
• Maneja resultados vacíos (total === 0) y campos faltantes (price, imágenes) de manera adecuada.

---

🔗 Documentación Relacionada

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

---