Desarrolladores

API de Vuelve

Conectá el sistema de ventas o la tienda online de tu comercio con su tarjeta de fidelidad. Cada venta suma sola en la tarjeta del cliente, y Vuelve te avisa al instante las compras, los canjes y los clientes nuevos.

  1. El dueño del comercio entra a su panel → Integraciones y crea una clave (plan Full).
  2. Tu sistema manda la clave en cada pedido.
  3. Al cobrar, mandás la compra con el DNI, el email, el teléfono o el código de la tarjeta del cliente.

Dirección base:

https://tarjetavuelve.com.ar/api/v1

Todo es JSON, en UTF-8. Las fechas van en ISO 8601. Los montos, en pesos y con punto decimal.

Autenticación

Mandá la clave en el encabezado Authorization. Es secreta: usala solo desde tu servidor, nunca desde una página web o una app del cliente.

Authorization: Bearer vk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Ejemplo rápido, para ver si funciona:

curl https://tarjetavuelve.com.ar/api/v1/programa \
  -H "Authorization: Bearer vk_live_..."

Clientes

Cada cliente tiene una tarjeta con un codigo (es lo que lee el QR en la caja). Para identificar a un cliente en cualquier pedido podés usar codigo, dni, email, telefono o cliente_id.

GET /clientes

Busca un cliente con ?dni=, ?email=, ?telefono= o ?codigo=. Sin esos filtros, lista todos (los más nuevos primero) con ?pagina= y ?limite= (hasta 100). Con ?buscar= busca por nombre.

curl "https://tarjetavuelve.com.ar/api/v1/clientes?dni=30111222" -H "Authorization: Bearer vk_live_..."
{
  "clientes": [
    {
      "codigo": "kQ2x9fL0aZ3m",
      "cliente": { "id": "5b1c…", "nombre": "Lucía Gómez", "dni": "30111222" },
      "saldo": 7,
      "saldo_texto": "7 de 10 sellos",
      "proximo_premio": { "nombre": "un café de regalo", "faltan": 3 },
      "premios": [{ "id": "a91e…", "nombre": "una medialuna", "vence": "2026-12-01T03:00:00.000Z" }],
      "canjes": 2
    }
  ],
  "total": 1
}

GET /clientes/{codigo}

La tarjeta por su código. Responde 404 si no es de este comercio.

POST /clientes

Da de alta un cliente con su tarjeta. acepto: true confirma que el cliente aceptó los términos y la política de privacidad del comercio (es obligatorio por la Ley 25.326). Si el DNI ya existe responde 409 con el cliente.

curl https://tarjetavuelve.com.ar/api/v1/clientes \
  -H "Authorization: Bearer vk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "nombre": "Lucía Gómez", "telefono": "1155556666", "email": "lucia@mail.com", "dni": "30111222", "nacimiento": "1994-05-21", "acepto": true }'

Compras

POST /compras

Suma una compra con las reglas del programa del comercio (sellos, puntos, saldo o metas). Si la compra hace ganar un premio, aparece en premios_ganados y queda en la tarjeta.

referencia es el número de ticket o de pedido en tu sistema. Si la misma referencia llega dos veces (por ejemplo, un reintento), no suma de nuevo y responde duplicada: true.

curl https://tarjetavuelve.com.ar/api/v1/compras \
  -H "Authorization: Bearer vk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "cliente": { "dni": "30111222" }, "monto": 8500, "referencia": "T-000123" }'
{
  "referencia": "T-000123",
  "monto": 8500,
  "sumo": 1,
  "premios_ganados": [],
  "cliente": { "codigo": "kQ2x9fL0aZ3m", "saldo": 8, "saldo_texto": "8 de 10 sellos", … }
}

Opcional: sucursal_id para que la compra quede en una sucursal (los ids están en el panel → Sucursales).

GET /compras

Las compras del comercio, de la más nueva a la más vieja. Filtros: ?desde=AAAA-MM-DD, ?hasta=AAAA-MM-DD (hora de Argentina), ?pagina= y ?limite= (hasta 500).

Canjes

POST /canjes

Canjea un premio que el cliente ya ganó. El premio_id sale de premios en la tarjeta. Un premio se canjea una sola vez: si se intenta de nuevo responde 409.

curl https://tarjetavuelve.com.ar/api/v1/canjes \
  -H "Authorization: Bearer vk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "cliente": { "codigo": "kQ2x9fL0aZ3m" }, "premio_id": "a91e…" }'

Programa

GET /programa

Cómo suma la tarjeta del comercio (sellos, puntos, saldo o metas), la compra mínima y la lista de premios.

Webhooks

En el panel → Integraciones el comercio carga la dirección de tu sistema (https). Vuelve manda un POST con JSON cada vez que pasa algo, venga de la caja, de Mercado Pago o de la API:

  • compra.creada: una compra sumó en una tarjeta.
  • canje.creado: se canjeó un premio o se usó saldo.
  • cliente.creado: alguien sacó su tarjeta.
POST https://tusistema.com/vuelve
X-Vuelve-Evento: compra.creada
X-Vuelve-Firma: sha256=6f1c…

{
  "evento": "compra.creada",
  "fecha": "2026-11-06T14:03:11.000Z",
  "comercio": "tostado",
  "datos": { "monto": 8500, "sumo": 1, "premios_ganados": [], "cliente": { … }, "origen": "caja" }
}

Verificá la firma: es el HMAC-SHA256 del cuerpo, tal cual llega, con la clave del webhook (empieza con whsec_). Respondé 200 en menos de 5 segundos. El campo origen (caja, mercadopago, api o cartel) te sirve para ignorar lo que cargó tu propio sistema.

// Node.js
import crypto from "node:crypto";

function firmaValida(cuerpo, firma, clave) {
  const esperada = "sha256=" + crypto.createHmac("sha256", clave).update(cuerpo).digest("hex");
  return firma.length === esperada.length && crypto.timingSafeEqual(Buffer.from(firma), Buffer.from(esperada));
}

Errores

Los errores responden con el código HTTP que corresponde y este formato:

{ "error": { "codigo": "cliente_no_encontrado", "mensaje": "No hay un cliente con esos datos en este comercio." } }
401Falta la clave, no existe o fue revocada.
403La cuenta está suspendida o el plan no incluye la API.
404No existe ese cliente o esa tarjeta en el comercio.
409El DNI ya existe o el premio ya se canjeó.
422Faltan datos o no son válidos (el mensaje dice cuál).

¿Dudas o querés que te ayudemos a conectar tu sistema? Escribinos a hola@tarjetavuelve.com.ar.