Guía de Integración Rápida

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"]
  }'

curl -X POST https://crypto.cucu.ai/api/v1/merchants/me/webhook/test \
  -H "X-API-Key: sk_live_xxxx"

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         │                           │
     │──────────────────────────────────────────────────────────►

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