Skip to content
Referencia del API/
/
Resolver Código QR

QRwey! API (1.2.0)

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.
Download OpenAPI description
QRwey.json
QRwey.yaml
Languages
Servers
Mock server
https://developers.qrwey.com/_mock/apis/qrwey/
Entorno de Producción
https://clients.qrwey.com/
Entorno de Desarrollo/Pruebas
https://api-dev.qrwey.com/

QRs

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

Operations

Generar Código QR

Request

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
Security
ApiKeyAuth
Headers
Idempotency-Keystring(uuid)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
Bodyapplication/jsonrequired
storestringrequired

Identificador único de la tienda que realiza la venta.

Example: "PetroStation #45"
issuer_rfcstring

RFC del emisor de la factura. Útil cuando el comercio tiene más de un emisor y no desea usar el predeterminado.

Example: "EKU9003173C9"
amountnumber(double)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
subtotalnumber(double)required

Subtotal de la transacción. Precisión: Hasta nueve enteros con seis decimales (15, 6).

Example: 115.08
currencystring= 3 charactersrequired

Código de moneda de 3 letras en formato ISO 4217 (ej. 'MXN', 'USD').

Example: "MXN"
sat_payment_methodstring= 2 charactersrequired

Clave de Forma de Pago de 2 caracteres según el catálogo del SAT (forma_pago).

Example: "04"
expires_atstring(date-time)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"
operationstringrequired

Tipo de operación: INVOICE, PAYMENT, REFUND.

Enum"INVOICE""PAYMENT""REFUND"
Example: "INVOICE"
operation_dataArray of objects(OperationItem)required

Un arreglo de objetos, donde cada objeto representa un producto o servicio.

operation_data[].​skustring

Identificador único de producto (SKU) para control interno.

Example: "GAS87"
operation_data[].​descriptionstringrequired

Descripción del producto o servicio.

Example: "Gasolina Magna"
operation_data[].​amountnumber(double)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[].​quantitynumber(double)required

Número de unidades vendidas. Precisión: Hasta nueve enteros con seis decimales (15, 6).

Example: 5.662
operation_data[].​sat_unit_keystring<= 3 charactersrequired

Clave de Unidad de hasta 3 caracteres según el catálogo del SAT (clave_unidad).

Example: "LTR"
operation_data[].​unit_pricenumber(double)required

Precio unitario del producto. Precisión: Hasta nueve enteros con seis decimales (15, 6).

Example: 20.325
operation_data[].​sat_product_service_keystring= 8 charactersrequired

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_keystringrequired

Clave que indica si el concepto es objeto de impuesto según el catálogo del SAT (objeto_imp).

Example: "02"
operation_data[].​taxesArray of objects(TaxItem)

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.

curl -i -X POST \
  https://developers.qrwey.com/_mock/apis/qrwey/api/v1/qrs \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: a8f2d7a6-c5f1-4a94-9a1c-1f7a2c4e6a3b' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "store": "PetroStation #45",
    "issuer_rfc": "EKU9003173C9",
    "amount": 133,
    "subtotal": 115.08,
    "currency": "MXN",
    "sat_payment_method": "04",
    "expires_at": "2025-11-01T23:59:59Z",
    "operation": "INVOICE",
    "operation_data": [
      {
        "sku": "GAS87",
        "description": "Gasolina Magna",
        "amount": 115.08,
        "quantity": 5.662,
        "sat_unit_key": "LTR",
        "unit_price": 20.325,
        "sat_product_service_key": "15101515",
        "sat_tax_object_key": "02",
        "taxes": [
          {
            "type": "Traslado",
            "tax": "002",
            "factor": "Tasa",
            "rate": "0.160000",
            "taxable_base": 112,
            "amount": 17.92
          }
        ]
      }
    ]
  }'

Responses

QR generado exitosamente

Bodyapplication/json
qr_base64stringrequired

La imagen del QR codificada en base64, lista para ser incrustada o impresa.

Example: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
qr_urlstringrequired

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_contentstringrequired

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_atstring(date-time)required

Fecha y hora de creación de la transacción en formato ISO 8601.

Example: "2025-09-11T18:25:43Z"
expires_atstring(date-time)required

Fecha y hora de expiración del código QR en formato ISO 8601.

Example: "2025-09-30T23:59:59Z"
Response
application/json
{
  "qr_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
  "qr_url": "https://clients.qrwey.com/qr.png?t=YWFh...&exp=1696200000&sig=YmJi...",
  "qr_content": "https://clients.qrwey.com/go?v=1&t=YWFh...&m=YmJi...",
  "created_at": "2025-09-11T18:25:43Z",
  "expires_at": "2025-09-30T23:59:59Z"
}

Resolver Código QR

Request

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
Security
ApiKeyAuth
Query
vstringrequired

Versión del formato del QR (actualmente '1').

Example: v=1
tstringrequired

El token opaco (Base64URL) extraído del QR.

Example: t=YWFhYWFh...
mstringrequired

El Message Authentication Code (Base64URL), que es la firma HMAC truncada que valida la integridad del token.

Example: m=YmJiYmJi...
curl -i -X GET \
  'https://developers.qrwey.com/_mock/apis/qrwey/api/v1/qrs?v=1&t=YWFhYWFh...&m=YmJiYmJi...' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Transacción resuelta exitosamente

Bodyapplication/json
idstringrequired

ID único de la transacción.

Example: "tra_4aca0361cfcd41c097663db44008fbb9"
storestringrequired

Identificador de la tienda.

Example: "PetroStation #45"
issuer_rfcstring

RFC del emisor.

Example: "EKU9003173C9"
issuer_namestring

Nombre o razón social del emisor.

Example: "ESCUELA KEMPER URGATE"
amountnumber(double)required

Monto total de la transacción. Precisión: Hasta nueve enteros con seis decimales (15, 6).

Example: 133
subtotalnumber(double)required

Subtotal de la transacción. Precisión: Hasta nueve enteros con seis decimales (15, 6).

Example: 115.08
currencystringrequired

Código de moneda ISO 4217.

Example: "MXN"
sat_payment_methodstringrequired

Clave de Forma de Pago del SAT.

Example: "04"
sat_payment_method_descstring

Descripción de la forma de pago según el catálogo del SAT.

Example: "Tarjeta de crédito"
created_atstring(date-time)required

Fecha y hora de creación de la transacción en formato ISO 8601.

Example: "2025-09-29T13:00:00Z"
expires_atstring(date-time)required

Fecha y hora de expiración del código QR en formato ISO 8601.

Example: "2025-09-30T23:59:59Z"
operationstringrequired

Tipo de operación: INVOICE, PAYMENT, REFUND.

Example: "INVOICE"
operation_dataArray of objects(ResolvedOperationItem)required
operation_data[].​skustring

Identificador único de producto (SKU) para control interno.

Example: "GAS87"
operation_data[].​descriptionstringrequired

Descripción del producto o servicio.

Example: "Gasolina Magna"
operation_data[].​amountnumber(double)required

Monto total del concepto (unit_price * quantity). Precisión: Hasta nueve enteros con seis decimales (15, 6).

Example: 115.08
operation_data[].​quantitynumber(double)required

Número de unidades vendidas. Precisión: Hasta nueve enteros con seis decimales (15, 6).

Example: 30
operation_data[].​sat_unit_keystringrequired

Clave de Unidad según el catálogo del SAT.

Example: "LTR"
operation_data[].​sat_unit_descstringrequired

Descripción de la clave de unidad del SAT.

Example: "Litro"
operation_data[].​unit_pricenumber(double)required

Precio unitario del producto. Precisión: Hasta nueve enteros con seis decimales (15, 6).

Example: 20.325
operation_data[].​sat_product_service_keystringrequired

Clave de Producto/Servicio según el catálogo del SAT.

Example: "15101515"
operation_data[].​sat_product_service_descstringrequired

Descripción de la clave de producto/servicio del SAT.

Example: "Gasolina premium mayor o igual a 91 octanos"
operation_data[].​sat_tax_object_keystringrequired

Clave que indica si el concepto es objeto de impuesto.

Example: "02"
operation_data[].​sat_tax_object_descstringrequired

Descripción de la clave de objeto de impuesto del SAT.

Example: "Sí objeto de impuesto"
operation_data[].​taxesArray of objects(TaxItem)

Arreglo de impuestos aplicables al concepto.

Response
application/json
{
  "id": "tra_4aca0361cfcd41c097663db44008fbb9",
  "store": "PetroStation #45",
  "issuer_rfc": "EKU9003173C9",
  "issuer_name": "ESCUELA KEMPER URGATE",
  "amount": 133,
  "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": [
    { … }
  ]
}