Objetos

Los objetos que devuelve la API, campo por campo, y la diferencia entre un beneficio y un beneficio canjeable.

Esta página es el diccionario de la API: cada objeto que aparece en una respuesta, con todos sus campos. Las páginas de endpoint enlazan acá en lugar de repetir las listas.

Los tres códigos

Antes que nada, esto: la API maneja tres identificadores parecidos y confundirlos es el error más común al integrarse.

Código	Qué identifica	Dónde se usa
`client_code`	Un cliente. Es el número que tiene cada persona registrada en Loybox.	Registrar un consumo, consultar un cliente
`benefit_id`	Un beneficio del catálogo, el que creó el comercio.	Consultar un beneficio, comprarlo
`client_benefit_code`	Un beneficio ya comprado por un cliente concreto.	Consultar el código, canjearlo

Beneficio y beneficio canjeable no son lo mismo

El comercio crea beneficios, y cada uno tiene un benefit_id. Cuando un cliente compra uno con sus puntos recibe un beneficio canjeable con su propio client_benefit_code.

El benefit_id sirve sólo para consultar información. El client_benefit_code sirve para consultar y para canjear: es el código que el cliente presenta en el local, o pega en el checkout de la tienda online.

Cliente

Aparece en listar clientes y consultar un cliente.

codeintegerrequerido

El código del cliente.

usernamestringrequerido

Nombre del cliente.

emailstringrequerido

Email del cliente.

pointsinteger | null

Puntos que tiene en el comercio.

Beneficio

El beneficio del catálogo. Aparece en casi todas las respuestas de Beneficios, Clientes, Mi cuenta y Público.

idstringrequerido

El benefit_id.

typestringrequerido

Qué clase de premio es: percentage_discount, absolute_discount o free_product.

descriptionstringrequerido

Descripción del beneficio.

costnumberrequerido

Cuántos puntos cuesta comprarlo.

expirationdate-time | nullrequerido

Hasta cuándo está vigente. null si no vence.

benefit_typestring

normal para los del catálogo; welcome, birthday, monthly_top o level para las recompensas especiales. Por defecto, normal.

colorstring | null

Color de marca del comercio, en hexadecimal.

buy_limitinteger | null

Cantidad total de canjes permitidos para este beneficio. 0 significa sin límite.

prizePremio | null

El detalle del premio. Ver Premio.

tiendanube_couponCupón de Tiendanube | null

El cupón, si el beneficio se aplica en una tienda de Tiendanube. Ver Cupón de Tiendanube.

Beneficio (v2)

GET /v2/benefits/preview/{client_benefit_code} devuelve una versión con tres campos más, que evitan tener que entrar a prize para lo básico:

titlestringrequerido

Título del beneficio. En la v1 sólo estaba dentro de prize.

valuenumber | null

El valor del descuento: el porcentaje si es percentage_discount, el monto si es absolute_discount.

productProducto | null

El producto, si es free_product. Ver Producto.

El resto de los campos son los mismos que en Beneficio.

Beneficio canjeable

Un beneficio que un cliente ya compró. Aparece en beneficios comprados, mis beneficios y como respuesta de comprar un beneficio.

client_benefit_codeintegerrequerido

El código de canje. Es lo que el cliente presenta en el comercio, y también el código de cupón en una tienda online.

issue_datedate-timerequerido

Cuándo lo compró.

due_datedate-time | null

Hasta cuándo puede canjearlo. null si no vence.

usedboolean

Si ya fue canjeado. Por defecto, false.

benefitBeneficiorequerido

El beneficio comprado. Ver Beneficio.

Premio

El detalle de lo que gana el cliente. Va dentro de prize.

typestringrequerido

percentage_discount, absolute_discount o free_product.

titlestring | null

Título del premio.

descriptionstring | null

Descripción del premio.

valuenumber | null

El porcentaje o el monto del descuento, según el type.

productProducto | null

El producto de regalo. Ver Producto.

expirationdate-time | null

Vencimiento del premio.

imagestring | null

URL de la imagen del premio.

Producto

idinteger | string | null

Id del producto en Loybox.

namestring | null

Nombre del producto.

external_idstring | null

Id del producto en el sistema del comercio.

Comercio

Los datos de marca del programa. Aparece en datos del comercio y dentro de mi cuenta.

idintegerrequerido

El commerce_id, el mismo que va en el header X-Commerce-Id.

namestringrequerido

Nombre del comercio.

logostring | null

URL del logo.

colorstring | null

Color de marca en hexadecimal, para la UI del programa.

category_namestring | null

Rubro del comercio, por ejemplo Tienda de comics.

currencystring | null

Moneda del comercio.

Mi cuenta

La respuesta de GET /v1/me.

usernamestring | null

Nombre del usuario.

emailstring | null

Email del usuario.

phonestring | null

Teléfono del usuario.

pointsinteger

Puntos del usuario en este comercio. Por defecto, 0.

subscribedboolean

Si el usuario está adherido al programa de este comercio. Por defecto, false.

commerceComercio | null

Datos del comercio, para pintar la marca del programa. Ver Comercio.

points_expirationVencimiento de puntos | null

Puntos que están por vencer. Ver Vencimiento de puntos.

Vencimiento de puntos

pointsinteger

Puntos que están por vencer. Por defecto, 0.

expiration_datedate-time | null

Cuándo vencen.

days_leftinteger | null

Días que faltan.

months_leftinteger | null

Meses que faltan.

modestring | null

Cómo vencen los puntos en este comercio: none, rolling o accumulated. none significa que no vencen.

Cuando los puntos no vencen

Si el comercio no hace vencer los puntos, el objeto viene con mode: "none" y points: 0, no en null. Ver Vencimiento de puntos para el detalle de los modos.

Nivel

La respuesta de GET /v1/me/level.

namestring | null

Nombre del nivel.

rankinteger | null

Posición del nivel en la escalera.

points_multipliernumber | null

Multiplicador de puntos que da el nivel.

icon_urlstring | null

URL del icono del nivel.

reached_atdate-time | null

Cuándo alcanzó el nivel.

expiration_datedate-time | null

Cuándo vence el nivel.

is_expiredboolean | null

Si el nivel ya venció.

next_levelPróximo nivel | null

El nivel siguiente y qué falta para alcanzarlo. Ver Próximo nivel.

total_earned_pointsinteger | null

Puntos ganados en total, el acumulado histórico.

total_spent_amountnumber | null

Monto gastado en total.

total_consumptions_countinteger | null

Cantidad de consumos registrados.

Próximo nivel

namestring | null

Nombre del próximo nivel.

rankinteger | null

Posición del próximo nivel.

threshold_typestring | null

Con qué se mide el umbral: por puntos acumulados o por monto gastado.

thresholdnumber | null

El valor del umbral a alcanzar.

Movimiento

Cada item de mi historial.

typestringrequerido

Qué pasó: consumption (una compra que sumó puntos), benefit_exchange (compró un beneficio con puntos), benefit_usage (canjeó un beneficio) o points_special_reward (una recompensa automática le dio puntos).

datedate-time | null

Cuándo pasó.

pointsinteger | null

Puntos que sumó o restó el movimiento.

benefitBeneficio | null

El beneficio involucrado, en los movimientos de beneficio. Ver Beneficio.

amountnumber | null

Monto de la compra, en los movimientos de tipo consumption.

eventstring | null

El evento que disparó la recompensa, en los points_special_reward.

additional_notestring | null

Nota adicional del movimiento.

Recompensa automática

Cada item de recompensas del programa.

eventstringrequerido

Evento que la dispara: welcome, birthday o monthly_top.

reward_typestringrequerido

benefit si entrega un beneficio, points si entrega puntos.

benefitBeneficio | null

El beneficio que entrega, cuando reward_type es benefit. Ver Beneficio.

pointsinteger | null

Los puntos que entrega, cuando reward_type es points.

Sesión

La respuesta de verificar el código.

accessstringrequerido

Token de acceso. Se manda como Authorization: Bearer {access} en los endpoints de Mi cuenta.

refreshstringrequerido

Token de refresco, para obtener un nuevo access sin volver a pedir un código.

expires_inintegerrequerido

Segundos de validez del token de acceso.

user_idintegerrequerido

Id del usuario.

usernamestring | null

Nombre del usuario.

emailstring | null

Email del usuario.

phonestring | null

Teléfono del usuario.

Cupón de Tiendanube

Va dentro de tiendanube_coupon cuando el beneficio se aplica en una tienda de Tiendanube.

typestringrequerido

percentage, absolute o shipping.

valuenumberrequerido

El valor del cupón.

categorystring | null

Id de la categoría de Tiendanube a la que aplica el cupón.

category_namestring | null

Nombre de esa categoría.

end_datedate-time | null

Hasta cuándo vale el cupón.

productProducto de Tiendanube | null

El producto al que aplica el cupón, si aplica a uno solo. Ver Producto de Tiendanube.

Producto de Tiendanube

tiendanube_idinteger | null

Id del producto en Tiendanube.

namestring | null

Nombre del producto.

urlstring | null

URL del producto en la tienda.

availableboolean | null

Si hay stock.

publishedboolean | null

Si está publicado en la tienda.

brandstring | null

Marca del producto.

categoriesarray de categorías

Categorías del producto, cada una con id y name. Por defecto, vacío.

Objetos

En esta página