Skip to content
/
Resolver código QR
Last updated

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

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:

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:

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:

{
  "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ódigoSignificadoQué hacer
400Parámetros inválidos (v, t o m) / firma inválidaVerifica que copiaste completo t y m
401API Key inválida o ausenteRevisa X-API-Key y el ambiente
404Token no encontrado (revocado/purgado)Trata como QR inválido
409Token ya consumido (si aplica)Muestra mensaje de “QR ya utilizado”
410QR expiradoSolicita generar uno nuevo
422Regla de negocio / configuraciónRevisa code y message en la respuesta

Consulta: Manejo de errores

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?

Previous page
Next page