Skip to content
/
Expiración & Reuso de Tok...
Last updated

Expiración & Reuso

En QRwey!, los códigos QR están diseñados para ser seguros y efímeros. Eso significa que tienen una ventana de validez (expiración) y una política de uso que evita fraudes, duplicados e inconsistencias fiscales.

Esta guía explica:

  • Cómo definir expires_at
  • Qué pasa cuando un QR expira
  • Por qué no debe reutilizarse un QR
  • Qué hacer cuando el cliente necesita un QR nuevo

Expiración: ¿qué es y por qué existe?

La expiración limita el tiempo durante el cual un QR es válido. Esto reduce riesgos como:

  • Reuso indebido de tickets
  • Capturas tardías no controladas
  • Copias/fotos del QR usadas fuera de contexto
  • Discrepancias entre venta y facturación

En el contrato del API, la expiración se define mediante el campo:

  • expires_at

al generar el QR (POST /api/v1/qrs).

Cómo definir expires_at

Recomendación general

Para la mayoría de comercios:

  • La expiración debe de ir acorde a las reglas del negocio
  • Es común usar este campo como la fecha actual más 5 días o hasta fin de mes

Evita ventanas demasiado largas o que brinquen de mes a menos que exista una justificación de negocio y controles adicionales.

Consejo: usa tiempos "standard" por default y aumenta solo si el flujo real lo requiere.

¿Qué pasa cuando expira un QR?

Cuando el QR expira, el endpoint de resolución responde:

  • 410 Gone

Esto indica que:

  • El QR ya no puede resolverse
  • No puede reactivarse
  • Se requiere generar uno nuevo

Consulta: Manejo de errores

Reuso: por qué NO debes reutilizar un QR

Un QR en QRwey! representa una única intención de autofactura y por diseño:

  • Debe corresponder a una sola venta
  • No debe repetirse en otra operación
  • No debe “reciclarse” para nuevos tickets

Reutilizar QRs puede provocar:

  • Facturación duplicada
  • Errores de conciliación
  • Riesgos fiscales
  • Experiencias confusas para el usuario

¿Puedo volver a imprimir el mismo QR?

Depende del contexto:

✅ Permitido (misma transacción, dentro de vigencia)

  • Volver a imprimir el ticket si el QR sigue vigente
  • Volver a mostrar el QR en pantalla si no ha expirado

❌ No permitido (cambiar datos o reutilizar para otra venta)

  • Alterar monto/conceptos y usar el mismo QR
  • Usar el mismo QR para otra venta

¿Qué hacer si el cliente pide un QR nuevo?

Escenarios típicos:

1) El QR expiró (410)

Acción:

  • Genera un QR nuevo con POST /api/v1/qrs
  • Presenta el nuevo QR al cliente

2) El ticket se reimprimió y el QR sigue vigente

Acción:

  • Puedes mostrar el mismo QR original

3) Hubo timeout al generar QR

Acción:

  • Reintenta con el mismo Idempotency-Key
  • No generes un QR adicional si ya existe uno

Consulta: Idempotencia & Reintentos

Buenas prácticas

  • Define expiración "standard" como hasta fin de mes por default
  • Maneja explícitamente 410 Gone
  • No reutilices QRs entre ventas
  • Usa idempotencia para evitar duplicados
  • Registra expires_at y created_at para soporte

Checklist para producción

  • expires_at definido según operación y reglas del negocio
  • UI/UX maneja “expiró” de forma clara
  • Backend maneja 410 y genera QR nuevo
  • No reutilizas QRs entre ventas
  • Reintentos usan el mismo Idempotency-Key

¿Qué sigue?

Previous page
Next page