API Documentation

La API REST de Vuelora te permite integrar tu programa de fidelización con cualquier sistema externo: POS, CRM, agentes IA, o tu propia app.

Base URL: https://vuelora.com/api/v1

Autenticación

Todas las llamadas requieren una API Key enviada en el header Authorization. Las keys se generan desde Dashboard → Integraciones → API Keys.

Ejemplo de autenticación

curl -H "Authorization: Bearer vl_tu_api_key_aqui" \
  https://vuelora.com/api/v1/customers

Scopes disponibles

readLectura de clientes, puntos, recompensas, canjes

writeIncluye read + crear puntos, check-ins, canjes

adminIncluye write + gestión de webhooks, settings

Endpoints

Clientes

GET

/api/v1/customers

Lista todos los clientes con su balance de puntos. Soporta paginación con ?limit=&offset=.

Scope requerido: read

Puntos

GET

/api/v1/points

Lista transacciones de puntos. Filtrable por ?user_id= y ?type= (checkin, redemption, adjustment, bonus).

Scope requerido: read

POST

/api/v1/points

Agrega o resta puntos manualmente. Body: { user_id, points, description? }.

Scope requerido: write

Ejemplo: agregar puntos

curl -X POST \
  -H "Authorization: Bearer vl_xxx" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "abc123", "points": 50, "description": "Bonus de bienvenida"}' \
  https://vuelora.com/api/v1/points

# Respuesta
{
  "success": true,
  "points": 50,
  "description": "Bonus de bienvenida"
}

Recompensas

GET

/api/v1/rewards

Lista todas las recompensas configuradas del negocio.

Scope requerido: read

POST

/api/v1/rewards

Crea una nueva recompensa. Body: { name, points_required, description?, image_url?, stock? }.

Scope requerido: write

Check-in

GET

/api/v1/checkin

Estadísticas de check-in: total, hoy, esta semana.

Scope requerido: read

POST

/api/v1/checkin

Registra un check-in para un cliente. Body: { user_id }.

Scope requerido: write

Canjes (Redemptions)

GET

/api/v1/redemptions

Lista canjes. Filtrable por ?status= (pending, fulfilled, cancelled).

Scope requerido: read

POST

/api/v1/redemptions

Crea un canje. Body: { user_id, reward_id }. Devuelve verification_code.

Scope requerido: write

Webhooks

GET

/api/v1/webhooks

Lista todos los webhooks configurados.

Scope requerido: admin

POST

/api/v1/webhooks

Crea un nuevo webhook. Body: { url, events[] }. Genera un secret automáticamente.

Scope requerido: admin

PATCH

/api/v1/webhooks

Actualiza un webhook. Body: { id, url?, events[]?, is_active? }.

Scope requerido: admin

DELETE

/api/v1/webhooks?id=xxx

Elimina un webhook por ID.

Scope requerido: admin

Webhooks

Recibe notificaciones HTTP en tiempo real cuando ocurren eventos en tu programa. Cada delivery incluye una firma HMAC-SHA256 en el header X-Vuelora-Signature.

Eventos disponibles

checkin.createdUn cliente completó un check-in

redemption.createdUn cliente canjeó una recompensa

redemption.fulfilledUn canje fue marcado como entregado

customer.joinedUn nuevo cliente se unió al negocio

points.adjustedSe ajustaron puntos manualmente

Verificar firma HMAC (Node.js)

import crypto from "crypto";

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Servidor MCP

Vuelora incluye un servidor Model Context Protocol (MCP) que permite a agentes de IA como Claude o ChatGPT interactuar con tu programa de fidelización.

Solo Enterprise. El servidor MCP está disponible exclusivamente en el plan Enterprise.

Configuración en Claude Desktop

{
  "mcpServers": {
    "vuelora": {
      "url": "https://vuelora.com/api/mcp",
      "headers": {
        "Authorization": "Bearer vl_tu_api_key"
      }
    }
  }
}

Tools disponibles

get_customersListar clientes con balance de puntos

get_customer_pointsVer puntos de un cliente específico

add_pointsAgregar o restar puntos a un cliente

get_rewardsListar recompensas configuradas

create_checkinRegistrar un check-in para un cliente

get_statsObtener estadísticas generales del negocio

Acceso por plan

Cada plan define a qué endpoints puedes acceder. El plan Gratis no incluye acceso a la API.

Endpoint	Pro	Enterprise
GET /customers	✓	✓
GET /points	✓	✓
POST /points	—	✓
GET /rewards	✓	✓
POST /rewards	—	✓
GET /checkin	✓	✓
POST /checkin	✓	✓
GET /redemptions	—	✓
POST /redemptions	—	✓
Webhooks (todos)	—	✓
MCP	—	✓

¿Listo para integrar?

Crea tu API Key desde el dashboard y empieza a construir

Ir al Dashboard Soporte