# Documentación de Loybox > Loybox es una plataforma de fidelización para marcas: cada marca arma su > propio club de miembros donde los clientes acumulan puntos con cada compra y > los canjean por premios, con niveles VIP, referidos, reseñas, recomendaciones > y campañas. Opera en locales físicos (app PWA con la marca del cliente) y en > tiendas online integradas al checkout. Esta documentación es en español y > describe el producto desde el panel de administración y desde la API. ## Formatos para agentes - [llms-full.txt](https://docs.loybox.com.ar/llms-full.txt): el texto completo de toda la documentación en un solo archivo. - [openapi.json](https://docs.loybox.com.ar/openapi.json): la especificación OpenAPI 3.1 de la API pública, con los 25 endpoints, los esquemas de respuesta y las dos credenciales. Es la fuente para generar un cliente. - Cualquier página en Markdown crudo, agregándole `.md` al path. Por ejemplo [https://docs.loybox.com.ar/conceptos.md](https://docs.loybox.com.ar/conceptos.md). También responde al header `Accept: text/markdown` sobre la URL normal. - [sitemap.xml](https://docs.loybox.com.ar/sitemap.xml): todas las URLs indexables. ## La API en dos minutos Referencia completa en [Sobre la API](https://docs.loybox.com.ar/api-reference) y la integración de punta a punta en [Primeros pasos](https://docs.loybox.com.ar/api-reference/primeros-pasos). Lo esencial: - **URL base**: `https://loybox-public-api-752998171300.southamerica-west1.run.app`. La versión va en el primer segmento (`/v1/...`), REST sobre HTTPS, JSON, campos en `snake_case`, fechas ISO 8601. - **Dos credenciales que no son intercambiables**: la API key del comercio (`Authorization: Bearer {api-key}`) opera sobre todos los clientes y vive sólo en el servidor; el token del usuario final (`Authorization: Bearer {access}`, siempre junto al header `X-Commerce-Id`) sólo ve lo suyo y puede vivir en el browser. - **El header `X-Commerce-Id`** es obligatorio en Autenticación, Mi cuenta y Público, incluso sin token. No es secreto: delimita, no autoriza. Es la causa más frecuente de un `422`. - **La integración mínima** es una sola llamada: `POST /v1/consumptions/email` con el email y el monto de la compra. Loybox calcula los puntos. - **El ciclo del premio**: el usuario compra un beneficio con puntos (`POST /v1/me/benefits/exchange`) y recibe un `client_benefit_code`; el comercio lo consulta (`GET /v2/benefits/preview/{code}`), aplica el descuento y sólo entonces lo quema (`POST /v1/benefits/redeem`). - **Las respuestas no llevan sobre**: el objeto viene en la raíz y los listados son un array directo. Los campos opcionales vienen presentes y en `null`. ## Cómo funciona Loybox Referencia completa en [Referencia técnica](https://docs.loybox.com.ar/referencia-tecnica). Lo esencial: - **Entidades**: marca, cliente, consumo (una compra registrada), punto y premio. - **Puntos por compra**: `puntos = piso(monto ÷ dinero por punto)`, redondeando hacia abajo. Si la marca no define esa regla, se aplica una conversión por moneda (50 puntos por €; 1 punto cada 50 MXN; el resto se convierte a USD por cotización MEP y otorga 50 puntos por dólar). - **Multiplicadores en cascada**: primero el punto base, después puntos dobles si están vigentes y al final el bonus porcentual del nivel que el cliente tenía al momento de la compra. - **Saldo**: se calcula siempre como puntos ganados vigentes menos puntos canjeados. No hay contador persistido. Los puntos vencidos no se borran del historial, dejan de sumar. - **Vencimiento de puntos**: tres modos, sin vencimiento (por defecto), acumulado (una fecha para todo el saldo, que se renueva con cada compra) y por transacción (cada consumo con su propia fecha). Sólo aplica si el período en días es mayor que cero. - **Niveles**: cada nivel tiene un umbral medido por puntos acumulados o por monto gastado, siempre sobre el historial completo y no sobre el saldo, así que canjear nunca baja de nivel. El cliente queda en el nivel más alto cuyo umbral alcanzó. Los umbrales son crecientes y el nivel base no vence. - **Premios**: tipo y valor, costo en puntos, límite de canjes (cero es ilimitado), vencimiento. Estados activo, inactivo, vencido y agotado; sólo los activos se pueden canjear. - **Canje**: se valida el saldo, se descuentan los puntos y se emite un código corto y único, atado a la marca y a ese canje, que no puede validarse dos veces. - **Segmentación**: modelo RFM (recencia, frecuencia y monto) sobre los pedidos de la tienda online conectada, con los segmentos estándar (Champions, Leales, En riesgo, Hibernando, Perdidos y otros). - **Integraciones**: Tiendanube (pedidos, productos y clientes), WhatsApp Business (notificaciones) y Perfit (contactos para email). ## Guías - [Introducción](https://docs.loybox.com.ar/introduccion): Loybox es el programa de fidelidad para marcas ambiciosas. Creá tu club de miembros, sumá puntos con cada compra y convertí la compra en un hábito. - [Conceptos](https://docs.loybox.com.ar/conceptos): El modelo mental de Loybox (marcas, clientes, puntos y premios) para entender cómo encaja todo antes de configurar tu club. ### Fidelización - Puntos y premios - [Fundamentos](https://docs.loybox.com.ar/puntos-y-premios): El sistema de puntos y premios de Loybox, la mecánica central de tu programa de fidelidad, de un vistazo. - [Ganar puntos](https://docs.loybox.com.ar/puntos-y-premios/ganar-puntos): Cómo Loybox calcula los puntos de cada compra y qué otras acciones (referidos, cumpleaños, encuestas, niveles) también suman. - [Vencimiento de puntos](https://docs.loybox.com.ar/puntos-y-premios/expiracion): Los tres modos de vencimiento de Loybox (sin vencimiento, acumulado y por transacción) y cuándo conviene cada uno. - [Premios](https://docs.loybox.com.ar/puntos-y-premios/premios): Cómo armar tu catálogo de premios en Loybox, con los tipos de premio, el costo en puntos, el stock y la vigencia. - [Crear un premio](https://docs.loybox.com.ar/puntos-y-premios/crear-un-premio): Guía paso a paso para crear un premio en el panel de Loybox, desde elegir el tipo hasta ponerlo disponible para canje. - [Canje](https://docs.loybox.com.ar/puntos-y-premios/canje): El flujo de canje en Loybox, qué pasa cuando un cliente cambia sus puntos por un premio y cómo lo valida tu equipo con un código. - Niveles - [Fundamentos](https://docs.loybox.com.ar/niveles): Qué son los niveles VIP de Loybox y cómo recompensan a tus mejores clientes con más beneficios a medida que avanzan. - [Cómo suben de nivel](https://docs.loybox.com.ar/niveles/como-suben-de-nivel): Cómo Loybox decide el nivel de cada cliente con umbrales por puntos acumulados o por monto gastado, siempre sobre su historial completo. - [Beneficios de cada nivel](https://docs.loybox.com.ar/niveles/beneficios-de-nivel): Todo lo que podés dar en cada nivel de Loybox, desde el multiplicador de puntos hasta el premio al alcanzarlo y las recompensas exclusivas del nivel. - [Vencimiento y descenso](https://docs.loybox.com.ar/niveles/vencimiento-de-niveles): El vencimiento de niveles en Loybox, cómo mantener el estatus activo, el descenso por inactividad y cuándo conviene usarlo. - [Armá tus niveles](https://docs.loybox.com.ar/niveles/armar-tus-niveles): La guía para diseñar tu escalera de niveles VIP en Loybox y decidir cuántos niveles, qué umbrales, qué nombres y qué beneficios va a tener cada uno. - [Crear un nivel](https://docs.loybox.com.ar/niveles/crear-un-nivel): Guía paso a paso para crear un nivel en el panel de Loybox, desde el nivel base hasta los premios de cada escalón. - Referidos - [Fundamentos](https://docs.loybox.com.ar/referidos): Qué es el programa de referidos de Loybox y cómo tus propios clientes traen clientes nuevos a cambio de puntos. - [Activar los referidos](https://docs.loybox.com.ar/referidos/activar-referidos): Guía paso a paso para activar el programa de referidos en el panel de Loybox y definir cuántos puntos gana cada referido. - Reseñas - [Fundamentos](https://docs.loybox.com.ar/resenas): Cómo funcionan las reseñas de Loybox, con pedidos automáticos por WhatsApp después de la compra para juntar reseñas de tu negocio y tus productos. - [Configurar reseñas](https://docs.loybox.com.ar/resenas/configurar-resenas): Guía paso a paso para activar las reseñas en el panel de Loybox, tanto las de Google como las de productos (nativas o con tu propio sistema). - Recomendaciones - [Fundamentos](https://docs.loybox.com.ar/recomendaciones): Cómo funcionan las recomendaciones de productos con IA de Loybox, que muestran productos similares, complementarios, superiores y personalizados para aumentar tus ventas. - [Configurar recomendaciones](https://docs.loybox.com.ar/recomendaciones/configurar-recomendaciones): Guía paso a paso para activar y ajustar las recomendaciones de productos en el panel de Loybox, dónde se muestran y qué notificaciones enviar. ### Automatizaciones - Carrito - [Fundamentos](https://docs.loybox.com.ar/carrito): Las herramientas de carrito de Loybox para recuperar carritos abandonados y premiar las compras que superan un monto. - [Recuperar carritos abandonados](https://docs.loybox.com.ar/carrito/recuperar-carritos): Guía paso a paso para configurar los recordatorios de carrito abandonado por WhatsApp en Loybox. - [Recompensas en el carrito](https://docs.loybox.com.ar/carrito/recompensas-en-carrito): Guía paso a paso para crear reglas de recompensa por monto en el carrito de Loybox y aumentar el ticket promedio. - Segmentación - [Fundamentos](https://docs.loybox.com.ar/segmentacion): Cómo funciona la segmentación de clientes de Loybox, que agrupa tu base según sus patrones de compra (RFM) para que puedas accionar sobre cada grupo. - [Usar tus segmentos](https://docs.loybox.com.ar/segmentacion/usar-tus-segmentos): Cómo leer el panel de segmentación de Loybox, ver los clientes de cada segmento y accionar sobre ellos con campañas. - Campañas - [Fundamentos](https://docs.loybox.com.ar/campanas): Cómo funcionan las campañas de Loybox, mensajes dirigidos a un segmento de clientes por WhatsApp o email, con seguimiento de resultados. - [Crear una campaña](https://docs.loybox.com.ar/campanas/crear-una-campana): Guía paso a paso para crear, programar y enviar una campaña a un segmento de clientes en Loybox. - Integraciones - [Integraciones](https://docs.loybox.com.ar/integraciones): Conectá tu tienda, tu WhatsApp y tus herramientas de marketing con Loybox para que todo funcione junto. - [Tiendanube](https://docs.loybox.com.ar/integraciones/tiendanube): Conectá tu tienda de Tiendanube con Loybox para sincronizar pedidos, productos y clientes. - [WhatsApp Business](https://docs.loybox.com.ar/integraciones/whatsapp): Conectá WhatsApp Business con Loybox para enviar notificaciones y mensajes de fidelización a tus clientes. - [Perfit](https://docs.loybox.com.ar/integraciones/perfit): Conectá Perfit con Loybox para sincronizar tus contactos y potenciar tus campañas de email marketing. - [Referencia técnica](https://docs.loybox.com.ar/referencia-tecnica): Cómo funciona Loybox por dentro, con el modelo de datos, las fórmulas de cálculo de puntos, los modos de vencimiento y las reglas de niveles, premios y canje en una sola página. ## Referencia de API - [Sobre la API](https://docs.loybox.com.ar/api-reference): Una API REST para conectar tu programa de fidelidad con tus propios sistemas, desde tu servidor o directo desde tu web. - [Primeros pasos](https://docs.loybox.com.ar/api-reference/primeros-pasos): De cero a la primera compra que suma puntos, y de ahí al canje, con las llamadas exactas de cada paso. - [Credenciales](https://docs.loybox.com.ar/api-reference/credenciales): Las dos credenciales de la API, qué headers lleva cada llamada y cuál puede vivir en el browser. - [Objetos](https://docs.loybox.com.ar/api-reference/objetos): Los objetos que devuelve la API, campo por campo, y la diferencia entre un beneficio y un beneficio canjeable. - [Errores](https://docs.loybox.com.ar/api-reference/errores): Los códigos de estado que devuelve la API, la forma del cuerpo de error y qué hacer con cada caso. ### Consumos - [Consumos](https://docs.loybox.com.ar/api-reference/consumos): Registrar las compras de tus clientes para que sumen puntos, por código de cliente o por email. - [Crear consumo por código](https://docs.loybox.com.ar/api-reference/consumos/crear-por-codigo): Registra una compra usando el código del cliente, para que sume puntos. - [Crear consumo por email](https://docs.loybox.com.ar/api-reference/consumos/crear-por-email): Registra una compra usando el email del cliente, incluso si todavía no tiene cuenta en Loybox. ### Clientes - [Clientes](https://docs.loybox.com.ar/api-reference/clientes): Consultar los clientes del comercio, sus puntos y los beneficios que pueden comprar o ya compraron. - [Listar clientes](https://docs.loybox.com.ar/api-reference/clientes/listar): El listado de clientes del comercio, paginado por límite y desplazamiento. - [Obtener un cliente](https://docs.loybox.com.ar/api-reference/clientes/obtener): Busca un cliente por su código y devuelve sus datos y su saldo de puntos. - [Beneficios que puede comprar](https://docs.loybox.com.ar/api-reference/clientes/beneficios-disponibles): Los beneficios que un cliente puede comprar con los puntos que tiene. - [Beneficios comprados](https://docs.loybox.com.ar/api-reference/clientes/beneficios-comprados): Los beneficios que un cliente ya compró y todavía puede canjear, con el código de canje de cada uno. ### Beneficios - [Beneficios](https://docs.loybox.com.ar/api-reference/beneficios): El catálogo de premios del comercio, la consulta de un código de canje y el canje en sí. - [Listar beneficios](https://docs.loybox.com.ar/api-reference/beneficios/listar): Todos los beneficios que creó el comercio. - [Obtener un beneficio](https://docs.loybox.com.ar/api-reference/beneficios/obtener): Los datos de un beneficio del catálogo, por su benefit_id. - [Consultar un código](https://docs.loybox.com.ar/api-reference/beneficios/consultar-codigo): Qué premio es un código de canje, antes de canjearlo. - [Consultar un código (v2)](https://docs.loybox.com.ar/api-reference/beneficios/consultar-codigo-v2): La versión 2 de la consulta de un código, con el título y el valor del descuento al nivel de arriba. - [Canjear un beneficio](https://docs.loybox.com.ar/api-reference/beneficios/canjear): Marca un código de canje como usado. Es definitivo. ### Autenticación - [Autenticación](https://docs.loybox.com.ar/api-reference/autenticacion): Login del usuario final con un código de un solo uso enviado por email, para integrar Loybox directo en tu web. - [Pedir un código](https://docs.loybox.com.ar/api-reference/autenticacion/pedir-codigo): Le envía al usuario un código de 6 dígitos por email para iniciar sesión. - [Verificar el código](https://docs.loybox.com.ar/api-reference/autenticacion/verificar-codigo): Valida el código recibido por email y devuelve los tokens de sesión del usuario. - [Renovar el token](https://docs.loybox.com.ar/api-reference/autenticacion/renovar-token): Un token de acceso nuevo a partir del token de refresco, sin pedirle otro código al usuario. ### Mi cuenta - [Mi cuenta](https://docs.loybox.com.ar/api-reference/mi-cuenta): Los endpoints del usuario final: sus puntos, sus beneficios, su historial y su nivel en tu programa. - [Mi cuenta](https://docs.loybox.com.ar/api-reference/mi-cuenta/obtener): Todo lo que necesita el primer render: los datos del usuario, sus puntos, la marca del comercio y los puntos por vencer. - [Beneficios que puedo comprar](https://docs.loybox.com.ar/api-reference/mi-cuenta/beneficios-disponibles): El catálogo de beneficios vigentes del comercio que el usuario puede comprar con sus puntos. - [Comprar un beneficio](https://docs.loybox.com.ar/api-reference/mi-cuenta/comprar-beneficio): Cambia los puntos del usuario por un beneficio del catálogo y devuelve el código de canje. - [Mis beneficios](https://docs.loybox.com.ar/api-reference/mi-cuenta/mis-beneficios): Los beneficios que el usuario ya compró y todavía puede canjear, con su código. - [Mi historial](https://docs.loybox.com.ar/api-reference/mi-cuenta/historial): Los movimientos del usuario en el programa: consumos, compras de beneficios, canjes y recompensas. - [Mi nivel](https://docs.loybox.com.ar/api-reference/mi-cuenta/nivel): El nivel actual del usuario, su multiplicador de puntos y qué le falta para el siguiente. - [Recompensas del programa](https://docs.loybox.com.ar/api-reference/mi-cuenta/recompensas): Las recompensas que el comercio entrega solas: bienvenida, cumpleaños y cliente del mes. - [Adherirme al programa](https://docs.loybox.com.ar/api-reference/mi-cuenta/adherirme): Adhiere al usuario al programa de fidelidad del comercio y devuelve la recompensa de bienvenida. - [Darme de baja](https://docs.loybox.com.ar/api-reference/mi-cuenta/darme-de-baja): Da de baja al usuario del programa del comercio, sin perder los puntos acumulados. ### Público - [Público](https://docs.loybox.com.ar/api-reference/publico): Los datos del comercio y el catálogo de beneficios sin ningún token, para mostrarle el programa a un visitante. - [Datos del comercio](https://docs.loybox.com.ar/api-reference/publico/comercio): Nombre, logo, color de marca y rubro del comercio, sin necesidad de token. - [Catálogo de beneficios](https://docs.loybox.com.ar/api-reference/publico/beneficios): Los beneficios vigentes del comercio, sin necesidad de token.