# Objetos (https://docs.loybox.com.ar/api-reference/objetos)



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 [#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](https://docs.loybox.com.ar/api-reference/consumos/crear-por-codigo), [consultar un cliente](https://docs.loybox.com.ar/api-reference/clientes/obtener) |
| `benefit_id`          | Un **beneficio del catálogo**, el que creó el comercio.                   | [Consultar un beneficio](https://docs.loybox.com.ar/api-reference/beneficios/obtener), [comprarlo](https://docs.loybox.com.ar/api-reference/mi-cuenta/comprar-beneficio)      |
| `client_benefit_code` | Un **beneficio ya comprado** por un cliente concreto.                     | [Consultar el código](https://docs.loybox.com.ar/api-reference/beneficios/consultar-codigo), [canjearlo](https://docs.loybox.com.ar/api-reference/beneficios/canjear)         |

<Callout title="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.
</Callout>

## Cliente [#cliente]

Aparece en [listar clientes](https://docs.loybox.com.ar/api-reference/clientes/listar) y
[consultar un cliente](https://docs.loybox.com.ar/api-reference/clientes/obtener).

<Fields>
  <Field name="code" type="integer" required="true">
    El código del cliente.
  </Field>

  <Field name="username" type="string" required="true">
    Nombre del cliente.
  </Field>

  <Field name="email" type="string" required="true">
    Email del cliente.
  </Field>

  <Field name="points" type="integer | null">
    Puntos que tiene en el comercio.
  </Field>
</Fields>

## Beneficio [#beneficio]

El beneficio del catálogo. Aparece en casi todas las respuestas de
[Beneficios](https://docs.loybox.com.ar/api-reference/beneficios), [Clientes](https://docs.loybox.com.ar/api-reference/clientes),
[Mi cuenta](https://docs.loybox.com.ar/api-reference/mi-cuenta) y [Público](https://docs.loybox.com.ar/api-reference/publico).

<Fields>
  <Field name="id" type="string" required="true">
    El `benefit_id`.
  </Field>

  <Field name="type" type="string" required="true">
    Qué clase de premio es: `percentage_discount`, `absolute_discount` o
    `free_product`.
  </Field>

  <Field name="description" type="string" required="true">
    Descripción del beneficio.
  </Field>

  <Field name="cost" type="number" required="true">
    Cuántos puntos cuesta comprarlo.
  </Field>

  <Field name="expiration" type="date-time | null" required="true">
    Hasta cuándo está vigente. `null` si no vence.
  </Field>

  <Field name="benefit_type" type="string">
    `normal` para los del catálogo; `welcome`, `birthday`, `monthly_top` o
    `level` para las recompensas especiales. Por defecto, `normal`.
  </Field>

  <Field name="color" type="string | null">
    Color de marca del comercio, en hexadecimal.
  </Field>

  <Field name="buy_limit" type="integer | null">
    Cantidad total de canjes permitidos para este beneficio. `0` significa sin
    límite.
  </Field>

  <Field name="prize" type="Premio | null">
    El detalle del premio. Ver [Premio](#premio).
  </Field>

  <Field name="tiendanube_coupon" type="Cupón de Tiendanube | null">
    El cupón, si el beneficio se aplica en una tienda de Tiendanube. Ver
    [Cupón de Tiendanube](#cupón-de-tiendanube).
  </Field>
</Fields>

### Beneficio (v2) [#beneficio-v2]

[`GET /v2/benefits/preview/{client_benefit_code}`](https://docs.loybox.com.ar/api-reference/beneficios/consultar-codigo-v2)
devuelve una versión con tres campos más, que evitan tener que entrar a `prize`
para lo básico:

<Fields>
  <Field name="title" type="string" required="true">
    Título del beneficio. En la v1 sólo estaba dentro de `prize`.
  </Field>

  <Field name="value" type="number | null">
    El valor del descuento: el porcentaje si es `percentage_discount`, el monto
    si es `absolute_discount`.
  </Field>

  <Field name="product" type="Producto | null">
    El producto, si es `free_product`. Ver [Producto](#producto).
  </Field>
</Fields>

El resto de los campos son los mismos que en [Beneficio](#beneficio).

## Beneficio canjeable [#beneficio-canjeable]

Un beneficio que un cliente ya compró. Aparece en
[beneficios comprados](https://docs.loybox.com.ar/api-reference/clientes/beneficios-comprados),
[mis beneficios](https://docs.loybox.com.ar/api-reference/mi-cuenta/mis-beneficios) y como respuesta de
[comprar un beneficio](https://docs.loybox.com.ar/api-reference/mi-cuenta/comprar-beneficio).

<Fields>
  <Field name="client_benefit_code" type="integer" required="true">
    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.
  </Field>

  <Field name="issue_date" type="date-time" required="true">
    Cuándo lo compró.
  </Field>

  <Field name="due_date" type="date-time | null">
    Hasta cuándo puede canjearlo. `null` si no vence.
  </Field>

  <Field name="used" type="boolean">
    Si ya fue canjeado. Por defecto, `false`.
  </Field>

  <Field name="benefit" type="Beneficio" required="true">
    El beneficio comprado. Ver [Beneficio](#beneficio).
  </Field>
</Fields>

## Premio [#premio]

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

<Fields>
  <Field name="type" type="string" required="true">
    `percentage_discount`, `absolute_discount` o `free_product`.
  </Field>

  <Field name="title" type="string | null">
    Título del premio.
  </Field>

  <Field name="description" type="string | null">
    Descripción del premio.
  </Field>

  <Field name="value" type="number | null">
    El porcentaje o el monto del descuento, según el `type`.
  </Field>

  <Field name="product" type="Producto | null">
    El producto de regalo. Ver [Producto](#producto).
  </Field>

  <Field name="expiration" type="date-time | null">
    Vencimiento del premio.
  </Field>

  <Field name="image" type="string | null">
    URL de la imagen del premio.
  </Field>
</Fields>

## Producto [#producto]

<Fields>
  <Field name="id" type="integer | string | null">
    Id del producto en Loybox.
  </Field>

  <Field name="name" type="string | null">
    Nombre del producto.
  </Field>

  <Field name="external_id" type="string | null">
    Id del producto en el sistema del comercio.
  </Field>
</Fields>

## Comercio [#comercio]

Los datos de marca del programa. Aparece en
[datos del comercio](https://docs.loybox.com.ar/api-reference/publico/comercio) y dentro de
[mi cuenta](https://docs.loybox.com.ar/api-reference/mi-cuenta/obtener).

<Fields>
  <Field name="id" type="integer" required="true">
    El `commerce_id`, el mismo que va en el header `X-Commerce-Id`.
  </Field>

  <Field name="name" type="string" required="true">
    Nombre del comercio.
  </Field>

  <Field name="logo" type="string | null">
    URL del logo.
  </Field>

  <Field name="color" type="string | null">
    Color de marca en hexadecimal, para la UI del programa.
  </Field>

  <Field name="category_name" type="string | null">
    Rubro del comercio, por ejemplo `Tienda de comics`.
  </Field>

  <Field name="currency" type="string | null">
    Moneda del comercio.
  </Field>
</Fields>

## Mi cuenta [#mi-cuenta]

La respuesta de [`GET /v1/me`](https://docs.loybox.com.ar/api-reference/mi-cuenta/obtener).

<Fields>
  <Field name="username" type="string | null">
    Nombre del usuario.
  </Field>

  <Field name="email" type="string | null">
    Email del usuario.
  </Field>

  <Field name="phone" type="string | null">
    Teléfono del usuario.
  </Field>

  <Field name="points" type="integer">
    Puntos del usuario en este comercio. Por defecto, `0`.
  </Field>

  <Field name="subscribed" type="boolean">
    Si el usuario está adherido al programa de este comercio. Por defecto,
    `false`.
  </Field>

  <Field name="commerce" type="Comercio | null">
    Datos del comercio, para pintar la marca del programa. Ver
    [Comercio](#comercio).
  </Field>

  <Field name="points_expiration" type="Vencimiento de puntos | null">
    Puntos que están por vencer. Ver
    [Vencimiento de puntos](#vencimiento-de-puntos).
  </Field>
</Fields>

## Vencimiento de puntos [#vencimiento-de-puntos]

<Fields>
  <Field name="points" type="integer">
    Puntos que están por vencer. Por defecto, `0`.
  </Field>

  <Field name="expiration_date" type="date-time | null">
    Cuándo vencen.
  </Field>

  <Field name="days_left" type="integer | null">
    Días que faltan.
  </Field>

  <Field name="months_left" type="integer | null">
    Meses que faltan.
  </Field>

  <Field name="mode" type="string | null">
    Cómo vencen los puntos en este comercio: `none`, `rolling` o `accumulated`.
    `none` significa que no vencen.
  </Field>
</Fields>

<Callout type="info" title="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](https://docs.loybox.com.ar/puntos-y-premios/expiracion) para el detalle de los
  modos.
</Callout>

## Nivel [#nivel]

La respuesta de [`GET /v1/me/level`](https://docs.loybox.com.ar/api-reference/mi-cuenta/nivel).

<Fields>
  <Field name="name" type="string | null">
    Nombre del nivel.
  </Field>

  <Field name="rank" type="integer | null">
    Posición del nivel en la escalera.
  </Field>

  <Field name="points_multiplier" type="number | null">
    Multiplicador de puntos que da el nivel.
  </Field>

  <Field name="icon_url" type="string | null">
    URL del icono del nivel.
  </Field>

  <Field name="reached_at" type="date-time | null">
    Cuándo alcanzó el nivel.
  </Field>

  <Field name="expiration_date" type="date-time | null">
    Cuándo vence el nivel.
  </Field>

  <Field name="is_expired" type="boolean | null">
    Si el nivel ya venció.
  </Field>

  <Field name="next_level" type="Próximo nivel | null">
    El nivel siguiente y qué falta para alcanzarlo. Ver
    [Próximo nivel](#próximo-nivel).
  </Field>

  <Field name="total_earned_points" type="integer | null">
    Puntos ganados en total, el acumulado histórico.
  </Field>

  <Field name="total_spent_amount" type="number | null">
    Monto gastado en total.
  </Field>

  <Field name="total_consumptions_count" type="integer | null">
    Cantidad de consumos registrados.
  </Field>
</Fields>

### Próximo nivel [#próximo-nivel]

<Fields>
  <Field name="name" type="string | null">
    Nombre del próximo nivel.
  </Field>

  <Field name="rank" type="integer | null">
    Posición del próximo nivel.
  </Field>

  <Field name="threshold_type" type="string | null">
    Con qué se mide el umbral: por puntos acumulados o por monto gastado.
  </Field>

  <Field name="threshold" type="number | null">
    El valor del umbral a alcanzar.
  </Field>
</Fields>

## Movimiento [#movimiento]

Cada item de [mi historial](https://docs.loybox.com.ar/api-reference/mi-cuenta/historial).

<Fields>
  <Field name="type" type="string" required="true">
    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).
  </Field>

  <Field name="date" type="date-time | null">
    Cuándo pasó.
  </Field>

  <Field name="points" type="integer | null">
    Puntos que sumó o restó el movimiento.
  </Field>

  <Field name="benefit" type="Beneficio | null">
    El beneficio involucrado, en los movimientos de beneficio. Ver
    [Beneficio](#beneficio).
  </Field>

  <Field name="amount" type="number | null">
    Monto de la compra, en los movimientos de tipo `consumption`.
  </Field>

  <Field name="event" type="string | null">
    El evento que disparó la recompensa, en los `points_special_reward`.
  </Field>

  <Field name="additional_note" type="string | null">
    Nota adicional del movimiento.
  </Field>
</Fields>

## Recompensa automática [#recompensa-automática]

Cada item de [recompensas del programa](https://docs.loybox.com.ar/api-reference/mi-cuenta/recompensas).

<Fields>
  <Field name="event" type="string" required="true">
    Evento que la dispara: `welcome`, `birthday` o `monthly_top`.
  </Field>

  <Field name="reward_type" type="string" required="true">
    `benefit` si entrega un beneficio, `points` si entrega puntos.
  </Field>

  <Field name="benefit" type="Beneficio | null">
    El beneficio que entrega, cuando `reward_type` es `benefit`. Ver
    [Beneficio](#beneficio).
  </Field>

  <Field name="points" type="integer | null">
    Los puntos que entrega, cuando `reward_type` es `points`.
  </Field>
</Fields>

## Sesión [#sesión]

La respuesta de
[verificar el código](https://docs.loybox.com.ar/api-reference/autenticacion/verificar-codigo).

<Fields>
  <Field name="access" type="string" required="true">
    Token de acceso. Se manda como `Authorization: Bearer {access}` en los
    endpoints de Mi cuenta.
  </Field>

  <Field name="refresh" type="string" required="true">
    Token de refresco, para obtener un nuevo `access` sin volver a pedir un
    código.
  </Field>

  <Field name="expires_in" type="integer" required="true">
    Segundos de validez del token de acceso.
  </Field>

  <Field name="user_id" type="integer" required="true">
    Id del usuario.
  </Field>

  <Field name="username" type="string | null">
    Nombre del usuario.
  </Field>

  <Field name="email" type="string | null">
    Email del usuario.
  </Field>

  <Field name="phone" type="string | null">
    Teléfono del usuario.
  </Field>
</Fields>

## Cupón de Tiendanube [#cupón-de-tiendanube]

Va dentro de `tiendanube_coupon` cuando el beneficio se aplica en una tienda de
[Tiendanube](https://docs.loybox.com.ar/integraciones/tiendanube).

<Fields>
  <Field name="type" type="string" required="true">
    `percentage`, `absolute` o `shipping`.
  </Field>

  <Field name="value" type="number" required="true">
    El valor del cupón.
  </Field>

  <Field name="category" type="string | null">
    Id de la categoría de Tiendanube a la que aplica el cupón.
  </Field>

  <Field name="category_name" type="string | null">
    Nombre de esa categoría.
  </Field>

  <Field name="end_date" type="date-time | null">
    Hasta cuándo vale el cupón.
  </Field>

  <Field name="product" type="Producto de Tiendanube | null">
    El producto al que aplica el cupón, si aplica a uno solo. Ver
    [Producto de Tiendanube](#producto-de-tiendanube).
  </Field>
</Fields>

### Producto de Tiendanube [#producto-de-tiendanube]

<Fields>
  <Field name="tiendanube_id" type="integer | null">
    Id del producto en Tiendanube.
  </Field>

  <Field name="name" type="string | null">
    Nombre del producto.
  </Field>

  <Field name="url" type="string | null">
    URL del producto en la tienda.
  </Field>

  <Field name="available" type="boolean | null">
    Si hay stock.
  </Field>

  <Field name="published" type="boolean | null">
    Si está publicado en la tienda.
  </Field>

  <Field name="brand" type="string | null">
    Marca del producto.
  </Field>

  <Field name="categories" type="array de categorías">
    Categorías del producto, cada una con `id` y `name`. Por defecto, vacío.
  </Field>
</Fields>