Primeros pasos

Registrá la compra

En el checkout online ya tenés el email, así que por email 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 una caja física, 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. Mandás el monto y Loybox aplica la regla de dinero por punto, los puntos dobles si están vigentes y el bonus del nivel, en ese orden (la fórmula).

Mostrale 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 tenés un programa funcionando: las compras suman y el cliente tiene un saldo.

Consultá 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. Usá 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 aplicás el descuento en tu venta:

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

Canjealo 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
  }'

Pedile 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 email no tiene cuenta. En la UI mostrás siempre el mismo mensaje ("te mandamos un código a tu email"), porque no podés saber si la cuenta existía.

Verificalo y guardá 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. Guardá 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 email no tenía cuenta, se crea, y en ambos casos el usuario queda adherido a tu programa.

Pintá 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, mostrá el llamado a adherirse

Un 401 acá quiere decir que el access venció: renovalo y reintentá la llamada.

Mostrá el catálogo y comprá

El catálogo viene sin filtrar por saldo: comparás el cost de cada beneficio con los points del usuario y decidís 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"
  }'

Mostrale 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 local es lo que muestra en el mostrador.

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