Convenzioni dell’API

Regole trasversali a tutte le risorse della v1.

Tema	Regola
Formato	JSON UTF-8. Le richieste con body portano `Content-Type: application/json`.
ID	UUID pubblici. Gli ID numerici interni non vengono mai esposti.
Date	ISO 8601. Istanti in UTC (`2026-07-08T09:30:00Z`); date di calendario `YYYY-MM-DD`.
Base URL	Versionata nel path: `https://api.kinmu.app/v1` · Dev: `https://api.dev.kinmu.app/v1`.

Paginazione (cursore)

Tutti gli elenchi sono paginati per cursore:

?limit= (default 25, max 100) · ?cursor=<opaco>.
Risposta: { "data": [...], "meta": { "next_cursor": "…"|null, "has_more": true|false } }.
Per la pagina successiva, reinvia cursor=<meta.next_cursor>. has_more=false o next_cursor=null → fine.


curl "https://api.kinmu.app/v1/employees?limit=50&cursor=eyJpZCI6MTIzfQ" \
  -H "Authorization: Bearer kinmu_sk_live_…"

Il cursor è opaco: non costruirlo né parsarlo, reinvialo così com’è.

Sincronizzazione incrementale (`updated_since`)

Il parametro ?updated_since=<ISO 8601> restituisce solo ciò che è cambiato da quell’istante (polling incrementale per BI ed ERP). Non è universale: filtra solo su questi elenchi.

Elenco	Filtra per `updated_since`?
`GET /v1/employees`	Sì
`GET /v1/check-ins`	Sì
`GET /v1/absences`	Sì
`GET /v1/locations`	Sì
`GET /v1/units`	Sì
`GET /v1/webhook-endpoints`	Sì
`GET /v1/vacation-balances`	No — accettato ma ignorato; obsoleto, rimozione il 27-08-2027
`GET /v1/work-summaries`	No — accettato ma ignorato; obsoleto, rimozione il 27-08-2027


curl "https://api.kinmu.app/v1/employees?updated_since=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer kinmu_sk_live_…"

Salva l’istante dell’ultima sincronizzazione e usalo come updated_since nella successiva. Trovi il pattern completo nella guida BI.

vacation-balances e work-summaries non filtrano per updated_since. Sono aggregati: non c’è un delta da chiedere. Richiedi di nuovo l’intervallo che ti serve (year= per i saldi, from/to per i riepiloghi) oppure ricaricalo per intero a ogni passata, e fai upsert per chiave nel tuo storage. Il parametro continua a essere accettato su questi due endpoint, per non rompere gli SDK già generati, ma non filtra nulla: è marcato come obsoleto e verrà rimosso il 27-08-2027.

Errori

Tutti gli errori sono RFC 9457 (application/problem+json):


{
  "type": "https://docs.kinmu.app/errors/invalid_scope",
  "title": "Scope insuficiente",
  "status": 403,
  "code": "invalid_scope",
  "detail": "La API key no tiene el scope requerido: org:empleados:read.",
  "errors": { "required_scope": "org:empleados:read" }
}

Programma sul campo code (stabile), non su title/detail.

Tabella dei codici

`code`	HTTP	Quando
`unauthenticated`	401	Chiave assente, non valida, revocata o scaduta.
`invalid_scope`	403	La chiave non ha lo scope richiesto (`errors.required_scope`).
`subscription_inactive`	403	L’azienda non ha servizio attivo: sospesa o archiviata, senza abbonamento, abbonamento sospeso, trial scaduto, oppure abbonamento disdetto e ormai scaduto o non più valido.
`addon_disabled`	403	L’addon Public API non è attivo per l’azienda.
`validation_failed`	422	Body o parametri non validi (`errors` con il dettaglio per campo).
`not_found`	404	La risorsa non esiste o appartiene a un’altra azienda.
`conflict`	409	Conflitto di stato (ad es. decidere un’assenza già decisa).
`idempotency_conflict`	409	La `Idempotency-Key` è stata riusata con un body diverso.
`rate_limited`	429	Limite al minuto superato (vedi `Retry-After`).
`quota_exceeded`	429	Quota mensile esaurita.
`billing_required`	402	Il piano non consente l’azione (ad es. creare un dipendente senza posti disponibili).
`internal_error`	500	Errore interno.

Isolamento multitenant. Richiedere una risorsa di un’altra azienda restituisce 404 (not_found), mai un 403 che ne riveli l’esistenza.

Un trial esaurito o una disdetta chiudono il /v1 con 403 subscription_inactive, mai con un 402. Il 402 (billing_required) è un’altra cosa: l’abbonamento è vivo ma il piano non copre l’azione richiesta (ad es. creare un dipendente senza posti liberi). Leggi il 403 come « servizio assente, va riattivato dalla dashboard » e il 402 come « piano da ampliare ».

Revocare API key e webhook (DELETE) continua a funzionare con l’abbonamento inattivo: è un controllo di sicurezza, non consumo del servizio.

Rate limit e quota

Ogni risposta (2xx e 4xx) include, con due eccezioni documentate più sotto:

Header	Significato
`X-RateLimit-Limit`	Limite al minuto della chiave.
`X-RateLimit-Remaining`	Richieste rimanenti nella finestra corrente.
`X-RateLimit-Reset`	Timestamp Unix in cui la finestra si azzera.
`X-Kinmu-Quota-Remaining`	Richieste rimanenti della quota mensile.

Due risposte non portano queste intestazioni. I 401 (unauthenticated), perché l’autenticazione blocca prima del throttle e la richiesta non viene mai conteggiata; e tutte le risposte di GET /v1/reports/{report}/download, perché il download firmato è servito fuori dal pipeline autenticato. Non trattare la loro assenza come un errore: in questi due casi è il comportamento previsto.

Limiti: live 120/min, test 30/min. Quota mensile: live 10.000 + 1.000×empleados_activos (max 100.000); test 5.000.

Superato il limite al minuto → 429 rate_limited con Retry-After: <secondi>. Esaurita la quota → 429 quota_exceeded. Riprova con backoff rispettando Retry-After.


import time, requests
 
def call_with_retry(session, method, url, **kwargs):
    for attempt in range(5):
        resp = session.request(method, url, **kwargs)
        if resp.status_code != 429:
            return resp
        wait = int(resp.headers.get("Retry-After", 2 ** attempt))
        time.sleep(wait)
    resp.raise_for_status()
    return resp

Tieni d’occhio X-RateLimit-Remaining e X-Kinmu-Quota-Remaining per distanziare le richieste prima di ricevere un 429.

Idempotenza

Nei metodi che mutano (POST / PATCH / DELETE) puoi inviare Idempotency-Key: <unico>:


curl -s -X POST "https://api.kinmu.app/v1/check-ins" \
  -H "Authorization: Bearer kinmu_sk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f9a…-uuid" \
  -d '{ "employee_id": "…", "type": "in", "timestamp": "2026-07-08T08:00:00Z" }'

La prima richiesta viene eseguita e la sua risposta resta in cache per 24 h; un reinvio con lo stesso body restituisce la risposta originale (senza ri-esecuzione). Riusare la stessa chiave con un body diverso → 409 idempotency_conflict.

La creazione di un webhook è l’unica eccezione: il suo secret copy-once non viene mai messo in cache.