Skip to content
Referencia del API/QRs

QRwey! API (1.0.0)

La API de QRwey! permite a los negocios generar códigos QR seguros y efímeros para representar intenciones de autofactura.

  • 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://api.qrwey.com
Entorno de Desarrollo/Pruebas
https://api-dev.qrwey.com

QRs

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

Operations

Generar Código QR

Request

Crea una nueva intención de autofactura 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 intención de autofactura en tres formatos: imagen base64, URL de descarga firmada y contenido de texto (deep link)
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
X-TIME-ZONEstring

Zona horaria para establecer la fecha de emisión (ej. America/Mexico_City).

Example: America/Mexico_City
Bodyapplication/jsonrequired
store_uidstringrequired

Identificador único del punto de venta.

Example: "store_abc123"
sale_idstringrequired

Identificador de la venta proporcionado por el negocio (ej. UUID).

Example: "fcd68791-6a27-412f-a50f-8d47b7bc34d2"
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
currencystring= 3 charactersrequired

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

Example: "MXN"
exchange_ratenumber(double)

Tasa de cambio, necesario si currency es diferente a MXN.

Example: 1
sat_payment_methodstring

Método de pago SAT (PUE o PPD). Default PUE si no se envía.

Default "PUE"
Example: "PUE"
sat_payment_formstring= 2 charactersrequired

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

Example: "04"
type_of_receiptstring

Tipo de comprobante SAT (ej. I Ingreso, E Egreso, P Pago). Default I si no se envía.

Default "I"
Example: "I"
export_codestring

Identifica si la factura ampara una operación de exportación. Default 01 (No aplica) si no se envía.

Default "01"
Example: "01"
expires_atstring(date-time)required

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

Example: "2026-01-03T23:59:59Z"
operationstringrequired

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

Enum"INVOICE""PAYMENT""REFUND"
Example: "INVOICE"
related_cfdisobject or null(RelatedCfdis)

Para Sustitución de facturas o Notas de Crédito.

global_infoobject or null(GlobalInfo)

Para facturas globales. Información relacionada con el comprobante global de operaciones con el público en general.

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. 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[].​discountnumber(double)

Descuento aplicado al concepto.

Example: 0
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.

metadataobject or null

Objeto opcional con datos adicionales del comercio (clave-valor libre).

curl -i -X POST \
  https://developers.qrwey.com/_mock/apis/qrwey/v1/qrs \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -H 'X-TIME-ZONE: America/Mexico_City' \
  -H 'idempotency-key: a8f2d7a6-c5f1-4a94-9a1c-1f7a2c4e6a3b' \
  -d '{
    "store_uid": "store_abc123",
    "sale_id": "fcd68791-6a27-412f-a50f-8d47b7bc34d2",
    "operation": "INVOICE",
    "amount": 133,
    "subtotal": 115.08,
    "currency": "MXN",
    "exchange_rate": 1,
    "sat_payment_method": "PUE",
    "sat_payment_form": "04",
    "expires_at": "2026-01-03T23:59:59Z",
    "type_of_receipt": "I",
    "export_code": "01",
    "related_cfdis": null,
    "global_info": null,
    "metadata": null,
    "operation_data": [
      {
        "sku": "GAS87",
        "description": "Gasolina Magna",
        "amount": 115.08,
        "quantity": 5.662,
        "sat_unit_key": "LTR",
        "unit_price": 20.325,
        "discount": 0,
        "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_idstringrequired

Identificador único de la transacción QR.

Example: "tra_4aca0361cfcd41c097663db44008fbb9"
store_uidstringrequired

Identificador del punto de venta.

Example: "store_abc123"
sale_idstringrequired

Identificador de la venta proporcionado por el negocio.

Example: "fcd68791-6a27-412f-a50f-8d47b7bc34d2"
idempotency_keystringrequired

Clave de idempotencia usada en la solicitud.

Example: "550e8400-e29b-41d4-a716-446655440000"
amountnumber(double)required

Monto total de la transacción.

Example: 133
subtotalnumber(double)required

Subtotal de la transacción.

Example: 115.08
currencystringrequired

Código de moneda ISO 4217.

Example: "MXN"
exchange_ratenumber(double)

Tasa de cambio.

Example: 1
sat_payment_methodstringrequired

Método de pago SAT.

Example: "PUE"
sat_payment_formstringrequired

Forma de pago SAT.

Example: "04"
type_of_receiptstringrequired

Tipo de comprobante SAT.

Example: "I"
export_codestringrequired

Código de exportación.

Example: "01"
operationstringrequired

Tipo de operación.

Example: "INVOICE"
statusstringrequired

Estado actual de la transacción QR.

Enum"PENDING""SCANNED""INVOICED""EXPIRED""CANCELLED"
Example: "PENDING"
operation_dataArray of objects(ResolvedOperationItem)required

Detalle de los conceptos con descripciones SAT resueltas.

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: 5.662
operation_data[].​discountnumber(double)

Descuento aplicado al producto.

Example: 0
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.

metadataobject or null

Datos adicionales del comercio.

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 para ver o descargar la imagen PNG del código QR.

Example: "https://api.qrwey.com/qr.png?t=YWFh..."
qr_contentstringrequired

La URL segura (deep link) contenida en el QR, que incluye el token (t) y la firma HMAC (m).

Example: "https://api.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: "2026-01-01T13:00:00Z"
expires_atstring(date-time)required

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

Example: "2026-01-03T23:59:59Z"
Response
application/json
{
  "qr_id": "tra_4aca0361cfcd41c097663db44008fbb9",
  "store_uid": "store_abc123",
  "sale_id": "fcd68791-6a27-412f-a50f-8d47b7bc34d2",
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 133,
  "subtotal": 115.08,
  "currency": "MXN",
  "exchange_rate": 1,
  "sat_payment_method": "PUE",
  "sat_payment_form": "04",
  "type_of_receipt": "I",
  "export_code": "01",
  "operation": "INVOICE",
  "status": "PENDING",
  "operation_data": [
    { … }
  ],
  "metadata": null,
  "qr_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
  "qr_url": "https://api.qrwey.com/qr.png?t=YWFh...",
  "qr_content": "https://api.qrwey.com/go?v=1&t=YWFh...&m=YmJi...",
  "created_at": "2026-01-01T13:00:00Z",
  "expires_at": "2026-01-03T23:59:59Z"
}

Obtener detalle de QR

Request

Obtiene el detalle completo de una transacción QR usando su identificador único.

Este endpoint permite:

  1. Consultar el estado actual de la transacción (status)
  2. Verificar si la transacción ya fue facturada (campo invoice)
  3. Obtener los datos fiscales del cliente que facturó (campo customer)
  4. Acceder a los datos completos de la transacción con descripciones SAT resueltas

El campo status indica el estado actual de la transacción:

  • PENDING: QR generado, esperando a ser escaneado
  • SCANNED: QR escaneado por el usuario desde la app
  • INVOICED: La intención fue confirmada y el CFDi fue timbrado
  • EXPIRED: El QR alcanzó su fecha expires_at sin ser facturado
  • CANCELLED: El QR fue cancelado manualmente
Security
ApiKeyAuth
Path
qrIdstringrequired

Identificador único de la transacción QR.

Example: tra_4aca0361cfcd41c097663db44008fbb9
curl -i -X GET \
  https://developers.qrwey.com/_mock/apis/qrwey/v1/qrs/tra_4aca0361cfcd41c097663db44008fbb9 \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Detalle de la transacción QR

Bodyapplication/json
qr_idstringrequired

Identificador único de la transacción QR.

Example: "tra_4aca0361cfcd41c097663db44008fbb9"
store_uidstringrequired

Identificador del punto de venta.

Example: "store_abc123"
store_namestring

Nombre del punto de venta.

Example: "PetroStation #45"
sale_idstringrequired

Identificador de la venta proporcionado por el negocio.

Example: "fcd68791-6a27-412f-a50f-8d47b7bc34d2"
idempotency_keystringrequired

Clave de idempotencia usada al generar el QR.

Example: "550e8400-e29b-41d4-a716-446655440000"
operationstringrequired

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

Example: "INVOICE"
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"
exchange_ratenumber(double)

Tasa de cambio, en caso de que currency sea diferente de MXN.

Example: 1
sat_payment_methodstringrequired

Clave del Método de Pago del SAT.

Example: "PUE"
sat_payment_method_descstring

Descripción del método de pago según el catálogo del SAT.

Example: "Pago en una sola exhibición"
sat_payment_formstringrequired

Clave de Forma de Pago del SAT.

Example: "04"
sat_payment_form_descstring

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

Example: "Tarjeta de crédito"
type_of_receiptstringrequired

Tipo de comprobante según el catálogo del SAT.

Example: "I"
type_of_receipt_descstring

Descripción del Tipo de comprobante según el catálogo del SAT.

Example: "Ingreso"
export_codestringrequired

Identifica si la factura ampara una operación de exportación.

Example: "01"
export_code_descstring

Descripción de la clave de exportación.

Example: "No aplica"
statusstringrequired

Estado actual de la transacción QR.

Enum"PENDING""SCANNED""INVOICED""EXPIRED""CANCELLED"
Example: "PENDING"
related_cfdisobject or null(RelatedCfdis)

Para Sustitución de facturas o Notas de Crédito.

global_infoobject or null(GlobalInfo)

Para facturas globales. Información relacionada con el comprobante global de operaciones con el público en general.

operation_dataArray of objects(ResolvedOperationItem)required

Detalle de los conceptos con descripciones SAT resueltas.

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: 5.662
operation_data[].​discountnumber(double)

Descuento aplicado al producto.

Example: 0
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.

metadataobject or null

Datos adicionales del comercio.

invoiceobject or null(QrInvoiceDetail)

Detalle de la factura generada. Presente cuando la transacción ya fue timbrada a CFDi.

customerobject or null(QrCustomerDetail)

Datos fiscales del cliente que completó la facturación.

qr_base64stringrequired

La imagen del QR codificada en base64.

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

URL pública para ver o descargar la imagen PNG del código QR.

Example: "https://api.qrwey.com/qr.png?t=YWFh..."
qr_contentstringrequired

La URL segura (deep link) contenida en el QR.

Example: "https://api.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: "2026-01-01T13:00:00Z"
updated_atstring(date-time)required

Fecha y hora de la última actualización.

Example: "2026-01-01T13:00:00Z"
scanned_atstring or null(date-time)

Fecha y hora en que el QR fue escaneado. Null si aún no ha sido escaneado.

Example: null
expires_atstring(date-time)required

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

Example: "2026-01-03T23:59:59Z"
Response
application/json
{
  "qr_id": "tra_4aca0361cfcd41c097663db44008fbb9",
  "store_uid": "store_abc123",
  "store_name": "PetroStation #45",
  "sale_id": "fcd68791-6a27-412f-a50f-8d47b7bc34d2",
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  "operation": "INVOICE",
  "issuer_rfc": "EKU9003173C9",
  "issuer_name": "ESCUELA KEMPER URGATE",
  "amount": 133,
  "subtotal": 115.08,
  "currency": "MXN",
  "exchange_rate": 1,
  "sat_payment_method": "PUE",
  "sat_payment_method_desc": "Pago en una sola exhibición",
  "sat_payment_form": "04",
  "sat_payment_form_desc": "Tarjeta de crédito",
  "type_of_receipt": "I",
  "type_of_receipt_desc": "Ingreso",
  "export_code": "01",
  "export_code_desc": "No aplica",
  "status": "PENDING",
  "related_cfdis": null,
  "global_info": null,
  "operation_data": [
    { … }
  ],
  "metadata": null,
  "invoice": null,
  "customer": null,
  "qr_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
  "qr_url": "https://api.qrwey.com/qr.png?t=YWFh...",
  "qr_content": "https://api.qrwey.com/go?v=1&t=YWFh...&m=YmJi...",
  "created_at": "2026-01-01T13:00:00Z",
  "updated_at": "2026-01-01T13:00:00Z",
  "scanned_at": null,
  "expires_at": "2026-01-03T23:59:59Z"
}