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.
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." }
- ticket (muy recomendable): tu número de ticket. Si repites la llamada con el mismo ticket (por un reintento), no se suma dos veces: devuelve el mismo resultado con
"repetido": true. - importe: en euros (número o texto con coma). Obligatorio para sumar puntos.
- Si no se manda cliente o no tiene tarjeta, la venta se apunta igualmente para las estadísticas (si la conexión tiene
ventas). - Si el cliente ya tiene un premio pendiente, no se sella:
"hecho": falsecon el motivo (hay que canjearlo antes).
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
- Al leer el QR del cliente:
GET /cliente?codigo=…y enseñapantalla[0](nombre, sellos o puntos, si tiene premio). - Al cobrar el ticket:
POST /compracon el mismocodigo, elimportey elticket. - Tickets sin cliente:
POST /venta(o/comprasin 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 HTTP | Qué significa |
|---|---|
| 400 | Faltan datos o no son válidos (el campo error lo explica). |
| 401 | Falta la clave, no es válida o el negocio la ha borrado. |
| 403 | La conexión no tiene permiso para eso, o la cuenta del negocio no está activa. |
| 409 | Ese ticket se está procesando en este momento (reintenta en unos segundos). |
| 429 | Demasiadas 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.