BI / Power BI

Mål: få in tidrapporteringsdatan i ditt data warehouse eller direkt i Power BI / Looker / Metabase via inkrementell synkronisering.

Rekommenderade scopes (endast läsning): org:fichajes:read, org:ausencias:read, org:saldos:read, org:estructura:read.

Använd en dedikerad read-only-nyckel för BI. Då kan du återkalla eller rotera den utan att påverka skrivande integrationer.

Mönster: inkrementell polling med `updated_since`

Alla listor accepterar updated_since=<ISO8601> och returnerar bara det som ändrats sedan den tidpunkten. Mönstret:

Initial laddning (backfill)

Gå igenom varje resurs och paginera med cursor tills has_more=false. Spara starttidpunkten som vattenmärke (watermark).

Inkrementella laddningar

Vid varje schemalagd körning, skicka ?updated_since=<watermark> och uppdatera ditt vattenmärke till tidpunkten strax före att anropet startade.

Deduplicera på `id`

Eftersom updated_since bygger på updated_at kan samma post dyka upp igen om den har ändrats. Gör upsert på id (UUID) i ditt lager.

Exempel i Python


import os, requests
from datetime import datetime, timezone
 
BASE = os.environ["KINMU_BASE_URL"]
KEY = os.environ["KINMU_API_KEY"]
session = requests.Session()
session.headers.update({"Authorization": f"Bearer {KEY}"})
 
def sync(resource, since=None):
    rows, cursor = [], None
    params = {"limit": 100}
    if since:
        params["updated_since"] = since
    while True:
        if cursor:
            params["cursor"] = cursor
        r = session.get(f"{BASE}/{resource}", params=params, timeout=30)
        r.raise_for_status()
        body = r.json()
        rows.extend(body["data"])
        if not body["meta"]["has_more"]:
            break
        cursor = body["meta"]["next_cursor"]
    return rows
 
# Marca de agua ANTES de llamar, para no perder registros escritos durante la sync
watermark = datetime.now(timezone.utc).isoformat()
employees = sync("employees", since=load_last_watermark())   # incremental
checkins = sync("check-ins", since=load_last_watermark())
save_watermark(watermark)

Ta vattenmärket innan synkroniseringen börjar, inte efteråt. Då kommer poster som skrivs medan processen kör med i nästa körning.

Användbara resurser för BI

Resurs	Ger
`work-summaries`	Arbetstidsmetrik redo för aggregering (timmar, övertid, natt).
`check-ins`	Händelsenivå för analys av närvaro och punktlighet.
`absences`	Frånvaro per typ och period.
`vacation-balances`	Semestersaldon och avsättningar.
`locations` / `units`	Dimensioner att segmentera på (plats, avdelning).

Anslut från Power BI

Power BI kan konsumera API:et direkt med Web.Contents och en authorization-header. Förenklat exempel i Power Query (M):


let
    BaseUrl = "https://api.kinmu.app/v1",
    ApiKey  = "kinmu_sk_live_…",   // usa Parámetros / almacén de credenciales, no lo escribas en claro
    Source = Json.Document(
        Web.Contents(BaseUrl, [
            RelativePath = "work-summaries",
            Query = [ period = "month", from = "2026-01-01", #"to" = "2026-12-31", limit = "100" ],
            Headers = [ Authorization = "Bearer " & ApiKey, Accept = "application/json" ]
        ])
    ),
    Data = Source[data],
    Table = Table.FromRecords(Data)
in
    Table

För att paginera i Power Query, kapsla anropet i en funktion som följer meta.next_cursor med List.Generate tills has_more är false.

Respektera rate limits: för stora volymer, schemalägg uppdateringen utanför rusningstid och håll koll på X-Kinmu-Quota-Remaining.

Eventdrivet alternativ

Vill du slippa polla? Prenumerera på webhooks (checkin.created, absence.approved, vacation_balance.updated, …) och uppdatera ditt lager när varje event kommer in. Kombinationen fungerar bra: webhooks för realtid + en nattlig polling med updated_since som skyddsnät.