Documentación técnica

API & Widgets

Guía completa para integrar CoverUF en tu producto financiero, SaaS o ERP. Endpoints REST, widgets iframe con branding personalizable y eventos postMessage.

¿Aún no tienes API keys? Los partners obtienen keys desde su panel en /app/partner/integrations una vez aprobada la relación comercial. Escríbenos a partners@coveruf.cl para iniciar.

Overview

La API v1 de CoverUF permite a terceras plataformas embeber la infraestructura de cobertura inflacionaria en sus productos. Todos los endpoints REST responden JSON con el envelope { ok, data | error }.

Base URL

https://coveruf.cl/api/v1

Autenticación

Header Authorization: Bearer <api_key>

Formato

JSON en request y response · UTF-8

Errores

HTTP status + { ok: false, error: { code, message } }

POST/api/v1/onboarding/init

Iniciar onboarding de una empresa

Crea (o encuentra) una empresa bajo tu ecosistema y devuelve un enlace/iframe listo para embeber donde el cliente completa el KYB/KYC. Ideal para incorporar el registro de tu PYME dentro de tu propio flujo de alta.

Request body

{
  "company": {
    "rut": "76.123.456-7",
    "legal_name": "Comercial Andes SpA",
    "contact_name": "Juan Pérez",
    "contact_email": "juan@andes.cl",
    "contact_phone": "+56912345678",
    "sector": "Retail",
    "annual_revenue_uf": 8500,
    "uf_exposure_monthly": 300
  },
  "callback_url": "https://tu-app.com/return"
}

Response body

{
  "ok": true,
  "data": {
    "company_id": "c1a2b3c4-...",
    "kyc_status": "draft",
    "onboarding_url": "https://coveruf.cl/embed/onboarding?token=...",
    "embed_iframe_snippet": "<iframe src=\"...\" />",
    "expires_in": 86400
  }
}

curl

curl -X POST https://coveruf.cl/api/v1/onboarding/init \
  -H "Authorization: Bearer $COVERUF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company": {
      "rut": "76.123.456-7",
      "legal_name": "Comercial Andes SpA",
      "contact_email": "juan@andes.cl"
    },
    "callback_url": "https://tu-app.com/return"
  }'

JavaScript

const res = await fetch("https://coveruf.cl/api/v1/onboarding/init", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.COVERUF_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    company: {
      rut: "76.123.456-7",
      legal_name: "Comercial Andes SpA",
      contact_email: "juan@andes.cl",
    },
    callback_url: "https://tu-app.com/return",
  }),
});
const { data } = await res.json();
// data.onboarding_url — pega esta URL en un iframe o abre en nueva pestaña

POST/api/v1/quotes

Cotizar una cobertura

Genera una cotización priceada con el motor Black-Scholes sobre la curva forward UF real. Retorna la prima del banco, spread CoverUF y cuota mensual.

Request body

{
  "strategy": "zero_cost_collar",
  "notional_uf": 6000,
  "tenor_months": 12,
  "company": {
    "tax_id": "76.123.456-7",
    "legal_name": "Comercial Andes SpA"
  }
}

Response body

{
  "ok": true,
  "data": {
    "quote_id": "q1a2b3c4-...",
    "strategy": "zero_cost_collar",
    "notional_uf": 6000,
    "tenor_months": 12,
    "premium_uf": 12.4,
    "spread_uf": 30,
    "monthly_fee_uf": 3.53,
    "status": "sent",
    "expires_at": "2027-05-01T00:00:00Z"
  }
}

curl

curl -X POST https://coveruf.cl/api/v1/quotes \
  -H "Authorization: Bearer $COVERUF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "strategy": "zero_cost_collar",
    "notional_uf": 6000,
    "tenor_months": 12,
    "company": { "tax_id": "76.123.456-7" }
  }'

JavaScript

const res = await fetch("https://coveruf.cl/api/v1/quotes", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.COVERUF_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    strategy: "zero_cost_collar",
    notional_uf: 6000,
    tenor_months: 12,
    company: { tax_id: "76.123.456-7" },
  }),
});

GET/api/v1/hedges?status=active

Listar coberturas de tu ecosistema

Devuelve las coberturas activas o históricas de las empresas registradas bajo tu partner. Filtro opcional por status.

Response body

{
  "ok": true,
  "data": {
    "hedges": [
      {
        "id": "h1a2b3c4-...",
        "company_id": "c1a2b3c4-...",
        "strategy": "zero_cost_collar",
        "notional_uf": 6000,
        "tenor_months": 12,
        "strike_uf": 41635,
        "monthly_fee_uf": 3.5,
        "status": "active",
        "start_date": "2026-04-01",
        "end_date": "2027-04-01"
      }
    ],
    "count": 1
  }
}

curl

curl https://coveruf.cl/api/v1/hedges?status=active \
  -H "Authorization: Bearer $COVERUF_API_KEY"

JavaScript

const res = await fetch("https://coveruf.cl/api/v1/hedges?status=active", {
  headers: { "Authorization": `Bearer ${process.env.COVERUF_API_KEY}` },
});
const { data } = await res.json();

GET/api/v1/market/ufpúblico · sin auth

Datos de mercado UF

Endpoint público (sin auth) con el valor spot actual de la UF y la curva forward (2 a 24 meses). Refrescado diariamente.

Response body

{
  "ok": true,
  "data": {
    "spot": {
      "date": "2026-07-28",
      "value": 38972
    },
    "forwards": [
      {
        "tenor_months": 6,
        "mid": 41044,
        "bid": 41039,
        "offer": 41049
      },
      {
        "tenor_months": 12,
        "mid": 41635,
        "bid": 41630,
        "offer": 41640
      },
      {
        "tenor_months": 24,
        "mid": 42995,
        "bid": 42990,
        "offer": 43000
      }
    ]
  }
}

curl

curl https://coveruf.cl/api/v1/market/uf

JavaScript

const { data } = await fetch("https://coveruf.cl/api/v1/market/uf").then((r) => r.json());

Widgets embebibles

Componentes iframe listos para pegar en tu producto. Con branding personalizable y comunicación por window.postMessage al parent.

Cotizador de coberturas

Slider interactivo donde el usuario final ajusta nocional, plazo y estrategia y ve el precio en vivo. Al enviar, dispara un evento coveruf.quote.created.

Snippet HTML

<iframe
  src="https://coveruf.cl/embed/quote?partner=your-partner-slug"
  style="border:0;width:100%;height:720px"
  loading="lazy"
></iframe>

Onboarding KYB/KYC

Wizard de 3 pasos donde la PYME completa datos operativos, representante legal, UBOs y declaraciones. Requiere token generado desde /api/v1/onboarding/init.

Snippet HTML

<iframe
  src="https://coveruf.cl/embed/onboarding?token=<TOKEN_FROM_INIT>"
  style="border:0;width:100%;height:820px"
  loading="lazy"
></iframe>

Eventos window.postMessage

Los iframes envían mensajes a la ventana padre para reportar acciones y ajustar layout dinámicamente.

Type	Payload	Cuándo
coveruf.resize	{ height: number }	Cambio de altura del contenido — actualiza el height del iframe.
coveruf.quote.created	{ partner, strategy, notional_uf, tenor_months, monthly_fee_uf }	Emitido cuando el usuario solicita una cotización en el widget de cotización.
coveruf.onboarding.submitted	{ company_id }	Emitido cuando la PYME envía sus datos KYB para revisión.

Ejemplo de handler en tu app

window.addEventListener("message", (e) => {
  if (!e.data || typeof e.data !== "object") return;
  const { type, height, payload } = e.data;

  if (type === "coveruf.resize" && typeof height === "number") {
    document.getElementById("coveruf-iframe").style.height = height + "px";
    return;
  }

  if (type === "coveruf.quote.created") {
    // Registra la intención en tu CRM, muestra confirmación, etc.
    console.log("Nueva cotización:", payload);
  }

  if (type === "coveruf.onboarding.submitted") {
    // Redirige al cliente a tu propio checkout / next step
    window.location.href = "/dashboard";
  }
});

Manejo de errores

Status	Code	Significado
400	bad_request	Payload inválido — revisa el detalle en error.details
401	unauthorized	API key ausente, expirada o revocada
404	not_found	Recurso no encontrado
500	internal_error	Error interno del servidor