Saltar al contenido principal
Version: v2.0 (RESTful)

Casos de uso

Para facilitar tu proceso de diseño técnico, a continuación detallamos cómo configurar el payload del QR según tus reglas de negocio y, posteriormente, cómo estructurar la arquitectura física y lógica de tu integración.

1. Configuración del QR según el Caso de Uso​

Dependiendo del flujo de cobranza que requieras, puedes combinar los campos is_multi_use, modify_amount y qr_expiration de la siguiente manera:

A. QR de un Solo Uso (Venta Estándar)​

  • Caso de uso: Ventas minoristas directas, facturación individual o e-commerce tradicional. El QR solo puede ser pagado una vez. Una vez pagado, se cancela y no aceptará más transacciones.
  • Banderas clave: "is_multi_use": false, "modify_amount": false
  • Ejemplo de Payload: 
    {
      "business_code": 17,
      "amount": 150.00,
      "modify_amount": false,
      "is_multi_use": false,
      "description": "Pago único de orden #49583"
    }

B. QR Multiuso (Recaudaciones Colectivas)​

  • Caso de uso: Donaciones, campañas de recaudación de fondos, pago de cuotas fijas o cobros recurrentes de un mismo valor donde varios clientes diferentes escanean y pagan el mismo código QR.
  • Banderas clave: "is_multi_use": true, "modify_amount": false
  • Ejemplo de Payload: 
    {
      "business_code": 17,
      "amount": 50.00,
      "modify_amount": false,
      "is_multi_use": true,
      "description": "Cuota Mensual del Club - Mayo"
    }
nota

Cada pago individual que reciba este QR disparará una notificación de Webhook independiente con los detalles del pagador.

C. QR con Monto Editable (Pagos Abiertos)​

  • Caso de uso: Propinas digitales, donaciones libres o pago de facturas donde el cliente decide el monto final a transferir al momento del escaneo en la aplicación de su banco.
  • Banderas clave: "modify_amount": true
  • Ejemplo de Payload: 
    {
      "business_code": 17,
      "amount": 10.00,
      "modify_amount": true,
      "is_multi_use": true,
      "description": "Aporte Voluntario / Propina"
    }

D. QR con Expiración (Control de Tiempo)​

  • Caso de uso: Compra de boletos para eventos de alta demanda, pasarelas con tiempo de reserva de inventario limitado (ej. pasajes aéreos) o transacciones de kioscos interactivos.
  • Campos clave: "qr_expiration": "YYYY-MM-DD HH:mm:ss"
  • Ejemplo de Payload: 
    {
      "business_code": 17,
      "amount": 250.00,
      "modify_amount": false,
      "is_multi_use": false,
      "qr_expiration": "2026-05-25 15:30:00",
      "description": "Reserva de entrada VIP"
    }

2. Arquitecturas de Integración Frecuentes​

A. Comercio Electrónico (E-Commerce Checkout)​

Este escenario aplica cuando un usuario realiza una compra en tu sitio web o aplicación móvil y selecciona "Pago con QR" al finalizar el checkout.

Arquitectura de Integración:​

  1. Petición Inicial: El backend de tu e-commerce llama a la API de Vendis para generar un QR de único uso ("is_multi_use": false) con el monto exacto de la orden.
  2. Visualización: Tu página web renderiza la imagen qr_image o muestra un botón que abre la qr_url.
  3. Manejo en Tiempo Real:
    • Backend (Webhook): Debes tener configurado el Webhook de pago recibido. En cuanto el cliente pague, tu webhook recibirá la confirmación, actualizará el estado de la compra a "Completada" en tu base de datos y preparará el pedido.
    • Frontend (Polling): Mientras el usuario ve el QR, tu interfaz de frontend puede realizar peticiones periódicas (polling) de tipo GET a tu propio backend (ej. cada 4-5 segundos) para saber si la orden ya cambió a pagada, y así mostrarle una pantalla de éxito sin requerir que recargue la página.

B. Punto de Venta Físico (POS en Caja)​

Este flujo es ideal para tiendas físicas, restaurantes o supermercados donde un cajero o vendedor genera un código QR para que el cliente lo escanee en persona.

Arquitectura de Integración:​

  1. Disparador: El cajero finaliza el registro de productos en el software de facturación y selecciona "Pago QR".
  2. Generación: El sistema del Punto de Venta (POS) realiza una llamada inmediata a la API de Vendis para crear el QR.
  3. Despliegue: La imagen del QR se muestra en una pantalla secundaria orientada al cliente o se imprime directamente en un ticket térmico de pre-factura.
  4. Sincronización: Dado que el cliente está físicamente en caja esperando para llevarse sus productos, el software de caja debe realizar un polling de alta frecuencia directo a la API de Vendis (GET /api/v2/simple-qrs/<QR-ID>) cada 2 o 3 segundos para detectar el pago al instante.
  5. Cierre: Al detectar el estado PAID, la caja confirma la venta de manera automática, imprime la factura de ley y abre el cajón monedero. El webhook de Vendis actúa aquí como un respaldo (failover) de seguridad.

C. Kioscos de Autoservicio y Máquinas Expendedoras (Vending)​

Este modelo aplica para terminales de venta desatendidas (kioscos interactivos, cobro de parqueos, máquinas expendedoras).

Arquitectura de Integración:​

  1. Selección: El usuario interactúa con la pantalla táctil y selecciona el servicio o producto a adquirir.
  2. Creación: El kiosco realiza la petición POST para generar el QR. Debido a las limitaciones de tiempo de estas terminales, se recomienda configurar una expiración corta (ej. "qr_expiration": "+5 minutes").
  3. Espera Activa: El kiosco muestra el QR y un contador regresivo en pantalla. El software del kiosco consulta intermitentemente la API de Vendis para monitorizar el estado.
  4. Despacho: Si la respuesta de consulta devuelve PAID dentro del tiempo límite, el kiosco activa el hardware correspondiente para dispensar el producto físico o imprimir el ticket de acceso. Si el contador llega a cero, el kiosco cambia su pantalla al estado CANCELED e invita al usuario a iniciar una nueva transacción.