# Generar código QR

En QRwey!, **generar un código QR** significa crear una **intención de autofactura**
asociada a una transacción específica.

Este QR representa una operación fiscal pendiente que:

- Tiene un monto definido
- Tiene una expiración
- Está firmada y protegida
- Puede convertirse en un CFDI timbrado cuando el usuario la confirma


## ¿Cuándo generar un QR?

Normalmente debes generar un QR cuando:

- Se completa una venta
- Se imprime un ticket
- El cliente solicita factura
- Deseas habilitar autofactura sin capturas manuales


Cada QR debe representar **una sola transacción**.

## Endpoint


```
POST /api/v1/qrs
```

**Host (DEV):**


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

**Host (PROD):**


```
https://clients.qrwey.com
```

## Headers requeridos


```http
X-API-Key: TU_API_KEY
Idempotency-Key: <uuid>
Content-Type: application/json
```

- `X-API-Key` autentica la solicitud
- `Idempotency-Key` evita duplicados en reintentos


> ⚠️ Usa **el mismo Idempotency-Key** si reintentas la operación.


## Request body

El cuerpo de la solicitud describe completamente la transacción fiscal.

### Campos principales

| Campo | Descripción |
|  --- | --- |
| `store` | Identificador o nombre del punto de venta |
| `issuer_rfc` | RFC del emisor configurado en QRwey! |
| `amount` | Total de la operación |
| `subtotal` | Subtotal antes de impuestos |
| `currency` | Moneda (MXN) |
| `sat_payment_method` | Forma de pago SAT |
| `expires_at` | Fecha/hora de expiración del QR |
| `operation` | Tipo de operación (ej. `INVOICE`) |


### Detalle de conceptos (`operation_data`)

Cada elemento representa un concepto del CFDI:

| Campo | Descripción |
|  --- | --- |
| `sku` | Identificador interno del producto |
| `description` | Descripción del concepto |
| `quantity` | Cantidad |
| `unit_price` | Precio unitario |
| `amount` | Importe del concepto |
| `sat_unit_key` | Clave SAT de unidad |
| `sat_product_service_key` | Clave SAT producto/servicio |
| `sat_tax_object_key` | Objeto de impuesto |
| `taxes` | Impuestos aplicables |


## Ejemplo de request (DEV)


```bash
curl -X POST "https://api-dev.qrwey.com/api/v1/qrs"   -H "X-API-Key: TU_API_KEY"   -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000"   -H "Content-Type: application/json"   -d '{
    "store": "PetroStation #45",
    "issuer_rfc": "EKU9003173C9",
    "amount": 133.00,
    "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",
        "quantity": 5.662,
        "unit_price": 20.325,
        "amount": 115.08,
        "sat_unit_key": "LTR",
        "sat_product_service_key": "15101515",
        "sat_tax_object_key": "02",
        "taxes": [
          {
            "type": "Traslado",
            "tax": "002",
            "factor": "Tasa",
            "rate": "0.160000",
            "taxable_base": 112.0,
            "amount": 17.92
          }
        ]
      }
    ]
  }'
```

## Respuesta


```json
{
  "qr_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
  "qr_url": "https://clients.qrwey.com/qr.png?...",
  "qr_content": "https://clients.qrwey.com/go?v=1&t=...&m=...",
  "created_at": "2025-09-11T18:25:43Z",
  "expires_at": "2025-11-01T23:59:59Z"
}
```

### ¿Qué debes guardar?

- `qr_content`: **valor principal**
- `expires_at`: control de vigencia
- `qr_url` o `qr_base64`: para mostrar o imprimir


## Errores comunes

| Código | Motivo |
|  --- | --- |
| 400 | Campos inválidos o faltantes |
| 401 | API Key inválida |
| 409 | Solicitud duplicada |
| 410 | QR expirado |
| 422 | Error de reglas de negocio |


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

## Buenas prácticas

- Genera el QR **una sola vez por venta**
- Define expiraciones realistas conforme a las reglas del negocio (ej. 5 días, hasta fin de mes, etc.)
- Maneja explícitamente errores `409` y `410`


## ¿Qué sigue?

- Resolver un QR: [Resolver código QR](/guides/resolve-qr)
- Entender estados: [Ciclo de vida del QR](/guides/qr-lifecycle)
- Detalle completo: [Referencia del API](/apis/qrwey)