> ## 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, uso de imágenes QR, conciliación y configuración de ambientes.

## Buenas prácticas de integración

***

## Flujo de integración recomendado

```
1. Comercio crea QR  →  POST /transfers/qr  (con Idempotency-Key)
2. Mostrar qrImageUrl al usuario final (o qrImageBase64 como fallback)
3. Esperar webhook de confirmación en endpoint propio del comercio
4. Si no llega webhook en X segundos  →  GET /transfers/qr/{id}  (polling)
5. Al recibir status PAID  →  confirmar orden en sistema del comercio
```

***

## Uso de la imagen QR

```html theme={"system"}
<!-- Preferir URL CDN: se puede almacenar en caché y no satura el servidor -->
<img src="{{ transaction.qrImageUrl }}" alt="QR de pago CUCU" />

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

***

## Conciliación

* Usar `externalReference` para mapear cada transacción CUCU a la orden interna del comercio.
* El campo `metadata` es libre — úsarlo para pasar datos de contexto (canal, SKU, sesión) que serán devueltos en la consulta de estado y en los webhooks.
* No usar el `transactionId` de CUCU como clave primaria en la base de datos del comercio — usar `externalReference` como llave de conciliación.

***

## Ambientes

| Ambiente          | Base URL                             |
| ----------------- | ------------------------------------ |
| Staging (pruebas) | `https://pay-staging.cucu.bo/api/v1` |
| Producción        | `https://qrsimple.cucu.bo/api/v1`    |

Los tokens de staging y producción son distintos. Nunca usar credenciales de producción en pruebas.