Primeros pasos

Registra la compra

En el checkout online ya tienes el correo, así que por correo es el camino corto: funciona incluso si el cliente todavía no tiene cuenta en Loybox.

curl -X POST https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/consumptions/email \
  -H "Authorization: Bearer $LOYBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_email": "ana@example.com",
    "amount": 1750
  }'

En un punto de venta físico, donde el cliente da su número, es la misma llamada por código con client_code.

Cuántos puntos suma no lo decide tu llamada: lo decide la configuración del comercio. Mandas el monto y Loybox aplica la regla de dinero por punto, los puntos dobles si están vigentes y el bono del nivel, en ese orden (la fórmula).

Muéstrale el saldo

La respuesta del consumo no dice cuántos puntos sumó. El saldo se consulta aparte:

curl https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/clients/12345 \
  -H "Authorization: Bearer $LOYBOX_API_KEY"

Con esto ya tienes un programa funcionando: las compras suman y el cliente tiene un saldo.

Consulta el código que trae el cliente

Cuando el cliente llega con un código de canje (su client_benefit_code), lo primero es ver qué es. Usa la v2, que trae el valor del descuento en la raíz:

curl https://loybox-public-api-752998171300.southamerica-west1.run.app/v2/benefits/preview/887766 \
  -H "Authorization: Bearer $LOYBOX_API_KEY"

Con el type y el value de la respuesta aplicas el descuento en tu venta:

Un 400 aquí significa que el código ya se usó: no apliques nada.

Canjéalo cuando la venta se cerró

El canje quema el código y no tiene vuelta atrás:

curl -X POST https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/benefits/redeem \
  -H "Authorization: Bearer $LOYBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_benefit_code": 887766
  }'

Pídele el código

curl -X POST https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/auth/otp/request \
  -H "X-Commerce-Id: 87" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ana@example.com"
  }'

Responde 200 siempre, incluso si ese correo no tiene cuenta. En la UI muestras siempre el mismo mensaje ("te mandamos un código a tu correo"), porque no puedes saber si la cuenta existía.

Verifícalo y guarda la sesión

curl -X POST https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/auth/otp/verify \
  -H "X-Commerce-Id: 87" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ana@example.com",
    "otp": "418302"
  }'

Devuelve access y refresh. Guarda los dos: el access vence a los expires_in segundos y el refresh sirve para renovarlo sin pedirle otro código al usuario. Si el correo no tenía cuenta, se crea, y en ambos casos el usuario queda adherido a tu programa.

Pinta la pantalla con una sola llamada

GET /v1/me trae de una los puntos, la marca del comercio y los puntos por vencer:

const res = await fetch(
  'https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/me',
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'X-Commerce-Id': '87',
    },
  },
);

const me = await res.json();
// me.points -> el saldo grande de la pantalla
// me.commerce -> logo, nombre y color para la marca del programa
// me.subscribed -> si viene false, muestra el llamado a adherirse

Un 401 aquí quiere decir que el access venció: renuévalo y reintenta la llamada.

Muestra el catálogo y compra

El catálogo viene sin filtrar por saldo: comparas el cost de cada beneficio con los points del usuario y decides qué mostrar como alcanzable y qué como "te faltan N puntos".

curl -X POST https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/me/benefits/exchange \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Commerce-Id: 87" \
  -H "Idempotency-Key: 8f14e45f-ea0f-4d1c-9a1b-2c3d4e5f6a7b" \
  -H "Content-Type: application/json" \
  -d '{
    "benefit_id": "b_9f2a"
  }'

Muéstrale el código

La compra devuelve un client_benefit_code. Ese número es el código de canje y también el código de cupón: en una tienda online es lo que el usuario pega en el checkout, y en un negocio físico es lo que muestra en el mostrador.

Muéstralo grande, con un botón de copiar y el due_date al lado. La lista completa de los que tiene está en mis beneficios.