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:

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

Iscriviti agli avvisi dalla pagina di supporto.

Storico

`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.