Usa l'API REST

L'API REST permette ai tuoi sistemi di parlare con Bueggio HR: leggere persone, reparti, assenze e saldi, vedere chi è assente, simulare una richiesta prima di crearla e — con una chiave in lettura e scrittura — prenotare, approvare, rifiutare o annullare, con ogni azione tracciata. È lo stesso motore dell'app, esposto come JSON pulito.

Crea una chiave API

Le chiavi le gestiscono gli admin e appartengono all'organizzazione, non a una persona:

1. Vai in Impostazioni → Integrazioni → API.
2. Dai alla chiave un nome che dica dove verrà usata ("Zapier", "Export paghe"…).
3. Scegli i permessi: Sola lettura o Lettura e scrittura. Parti dalla sola lettura, a meno che tu non debba scrivere.
4. Clicca Crea chiave e copiala subito — viene mostrata una sola volta e conservata solo come hash. Se la perdi, revocala e creane una nuova.

La prima richiesta

Autentica ogni chiamata con la chiave come Bearer token:

curl https://www.bueggiohr.eu/api/v1/whos_off \
  --header "Authorization: Bearer bhr_..."

Tre posti dove studiare la superficie:

• Documentazione API — la guida leggibile di ogni endpoint.
• /api/v1/openapi.json — la specifica OpenAPI, per generare client e strumenti di test.
• /api/docs.md — l'intera documentazione in un unico file Markdown, comodo da incollare a un assistente AI.

Cosa c'è nell'API

• Lettura — organizzazione, persone, reparti, tipi di assenza, festività, assenze, saldi per persona, chi è assente in un intervallo di date.
• Preventivo — la prova generale di una richiesta: quanti giorni scalerebbe e gli eventuali conflitti, senza creare nulla.
• Scrittura (permessi lettura e scrittura) — creare richieste, approvare, rifiutare, annullare. Le richieste seguono le stesse regole dell'app: flussi di approvazione, blocchi date e tetti di assenza valgono comunque, e tutto finisce nello storico della richiesta.
• Gestione webhook — registrare e rimuovere endpoint webhook in modo programmatico.

Tieni le chiavi al sicuro

• Tratta una chiave come una password: dà accesso ai dati di assenza di tutta la tua organizzazione.
• Usa una chiave per sistema, con un nome chiaro — l'elenco mostra l'ultimo utilizzo di ogni chiave, così quelle inutilizzate si riconoscono e si revocano al volo.
• Revoca subito se una chiave trapela; le integrazioni che la usano si fermano nello stesso istante.

Problemi comuni

• 401 invalid_api_key — l'header deve essere esattamente Authorization: Bearer bhr_...; controlla che la chiave non sia stata revocata.
• 403 su una scrittura — la chiave è in sola lettura; creane una in lettura e scrittura.
• Una richiesta viene rifiutata — l'API applica le stesse regole dell'app (blocchi date, tetti di assenza, saldi). Il messaggio d'errore dice quale regola l'ha respinta.