Sobre la API

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

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 y su versión 2.

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:

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

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.

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

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.

// 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

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

Límite y desplazamiento

Listar clientes usa limit y offset, y devuelve el total para que puedas armar los números de página.

// 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

Mi 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=.

// 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