# Sobre la API (https://docs.loybox.com.ar/api-reference)



La API de Loybox sirve para lo mismo que el panel, pero desde tu código:
registrar compras que suman puntos, mostrar el catálogo de premios, canjear
códigos y consultar el estado de un cliente.

Es una API **REST sobre HTTPS**. Todo va y vuelve en JSON, los nombres de los
campos están en `snake_case` y las fechas en formato ISO 8601 con zona
horaria (`2026-03-14T18:30:00Z`).

## URL base [#url-base]

Todas las rutas de esta referencia cuelgan de:

```
https://loybox-public-api-752998171300.southamerica-west1.run.app
```

La versión va en el primer segmento de la ruta (`/v1/...`). Cuando un endpoint
cambia de forma no compatible aparece una versión nueva al lado de la anterior,
y la anterior sigue funcionando: es el caso de
[consultar un código](https://docs.loybox.com.ar/api-reference/beneficios/consultar-codigo) y su
[versión 2](https://docs.loybox.com.ar/api-reference/beneficios/consultar-codigo-v2).

## Los ejemplos [#los-ejemplos]

Cada página de endpoint trae la llamada entera en `curl`, lista para pegar en una
terminal. Tres cosas son variables y valen para todos los ejemplos:

| En el ejemplo       | Qué poner                                                                                                             |
| ------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `$LOYBOX_API_KEY`   | Tu [API key](https://docs.loybox.com.ar/api-reference/credenciales#api-key-del-comercio). Exportala en el ambiente, no la pegues en el comando. |
| `$ACCESS_TOKEN`     | El [token del usuario](https://docs.loybox.com.ar/api-reference/credenciales#token-del-usuario-final) que devolvió el login.                    |
| `X-Commerce-Id: 87` | El id de **tu** comercio.                                                                                             |

## Formato de máquina [#formato-de-máquina]

La API también está publicada como especificación, para generar un cliente en
lugar de escribirlo:

```
https://docs.loybox.com.ar/openapi.json
```

Es OpenAPI 3.1 y cubre los 25 endpoints, los esquemas de respuesta y las dos
credenciales. Si estás integrando con la ayuda de un agente, pasale esa URL.

## Las dos formas de integrarse [#las-dos-formas-de-integrarse]

Esta es la decisión más importante y conviene tomarla antes de escribir código,
porque cambia la credencial, los endpoints disponibles y dónde corre tu código.

<Cards>
  <Card title="Desde tu servidor" icon="Building2" description="Tu backend opera sobre todos los clientes del comercio. Se autentica con la API key. Es la integración clásica: caja, ERP, e-commerce propio." href="/api-reference/credenciales" />

  <Card title="Desde tu web" icon="Smartphone" description="El usuario final inicia sesión con un código que le llega por email y consulta sus propios puntos. Loybox como motor de fidelidad del frontend." href="/api-reference/credenciales" />
</Cards>

Cada sección de esta referencia usa una de las dos, y cada página de endpoint lo
dice arriba:

| Sección                                       | Credencial        | Para qué                               |
| --------------------------------------------- | ----------------- | -------------------------------------- |
| [Consumos](https://docs.loybox.com.ar/api-reference/consumos)           | API key           | Registrar compras que suman puntos     |
| [Clientes](https://docs.loybox.com.ar/api-reference/clientes)           | API key           | Consultar clientes y sus beneficios    |
| [Beneficios](https://docs.loybox.com.ar/api-reference/beneficios)       | API key           | Catálogo, consulta de códigos y canje  |
| [Autenticación](https://docs.loybox.com.ar/api-reference/autenticacion) | —                 | Login del usuario final por email      |
| [Mi cuenta](https://docs.loybox.com.ar/api-reference/mi-cuenta)         | Token del usuario | Puntos, canjes e historial del usuario |
| [Público](https://docs.loybox.com.ar/api-reference/publico)             | —                 | Marca y catálogo, sin login            |

<Callout type="warn" title="La API key nunca va en el frontend">
  La API key del comercio da acceso a los datos de **todos** tus clientes. Vive
  sólo en tu servidor. Lo que sí puede vivir en el browser es el token de acceso
  del usuario final, que sólo ve lo suyo.
</Callout>

## Cómo se ven las respuestas [#cómo-se-ven-las-respuestas]

Las respuestas no llevan sobre: el objeto viene en la raíz, y los listados
vienen como array directo.

```json
// GET /v1/clients/12345
{
  "code": 12345,
  "username": "Ana Pérez",
  "email": "ana@example.com",
  "points": 340
}
```

Los campos opcionales vienen presentes y en `null`, no ausentes. Podés leerlos
sin chequear si existen, pero sí hay que chequear si son `null`.

## Paginación [#paginación]

Hay dos esquemas, y cada uno vive en un solo endpoint:

### Límite y desplazamiento [#límite-y-desplazamiento]

[Listar clientes](https://docs.loybox.com.ar/api-reference/clientes/listar) usa `limit` y `offset`, y
devuelve el total para que puedas armar los números de página.

```json
// GET /v1/clients/list?limit=20&offset=40
{
  "items": [],
  "total": 1875,
  "limit": 20,
  "offset": 40
}
```

`limit` va de 1 a 100 y por defecto es 20. `offset` arranca en 0.

### Cursor [#cursor]

[Mi historial](https://docs.loybox.com.ar/api-reference/mi-cuenta/historial) usa cursor, porque es una
lista que crece por arriba y los números de página se desacomodan. Se pide la
página siguiente pasando el `next_cursor` de la respuesta anterior en `?cursor=`.

```json
// GET /v1/me/activity
{
  "results": [],
  "next_cursor": "eyJkIjoiMjAyNi0wMy0xNCJ9",
  "previous_cursor": null
}
```

Cuando `next_cursor` viene en `null`, no hay más páginas.

## Por dónde empezar [#por-dónde-empezar]

<Cards>
  <Card title="Primeros pasos" icon="Rocket" description="La integración completa de punta a punta: de la primera compra que suma puntos hasta el canje." href="/api-reference/primeros-pasos" />

  <Card title="Credenciales" icon="BadgeCheck" description="Cómo se autentica cada una de las dos integraciones y qué headers van en cada llamada." href="/api-reference/credenciales" />

  <Card title="Objetos" icon="Boxes" description="Los objetos que devuelve la API y la diferencia entre un beneficio y un beneficio canjeable." href="/api-reference/objetos" />

  <Card title="Errores" icon="TriangleAlert" description="Los códigos de estado que puede devolver la API y qué hacer con cada uno." href="/api-reference/errores" />

  <Card title="Referencia técnica" icon="Braces" description="Cómo funciona Loybox por dentro: fórmulas de puntos, vencimientos y reglas de niveles." href="/referencia-tecnica" />
</Cards>