# Gestión de transacciones

Las **transacciones** representan las operaciones de facturación realizadas a través de un comercio.
Desde la Gestión de Clientes puedes consultar el listado, obtener el detalle completo y cancelar
transacciones pendientes.

## Listar transacciones

### Endpoint

```
GET /v1/qrs/merchants/{merchantId}/transactions
```

**Host (DEV):**

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

**Host (PROD):**

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

### Headers requeridos

```http
Authorization: Bearer {{access_token}}
```

### Path params

| Parámetro | Descripción |
|  --- | --- |
| `merchantId` | ID del comercio (requerido) |


### Query params

| Parámetro | Descripción |
|  --- | --- |
| `transactionId` | Filtrar por ID de transacción (opcional) |
| `status` | Filtrar por estado: `PENDING`, `USED`, `EXPIRED`, `CANCELLED` (opcional) |
| `rfc` | Filtrar por RFC del receptor (opcional) |
| `page` | Número de página (default: 0) |
| `size` | Elementos por página (default: 20) |
| `sort` | Campo y dirección de ordenamiento (ej. `createdAt,desc`) |


### Ejemplo de request (DEV)

```bash
curl -X GET "https://api-dev.qrwey.com/v1/qrs/merchants/mer_4aca0361cfcd41c097663db44008fbb9/transactions?status=USED&page=0&size=10" \
  -H "Authorization: Bearer {{access_token}}"
```

### Respuesta

```json
{
  "content": [
    {
      "transactionId": "qr_8b3f0a61cfcd41c097663db44008fcc1",
      "rfcReceptor": "EKU9003173C9",
      "products": 3,
      "total": 1160.00,
      "createdAt": "2026-03-19T14:30:00Z",
      "expiresAt": "2026-03-19T15:30:00Z",
      "status": "USED"
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "number": 0,
  "size": 10
}
```

### Campos de QrTransactionSummary

| Campo | Descripción |
|  --- | --- |
| `transactionId` | Identificador único de la transacción |
| `rfcReceptor` | RFC del receptor que escaneo el QR |
| `products` | Número de conceptos/productos en la transacción |
| `total` | Monto total de la transacción |
| `createdAt` | Fecha de creación de la transacción |
| `expiresAt` | Fecha de expiración del QR |
| `status` | Estado de la transacción: `ACTIVE`, `PENDING`, `USED`, `EXPIRED`, `CANCELED` |


## Obtener detalle de transacción

### Endpoint

```
GET /v1/qrs/merchants/{merchantId}/transactions/{transactionId}
```

### Headers requeridos

```http
Authorization: Bearer {{access_token}}
```

### Ejemplo de request (DEV)

```bash
curl -X GET "https://api-dev.qrwey.com/v1/qrs/merchants/mer_4aca0361cfcd41c097663db44008fbb9/transactions/qr_8b3f0a61cfcd41c097663db44008fcc1" \
  -H "Authorization: Bearer {{access_token}}"
```

### Respuesta

```json
{
  "transactionId": "qr_8b3f0a61cfcd41c097663db44008fcc1",
  "store": "Estación Reforma Centro",
  "issuerRfc": "FUNK671228PH6",
  "issuerName": "KARLA FUENTE NOLASCO",
  "receiverRfc": "EKU9003173C9",
  "receiverName": "ESCUELA KEMPER URGATE",
  "invoiceStatus": "GENERATED",
  "invoiceUuid": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
  "operation": "SALE",
  "currency": "MXN",
  "amount": 1160.00,
  "subtotal": 1000.00,
  "status": "USED",
  "expiresAt": "2026-03-19T15:30:00Z",
  "createdAt": "2026-03-19T14:30:00Z",
  "qrContent": "https://app.qrwey.com/qr?t=...",
  "qrUrl": "https://app.qrwey.com/qr?t=...",
  "qrBase64": "data:image/png;base64,iVBORw0KGgo...",
  "operationItems": [
    {
      "sku": "GAS87",
      "description": "Gasolina Magna",
      "quantity": 49.210,
      "unitPrice": 20.321,
      "amount": 1000.00,
      "satProductServiceKey": "15101515"
    }
  ]
}
```

### Campos del detalle de transacción

| Campo | Descripción |
|  --- | --- |
| `transactionId` | Identificador único de la transacción |
| `store` | Nombre del comercio |
| `issuerRfc` | RFC del emisor |
| `issuerName` | Razón social del emisor |
| `receiverRfc` | RFC del receptor (si ya fue escaneado/facturado) |
| `receiverName` | Razón social del receptor |
| `invoiceStatus` | Estado de la factura asociada (ej. `GENERATED`, `null`) |
| `invoiceUuid` | UUID fiscal de la factura asociada (si ya fue timbrada) |
| `operation` | Tipo de operación |
| `currency` | Moneda de la transacción |
| `amount` | Monto total |
| `subtotal` | Subtotal antes de impuestos |
| `status` | Estado de la transacción |
| `expiresAt` | Fecha de expiración del QR |
| `createdAt` | Fecha de creación |
| `qrContent` | Contenido codificado del QR |
| `qrUrl` | URL de resolución del QR |
| `qrBase64` | Imagen del QR en formato base64 (data URI) |
| `operationItems` | Lista de conceptos de la operación |
| `operationItems[].sku` | Identificador interno del producto |
| `operationItems[].description` | Descripción del concepto |
| `operationItems[].quantity` | Cantidad |
| `operationItems[].unitPrice` | Precio unitario |
| `operationItems[].amount` | Importe del concepto |
| `operationItems[].satProductServiceKey` | Clave de producto/servicio SAT |


## Cancelar transacción

Cancela una transacción activa o pendiente. Solo se pueden cancelar transacciones con estado `ACTIVE` o `PENDING`.

### Endpoint

```
PATCH /v1/qrs/merchants/{merchantId}/transactions/{transactionId}/cancel
```

### Headers requeridos

```http
Authorization: Bearer {{access_token}}
```

### Ejemplo de request (DEV)

```bash
curl -X PATCH "https://api-dev.qrwey.com/v1/qrs/merchants/mer_4aca0361cfcd41c097663db44008fbb9/transactions/qr_8b3f0a61cfcd41c097663db44008fcc1/cancel" \
  -H "Authorization: Bearer {{access_token}}"
```

### Respuesta

```
HTTP/1.1 200 OK
```

La operación no devuelve cuerpo en la respuesta.

## Errores comunes

| Código | Motivo |
|  --- | --- |
| 400 | La transacción no está en estado `ACTIVE` o `PENDING` y no puede ser cancelada |
| 401 | Token inválido o expirado |
| 404 | Transacción o comercio no encontrado, o no pertenece a tu cuenta |


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

## Buenas prácticas

- Usa los filtros de `status` y `rfc` para localizar transacciones rápidamente
- Cancela transacciones pendientes que ya no serán facturadas para mantener el orden
- Consulta el detalle de la transacción para verificar la información de facturación antes de generar el CFDI


## ¿Qué sigue?

- Consulta reportes de consumo: [Reportes del cliente](/guides/customer-reports)
- Timbra un CFDI: [Timbrar CFDI 4.0](/guides/stamp-cfdi)
- Vuelve al índice: [Gestión de Clientes](/guides/customer-portal)