# Referencia técnica (https://docs.loybox.com.ar/es-419/referencia-tecnica) Esta página resume, en un solo lugar, cómo funciona Loybox a nivel técnico: las entidades, las fórmulas y las reglas que gobiernan cada mecanismo. Cada sección enlaza a la guía correspondiente si necesitas el detalle completo. ## Entidades Todo el modelo se apoya en cinco piezas ([Conceptos](https://docs.loybox.com.ar/conceptos)): | Entidad | Qué representa | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | **Marca** | La empresa dentro de Loybox. Define moneda, reglas de puntos, catálogo de recompensas e identidad de la app. Puede tener una o varias sucursales. | | **Cliente** | La persona sumada al club. Tiene una relación con la marca, con saldo de puntos e historial propios. | | **Consumo** | El registro de una compra, en el negocio físico o en la tienda online. Es lo que dispara el cálculo de puntos. | | **Punto** | La unidad de lealtad. Se gana con consumos y otras acciones, y se gasta canjeando recompensas. | | **Recompensa** | Lo que el cliente obtiene a cambio de puntos. | ## Cálculo de puntos La regla principal es dinero por punto ([Ganar puntos](https://docs.loybox.com.ar/puntos-y-premios/ganar-puntos)): ``` puntos = piso( monto de la compra ÷ dinero por punto ) ``` El redondeo es siempre hacia abajo. Con `100 = 1 punto`, una compra de `1.750` otorga `17` puntos. ### Conversión por defecto según moneda Si la marca no define una regla de dinero por punto, se aplica una conversión por moneda: | Moneda | Regla por defecto | | ------------------- | -------------------------------------------------------------------------------------------------- | | Euro (EUR) | 50 puntos por cada € | | Peso mexicano (MXN) | 1 punto cada 50 MXN | | Resto | Se convierte a dólares (cotización MEP, actualizada periódicamente) y se otorgan 50 puntos por USD | En cuanto la marca define su propia regla, esta conversión deja de aplicar. ### Orden de los multiplicadores El orden importa, porque los ajustes se aplican en cascada: ### Punto base Según la regla de dinero por punto, o la conversión por moneda. ### Puntos dobles Si la promoción está vigente, duplica el resultado anterior. ### Bono porcentual del nivel Se aplica al final, según el nivel que el cliente tiene en el momento de la compra ([Beneficios de nivel](https://docs.loybox.com.ar/niveles/beneficios-de-nivel)). ### Otras fuentes de puntos Además del consumo, otorgan puntos los referidos (al concretarse la primera compra del invitado), el cumpleaños, la bienvenida al club y el hecho de alcanzar un nivel por primera vez. ## Saldo El saldo de un cliente es siempre `puntos ganados vigentes − puntos canjeados`. No existe un contador persistido que haya que reconciliar, así que el número es consistente con el historial real por construcción. Los puntos vencidos no se borran del historial: dejan de sumar cuando se calcula el saldo disponible. ## Vencimiento de puntos Hay tres modos ([Vencimiento de puntos](https://docs.loybox.com.ar/puntos-y-premios/expiracion)): | Modo | Comportamiento | | ------------------- | -------------------------------------------------------------------------------------------- | | **Sin vencimiento** | Los puntos no vencen nunca. Es el modo por defecto. | | **Acumulado** | Todo el saldo comparte una única fecha de vencimiento, que se renueva con cada compra nueva. | | **Por transacción** | Los puntos de cada consumo vencen a su propio ritmo, sin importar las compras posteriores. | El vencimiento se aplica sólo si el modo es `acumulado` o `por transacción` y el período en días es mayor que cero. Con el período en cero, los puntos no vencen aunque el modo esté activo. ## Niveles El nivel de un cliente se resuelve por umbrales ([Cómo suben de nivel](https://docs.loybox.com.ar/niveles/como-suben-de-nivel)): * Cada nivel se mide por puntos acumulados o por monto gastado, y cada nivel puede usar su propio criterio dentro de la misma escalera. * El avance se calcula sobre el historial completo de la relación, no sobre el saldo actual. Por eso canjear nunca baja de nivel: el saldo baja, el nivel no. * Después de cada compra, el cliente queda en el nivel más alto cuyo umbral ya alcanzó. * Los umbrales son siempre crecientes: un nivel superior no puede exigir menos que uno inferior. El nivel base es el escalón de entrada: no tiene umbral ni expiración, y no vence nunca ([Vencimiento y descenso](https://docs.loybox.com.ar/niveles/vencimiento-de-niveles)). El vencimiento de niveles sólo aplica a los niveles VIP medidos por puntos. ## Recompensas Una recompensa se define por tipo y valor, costo en puntos, límite de canjes, vencimiento e imagen opcional ([Recompensas](https://docs.loybox.com.ar/puntos-y-premios/premios)). El texto que ve el cliente se genera a partir del tipo y el valor. Tipos: producto gratis, vale de dinero (`$`), descuento porcentual (`%`), 2x1, envío gratis y libre (texto propio). Estados posibles, derivados de la configuración: | Estado | Condición | | ------------ | ---------------------------------- | | **Activo** | Disponible para canjear. | | **Inactivo** | Pausado manualmente. | | **Vencido** | Pasó su fecha de vencimiento. | | **Agotado** | Alcanzó su límite total de canjes. | Sólo las recompensas activas aparecen disponibles para el cliente. Un límite de canjes en cero significa ilimitado. ## Canje El flujo valida saldo antes de descontar ([Canje](https://docs.loybox.com.ar/puntos-y-premios/canje)): ### Validación de saldo El canje procede sólo si el cliente cubre el costo en puntos de la recompensa. ### Descuento y emisión Se registra el canje, el costo se resta del saldo y la recompensa queda a nombre del cliente con un código de validación corto y único. ### Validación del código El código está asociado a la marca y a ese canje puntual. Una vez marcado como usado no puede volver a validarse, lo que evita el doble uso. Una recompensa ya canjeada conserva la fecha de vigencia de la original. ## Segmentación Los clientes se agrupan automáticamente con el modelo RFM ([Segmentación](https://docs.loybox.com.ar/segmentacion)), sobre tres señales: recencia (hace cuánto compró), frecuencia (cuántas veces) y monto (cuánto gastó en total). Los segmentos siguen el estándar RFM: Champions, Leales, Leales en potencia, Necesitan atención, En riesgo, Hibernando y Perdidos. Cada uno expone su regla RFM, su volumen de clientes, su peso en la base y en las ventas, y promedios de recencia, frecuencia y ticket. La segmentación se calcula sobre los pedidos de la tienda online conectada. ## Canales e integraciones Una misma marca puede operar el club en negocios físicos (app PWA con su marca) y en su tienda online (integrada al checkout). Las reglas de puntos y el catálogo de recompensas se comparten entre canales. Integraciones disponibles ([Integraciones](https://docs.loybox.com.ar/integraciones)): Tiendanube (pedidos, productos y clientes), WhatsApp Business (notificaciones y mensajes) y Perfit (sincronización de contactos para correo). Las reseñas y las recomendaciones dependen de tener la tienda online conectada.