Catálogo

El módulo de catálogo es el corazón de TunoCommerce. Permite gestionar un catálogo completo de productos con variantes ilimitadas, categorías jerárquicas, marcas con control de visibilidad, etiquetas, modificadores contextuales e inventario — todo con soporte para operaciones en masa y SEO integrado.

Productos

Cada producto soporta una estructura rica de datos diseñada para cubrir desde catálogos simples hasta configuraciones B2B complejas.

Datos básicos y clasificación

• Nombre, slug, SKU y GTIN con unicidad por empresa.
• Descripción completa y descripción corta para listados y detalle.
• Marca (obligatoria), categoría primaria y categorías secundarias ilimitadas.
• Etiquetas (tags) sin límite para clasificación flexible.
• Estado: draft → active → archived con transiciones controladas.
• Destacado (featured) para promociones o listados especiales.

Precios y moneda

Cinco tipos de precio por producto, todos en la moneda configurada (ISO 4217):

Variantes y opciones

Los productos con múltiples opciones (ej. color, talla, material) generan variantes automáticamente al definir los valores de cada opción.

• Opciones de producto: Atributos de variación (ej. "Color") con valores (ej. "Rojo", "Azul").
• Tipos de visualización: Rectángulos, muestras de color (swatch) o dropdown.
• Campos por variante: SKU, GTIN, precio, costo, stock, peso y dimensiones independientes del producto base.
• Generación automática: Al crear valores de opción se generan todas las combinaciones posibles.
• Creación directa: También se pueden crear variantes manualmente con combinaciones específicas.

Imágenes y campos personalizados

• Imágenes sin límite por producto, con URL remota, texto alternativo SEO, imagen primaria y ordenamiento.
• Imágenes por variante: Cada variante puede tener sus propias imágenes.
• Campos personalizados: Pares clave-valor ilimitados para especificaciones, certificaciones o cualquier dato adicional.

Inventario integrado

• Rastreo de inventario activable por producto.
• Cantidad mínima y máxima de orden.
• Nivel de alerta de stock bajo.
• Opción de permitir sobreventa (oversell).

SEO

Todos los productos incluyen campos de SEO: título, descripción y palabras clave, además del slug amigable para URLs.

Operaciones en masa

• Cambio de estado para hasta 100 productos simultáneamente.
• Upsert por SKU: Crear o actualizar producto en una sola operación (ideal para sincronización).
• Upsert en lote: Hasta 100 productos por operación.

---

Marcas

Las marcas organizan productos por fabricante o proveedor y soportan dos alcances:

• Global: Visible para todas las empresas de la plataforma (requiere permiso especial).
• Por empresa: Privada, solo visible para la empresa que la creó.

Cada marca incluye nombre, slug, descripción, logo, website, estado activo/inactivo, orden de visualización, campos SEO y metadatos JSON.

Control de visibilidad: En jerarquías multi-empresa, las empresas subsidiarias solo ven las marcas que la empresa padre les ha asignado explícitamente a través del sistema de visibilidad de catálogo.

Protección: No se puede eliminar una marca que tiene productos activos asociados.

---

Categorías

Las categorías soportan una estructura jerárquica de hasta 3 niveles de profundidad utilizando rutas materializadas para consultas eficientes.

• Categoría raíz (nivel 0) → Subcategoría (nivel 1) → Sub-subcategoría (nivel 2).
• Slug único dentro del mismo padre por empresa.
• Desactivación en cascada: Al desactivar una categoría, todos sus descendientes se desactivan automáticamente.
• Vista de árbol: Endpoint dedicado para obtener la estructura completa jerarquizada.
• Campos SEO, metadatos y orden de visualización por nivel.
• Reparentalización: Las categorías se pueden mover a un padre diferente sin perder datos.

---

Tags (Etiquetas)

Clasificación plana (sin jerarquía) para agrupar productos de forma flexible. Un producto puede tener etiquetas ilimitadas.

• Nombre, slug único por empresa, estado activo/inactivo.
• La respuesta de la API incluye el conteo de productos que usan cada etiqueta.
• No se puede eliminar una etiqueta que tiene productos asociados.

---

Modificadores

Los modificadores son campos adicionales configurables que se aplican a productos para capturar información adicional (ej. grabado personalizado, instrucciones especiales, opciones pagadas).

Tipos de campo soportados

text, number, select, multiselect, checkbox, date — cada uno con opciones configurables, posición y flag de requerido.

Alcance (scope)

Los modificadores se aplican con diferentes alcances, resueltos por prioridad:

1. Producto (más alta): Modificador específico a un producto.
2. Tag: Aplicable a todos los productos con esa etiqueta.
3. Categoría: Aplicable a productos en la categoría (desde la más específica hacia la raíz).
4. Global (más baja): Aplicable a todos los productos de la empresa.

Si múltiples alcances definen un modificador con el mismo nombre, el de mayor prioridad gana. La API incluye un endpoint de resolución que devuelve los modificadores aplicables a un producto específico con la prioridad ya calculada.

---

Inventario

El módulo de inventario soporta tres operaciones principales:

Los ajustes trabajan a nivel de SKU (variante), la respuesta identifica SKUs no encontrados para manejo de errores.

---

Control multi-empresa

El catálogo soporta distribución selectiva entre empresas:

• La empresa master gestiona el catálogo base completo.
• Las empresas subsidiarias acceden solo a productos y marcas asignados explícitamente via el sistema de visibilidad (BrandVisibility y ProductVisibility).
• Las subsidiarias tienen acceso de lectura; las mutaciones están reservadas para la empresa master.