# Resolver código QR

En QRwey!, **resolver** un código QR significa validar su firma y obtener el **detalle completo**
de la transacción asociada.

Esto es lo que ocurre cuando un usuario escanea un QR desde la app de QRwey! (o cuando tú
necesitas validar un QR desde tu backend).

## ¿Qué “contiene” un QR de QRwey?

Un QR de QRwey! no expone datos sensibles. En su lugar contiene (o apunta a) un **deep link**
con 3 parámetros:

- `v`: versión del formato
- `t`: token opaco (Base64URL)
- `m`: firma HMAC truncada (Base64URL)


Ejemplo de contenido (deep link):


```
https://clients.qrwey.com/go?v=1&t=YWFh...&m=YmJi...
```

> ⚠️ Importante: **no confíes** en el contenido de cualquier QR sin validarlo vía API.
La verificación real ocurre en los servidores de QRwey!
Este endpoint es OPCIONAL ya que este proceso de lectura normalmente sucede en la app móvil
de QRwey!


## Endpoint


```
GET /api/v1/qrs?v=<v>&t=<t>&m=<m>
```

**Host (DEV):**


```
https://api-dev.qrwey.com
```

**Host (PROD):**


```
https://clients.qrwey.com
```

## Headers requeridos


```http
X-API-Key: TU_API_KEY
```

## Paso 1: Extraer v, t y m

Si tienes el `qr_content` (recomendado guardar este valor al generar el QR), extrae los parámetros
`v`, `t` y `m` desde la URL.

Ejemplo:


```
qr_content = "https://clients.qrwey.com/go?v=1&t=YWFh...&m=YmJi..."
```

Extrae:

- `v = 1`
- `t = YWFh...`
- `m = YmJi...`


## Paso 2: Resolver el QR (request)

Ejemplo en DEV:


```bash
curl -X GET "https://api-dev.qrwey.com/api/v1/qrs?v=1&t=YWFh...&m=YmJi..."   -H "X-API-Key: TU_API_KEY"
```

Si estás en PROD, cambia el host a:


```bash
curl -X GET "https://clients.qrwey.com/api/v1/qrs?v=1&t=YWFh...&m=YmJi..."   -H "X-API-Key: TU_API_KEY"
```

## Respuesta (detalle de transacción)

Una respuesta exitosa (`200`) retorna el detalle de la transacción y su desglose.
Ejemplo:


```json
{
  "id": "tra_4aca0361cfcd41c097663db44008fbb9",
  "store": "PetroStation #45",
  "issuer_rfc": "EKU9003173C9",
  "issuer_name": "ESCUELA KEMPER URGATE",
  "amount": 133.0,
  "subtotal": 115.08,
  "currency": "MXN",
  "sat_payment_method": "04",
  "sat_payment_method_desc": "Tarjeta de crédito",
  "created_at": "2025-09-29T13:00:00Z",
  "expires_at": "2025-09-30T23:59:59Z",
  "operation": "INVOICE",
  "operation_data": [
    {
      "sku": "GAS87",
      "description": "Gasolina Magna",
      "amount": 115.08,
      "quantity": 30,
      "sat_unit_key": "LTR",
      "sat_unit_desc": "Litro",
      "unit_price": 20.325,
      "sat_product_service_key": "15101515",
      "sat_product_service_desc": "Gasolina premium mayor o igual a 91 octanos",
      "sat_tax_object_key": "02",
      "sat_tax_object_desc": "Sí objeto de impuesto",
      "taxes": [
        {
          "type": "Traslado",
          "tax": "002",
          "factor": "Tasa",
          "rate": "0.160000",
          "taxable_base": 112.0,
          "amount": 17.92
        }
      ]
    }
  ]
}
```

## ¿Qué debes hacer con la respuesta?

Depende del actor:

### Si eres el comercio (backend)

- Muestra al cliente el detalle de la transacción (**solo si aplica***)
- Guarda el `id` como referencia interna


### App QRwey!:

- Presenta la información al usuario para revisión/confirmación
- Si el usuario esta OK con la información, puede timbrar dicha intención a CFDi con un clic


## Errores comunes al resolver

| Código | Significado | Qué hacer |
|  --- | --- | --- |
| 400 | Parámetros inválidos (`v`, `t` o `m`) / firma inválida | Verifica que copiaste completo `t` y `m` |
| 401 | API Key inválida o ausente | Revisa `X-API-Key` y el ambiente |
| 404 | Token no encontrado (revocado/purgado) | Trata como QR inválido |
| 409 | Token ya consumido (si aplica) | Muestra mensaje de “QR ya utilizado” |
| 410 | QR expirado | Solicita generar uno nuevo |
| 422 | Regla de negocio / configuración | Revisa `code` y `message` en la respuesta |


Consulta: [Manejo de errores](/guides/error-handling)

## Buenas prácticas

- Resuelve siempre desde tu backend (no expongas API Keys)
- Maneja explícitamente `410 Gone` (expiración)
- Trata `404` como “QR inválido” sin filtrar detalles
- Registra `id`, `created_at`, `expires_at` para auditoría y soporte


## ¿Qué sigue?

- Estados y seguridad: [Ciclo de vida del QR](/guides/qr-lifecycle)
- Reintentos seguros: [Idempotencia & Reintentos](/guides/idempotency)
- Contrato completo: [Referencia del API](/apis/qrwey)