Rondafy · para proveedores de TPV

Guía de conexión TPV

Con esta conexión, el TPV de un negocio que usa Rondafy puede ver quién es el cliente (sus sellos, puntos y premios) y apuntar cada compra en su tarjeta de fidelización, que el cliente lleva en Apple Wallet o Google Wallet.

Resumen: el negocio crea una conexión en su panel de Rondafy y te da una clave (empieza por rfy_). Con ella llamas a una API HTTPS sencilla con JSON. Solo puede hacer lo que el negocio haya permitido en esa conexión.

1. Cómo se identifica al cliente

El cliente enseña su tarjeta en el móvil. El QR de la tarjeta contiene un código que puedes leer con la cámara o con el lector de códigos del TPV (funciona como un teclado). Ese texto, tal cual, es el codigo que mandas a la API. También puedes buscar por email o telefono si el TPV los tiene.

2. Autenticación

Todas las llamadas van a https://rondafy.es/api/tpv/v1/ con la clave en la cabecera:

Authorization: Bearer rfy_XXXXXXXXXXXXXXXXXXXX

(También se acepta la cabecera X-Rondafy-Clave.) Se permiten llamadas desde el navegador (CORS abierto). No guardes la clave en sitios públicos: quien la tenga puede actuar como esa caja. Si se filtra, el negocio la borra en su panel y crea otra.

3. Llamadas

GET/api/tpv/v1/yo

Comprueba la clave. Devuelve el negocio, el nombre de la conexión y sus permisos.

{ "negocio": "Café Ejemplo", "conexion": "Caja barra",
  "permisos": { "ver_cliente": true, "sellar": true, "puntos": true, "canjear": false, "ventas": true },
  "sello_minimo": 0 }

GET/api/tpv/v1/cliente?codigo=… (o ?email=… o ?telefono=…)

Permiso: ver_cliente. Devuelve sus tarjetas en ese negocio y una línea corta lista para enseñar en la pantalla del TPV.

{ "encontrado": true,
  "pantalla": ["Lucía Pérez · 5/8 sellos"],
  "tarjetas": [{
    "tipo": "sellos", "codigo": "c58e7a08-…", "nombre": "Lucía Pérez",
    "sellos": 5, "sellos_necesarios": 8, "premio_listo": false, "anulada": false
  }] }

Para una tarjeta de puntos: "tipo": "puntos", "puntos": 85 y "premios": [{ "id", "nombre", "puntos", "se_puede" }].

POST/api/tpv/v1/compra

Permisos: sellar y/o puntos (y ventas para que cuente en las estadísticas). Llámala al cobrar. Pone un sello en la tarjeta de sellos y suma los puntos que tocan por el importe en la de puntos, según lo que permita la conexión.

POST /api/tpv/v1/compra
{ "codigo": "c58e7a08-…", "importe": 12.50, "ticket": "A-000123" }
{ "ok": true, "cliente_encontrado": true,
  "acciones": [{ "tipo": "sellos", "hecho": true, "sellos": 6, "de": 8, "premio_listo": false }],
  "mensaje": "Compra apuntada en la tarjeta del cliente." }

POST/api/tpv/v1/canjear

Permiso: canjear. Canjea el premio de la tarjeta de sellos, o un premio de puntos (con su id).

{ "codigo": "c58e7a08-…" }                       // premio de sellos
{ "codigo": "pt_f1bcacdd-…", "premio": "pcafe1" }   // premio de puntos

POST/api/tpv/v1/venta

Permiso: ventas. Una venta sin cliente, solo para las estadísticas del negocio.

{ "importe": 8.40, "ticket": "A-000124" }

4. Flujo recomendado en caja

  1. Al leer el QR del cliente: GET /cliente?codigo=… y enseña pantalla[0] (nombre, sellos o puntos, si tiene premio).
  2. Al cobrar el ticket: POST /compra con el mismo codigo, el importe y el ticket.
  3. Tickets sin cliente: POST /venta (o /compra sin código).

Opción más sencilla: solo mandar los cobros

Si tu TPV no puede leer la tarjeta del cliente, basta con que mande cada cobro con POST /venta (o /compra sin código). El trabajador pasa la tarjeta por el lector en el escáner de Rondafy con la opción «Sellar solo al cobrar». Rondafy junta la tarjeta y el cobro si llegan con menos de 3 minutos de diferencia, da igual cuál llegue primero, y pone el sello o los puntos por el importe real. La respuesta lleva "emparejado": true cuando se ha juntado con una tarjeta.

5. Errores

Código HTTPQué significa
400Faltan datos o no son válidos (el campo error lo explica).
401Falta la clave, no es válida o el negocio la ha borrado.
403La conexión no tiene permiso para eso, o la cuenta del negocio no está activa.
409Ese ticket se está procesando en este momento (reintenta en unos segundos).
429Demasiadas llamadas seguidas (más de 240 por minuto por clave).

Todas las respuestas de error son JSON: { "error": "texto para el usuario", "code": "…" }.

6. Ejemplo rápido

curl -H "Authorization: Bearer rfy_XXXX" \
  "https://rondafy.es/api/tpv/v1/cliente?codigo=c58e7a08-…"

curl -X POST -H "Authorization: Bearer rfy_XXXX" -H "Content-Type: application/json" \
  -d '{"codigo":"c58e7a08-…","importe":12.5,"ticket":"A-000123"}' \
  https://rondafy.es/api/tpv/v1/compra

¿Dudas con la integración? Escríbenos a través de rondafy.es.