# Obtener detalle de QR

En QRwey!, **obtener el detalle** de un código QR significa consultar la información completa
de la transacción asociada usando su identificador único (`qr_id`).

Esto te permite verificar el estado actual de la transacción, consultar si ya fue facturada,
y obtener los datos fiscales completos.

## Endpoint


```
GET /v1/qrs/{qrId}
```

**Host (DEV):**


```
https://api-dev.qrwey.com
```

**Host (PROD):**


```
https://api.qrwey.com
```

## Headers requeridos


```http
X-API-Key: TU_API_KEY
```

## Path parameters

| Parámetro | Descripción |
|  --- | --- |
| `qrId` | Identificador único de la transacción QR (ej. `tra_4aca0361cfcd41c097663db44008fbb9`) |


## Ejemplo de request (DEV)


```bash
curl -X GET "https://api-dev.qrwey.com/v1/qrs/tra_4aca0361cfcd41c097663db44008fbb9" \
  -H "X-API-Key: TU_API_KEY"
```

Si estás en PROD, cambia el host a:


```bash
curl -X GET "https://api.qrwey.com/v1/qrs/tra_4aca0361cfcd41c097663db44008fbb9" \
  -H "X-API-Key: TU_API_KEY"
```

## Respuesta (detalle de transacción)

Una respuesta exitosa (`200`) retorna el detalle completo de la transacción y su desglose.

### Campos principales

| Campo | Descripción |
|  --- | --- |
| `qr_id` | Identificador único de la transacción QR |
| `store_uid` | Identificador del punto de venta |
| `store_name` | Nombre del punto de venta |
| `sale_id` | Identificador de la venta del comercio |
| `idempotency_key` | Clave de idempotencia usada al generar el QR |
| `issuer_rfc` | RFC del emisor |
| `issuer_name` | Razón social del emisor |
| `amount` | Total de la operación |
| `subtotal` | Subtotal antes de impuestos |
| `currency` | Moneda |
| `exchange_rate` | Tasa de cambio |
| `sat_payment_form` | Forma de pago SAT |
| `sat_payment_form_desc` | Descripción de la forma de pago |
| `sat_payment_method` | Método de pago SAT |
| `sat_payment_method_desc` | Descripción del método de pago |
| `type_of_receipt` | Tipo de comprobante SAT |
| `type_of_receipt_desc` | Descripción del tipo de comprobante |
| `export_code` | Código de exportación |
| `export_code_desc` | Descripción del código de exportación |
| `operation` | Tipo de operación |
| `status` | Estado actual de la transacción |
| `operation_data` | Conceptos del CFDI |
| `related_cfdis` | CFDIs relacionados (si aplica) |
| `global_info` | Información de factura global (si aplica) |
| `metadata` | Datos adicionales del comercio |
| `invoice` | Detalle de la factura generada (si aplica) |
| `customer` | Datos fiscales del cliente que facturó (si aplica) |
| `qr_base64` | Imagen del QR en Base64 |
| `qr_url` | URL de la imagen del QR |
| `qr_content` | Contenido codificado del QR (deep link) |
| `created_at` | Fecha de creación |
| `updated_at` | Fecha de última actualización |
| `scanned_at` | Fecha en que fue escaneado |
| `expires_at` | Fecha de expiración |


### Detalle de factura (`invoice`)

Presente cuando la transacción ya fue timbrada a CFDi:

| Campo | Descripción |
|  --- | --- |
| `uuid` | Folio fiscal (UUID del CFDI) |
| `status` | Estado de la factura |
| `total` | Total facturado |
| `subtotal` | Subtotal facturado |
| `issued_at` | Fecha de emisión |
| `xml_url` | URL del archivo XML |
| `pdf_url` | URL del archivo PDF |


### Detalle del cliente (`customer`)

Presente cuando un cliente ya completó la facturación:

| Campo | Descripción |
|  --- | --- |
| `rfc` | RFC del receptor |
| `name` | Razón social del receptor |
| `tax_regime` | Régimen fiscal SAT |
| `postal_code` | Código postal fiscal |


### Conceptos (`operation_data`)

Cada elemento representa un concepto del CFDI:

| Campo | Descripción |
|  --- | --- |
| `sku` | Identificador interno del producto |
| `description` | Descripción del concepto |
| `amount` | Importe del concepto |
| `quantity` | Cantidad |
| `discount` | Descuento aplicado |
| `sat_unit_key` | Clave de unidad SAT |
| `sat_unit_desc` | Descripción de la unidad SAT |
| `unit_price` | Precio unitario |
| `sat_product_service_key` | Clave producto / servicio SAT |
| `sat_product_service_desc` | Descripción del producto / servicio SAT |
| `sat_tax_object_key` | Clave de objeto de impuesto SAT |
| `sat_tax_object_desc` | Descripción del objeto de impuesto |
| `taxes` | Impuestos aplicables |


### Impuestos del concepto (`taxes`)

| Campo | Descripción |
|  --- | --- |
| `type` | Tipo de impuesto SAT (`Traslado`, `Retencion`) |
| `tax` | Clave del impuesto SAT (ej. `002` IVA) |
| `factor` | Tipo de Factor SAT (`Tasa`, `Cuota`, `Exento`) |
| `rate` | La tasa o cuota del impuesto |
| `taxable_base` | La base imponible sobre la cual se calcula el impuesto |
| `amount` | El monto del impuesto |


### CFDIs relacionados (`related_cfdis`)

| Campo | Descripción |
|  --- | --- |
| `tipo_relacion` | Tipo de relación entre CFDI (ej. `04` Sustitución de los CFDI previos) |
| `cfdis` | Listado con los UUID de los CFDIs relacionados |


### Factura global (`global_info`)

| Campo | Descripción |
|  --- | --- |
| `periodicity` | Catálogo Periodicidad SAT (ej. `04` Mensual) |
| `months` | Catálogo Meses SAT (ej. `12` Diciembre) |
| `year` | Año a cuatro dígitos |


### Ejemplo de respuesta


```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",
  "issuer_rfc": "EKU9003173C9",
  "issuer_name": "ESCUELA KEMPER URGATE",
  "amount": 133.00,
  "subtotal": 115.08,
  "currency": "MXN",
  "exchange_rate": 1.0,
  "sat_payment_form": "04",
  "sat_payment_form_desc": "Tarjeta de crédito",
  "sat_payment_method": "PUE",
  "sat_payment_method_desc": "Pago en una sola exhibición",
  "type_of_receipt": "I",
  "type_of_receipt_desc": "Ingreso",
  "export_code": "01",
  "export_code_desc": "No aplica",
  "operation": "INVOICE",
  "status": "PENDING",
  "operation_data": [
    {
      "sku": "GAS87",
      "description": "Gasolina Magna",
      "amount": 115.08,
      "quantity": 5.662,
      "discount": 0.00,
      "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
        }
      ]
    }
  ],
  "related_cfdis": null,
  "global_info": null,
  "metadata": null,
  "invoice": null,
  "customer": null,
  "qr_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
  "qr_url": "https://api.qrwey.com/qr.png?...",
  "qr_content": "https://api.qrwey.com/go?v=1&t=...&m=...",
  "created_at": "2026-01-01T13:00:00Z",
  "updated_at": "2026-01-01T13:00:00Z",
  "scanned_at": null,
  "expires_at": "2026-01-03T23:59:59Z"
}
```

## ¿Qué debes hacer con la respuesta?

Depende del actor:

### Si eres el comercio (backend)

- Consulta el `status` para conocer el estado actual de la transacción
- Si `invoice` no es `null`, la factura ya fue generada y puedes obtener el XML/PDF
- Guarda el `qr_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

| Código | Significado | Qué hacer |
|  --- | --- | --- |
| 401 | API Key inválida o ausente | Revisa `X-API-Key` y el ambiente |
| 404 | Transacción no encontrada | Verifica que el `qr_id` sea correcto |
| 422 | Regla de negocio / configuración | Revisa `code` y `message` en la respuesta |


Consulta: [Manejo de errores](/guides/error-handling)

## Buenas prácticas

- Consulta siempre desde tu backend (no expongas API Keys)
- Registra `qr_id`, `status`, `created_at`, `expires_at` para auditoría y soporte
- Verifica el campo `invoice` para saber si la transacción ya fue facturada


## ¿Qué sigue?

- Estados y seguridad: [Ciclo de vida del QR](/guides/qr-lifecycle)
- Reintentos seguros: [Idempotencia & Reintentos](/guides/idempotency)
- Contrato completo: [Referencia del API](/apis/qrwey)