Skip to Content
Changelog e versioning

Changelog

Storico delle modifiche della Kinmu Public API. Le modifiche incompatibili non vengono mai applicate all’interno di una versione maggiore: si introducono in una nuova versione e si annunciano qui.

Politica di versioning

  • La versione sta nell’URL: https://api.kinmu.app/v1.
  • Contratto congelato dentro v1. Non introduciamo modifiche incompatibili in v1.

Cosa consideriamo una modifica compatibile (non breaking)

Queste modifiche possono avvenire in v1 senza preavviso; la tua integrazione deve tollerarle:

  • Aggiungere nuovi endpoint o risorse.
  • Aggiungere nuovi campi a una risposta.
  • Aggiungere nuovi valori a un enum documentato come estensibile (ad es. tipi di assenza custom).
  • Aggiungere parametri opzionali di query o di body.
  • Cambiare il testo dei messaggi di errore (title, detail) — per questo la tua logica deve basarsi sul campo stabile code.

Progetta client tolleranti. Ignora i campi che non conosci e non dare per scontato un ordine fisso negli elenchi. Così le modifiche compatibili non ti toccano.

Cosa consideriamo una modifica incompatibile (breaking)

Richiede una nuova versione maggiore (v2):

  • Eliminare o rinominare un endpoint, un campo o un valore di enum.
  • Cambiare il tipo di un campo o renderlo obbligatorio.
  • Cambiare il significato di un campo o il codice di un errore.

Politica di deprecazione (12 mesi)

Quando deprechiamo un endpoint, un campo o una versione:

  1. Viene annunciato in questo changelog e nella mailing list degli sviluppatori.
  2. Viene marcato come deprecated nello spec OpenAPI e, quando applicabile, con gli header di risposta Deprecation + Sunset.
  3. Resta operativo per almeno 12 mesi dall’annuncio prima del ritiro.

Iscriviti agli avvisi dalla pagina di supporto.

Storico

Tutte le modifiche elencate qui sotto sono compatibili: nessuna rompe un’integrazione v1 esistente. Sono documentate qui perché cambiano il comportamento osservabile.

2026-08-27 — spec OpenAPI e updated_since

  • La spec ora dichiara i codici 402 e 409 e gli header X-RateLimit-*, che l’API già emetteva.
  • Il 409 è dichiarato anche su POST /v1/reports e sulle operazioni idempotenti dei webhook, dove mancava.
  • updated_since implementato su GET /v1/webhook-endpoints.
  • updated_since marcato come obsoleto (deprecated) su GET /v1/vacation-balances e GET /v1/work-summaries: su queste risorse non ha mai filtrato. Resta accettato senza effetto — per non rompere gli SDK rigenerati — e verrà rimosso il 27-08-2027, secondo la politica di deprecazione di 12 mesi. Per questi aggregati, richiedi di nuovo l’intervallo (year, from/to). Vedi le convenzioni.

2026-08-20 — email del dipendente unica per azienda

  • L’unicità dell’email alla creazione di un dipendente diventa per azienda (prima era globale). Le creazioni che prima fallivano con 422 per collisione con l’email di un’altra azienda ora vengono accettate.

2026-08-10 — sandbox e chiavi vengono smantellate

  • Disattivando l’addon Public API si revocano tutte le API key (motivo addon_disabled), si cancellano i report generati e si elimina l’azienda sandbox con i suoi dati. Riattivare l’addon ricrea una sandbox vuota e non ripristina le chiavi. Vedi sandbox.

2026-07-31 — gate dell’abbonamento e revoca

  • Il gate dell’abbonamento si irrigidisce: trial esaurito, abbonamento disdetto e scaduto, abbonamento non più valido e azienda archiviata ora restituiscono 403 subscription_inactive su /v1.
  • Revocare API key e webhook (DELETE) non richiede più un abbonamento attivo: chiudere una credenziale è un controllo di sicurezza e deve essere sempre possibile.

2026-07-30 — impostazioni aziendali nell’emissione delle chiavi

  • L’emissione delle API key rispetta le impostazioni dell’addon per azienda: default_expiration_days (scadenza applicata quando non ne chiedi una esplicita) e max_active_keys (tetto di chiavi attive, 10 di default).

v1 · 1.0.0

Spec OpenAPI pubblicato (openapi-v1.json, v1.0.0). Il riferimento interattivo legge lo spec reale. La superficie della v1 è contratto congelato; le modifiche si annunciano qui con la politica di deprecazione di 12 mesi.

Risorse al lancio (MVP):

  • Organization — GET /v1/organization (introspezione).
  • Employees — elencare, ottenere, creare, aggiornare e cessare i dipendenti.
  • Check-ins — elencare, ottenere e registrare timbrature.
  • Work summaries — aggregati di giornata per il payroll.
  • Absences — elencare, ottenere, creare, approvare e rifiutare.
  • Vacation balances — saldi ferie.
  • Locations / Units — struttura organizzativa (sola lettura).
  • Reports — report asincroni (registro orario legale ed export), con download del file via GET /v1/reports/{id}/download.

Webhooks:

  • Eventi in uscita firmati (Standard Webhooks): gestione degli endpoint, invio di ping, elenco delle consegne e riaccodamento manuale di una consegna via POST /v1/webhook-endpoints/{id}/deliveries/{deliveryId}/retry.
Last updated on
Riferimento APISupporto