Tiendas (Storefronts)
Multi-storefront, API pública, visibilidad de catálogo y tokens
El módulo de tiendas permite a cada empresa operar múltiples escaparates en línea (storefronts), cada uno con su propia configuración, dominio, branding y catálogo visible. Incluye una API pública para que cualquier frontend consuma los datos del storefront.
Multi-Storefront
Cada empresa puede crear múltiples storefronts, cada uno funcionando como una tienda independiente.
Configuración por storefront
| Categoría | Campos |
|---|---|
| Identidad | Nombre, slug (URL amigable, único global), dominio personalizado |
| Estado | active, maintenance, coming_soon, disabled |
| Branding | Logo, favicon, colores primario y secundario (con fallback a colores de empresa) |
| Comercio | Moneda (ISO 4217), locale, impuestos incluidos, tasa impositiva por defecto |
| SEO | Título y descripción para motores de búsqueda |
| Mantenimiento | Mensaje personalizado cuando el storefront está en modo mantenimiento |
Límites configurables
La cantidad de storefronts que una empresa puede crear es configurable a nivel de empresa, permitiendo planes o tiers de servicio diferenciados.
API Pública del Storefront
API de solo lectura diseñada para que el frontend del portal de comprador consuma el catálogo sin autenticación administrativa. La autenticación se realiza mediante tokens de storefront (sf_*).
Endpoints disponibles
| Endpoint | Descripción |
|---|---|
GET /config | Configuración completa del storefront: nombre, moneda, locale, colores, logo |
GET /products | Listado paginado de productos visibles con filtros |
GET /products/:slug | Detalle de un producto: variantes, opciones, imágenes, campos personalizados, SKU, categoría primaria |
GET /categories/tree | Árbol jerárquico completo de categorías visibles |
GET /brands | Listado de marcas disponibles en el storefront |
Visibilidad inteligente
La API respeta automáticamente las reglas de visibilidad de catálogo:
- Si la empresa es master: muestra todo el catálogo.
- Si la empresa es subsidiaria: solo muestra productos y marcas asignados explícitamente por la empresa padre.
Los resultados se cachean en Redis con TTL configurable para rendimiento óptimo.
Rate limiting
Protección de doble capa contra abuso:
- Límite por IP.
- Límite por token de storefront.
Visibilidad de Catálogo
Sistema que controla qué productos y marcas son visibles para cada empresa en la jerarquía.
Tipos de asignación
| Tipo | Efecto |
|---|---|
| BrandVisibility | Todos los productos de una marca se hacen visibles para la empresa destino |
| ProductVisibility | Un producto específico se hace visible para la empresa destino |
Herencia jerárquica
La visibilidad respeta la jerarquía de empresas:
- Si la empresa A (padre) tiene acceso a una marca, todas sus subsidiarias heredan ese acceso.
- La resolución se hace en tiempo de consulta usando las rutas materializadas (path) de la jerarquía.
- No hay desnormalización — la herencia es dinámica.
Operaciones
- Asignar marca o producto a una empresa (upsert).
- Revocar acceso (detecta si la visibilidad es directa o heredada).
- Listar visibilidad directa + heredada con indicación de la fuente de cada grant.
- Dashboard: Interfaz visual para gestionar la visibilidad por empresa desde el panel administrativo.
Tokens de Storefront
Cada storefront se autentica mediante tokens dedicados que controlan el acceso a su API pública.
Tipos de tokens
| Tipo | Prefijo | Uso |
|---|---|---|
| Catalog token | pk_* | Acceso de lectura al catálogo desde aplicaciones externas |
| Storefront token | sf_* | Autenticación de requests a la API pública de un storefront específico |
Seguridad
- Los tokens se almacenan como hash SHA-256 (nunca en texto plano).
- Validación contra base de datos con verificación de expiración.
- Caché en Redis para invalidación inmediata al revocar.
- Registro de último uso (
lastUsedAt) para auditoría.
Gestión
- Máximo 20 tokens de catálogo por empresa.
- Límite configurable de tokens por storefront.
- Expiración configurable por token.
- CRUD completo desde el dashboard administrativo con interfaz visual de gestión de tokens por storefront.