# Generar Código QR

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

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

## Header parameters:

  - `Idempotency-Key` (string, required)
    Clave única (ej. UUID) generada por el cliente para garantizar que la solicitud pueda reintentarse de forma segura sin crear transacciones duplicadas. Si el servidor ve la misma clave, devolverá la respuesta original.
    Example: "a8f2d7a6-c5f1-4a94-9a1c-1f7a2c4e6a3b"

## Request fields (application/json):

  - `store` (string, required)
    Identificador único de la tienda que realiza la venta.
    Example: "PetroStation #45"

  - `issuer_rfc` (string)
    RFC del emisor de la factura. Útil cuando el comercio tiene más de un emisor y no desea usar el predeterminado.
    Example: "EKU9003173C9"

  - `amount` (number, required)
    Monto total de la transacción. Debe coincidir con la suma de los productos. 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 de 3 letras en formato ISO 4217 (ej. 'MXN', 'USD').
    Example: "MXN"

  - `sat_payment_method` (string, required)
    Clave de Forma de Pago de 2 caracteres según el catálogo del SAT (forma_pago).
    Example: "04"

  - `expires_at` (string, required)
    Fecha y hora de expiración del QR en formato ISO 8601. Después de este momento, el QR será inválido.
    Example: "2025-11-01T23:59:59Z"

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

  - `operation_data` (array, required)
    Un arreglo de objetos, donde cada objeto representa un producto o servicio.

  - `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, es la multiplicación del precio unitario por la cantidad (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: 5.662

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

  - `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 de 8 dígitos según el catálogo del SAT (clave_prod_serv).
    Example: "15101515"

  - `operation_data.sat_tax_object_key` (string, required)
    Clave que indica si el concepto es objeto de impuesto según el catálogo del SAT (objeto_imp).
    Example: "02"

  - `operation_data.taxes` (array)
    Arreglo de impuestos aplicables al concepto. Si el valor de sat_tax_object_key es '01' este valor no debe ser informado, en el resto de opciones aplican las reglas del SAT.

  - `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 201 fields (application/json):

  - `qr_base64` (string, required)
    La imagen del QR codificada en base64, lista para ser incrustada o impresa.
    Example: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."

  - `qr_url` (string, required)
    Una URL pública, firmada y de corta duración para ver o descargar la imagen PNG del código QR. Evita la enumeración de QRs.
    Example: "https://clients.qrwey.com/qr.png?t=YWFh...&exp=1696200000&sig=YmJi..."

  - `qr_content` (string, required)
    La URL segura (deep link) contenida en el QR, que incluye el token (t) y la firma HMAC (m).
    Example: "https://clients.qrwey.com/go?v=1&t=YWFh...&m=YmJi..."

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

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

## 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 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 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."