Power BI y otras herramientas de BI¶

Eval360Pro expone una API pública de solo lectura (/api/v1) pensada para alimentar Power BI, Looker Studio, Tableau, Excel (Power Query) o cualquier herramienta que consuma JSON por HTTP. Cada organización solo ve sus propios datos: el tenant se resuelve desde la API key, no hace falta pasar el tenant en la URL.

Es la vía recomendada para armar tableros propios sin tocar la base de datos.

1. Obtener una API key¶

Entra a Integraciones (menú Configuración).
Crea una API key. Cópiala al momento: se muestra una sola vez.
Guárdala como secreto. La clave da acceso de lectura a todos los datos del tenant; si se filtra, revócala y crea otra desde la misma pantalla.

Todas las llamadas van con el header:

X-Api-Key: TU_API_KEY

Para probar la conexión: GET /api/v1/ping devuelve el tenant resuelto.

2. Datasets disponibles¶

Base: https://{slug}.eval360pro.com (tu subdominio).

Tablas de hechos (planas, una fila por registro)¶

Cada fila viene denormalizada: trae las claves (cycleId, employeeId) para modelar en estrella y además, por comodidad, algunos atributos de la persona y del ciclo ya resueltos (nombre, departamento, cargo), para que un tablero rápido funcione sin unir tablas.

Endpoint	Grano	Campos
`/api/v1/datasets/scores`	ciclo × colaborador	`cycleId`, `cycleName`, `employeeId`, `employeeCode`, `employee`, `email`, `department`, `jobProfile`, `overall`, `calibrated`, `effective`, `submitted`, `totalParticipants`, `acknowledged`
`/api/v1/datasets/gaps`	ciclo × colaborador × requisito	`cycleId`, `cycleName`, `employeeId`, `employee`, `department`, `requirement`, `isCritical`, `requiredLevel`, `currentLevel`, `gapLevel`, `priority`
`/api/v1/datasets/nine-box`	ciclo × colaborador	`cycleId`, `cycleName`, `employeeId`, `employee`, `email`, `department`, `jobProfile`, `performanceScore`, `potentialScore`, `performanceLevel`, `potentialLevel`, `box` (0-8), `boxLabel`, `hasCareerPath`

Las tres aceptan ?cycleId={guid} para traer un solo ciclo (por defecto traen todos).

En gaps, cycleId/cycleName pueden venir vacíos si el análisis de brechas no quedó atado a un ciclo. En nine-box, box es el índice 0-8 de la casilla y boxLabel su etiqueta (Riesgo … Estrella).

Tablas de dimensión / otros hechos¶

Endpoint	Contenido
`/api/v1/employees`	Personas (paginado: `page`, `pageSize` ≤ 200)
`/api/v1/cycles`	Ciclos de evaluación
`/api/v1/goals`	Objetivos / OKR con avance
`/api/v1/pulse-surveys`	Encuestas de pulso con eNPS y fechas (`openedAt`, `closedAt`)

El score efectivo (effective) es el calibrado si existe, si no el general (calibrated ?? overall). Es el que se usa en los tableros de la app.

3. Conectar Power BI Desktop¶

Obtener datos → Web → Avanzado. En Partes de la dirección URL pon la base y, en Encabezados de solicitud web HTTP, agrega X-Api-Key con tu clave. Repite por cada tabla.

O, más robusto para actualización programada, pega esta consulta en el Editor avanzado (Power Query M) — usa RelativePath + Headers, que es lo que el servicio de Power BI necesita para refrescar:

let
    BaseUrl = "https://acme.eval360pro.com",
    ApiKey  = "TU_API_KEY",
    Fuente  = Json.Document(
        Web.Contents(BaseUrl, [
            RelativePath = "api/v1/datasets/scores",
            Headers = [ #"X-Api-Key" = ApiKey ]
        ])
    ),
    Tabla   = Table.FromRecords(Fuente)
in
    Tabla

Duplica la consulta cambiando RelativePath por api/v1/datasets/gaps, api/v1/datasets/nine-box, api/v1/employees, api/v1/cycles, etc.

Sugerencia: define BaseUrl y ApiKey como parámetros de Power Query (Administrar parámetros) para no repetir la clave en cada consulta y poder cambiarla en un solo lugar.

4. Modelar en estrella¶

Las tablas de hechos ya traen las claves para relacionar:

                 employees (id)
                      ▲
                      │ employeeId
   cycles (id) ◀──────┼──────▶ datasets/scores
        ▲             │        datasets/gaps
        │ cycleId     │        datasets/nine-box
        └─────────────┘

Relaciona scores[employeeId] → employees[id] y scores[cycleId] → cycles[id] (igual para gaps y nine-box).
Con eso puedes segmentar cualquier medida por departamento, cargo, período, etc.
Medidas típicas: promedio de effective por ciclo, % de brechas críticas por departamento, conteo por casilla del 9-Box, evolución de eNPS por fecha.

5. Actualización programada (Power BI Service)¶

Al publicar, en Configuración del conjunto de datos → Credenciales del origen de datos elige método Anónimo (la autenticación va en el header X-Api-Key dentro de la consulta).
Programa el refresco con la frecuencia que necesites. Los datos de la app se actualizan en tiempo real; el refresco define cada cuánto los relee Power BI.
La API key queda embebida en el dataset publicado. Trátalo como contenido sensible y limita quién puede editarlo. Si rotas la clave en Integraciones, actualiza el parámetro y republica.

Notas¶

Solo lectura. La v1 no permite escribir.
Sin paginar en los datasets/* (traen el conjunto completo del tenant); employees sí pagina.
Brechas y 9-Box dependen de que el ciclo tenga análisis de brechas y scores enviados; si un ciclo aún no los tiene, esas filas vendrán vacías para ese ciclo.
El detalle exacto de cada schema está en Swagger (/swagger, doc API pública), probable con tu misma API key.