API para tu POS

Suma las ventas de tu caja a la tarjeta del cliente. Crea una clave en Panel → API y webhooks. Usa una lk_test_… para probar sin guardar nada y una lk_live_… en producción.

Ver openapi.json

Autenticación

Authorization: Bearer lk_test_...

POST /api/v1/transactions

Registra una venta. Identifica al cliente con serial (el QR de la tarjeta) o phone.

Ejemplo

curl https://yovuelvo.com/api/v1/transactions \
  -H "Authorization: Bearer lk_test_..." \
  -H "Idempotency-Key: venta-10234" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+51987654321","amount":2500}'

Cabeceras y campos
Nombre	Dónde	Detalle
`Idempotency-Key`	Cabecera, obligatoria	De 8 a 100 caracteres. Si tu POS reintenta, usa la misma clave: nunca se cuenta dos veces.
`amount`	Cuerpo, obligatorio	Entero en centavos, mínimo 1.
`serial` o `phone`	Cuerpo	Código del QR de la tarjeta, o celular del cliente.

Idempotency-Key obligatorio. Repetirlo devuelve el mismo resultado.
amount va en centavos. Con sellos, progresivo y membresía se suma una visita y se ignora el monto.
Si el staff ya escaneó a ese cliente en los últimos 10 minutos, respondemos counted:false con reason:already_scanned.

Respuesta 200

{
  "transaction_id": "...",
  "counted": true,
  "balance": "...",
  "sandbox": true
}

Los errores llegan como {"error":{"code","message"}} con estado 400, 401, 404, 422 o 429.

Webhooks

Configura tu URL https en el panel. Enviamos transaction.created, reward.redeemed y transaction.undone con la cabecera YoVuelvo-Signature: t=…,v1=…, donde v1 es el HMAC-SHA256 hex de `${t}.${cuerpo}` con tu secreto. Rechaza firmas con t de más de 5 minutos.

Verificar la firma (Node)

import { createHmac, timingSafeEqual } from "node:crypto";

function valida(header, cuerpo, secreto) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const esperada = createHmac("sha256", secreto).update(`${t}.${cuerpo}`).digest("hex");
  return v1.length === esperada.length && timingSafeEqual(Buffer.from(v1), Buffer.from(esperada));
}

Shopify y WooCommerce

Crea un webhook que apunte a https://yovuelvo.com/api/connectors/shopify/<tu-id> (evento Order payment) o …/woocommerce/<tu-id> (evento Order updated), firmado con tu secreto de webhooks. Sumamos al cliente por el celular de la orden. Tu id y el secreto están en el panel.

Tiendanube se conecta con un clic desde el panel (OAuth), sin configurar nada a mano.