# QRwey! API

La API de **QRwey!** permite a los negocios generar códigos QR seguros y efímeros 
para representar intenciones de factura. 

- Los comercios registran una venta enviando los datos de la transacción.
- La API retorna un **código QR** con un enlace seguro (deep link).
- Los clientes escanean el QR con la app móvil de QRwey! y pueden consultar los detalles 
  de la venta para generar un CFDi
- La API asegura la integridad de cada transacción usando **tokens opacos** firmados 
con **HMAC-SHA256**, con control de expiración y protección contra reuso.


Version: 1.2.0

## Servers

Entorno de Producción
```
https://clients.qrwey.com
```

Entorno de Desarrollo/Pruebas
```
https://api-dev.qrwey.com
```

## Security

### ApiKeyAuth

API Key proporcionada por QRwey! para autenticación

Ejemplo: 17e82f0a-4693-40f0-974f-b7607c575cb8

Type: apiKey
In: header
Name: X-API-Key

## Download OpenAPI description

[QRwey! API](https://qrwey.redocly.app/_bundle/apis/QRwey.yaml)

## QRs

Generación y resolución de códigos QR (intenciones de autofactura).

### Generar Código QR

 - [POST /api/v1/qrs](https://qrwey.redocly.app/apis/qrwey/qrs/generateqr.md): Crea una nueva intención de factura y genera su correspondiente código QR seguro y efímero.

El flujo de operación:
1. La aplicación del comercio envía los detalles de una venta y su API Key
2. La API valida la API Key y guarda la información de la transacción
3. Genera un token opaco y único, firmado con HMAC para garantizar su integridad
4. Almacena una correspondencia entre el token y los detalles de la transacción
5. Aplica un TTL (Time To Live) basado en la fecha de expiración (expires_at)
6. Genera y devuelve el código QR para intento de autofactura en tres formatos: imagen base64, URL de descarga firmada y contenido de texto

### Resolver Código QR

 - [GET /api/v1/qrs](https://qrwey.redocly.app/apis/qrwey/qrs/resolveqr.md): Este endpoint es invocado cuando un cliente final escanea el QR. Valida el token y devuelve los detalles de la transacción.

El flujo de operación:
1. El cliente escanea el código QR desde la aplicación QRwey!
2. La aplicación extrae los parámetros de la URL (v, t, m)
3. La aplicación solicita al API el detalle de la venta
4. El API valida la firma HMAC para asegurar que el token no ha sido alterado
5. Verifica que el token no haya expirado y que no haya sido consumido
6. Si todas las validaciones son correctas, responde con los detalles completos de la transacción

El sistema utiliza:
- Tokens Opacos: Identificadores aleatorios sin secuencia
- Integridad (Anti-manipulación): Firmado con HMAC-SHA256 truncado
- Expiración Forzada: Basada en el campo expires_at
- Control de Reutilización (Anti-replay): Puede configurarse para un solo uso