Valkoru API

Autenticación

Todos los endpoints protegidos requieren el header X-API-Key con tu API key. Las keys tienen el formato vk-... y se generan desde tu panel o vía API.

# Todas las requests autenticadas llevan este header
X-API-Key: vk-tu_api_key_aqui

Crear tu primera API Key

Las API keys se generan desde la aplicación, en la sección Ajustes. Necesitas una cuenta activa.

Formato de la key

Todas las keys tienen el prefijo vk- seguido de 32 caracteres aleatorios. En el panel solo se muestra el prefijo corto (vk-AbCdEfG) — el secreto completo nunca vuelve a estar visible.

# Ejemplo de API key
vk-AbCdEfGhIjKlMnOpQrStUvWxYz012345678
formato

Simular territorio

Lanza una simulación sobre un conjunto de manzanas. El modelo corre en paralelo — el job se encola y puedes consultar el progreso con polling.

curl https://api.valkoru.cl/simulate \
  -H "X-API-Key: vk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "campana": "Tocó Crédito, Toca MACHBANK",
    "estimulo": "Crédito de consumo con abono inmediato, tasa desde 0,94%. 100% digital, sin filas.",
    "comunas": ["PROVIDENCIA", "NUNOA", "MAIPU"],
    "layer_preset": "financiero",
    "max_manzanas": 50
  }'
bash

{
  "job_id":       "uuid-del-job",
  "total":        50,
  "coverage_pct": 12.4
}
json

Consultar resultados

El job corre de forma asíncrona. Haz polling hasta que status sea "done" o "error". Tiempo típico: 15–60 segundos según el número de manzanas.

curl https://api.valkoru.cl/results/uuid-del-job \
  -H "X-API-Key: vk-..."
bash

{
  "status":   "done",
  "total":    50,
  "results": [
    {
      "objectid":   131422,
      "manzent":    "13101000100",
      "comuna":     "PROVIDENCIA",
      "score":      74,          // receptividad 0-100
      "reaccion":   "Los residentes ven el producto...",
      "razones":    ["Alta bancarización", "..."],
      "dimensiones": {
        "economica": 78,
        "cultural":  65,
        "politica":  60,
        "emocional": 72
      },
      "confidence": 0.83,      // calidad del estimado
      "divergence": +12        // diferencia LLM vs prior censal
    }
    // ... 49 manzanas más
  ]
}
json

Propagar opinión entre territorios

Simula cómo los scores se difunden entre manzanas vecinas a lo largo de rondas — modelo Friedkin-Johnsen con personalidad territorial derivada de clustering censal. Devuelve un snapshot del mapa por cada ronda y métricas de dinámica.

curl https://api.valkoru.cl/propagate \
  -H "X-API-Key: vk-..." \
  -H "Content-Type: application/json" \
  -d '{"job_id": "uuid-del-job", "iterations": 10}'
bash

{
  "iterations": 10,
  "steps": [
    // paso 0 (inicial) — incluye comuna y arquetipo territorial
    [{ "objectid": 131422, "score": 74, "delta": 0, "comuna": "PROVIDENCIA", "archetype": "Élite profesional" }, ...],
    // pasos 1-10
    [{ "objectid": 131422, "score": 72, "delta": -2 }, ...]
  ],
  "metrics": {
    "delta_promedio":           -1.2,
    "avg_abs_delta":           3.4,
    "pct_movimiento_material": 38.0,  // % con |Δ| ≥ 3
    "punto_inflexion":         2,       // ronda con mayor velocidad
    "convergencia":            true,
    "velocidades_por_ronda":   [2.1, 1.8, 0.4, ...],
    "top_volatiles":           [[131422, -8.2], ...],
    "top_resistentes":         [[131500, -0.1], ...]
  }
}
json

Exportar reporte PDF

Genera un reporte ejecutivo en PDF con resumen por comunas, distribución de receptividad, resumen LLM y — si incluyes métricas de propagación — una sección de dinámica territorial.

curl https://api.valkoru.cl/reporte \
  -H "X-API-Key: vk-..." \
  -H "Content-Type: application/json" \
  -o reporte.pdf \
  -d '{
    "job_id": "uuid-del-job",
    "estimulo": "Crédito de consumo con abono inmediato...",
    "comuna": "PROVIDENCIA",
    "prop_metrics": { ... }
  }'
bash

Consultar territorio disponible

curl "https://api.valkoru.cl/territory/estimate?comunas=PROVIDENCIA&comunas=NUNOA" \
  -H "X-API-Key: vk-..."
bash

{
  "n_manzanas":      4821,
  "n_comunas":       2,
  "n_regiones":      1,
  "project_required": false
}
json

Capas de datos disponibles

El parámetro layer_preset en /simulate controla qué datos adicionales ve el modelo al evaluar cada manzana.

Gestión de API Keys

Errores