> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cucu.bo/llms.txt
> Use this file to discover all available pages before exploring further.

# Buenas prácticas de integración

> Flujo recomendado, imagen del QR, conciliación y ambientes.

## Buenas prácticas de integración

***

## Flujo recomendado

```
1. Registra tu webhook →  POST /api/v1/webhook  (una vez, no por cobro)
2. Crea el QR          →  POST /api/v1/qr  (con Idempotency-Key)
3. Muestra la imagen   →  qrImageUrl (o qrImageBase64 si es null)
4. Te avisamos         →  qr.paid en tu webhook → confirma la orden (por externalReference)
5. Consulta puntual    →  GET /api/v1/qr/{qrId} si necesitas verificar uno
```

***

## Imagen del QR

```html theme={"system"}
<!-- Preferir la URL: se cachea y no satura tu servidor -->
<img src="{{ qr.qrImageUrl }}" alt="QR de pago" />

<!-- Base64 si qrImageUrl es null -->
<img src="data:image/png;base64,{{ qr.qrImageBase64 }}" alt="QR de pago" />
```

***

## Conciliación

* Usa `externalReference` para mapear cada QR a tu orden interna.
* `metadata` es libre: pasa ahí el contexto (canal, SKU, sesión); vuelve en la consulta de estado.
* No uses el `qrId` como clave primaria de tu base: concilia por `externalReference`.

***

## Ambientes

| Ambiente          | Base URL                                                         |
| ----------------- | ---------------------------------------------------------------- |
| Pruebas (sandbox) | `https://qrsimple.cucu.bo/api/v1`                                |
| Producción        | Se habilita al pasar a producción, con tu API key de producción. |

Las llaves de pruebas y de producción son distintas. Nunca uses credenciales de producción en pruebas.