API y webhooks de Vuelvo (v1)

API pública para integrar tu programa de fidelidad con tu POS, tu tienda en línea o herramientas como n8n, Make o Zapier. Cada negocio crea sus llaves en Panel → API y webhooks.

Especificación OpenAPI: /api/v1/openapi.json · URL base: https://vuelvo.co/api/v1

Autenticación

Cada solicitud lleva la llave del negocio. La llave se crea en el panel y se muestra una sola vez; guárdala como un secreto.

curl https://vuelvo.co/api/v1/customers -H "Authorization: Bearer vk_live_XXXXXXXX_..."

Límite: 120 solicitudes por minuto por llave. Los movimientos que crea la API quedan a nombre de “API · nombre de la llave” y en la sede elegida, con los mismos límites anti-fraude del escáner.

Endpoints

`GET /customers` — Listar clientes

limit (query)
cursor (query): next_cursor de la página anterior
phone (query): Buscar por celular

`POST /customers` — Crear cliente (con su autorización de datos)

Tu formulario debe mostrar el texto de autorización del negocio (Ley 1581) y enviar aquí la evidencia. Sin consent.accepted = true no se crea la tarjeta. Si el celular ya existe responde 409 con el cliente.

`GET /customers/{id}` — Un cliente

id (path)

`GET /transactions` — Listar movimientos (del más antiguo al más nuevo)

since (query)
limit (query)
cursor (query)

`POST /transactions` — Registrar una visita o un canje

visit suma un sello, usa una sesión del bono o registra la visita de la membresía, según el programa del negocio. Aplican los mismos límites anti-fraude que en el escáner.

Ejemplo: registrar una visita desde tu POS

curl -X POST https://vuelvo.co/api/v1/transactions \
  -H "Authorization: Bearer vk_live_..." -H "Content-Type: application/json" \
  -d '{"phone": "300 123 4567", "type": "visit"}'

Ejemplo: crear un cliente con su autorización

curl -X POST https://vuelvo.co/api/v1/customers \
  -H "Authorization: Bearer vk_live_..." -H "Content-Type: application/json" \
  -d '{"name": "Ana Gómez", "phone": "300 123 4567", "birthday": "03-15",
       "consent": {"accepted": true, "ip": "190.1.2.3", "user_agent": "Mi tienda"}}'

Tu formulario debe mostrar el texto de autorización de datos del negocio y no crear el cliente si la persona no la acepta. Vuelvo guarda la evidencia con canal “api”.

Webhooks

Crea un destino en el panel (URL https) y elige los eventos. Cada evento llega en menos de un minuto como POST JSON:

{ "id": "entrega_…", "event": "transaction.created", "created_at": "2026-09-25T15:00:00.000Z", "data": { … } }

card.created: Un cliente recibió su tarjeta (se inscribió o aceptó la invitación). Trae el cliente y el canal de la autorización.
transaction.created: Cualquier movimiento del libro: sello, canje, sesión, anulación, ajuste…
reward.redeemed: Se entregó un premio (principal o intermedio).
customer.deleted: El titular pidió eliminar sus datos: bórralos también en tu sistema.

Responde con un código 2xx. Si no, se reintenta a 1 min, 5 min, 30 min, 2 h, 6 h y 24 h. Usa id para no procesar dos veces la misma entrega.

Verificar la firma

Cada entrega trae X-Vuelvo-Signature: t=<unix>,v1=<hmac>, donde hmac = HMAC-SHA256(secreto, t + "." + cuerpo). Rechaza firmas de más de 5 minutos.

import crypto from 'node:crypto'
function valida(secreto, cuerpo, encabezado) {
  const { t, v1 } = Object.fromEntries(encabezado.split(',').map(p => p.split('=')))
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false
  const esperado = crypto.createHmac('sha256', secreto).update(t + '.' + cuerpo).digest('hex')
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(esperado))
}

n8n, Make y Zapier

Usa el nodo “Webhook” (n8n), “Custom webhook” (Make) o “Webhooks by Zapier” para recibir los eventos, y el nodo HTTP con tu llave para llamar a la API. Aún no hay una app oficial en esas plataformas.

Datos personales

Los eventos de clientes incluyen nombre, celular y correo: tu negocio es el responsable del tratamiento y debe usar esos datos solo para las finalidades que el titular autorizó. Cuando llegue customer.deleted, elimina los datos también en tu sistema.