> ## 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.

# Guía de Integración Rápida

> Tres pasos para salir a producción: configuración inicial, flujo de pago e implementación del receptor de webhooks.

## Guía de Integración Rápida

***

## Paso 1 — Configuración inicial

1. Solicita tu `X-API-Key` al equipo de CUCU.
2. Registra tu URL de webhook:

```bash theme={"system"}
curl -X POST https://crypto.cucu.ai/api/v1/merchants/me/webhook \
  -H "X-API-Key: sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-servidor.com/webhooks/cucu-crypto",
    "events": ["payment.confirmed", "payment.failed", "charge.expired"]
  }'
```

3. Guarda el `secret` de la respuesta en tu sistema de secretos (no en código).

4. Verifica la integración con el evento de prueba:

```bash theme={"system"}
curl -X POST https://crypto.cucu.ai/api/v1/merchants/me/webhook/test \
  -H "X-API-Key: sk_live_xxxx"
```

***

## Paso 2 — Flujo de pago

```
Tu Backend                    CUCU Crypto                   Usuario
     │                              │                           │
     │  POST /merchants/me/charges  │                           │
     │─────────────────────────────►│                           │
     │                              │                           │
     │   { charge_id, checkout_url, │                           │
     │     qrcode_link, expires_at }│                           │
     │◄─────────────────────────────│                           │
     │                              │                           │
     │   Muestra QR / redirect      │                           │
     │──────────────────────────────────────────────────────────►
     │                              │                           │
     │                              │   Usuario paga en USDT    │
     │                              │◄──────────────────────────│
     │                              │                           │
     │   POST webhook               │                           │
     │   payment.confirmed          │                           │
     │◄─────────────────────────────│                           │
     │                              │                           │
     │   Acredita el pedido         │                           │
     │──────────────────────────────────────────────────────────►
```

***

## Paso 3 — Implementa el receptor de webhooks

```python theme={"system"}
# FastAPI example
from fastapi import FastAPI, Request, Header, HTTPException
import hmac, hashlib, base64

app = FastAPI()
WEBHOOK_SECRET = "wh_sk_xxxxxxxxxxxxxxxxxxxx"  # desde variable de entorno

@app.post("/webhooks/cucu-crypto")
async def recibir_webhook(
    request: Request,
    webhook_id: str = Header(...),
    webhook_timestamp: str = Header(...),
    webhook_signature: str = Header(...),
    webhook_event: str = Header(...),
):
    body = await request.body()

    # 1. Verificar firma
    mensaje = f"{webhook_id}.{webhook_timestamp}.{body.decode()}"
    firma = base64.b64encode(
        hmac.new(WEBHOOK_SECRET.encode(), mensaje.encode(), hashlib.sha256).digest()
    ).decode()

    if not hmac.compare_digest(firma, webhook_signature.removeprefix("v1,")):
        raise HTTPException(status_code=401, detail="Firma inválida")

    # 2. Idempotencia por webhook_id
    if ya_procesado(webhook_id):
        return {"ok": True}  # 200 para que CUCU no reintente

    # 3. Procesar según el evento
    payload = await request.json()
    if webhook_event == "payment.confirmed":
        acreditar_pedido(payload["metadata"]["invoice_id"])
    elif webhook_event == "charge.expired":
        liberar_stock(payload["charge_id"])

    marcar_procesado(webhook_id)
    return {"ok": True}
```

***

## Consideraciones importantes

* **Idempotencia obligatoria:** CUCU puede entregar el mismo evento más de una vez en escenarios de red. Usa `webhook-id` como clave de deduplicación en tu base de datos.
* **Responde rápido:** tu endpoint debe responder en menos de 30 segundos. Si necesitas procesamiento pesado, encola internamente y responde `200` de inmediato.
* **Siempre verifica la firma:** nunca proceses un evento sin verificar la firma HMAC.
* **No uses `expiration_minutes` > 15** para pagos en caja (POS): el usuario debe completar el pago mientras está presente.

***

## Ambientes

| Ambiente   | Base URL                        |
| ---------- | ------------------------------- |
| Producción | `https://crypto.cucu.ai/api/v1` |

Contacta al equipo de CUCU para acceso a un ambiente de staging antes de pasar a producción.