# Primeros pasos (https://docs.loybox.com.ar/api-reference/primeros-pasos) Esta página es la integración completa de punta a punta. Si venís a implementar y querés 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 [#antes-de-empezar] Necesitás dos cosas, y las dos te las damos nosotros: escribinos 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 acá 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 [#camino-1-sumar-puntos-desde-tu-servidor] Es la integración mínima de un programa de fidelidad: una sola llamada, en el lugar donde tu sistema confirma una venta. ### Registrá la compra [#registrá-la-compra] En el checkout online ya tenés el email, así que [por email](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 una caja física, 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. 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](https://docs.loybox.com.ar/referencia-tecnica#cálculo-de-puntos)). ### Mostrale el saldo [#mostrale-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 tenés un programa funcionando: las compras suman y el cliente tiene un saldo. ### Consultá el código que trae el cliente [#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](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 aplicás 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` acá significa que el código ya se usó: no apliques nada. ### Canjealo cuando la venta se cerró [#canjealo-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 canjeás antes de cerrar la venta y la venta se cae, el cliente perdió el premio y no hay forma de devolvérselo por API. ## Camino 2: el club en tu frontend [#camino-2-el-club-en-tu-frontend] Acá Loybox funciona como motor de fidelidad debajo de tu producto: el usuario inicia sesión con un código que le llega por email y desde ahí ve sus puntos, compra beneficios y muestra sus códigos. Todo esto puede correr en el browser. 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. ### Pedile el código [#pedile-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 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 [#verificalo-y-guardá-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`. Guardá 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 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 [#pintá-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, mostrá el llamado a adherirse ``` Un `401` acá quiere decir que el `access` venció: [renovalo](https://docs.loybox.com.ar/api-reference/autenticacion/renovar-token) y reintentá la llamada. ### Mostrá el catálogo y comprá [#mostrá-el-catálogo-y-comprá] [El catálogo](https://docs.loybox.com.ar/api-reference/mi-cuenta/beneficios-disponibles) 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". ```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)). ### Mostrale el código [#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](https://docs.loybox.com.ar/api-reference/mi-cuenta/mis-beneficios). ## El circuito completo [#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 [#antes-de-salir-a-producción] * La **API key vive sólo en tu servidor**. Si se filtró, escribinos y la rotamos. * **Nunca reintentes un `400`** a ciegas: es el beneficio ya usado, el vencido o los puntos que no alcanzan. Leé el `message` y cortá. * **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"`. Chequeá el `mode` antes de mostrar el aviso. ## Si estás implementando con un agente [#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).