Casos de uso¶

Escenarios reales donde el QR dinámico de Yappy en Caja encaja de forma natural — desde cajas registradoras convencionales hasta equipos desatendidos.

Sistemas de cajas registradoras¶

El caso más directo: Yappy como método de pago adicional en un punto de venta con cajero humano.

Contexto: tienda, supermercado, ferretería o cualquier negocio con mostrador donde el cajero procesa ventas. El sistema de punto de venta (POS) ya acepta efectivo y tarjeta; se integra Yappy como tercer método de pago sin cambiar el flujo del cajero.

Flujo de integración

1. Configuración previa

Cada caja física = una unidad de cobro en el portal de Yappy Comercial. Si tienes 5 cajas, creas 5 unidades. Esto te permite ver en el portal y en los reportes qué caja procesó cada pago.

2. Inicio de turno

Al arrancar el turno, el POS llama a POST /session/device con las credenciales de esa caja. El token de sesión obtenido se guarda en memoria y se reutiliza durante toda la jornada — no necesitas abrir sesión por cada venta.

3. El cajero inicia el cobro con Yappy

Cuando el cliente elige pagar con Yappy, el cajero presiona “Cobrar con Yappy” en el POS. El sistema llama a POST /qr/generate con el monto exacto de la venta y obtiene un hash.

4. Presentación del QR

El hash obtenido se modela como QR y se muestra al cliente en la pantalla orientada al cliente. El cajero le indica al cliente que escane el QR con la app de Yappy.

5. Confirmación del pago

El POS hace polling a GET /transaction/{id} cada 2-5 segundos. Cuando el estado cambia a COMPLETED, el cajero recibe la confirmación en pantalla y la venta queda registrada.

6. Fin de turno

Al cerrar la caja, el POS llama a DELETE /session/device para liberar la sesión. Si el POS falla sin cerrar sesión, la sesión expira automáticamente.

Consideraciones clave

Autoservicio de pago de estacionamiento¶

Kiosco desatendido donde el conductor paga su estacionamiento con Yappy antes de retirar el vehículo.

Contexto: estacionamiento con kiosco de pago automático. El conductor ingresa la placa o acerca su ticket, el kiosco calcula el monto según el tiempo transcurrido, muestra el QR y, al confirmarse el pago, imprime el comprobante o envía la señal para levantar la barrera.

Lo que hace diferente este caso

A diferencia de una caja con cajero, aquí no hay operador humano. El sistema debe manejar de forma autónoma todos los posibles escenarios.

Gestión de sesión en modo desatendido

En un kiosco desatendido, la sesión debe mantenerse activa durante todo el horario de operación — no se abre y cierra por cada transacción. El patrón recomendado es:

• Abrir sesión al iniciar el kiosco (POST /session/device).
• Detectar cuando el token expire (respuesta 401) y renovarlo automáticamente.
• Cerrar sesión solo al apagar el equipo o durante mantenimiento programado.

Consideraciones específicas

Vending machines con display¶

Máquinas expendedoras que muestran un QR dinámico para cobrar exactamente el monto del producto seleccionado.

Contexto: máquina expendedora (bebidas, snacks, artículos de conveniencia) con capacidad de conectarse a internet y mostrar un QR en pantalla. El usuario selecciona el producto, la máquina genera el QR con el precio exacto, el usuario paga, la máquina dispensa.

Las vending machines son especialmente atractivas para Yappy porque eliminan el problema del cambio y reducen la manipulación de efectivo, pero el hardware varía mucho. Aquí describimos los escenarios más comunes.

Escenario A — Display táctil integrado

La máquina tiene una pantalla táctil donde el usuario navega el catálogo, selecciona el producto y completa el pago.

Flujo:

1. Usuario selecciona producto en pantalla táctil.
2. Máquina muestra resumen: nombre del producto + precio.
3. Usuario elige “Pagar con Yappy”.
4. Máquina llama a POST /qr/generate con el monto exacto.
5. QR se muestra en pantalla a tamaño completo durante máximo 5 minutos.
6. Usuario escanea con la app de Yappy y confirma.
7. Máquina detecta COMPLETED → dispensa el producto → muestra pantalla de confirmación.

Ventaja de este escenario: la experiencia es completamente fluida y familiar para el usuario; la máquina puede mostrar instrucciones paso a paso.

Escenario B — Sin display propio: QR impreso en ticket

Algunas máquinas expendedoras industriales no tienen display gráfico pero sí una impresora térmica de tickets. En este caso, el QR se genera e imprime en papel.

Flujo:

1. Usuario selecciona producto (botones físicos o teclado numérico).
2. Máquina imprime un ticket térmico con el QR dinámico y el monto.
3. Usuario escanea el QR del ticket con Yappy.
4. Máquina hace polling a GET /transaction/{id} hasta detectar COMPLETED.
5. Máquina dispensa el producto.

Consideraciones críticas de este escenario:

• Genera e imprime el ticket solo después de que el usuario confirme la selección — un ticket impreso sin pagar es un QR activo que ocupa recursos.
• Si la impresora falla, no generes el QR. Es mejor mostrar un error que generar un QR inaccesible para el usuario.

Escenario C — Display externo (tablet o monitor auxiliar)

La vending machine no tiene display propio pero está equipada con una tablet o monitor auxiliar montado en la estructura de la máquina. Es el escenario más fácil de implementar porque el display es un dispositivo estándar.

Flujo: idéntico al Escenario A desde el punto de vista de la API. La tablet es simplemente el frontend que llama a la API de Yappy en Caja y muestra el QR.

Consideraciones:

• La tablet necesita conexión a internet propia (WiFi del local o SIM dedicada).
• La comunicación entre la tablet y el controlador de la máquina (para dispensar el producto) se hace típicamente por serial (RS-232), USB HID o TCP local — eso queda fuera del alcance de la API de Yappy.

Gestión de inventario y prevención de errores

Autopago en restaurantes y negocios de comida¶

Tablets de autopedido en mesa o kioscos de autopago que generan el QR exacto al cierre de la cuenta.

Contexto: restaurante, cafetería, food court o cualquier negocio de comida donde el cliente puede revisar su cuenta y pagar directamente desde la mesa o desde un kiosco — sin esperar a que el mesero traiga el vuelto o la datáfono.

Este caso resuelve uno de los mayores puntos de fricción en la experiencia gastronómica: el tiempo de espera para pagar al final. Con Yappy en Caja, el cliente escanea el QR, confirma el monto y sale — en menos de 30 segundos.

Modalidades de implementación

A) Tablet en mesa

Cada mesa tiene una tablet fija o portátil. Cuando el cliente quiere pagar, toca “Cerrar cuenta” → la tablet muestra el desglose y el QR por el total. El sistema de pedidos del restaurante genera el QR vía API y el estado de la mesa se actualiza automáticamente al confirmarse el pago.

B) Kiosco de autopedido en la entrada

El cliente pide y paga en el kiosco antes de sentarse o pasar a recoger. El flujo es:

1. Cliente selecciona items en pantalla táctil.
2. Procede al pago → kiosco llama a POST /qr/generate con el total.
3. Cliente escanea y paga.
4. Kiosco imprime el ticket de pedido y envía la orden a cocina.

C) QR en la cuenta impresa

El mesero imprime la cuenta en papel, que incluye un QR dinámico generado en el momento de imprimir. El cliente escanea desde la mesa con su teléfono y paga. El mesero solo regresa para agradecer — no trae datáfono ni cobra efectivo.

Consideraciones operativas

¿Por dónde empezar?¶

Independientemente del caso de uso, el punto de entrada es el mismo: crear la unidad de cobro, obtener las credenciales y completar el quickstart.