# Primeros pasos (https://docs.loybox.com.ar/es-419/api-reference/primeros-pasos) Esta página es la integración completa de punta a punta. Si vienes a implementar y quieres leer una sola página antes de escribir código, es esta. Hay **dos caminos** y no son excluyentes: casi todas las integraciones empiezan por el primero y agregan el segundo cuando quieren que el cliente vea sus puntos por su cuenta. | Camino | Qué resuelve | Credencial | | ------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------ | | [Desde tu servidor](#camino-1-sumar-puntos-desde-tu-servidor) | Que las compras sumen puntos y que los códigos se canjeen en la venta | [API key](https://docs.loybox.com.ar/api-reference/credenciales#api-key-del-comercio) | | [Desde tu frontend](#camino-2-el-club-en-tu-frontend) | Que el cliente vea sus puntos, canjee y muestre su código | [Token del usuario](https://docs.loybox.com.ar/api-reference/credenciales#token-del-usuario-final) | ## Antes de empezar Necesitas dos cosas, y las dos te las damos nosotros: escríbenos a [hola@loybox.com.ar](mailto:hola@loybox.com.ar). La API key del comercio. Va sólo en tu servidor. El id de tu comercio. Es el que viaja en el header `X-Commerce-Id` y puede ir en el frontend. Los ejemplos de aquí en adelante usan las [convenciones de la referencia](https://docs.loybox.com.ar/api-reference#los-ejemplos): `$LOYBOX_API_KEY` para la API key, `$ACCESS_TOKEN` para el token del usuario y `87` como `commerce_id`. ## Camino 1: sumar puntos desde tu servidor Es la integración mínima de un programa de lealtad: una sola llamada, en el lugar donde tu sistema confirma una venta. ### Registra la compra En el checkout online ya tienes el correo, así que [por correo](https://docs.loybox.com.ar/api-reference/consumos/crear-por-email) es el camino corto: funciona incluso si el cliente todavía no tiene cuenta en Loybox. ```bash 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](https://docs.loybox.com.ar/api-reference/consumos/crear-por-codigo) con `client_code`. `amount` son unidades enteras de la moneda del comercio. Una compra de `1.750,50` se manda como `1750`. 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](https://docs.loybox.com.ar/referencia-tecnica#cálculo-de-puntos)). ### Muéstrale el saldo La respuesta del consumo no dice cuántos puntos sumó. El saldo se [consulta aparte](https://docs.loybox.com.ar/api-reference/clientes/obtener): ```bash 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](https://docs.loybox.com.ar/api-reference/beneficios/consultar-codigo-v2), que trae el valor del descuento en la raíz: ```bash 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: | `type` | Qué hacer | | --------------------- | --------------------------------- | | `percentage_discount` | Aplicar el porcentaje de `value`. | | `absolute_discount` | Descontar el monto de `value`. | | `free_product` | Agregar el producto de `product`. | Un `400` aquí significa que el código ya se usó: no apliques nada. ### Canjéalo cuando la venta se cerró [El canje](https://docs.loybox.com.ar/api-reference/beneficios/canjear) quema el código y no tiene vuelta atrás: ```bash 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 }' ``` Consultar es inofensivo y se puede repetir; canjear es definitivo. Si canjeas antes de cerrar la venta y la venta se cae, el cliente perdió la recompensa y no hay forma de devolvérsela por API. ## Camino 2: el club en tu frontend Aquí Loybox funciona como motor de lealtad debajo de tu producto: el usuario inicia sesión con un código que le llega por correo y desde ahí ve sus puntos, compra beneficios y muestra sus códigos. Todo esto puede correr en el navegador. Ninguna llamada de este camino lleva la API key: da acceso a los datos de todos tus clientes. Lo que viaja es el token del usuario, que sólo ve lo suyo, más el `X-Commerce-Id`, que no es secreto. ### Pídele el código ```bash 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 ```bash 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](https://docs.loybox.com.ar/api-reference/autenticacion/renovar-token) 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`](https://docs.loybox.com.ar/api-reference/mi-cuenta/obtener) trae de una los puntos, la marca del comercio y los puntos por vencer: ```js 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](https://docs.loybox.com.ar/api-reference/autenticacion/renovar-token) y reintenta la llamada. ### Muestra el catálogo y compra [El catálogo](https://docs.loybox.com.ar/api-reference/mi-cuenta/beneficios-disponibles) 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". ```bash 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" }' ``` Comprar cambia puntos por un beneficio, y lo hace el usuario desde tu frontend. Canjear usa ese beneficio en la venta, y lo hace tu servidor con la API key ([paso 4 del camino 1](#camino-1-sumar-puntos-desde-tu-servidor)). ### 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](https://docs.loybox.com.ar/api-reference/mi-cuenta/mis-beneficios). ## El circuito completo Los dos caminos se cierran así, y es el modelo mental que conviene tener antes de escribir código: ``` compra ──▶ POST /v1/consumptions/email (tu servidor, API key) │ ▼ puntos al cliente │ ▼ POST /v1/me/benefits/exchange (tu frontend, token del usuario) │ ▼ client_benefit_code │ ▼ GET /v2/benefits/preview/{code} (tu servidor, API key) │ ▼ POST /v1/benefits/redeem (tu servidor, API key) ``` ## Antes de salir a producción * La **API key vive sólo en tu servidor**. Si se filtró, escríbenos y la rotamos. * **Nunca reintentes un `400`** a ciegas: es el beneficio ya usado, el vencido o los puntos que no alcanzan. Lee el `message` y corta. * **Comprar un beneficio lleva `Idempotency-Key`**. Es lo que evita cobrar los puntos dos veces cuando se corta la red. * Un **`401`** en Mi cuenta es la señal de renovar el token, no de sacar al usuario de la sesión. * El **`404` de [mi nivel](https://docs.loybox.com.ar/api-reference/mi-cuenta/nivel)** es el caso normal de un cliente nuevo: esconder la sección de niveles, no mostrar un error. * **`points_expiration` no viene en `null`** cuando los puntos no vencen: viene con `mode: "none"`. Revisa el `mode` antes de mostrar el aviso. ## Si estás implementando con un agente La API está publicada en formato de máquina: * [`/openapi.json`](https://docs.loybox.com.ar/openapi.json): la especificación OpenAPI 3.1 completa, con los 25 endpoints, los esquemas y las dos credenciales. Sirve para generar un cliente tipado. * [`/llms.txt`](https://docs.loybox.com.ar/llms.txt) y [`/llms-full.txt`](https://docs.loybox.com.ar/llms-full.txt): la doc entera en texto, pensada para pasarle como contexto. * Cualquier página de la doc en Markdown crudo agregándole `.md` a la URL, por ejemplo [`/api-reference/credenciales.md`](https://docs.loybox.com.ar/api-reference/credenciales.md).