En QRwey!, un código QR representa una intención de autofactura. El API no expone un campo explícito de estado; en su lugar, el estado de un QR se infiere a partir del comportamiento del endpoint de resolución.
Esta guía explica cómo interpretar correctamente ese ciclo de vida usando las respuestas del API, de forma alineada al contrato OpenAPI.
QRwey! no devuelve un campo
status.
El estado de un QR se deduce a partir del código HTTP al resolverlo.
Esto permite mantener el API simple y seguro, sin exponer estados internos innecesarios.
De forma conceptual, un QR pasa por las siguientes fases lógicas:
Generado → Válido → (Consumido | Expirado | Inválido)Estas fases no se devuelven como valores, se interpretan mediante el resultado del endpoint de resolución.
La siguiente tabla describe cómo interpretar la respuesta del API al resolver un QR:
| Respuesta del API | Interpretación |
|---|---|
200 OK | El QR es válido y puede usarse |
409 Conflict | El QR ya fue consumido |
410 Gone | El QR expiró |
404 Not Found | El QR es inválido o fue revocado |
422 Unprocessable Entity | Error de reglas de negocio o configuración |
Este comportamiento aplica al endpoint:
GET /api/v1/qrs?v=<v>&t=<t>&m=<m>Cuando el endpoint responde 200 OK:
- El QR es auténtico
- La firma es válida
- La transacción existe
- La información fiscal puede mostrarse al usuario
Acciones recomendadas:
- Mostrar el detalle de la transacción
- Permitir al usuario revisar la información
- Continuar el flujo de autofactura en la app móvil de QRwey!
Cuando el endpoint responde 409 Conflict:
- El QR ya fue utilizado
- No puede volver a usarse
- La intención ya fue confirmada
Acciones recomendadas:
- Mostrar mensaje de “QR ya utilizado o factura timbrada”
- Evitar reintentos
- No revelar información sensible
Cuando el endpoint responde 410 Gone:
- El QR alcanzó su fecha
expires_at - No puede resolverse
- No puede reactivarse
Acciones recomendadas:
- Informar al usuario que el QR expiró
- Solicitar generar un nuevo QR
Cuando el endpoint responde 404 Not Found:
- El token no existe
- El QR fue revocado o purgado
- El QR es incorrecto
Acciones recomendadas:
- Tratarlo como QR inválido
- No diferenciar entre “no existe” o “revocado”
- Mostrar mensaje genérico
Este error indica:
- Problemas de configuración
- Reglas fiscales no cumplidas
- Datos inconsistentes
Acciones recomendadas:
- Revisar el cuerpo de la respuesta (
code,message) - Registrar el error para soporte
- No mostrar detalles técnicos al usuario final
Cada QR define una ventana de validez mediante expires_at.
Recomendaciones:
- Usa expiraciones cortas (5 días, hasta fin de mes, etc.)
- Alinearlo con las reglas del negocio
- Maneja siempre
410 Gone - No intentes reutilizar QRs expirados
Por diseño:
- Un QR representa una sola transacción
- No debe reutilizarse
- No debe regenerarse sin idempotencia
Si necesitas generar otro QR para la misma venta:
- Crea una nueva intención
- Usa un nuevo
Idempotency-Key
- Resuelve QRs siempre desde backend
- Nunca confíes en datos de cualquier QR sin validarlos vía API
- No expongas lógica de validación en frontend
- Maneja explícitamente todos los códigos 4xx
Antes de ir a producción:
- Interpretas el estado solo por código HTTP
- Manejas
409,410,404y422 - No dependes de campos inexistentes (
status) - Logs con request-id y timestamps
- Mensajes claros para el usuario final
- Reintentos seguros: Idempotencia & Reintentos
- Manejo de errores: Manejo de errores
- Flujo completo: Quickstart