# 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](/guides/error-handling)

## 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](/guides/idempotency)

## 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?

- Manejo de errores: [Manejo de errores](/guides/error-handling)
- Reintentos seguros: [Idempotencia & Reintentos](/guides/idempotency)
- Flujo completo: [Quickstart](/guides/quickstart)