# Resolver Código QR

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

Endpoint: GET /api/v1/qrs
Version: 1.2.0
Security: ApiKeyAuth

## Query parameters:

  - `v` (string, required)
    Versión del formato del QR (actualmente '1').
    Example: "1"

  - `t` (string, required)
    El token opaco (Base64URL) extraído del QR.
    Example: "YWFhYWFh..."

  - `m` (string, required)
    El Message Authentication Code (Base64URL), que es la firma HMAC truncada que valida la integridad del token.
    Example: "YmJiYmJi..."

## Response 200 fields (application/json):

  - `id` (string, required)
    ID único de la transacción.
    Example: "tra_4aca0361cfcd41c097663db44008fbb9"

  - `store` (string, required)
    Identificador de la tienda.
    Example: "PetroStation #45"

  - `issuer_rfc` (string)
    RFC del emisor.
    Example: "EKU9003173C9"

  - `issuer_name` (string)
    Nombre o razón social del emisor.
    Example: "ESCUELA KEMPER URGATE"

  - `amount` (number, required)
    Monto total de la transacción. Precisión: Hasta nueve enteros con seis decimales (15, 6).
    Example: 133

  - `subtotal` (number, required)
    Subtotal de la transacción. Precisión: Hasta nueve enteros con seis decimales (15, 6).
    Example: 115.08

  - `currency` (string, required)
    Código de moneda ISO 4217.
    Example: "MXN"

  - `sat_payment_method` (string, required)
    Clave de Forma de Pago del SAT.
    Example: "04"

  - `sat_payment_method_desc` (string)
    Descripción de la forma de pago según el catálogo del SAT.
    Example: "Tarjeta de crédito"

  - `created_at` (string, required)
    Fecha y hora de creación de la transacción en formato ISO 8601.
    Example: "2025-09-29T13:00:00Z"

  - `expires_at` (string, required)
    Fecha y hora de expiración del código QR en formato ISO 8601.
    Example: "2025-09-30T23:59:59Z"

  - `operation` (string, required)
    Tipo de operación: INVOICE, PAYMENT, REFUND.
    Example: "INVOICE"

  - `operation_data` (array, required)

  - `operation_data.sku` (string)
    Identificador único de producto (SKU) para control interno.
    Example: "GAS87"

  - `operation_data.description` (string, required)
    Descripción del producto o servicio.
    Example: "Gasolina Magna"

  - `operation_data.amount` (number, required)
    Monto total del concepto (unit_price * quantity). Precisión: Hasta nueve enteros con seis decimales (15, 6).
    Example: 115.08

  - `operation_data.quantity` (number, required)
    Número de unidades vendidas. Precisión: Hasta nueve enteros con seis decimales (15, 6).
    Example: 30

  - `operation_data.sat_unit_key` (string, required)
    Clave de Unidad según el catálogo del SAT.
    Example: "LTR"

  - `operation_data.sat_unit_desc` (string, required)
    Descripción de la clave de unidad del SAT.
    Example: "Litro"

  - `operation_data.unit_price` (number, required)
    Precio unitario del producto. Precisión: Hasta nueve enteros con seis decimales (15, 6).
    Example: 20.325

  - `operation_data.sat_product_service_key` (string, required)
    Clave de Producto/Servicio según el catálogo del SAT.
    Example: "15101515"

  - `operation_data.sat_product_service_desc` (string, required)
    Descripción de la clave de producto/servicio del SAT.
    Example: "Gasolina premium mayor o igual a 91 octanos"

  - `operation_data.sat_tax_object_key` (string, required)
    Clave que indica si el concepto es objeto de impuesto.
    Example: "02"

  - `operation_data.sat_tax_object_desc` (string, required)
    Descripción de la clave de objeto de impuesto del SAT.
    Example: "Sí objeto de impuesto"

  - `operation_data.taxes` (array)
    Arreglo de impuestos aplicables al concepto.

  - `operation_data.taxes.type` (string, required)
    Define el tipo de impuesto. Valores válidos: 'Traslado' o 'Retencion'.
    Enum: "Traslado", "Retencion"

  - `operation_data.taxes.tax` (string, required)
    La clave del impuesto según el catálogo del SAT (ej. '002' para IVA, '001' para ISR).
    Example: "002"

  - `operation_data.taxes.factor` (string, required)
    El tipo de factor aplicable según el catálogo del SAT: Tasa, Cuota, Exento.
    Enum: "Tasa", "Cuota", "Exento"

  - `operation_data.taxes.rate` (string, required)
    La tasa o cuota del impuesto en su valor numérico (ej. 0.160000 para el 16% de IVA).
    Example: "0.160000"

  - `operation_data.taxes.taxable_base` (number, required)
    La base imponible sobre la cual se calcula el impuesto. Generalmente es quantity * unit_price. Precisión: Hasta nueve enteros con seis decimales (15, 6).
    Example: 112

  - `operation_data.taxes.amount` (number, required)
    El monto total del impuesto ya calculado (taxable_base * rate), listo para ser timbrado. Precisión: Hasta nueve enteros con seis decimales (15, 6).
    Example: 17.92

## Response 400 fields (application/json):

  - `error` (string, required)
    Tipo de error
    Example: "Bad Request"

  - `code` (integer, required)
    Código de estado HTTP
    Example: 400

  - `message` (string, required)
    Descripción detallada del error
    Example: "Error de Validación. Ocurre si faltan campos, los tipos de datos son incorrectos, la firma HMAC es inválida o expires_at es una fecha pasada."

## Response 401 fields (application/json):

  - `error` (string, required)
    Tipo de error
    Example: "Unauthorized"

  - `code` (integer, required)
    Código de estado HTTP
    Example: 401

  - `message` (string, required)
    Descripción detallada del error
    Example: "API Key inválida o ausente"

## Response 404 fields (application/json):

  - `error` (string, required)
    Tipo de error
    Example: "Not Found"

  - `code` (integer, required)
    Código de estado HTTP
    Example: 404

  - `message` (string, required)
    Descripción detallada del error
    Example: "Token no Encontrado. El token proporcionado nunca fue emitido, fue revocado o ya fue purgado de la base de datos después de expirar."

## Response 409 fields (application/json):

  - `error` (string, required)
    Tipo de error
    Example: "Conflict"

  - `code` (integer, required)
    Código de estado HTTP
    Example: 409

  - `message` (string, required)
    Descripción detallada del error
    Example: "Token ya Consumido. El token es válido pero ya fue utilizado para generar una factura (cuando la política es de un solo uso)."

## Response 410 fields (application/json):

  - `error` (string, required)
    Tipo de error
    Example: "Gone"

  - `code` (integer, required)
    Código de estado HTTP
    Example: 410

  - `message` (string, required)
    Descripción detallada del error
    Example: "QR Expirado. El cliente intentó escanear el QR después de la fecha y hora indicadas en expires_at."

## Response 422 fields (application/json):

  - `error` (string, required)
    Tipo de error
    Example: "Unprocessable Entity"

  - `code` (integer, required)
    Código de estado HTTP
    Example: 422

  - `message` (string, required)
    Descripción detallada del error
    Example: "Error de Negocio. Ocurre si la empresa asociada al issuer_rfc no está configurada correctamente en el sistema."