Kinmu Public API
Integra la rilevazione presenze di Kinmu con il tuo software payroll, il tuo controllo accessi o i tuoi strumenti di BI. Un’API REST versionata, con credenziali aziendali, scopes espliciti e webhooks firmati.
curl https://api.kinmu.app/v1/organization \
-H "Authorization: Bearer $KINMU_API_KEY"Inizia da qui
Attiva l’addon, crea una chiave e fai la tua prima chiamata in circa 5 minuti.
QuickstartScopes, rotazione, sandbox e best practice.
Autenticazione e chiavi APIPaginazione, errori, idempotenza e limiti.
ConvenzioniEsplora le 9 risorse e prova ogni endpoint.
Riferimento interattivoIntegra il tuo caso d’uso
Ore effettive, assenze e saldi ferie per il tuo ciclo payroll.
Payroll e consulenza del lavoroRegistra le timbrature da tornelli, badge o chioschi con POST /v1/check-ins.
Sincronizzazione incrementale via polling per le tue dashboard.
BI / Power BICosa espone la v1
La superficie della v1 è composta da 9 risorse REST sotto https://api.kinmu.app/v1:
| Risorsa | A cosa serve |
|---|---|
| Organization | Introspezione della credenziale e dell’azienda. |
| Employees | Creazione, cessazione e aggiornamento dei dipendenti. |
| Check-ins | Eventi di timbratura (in/out/break) con origine. |
| Work summaries | Aggregati di giornata per il payroll. |
| Absences | Assenze: creazione, approvazione e rifiuto. |
| Vacation balances | Saldi ferie per dipendente e anno. |
| Locations / Units | Struttura organizzativa (sola lettura). |
| Reports | Report asincroni (registro orario legale, export). |
| Webhooks | Eventi in uscita firmati (Standard Webhooks). |
L’azienda si risolve sempre dalla credenziale. Non c’è mai {companyId} nelle route pubbliche né nel body.
Principi
- Contratto congelato. Ciò che entra nella v1 non cambia in modo incompatibile; ogni deprecazione viene annunciata con 12 mesi di anticipo nel changelog.
- Minimo privilegio. Ogni chiave ha scopes espliciti; senza scope non c’è accesso (
403 invalid_scope). - Tutto tracciato. Ogni richiesta con chiave aziendale viene registrata con
origin=public_api. - Stesse regole dell’app. Le scritture via API passano per le stesse validazioni di dominio dell’applicazione.