Leggi e modifica la pianificazione dai tuoi strumenti: un’API REST in JSON protetta da una chiave, e webhook firmati che ti avvisano di ciò che cambia. Va bene qualsiasi client HTTP.
URL di base
https://api.swissplanif.ch/api/v1
Autenticazione
Chiave nell’header Authorization
Formato
JSON, UTF-8, date in UTC
Frequenza
100 richieste ogni 60 s
Verificato sul codice e sulla produzione il 13 novembre 2026.
Avvio rapido
1
Crea una chiave
In Impostazioni → Chiavi API, crea una chiave con i soli permessi che servono alla tua integrazione. Viene mostrata una sola volta: mettila subito nel tuo gestore di segreti.
2
Tienila fuori dal codice
Il tuo programma legge la chiave da una variabile d’ambiente, qui SWISSPLANIF_TOKEN. Non scriverla in un repository, in un URL, né in una pagina web o in un’app mobile.
3
Fai una prima chiamata
Elenca le tue sedi con una chiave che porta locations:read. È una lettura: non modifica nulla.
Ogni richiesta porta l’header Authorization: Bearer seguito dalla tua chiave. Non c’è né cookie né chiave nell’URL.
Una chiave inizia con stk_live_, seguito da 64 caratteri casuali (48 byte). Ne conserviamo solo l’impronta SHA-256: nessuno, noi compresi, può mostrartela di nuovo. Se la perdi, creane un’altra.
Una chiave apre i dati di tutta l’organizzazione, entro i suoi permessi. Per crearne una serve quindi un account autorizzato a gestire le chiavi API e il cui accesso copre tutta l’organizzazione.
Una chiave revocata o scaduta viene rifiutata dalla chiamata successiva, con un 401. La sua durata si sceglie alla creazione: 30, 90 (proposta di default) o 365 giorni, oppure senza scadenza.
Permessi
Una chiave porta uno o più permessi. Una chiamata che ne richiede un altro viene rifiutata con un 403. Lettura e scrittura sono separate: una chiave per una dashboard non ha mai bisogno di scrivere.
URL di base: https://api.swissplanif.ch/api/v1. La versione è nel percorso: una modifica incompatibile passerà da un nuovo prefisso, mai da una modifica sul posto.
Solo HTTPS. Scrivi sempre https://: una chiave inviata in chiaro va considerata persa.
Richieste e risposte sono in JSON (UTF-8). Invia Content-Type: application/json ogni volta che c’è un corpo.
Le date sono istanti ISO 8601 in UTC, che terminano con Z, per esempio 2026-11-16T07:00:00Z. Uno scarto come +01:00 viene rifiutato.
Gli identificativi sono UUID.
Un campo sconosciuto in un corpo viene ignorato, non rifiutato.
Il corpo di una richiesta pesa al massimo 5 MB.
Paginazione
Solo l’elenco dei turni è paginato. limit fissa la dimensione di una pagina, da 1 a 200, 50 per impostazione predefinita. Finché la risposta contiene un nextCursor, rimandalo in cursor per leggere la pagina successiva; null significa che hai letto tutto.
Le pagine sono ordinate per identificativo. L’ordine è stabile da una pagina all’altra, ma non è cronologico: ordina tu su start se ti serve.
Gli elenchi di dipendenti, sedi e postazioni restituiscono tutto in un’unica risposta.
Oggetti
I quattro oggetti che l’API restituisce. Un campo indicato con «o null» può essere vuoto.
Turno
iduuid
Identificativo del turno.
startdatetime
Inizio.
enddatetime
Fine.
breakMinutesinteger
Pausa, in minuti.
statusenum
Stato del turno.DRAFTPUBLISHEDCOMPLETEDCANCELLED
positionIduuid
Postazione.
positionNamestring
Nome della postazione.
locationIduuid
Sede.
locationNamestring
Nome della sede.
employeeIduuid · o null
Persona assegnata; vuoto se il turno non è assegnato a nessuno.
employeeFullNamestring · o null
Nome e cognome di questa persona.dato personale
notestring · o null
Nota libera.dato personale
createdAtdatetime
Creazione.
updatedAtdatetime
Ultima modifica.
Dipendente
iduuid
Identificativo del dipendente.
firstNamestring
Nome.dato personale
lastNamestring
Cognome.dato personale
emailstring · o null
Indirizzo e-mail, se presente.dato personale
contractTypeenum
Tipo di contratto.PERMANENTFIXED_TERMTEMPINTERNFREELANCE
weeklyHoursnumber
Ore settimanali del contratto.
locationIdsuuid[]
Sedi a cui la persona è collegata.
positionIdsuuid[]
Postazioni che può occupare.
Sede
iduuid
Identificativo della sede.
namestring
Nome.
addressstring · o null
Indirizzo, se presente.
timezonestring
Fuso orario IANA, per esempio Europe/Zurich.
Postazione
iduuid
Identificativo della postazione.
namestring
Nome.
colorstring
Colore di visualizzazione, in esadecimale.
requiredSkillsstring[]
Competenze richieste per occupare la postazione.
Endpoint
Tutti i percorsi partono dall’URL di base. Oltre agli errori propri di ogni chiamata, tutti possono rispondere 401, 403 e 429.
GET/shiftsPermessoshifts:read
Elencare i turni
Restituisce i turni dell’organizzazione, per pagine.
from e to filtrano sull’ora di inizio: from è incluso, to è escluso.
Vengono restituiti tutti gli stati, turni annullati compresi: filtra su status se non li vuoi.
Parametri della richiesta
fromdatetime
Inizio della finestra, incluso.
todatetime
Fine della finestra, esclusa.
locationIduuid
Tieni solo questa sede.
employeeIduuid
Tieni solo questa persona.
positionIduuid
Tieni solo questa postazione.
limitinteger
Numero di turni per pagina.da 1 a 200predefinito: 50
cursoruuid
Valore di nextCursor ricevuto con la pagina precedente.
Risposta
200 Un oggetto con data, un array di oggetti Turno, e nextCursor.
Richiesta non valida: campo mancante o malformato, identificativo che non è un UUID, fine prima dell’inizio.Messaggi possibiliValidation failedValidation failed (uuid is expected)end must be strictly after start
401Unauthorized
Chiave assente, sconosciuta, revocata o scaduta.Messaggi possibiliMissing Bearer tokenEmpty bearer tokenInvalid API tokenToken revokedToken expired
402Payment Required
Abbonamento inattivo: periodo di prova terminato, pagamento non completato o abbonamento scaduto. Le scritture sono rifiutate, le letture restano possibili; tutto riprende appena è riattivato.Messaggi possibiliVotre période d’essai est terminée. Activez un abonnement pour continuer à modifier vos données.Votre paiement n’a pas été finalisé. Terminez la souscription pour reprendre les modifications.Votre abonnement est arrivé à échéance. Réactivez-le pour continuer à modifier vos données.
403Forbidden
La chiave non ha il permesso richiesto. Il messaggio indica il permesso mancante.Messaggi possibiliMissing scope: shifts:write
404Not Found
Risorsa non trovata nella tua organizzazione. Una risorsa di un’altra organizzazione dà esattamente la stessa risposta.Messaggi possibiliShift not foundemployee not foundposition not foundlocation not found
429Too Many Requests
Troppe richieste. Attendi il numero di secondi indicato da Retry-After.Messaggi possibiliThrottlerException: Too Many Requests
Un 400 ha tre forme
Corpo della richiesta rifiutato: message vale Validation failed e issues elenca ogni campo in causa.
Parametro di elenco rifiutato: il corpo è un oggetto le cui chiavi sono i nomi dei parametri in causa.
400
{
"limit": [
"Too big: expected number to be <=200"
]
}
Altri casi: il corpo standard.
400
{
"message": "end must be strictly after start",
"error": "Bad Request",
"statusCode": 400
}
Un corpo oltre i 5 MB viene rifiutato con un 413. Un 5xx segnala un guasto da parte nostra: riprova una lettura dopo un’attesa crescente; prima di ripetere una creazione, verifica che non sia andata a buon fine.
Limiti di frequenza
100 richieste per finestra di 60 secondi. Il contatore è tenuto separatamente per ogni endpoint ed è legato al chiamante: il suo indirizzo IP, oppure la sua chiave.
Ogni risposta porta X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset, il numero di secondi prima dell’azzeramento. Oltre il limite, la risposta è un 429 con Retry-After.
Un tetto globale per indirizzo protegge inoltre il servizio nel suo insieme. Risponde allo stesso modo.
429
HTTP/1.1 429 Too Many Requests
Retry-After: 42
Webhook
Un webhook ti invia una richiesta POST firmata ogni volta che si verifica un evento a cui sei abbonato. Li configuri in Impostazioni → Webhook.
L’indirizzo deve essere in https://, pubblico, senza credenziali nell’URL, e lungo al massimo 500 caratteri. Un indirizzo che porta a una rete privata viene rifiutato, al salvataggio e a ogni invio.
Il segreto di firma inizia con whs_ e viene mostrato una sola volta, alla creazione. Lo conserviamo cifrato (AES-256-GCM).
Come per le chiavi, serve un account autorizzato a gestire i webhook e il cui accesso copre tutta l’organizzazione.
sha256= seguito dall’impronta HMAC-SHA-256 del corpo grezzo, in esadecimale, calcolata con il tuo segreto.
X-SwissPlanif-Event
Nome dell’evento, identico al campo event.
X-SwissPlanif-Delivery-Id
Identificativo unico di questa consegna (UUID). Conservalo per riconoscere una consegna già elaborata.
eventstring
Nome dell’evento.
tenantIduuid
Identificativo della tua organizzazione.
occurredAtdatetime
Istante dell’invio, in UTC.
dataobject
Contenuto proprio dell’evento, descritto più sotto.
Verificare la firma
Leggi il corpo grezzo, byte per byte, prima di qualsiasi decodifica JSON.
Calcola il suo HMAC-SHA-256 con il tuo segreto e confrontalo con l’header tramite un confronto a tempo costante.
Rifiuta la richiesta se la firma non corrisponde, o se occurredAt risale a più di qualche minuto fa: è la tua protezione contro la riproduzione di una richiesta intercettata.
Rispondi 2xx subito, poi elabora l’evento in background.
Node.js, senza dipendenze
import { createHmac, timingSafeEqual } from 'node:crypto';
const MAX_AGE_MS = 5 * 60 * 1000;
// rawBody: the request body exactly as received (string or Buffer).
export function verifyWebhook(rawBody, signatureHeader, secret) {
const expected = Buffer.from(
`sha256=${createHmac('sha256', secret).update(rawBody).digest('hex')}`,
);
const received = Buffer.from(String(signatureHeader ?? ''));
if (received.length !== expected.length || !timingSafeEqual(received, expected)) {
return null;
}
const event = JSON.parse(rawBody.toString());
const age = Math.abs(Date.now() - Date.parse(event.occurredAt));
return age <= MAX_AGE_MS ? event : null;
}
// const event = verifyWebhook(
// rawBody,
// request.headers['x-swissplanif-signature'],
// process.env.SWISSPLANIF_WEBHOOK_SECRET,
// );
// if (!event) return response.writeHead(401).end();
Consegna
Un solo tentativo per evento, senza ripetizione automatica. Una risposta fuori da 2xx, un reindirizzamento o un’attesa di oltre 8 secondi contano come un errore.
Dopo 10 errori consecutivi, l’endpoint viene messo in pausa. Lo riattivi dalle Impostazioni, dove la cronologia delle sue consegne resta consultabile.
Un evento può quindi andare perso: per conoscere lo stato esatto, rileggi l’API.
Eventi
Il contenuto di data per ogni evento. Gli identificativi rimandano agli oggetti della tua organizzazione; le date sono in UTC.
shift.publishedTurno pubblicato
Un evento per ogni turno della pianificazione pubblicata.
shiftIduuid
Turno interessato.
scheduleIduuid
Pianificazione a cui appartiene il turno.
publicationIduuid
Pubblicazione che ha fissato questo turno.
employeeIduuid · o null
Persona interessata.
locationIduuid
Sede.
startdatetime
Inizio.
enddatetime
Fine.
weekStartdatetime
Inizio della settimana pubblicata.
publishedAtdatetime
Istante della pubblicazione.
shift.cancelledTurno annullato
Inviato quando un turno passa allo stato annullato. Un’eliminazione non invia nulla.
shiftIduuid
Turno interessato.
scheduleIduuid · o null
Pianificazione a cui appartiene il turno.
employeeIduuid · o null
Persona interessata.
locationIduuid
Sede.
startdatetime
Inizio.
enddatetime
Fine.
absence.requestedRichiesta di assenza
absenceIduuid
Assenza interessata.
employeeIduuid
Persona interessata.
startdatetime
Inizio.
enddatetime
Fine.
absence.approvedAssenza approvata
Approvare un’assenza non annulla più alcun turno: cancelledShifts vale sempre 0.
absenceIduuid
Assenza interessata.
cancelledShiftsinteger
Sempre 0.
keptShiftsinteger
Numero di turni della persona che si sovrappongono all’assenza e restano al loro posto.
absence.rejectedAssenza rifiutata
Inviato per un rifiuto, e anche quando un’assenza già approvata viene ritirata, per intero o per un solo giorno: revoked vale allora true.
absenceIduuid
Assenza interessata.
reasonstring
Motivo inserito dal responsabile, se presente.a seconda del casotesto libero
revokedboolean
true quando un’assenza già approvata viene ritirata.a seconda del caso
deletedboolean
true quando l’assenza ritirata è stata eliminata.a seconda del caso
partialboolean
true quando un solo giorno è stato tolto dall’assenza.a seconda del caso
restoredShiftsinteger
Numero di turni rimessi al loro posto.a seconda del caso
removedStartdatetime
Inizio del periodo tolto.a seconda del caso
removedEnddatetime
Fine del periodo tolto.a seconda del caso
tailAbsenceIduuid · o null
Assenza creata per i giorni successivi al giorno tolto, se ce ne sono.a seconda del caso
swap.requestedScambio richiesto
swapIduuid
Richiesta di scambio.
shiftIduuid
Turno interessato.
requestedByIduuid
Dipendente che chiede lo scambio.
targetEmployeeIduuid · o null
Dipendente a cui è rivolta, se la richiesta ne indica uno.
swap.approvedScambio approvato
swapIduuid
Richiesta di scambio.
swap.rejectedScambio rifiutato
swapIduuid
Richiesta di scambio.
reasonstring
Motivo inserito dal responsabile, se presente.a seconda del casotesto libero
open_shift.appliedCandidatura turno aperto
claimIduuid
Candidatura.
shiftIduuid
Turno interessato.
employeeIduuid
Persona interessata.
open_shift.assignedTurno aperto assegnato
claimIduuid
Candidatura.
shiftIduuid
Turno interessato.
employeeIduuid
Persona interessata.
shift_offer.sentProposta di missione inviata
offerIduuid
Proposta.
shiftIduuid
Turno interessato.
recipientsinteger
Numero di persone a cui è stata inviata la proposta.
shift_offer.claimedProposta di missione accettata
offerIduuid
Proposta.
shiftIduuid
Turno interessato.
employeeIduuid
Persona interessata.
mission.activatedMissione attivata
missionIduuid
Missione.
mission.completedMissione completata
missionIduuid
Missione.
mission.cancelledMissione annullata
missionIduuid
Missione.
employee.skill.expiringCompetenza in scadenza
Inviato una volta al giorno per ogni competenza che scade entro 30 giorni.
employeeSkillIduuid
Competenza del dipendente che sta per scadere.
employeeIduuid
Persona interessata.
skillIduuid
Competenza.
expiresAtdatetime
Data di scadenza.
observedAtdatetime
Istante del controllo.
noticeDaysinteger
Preavviso, in giorni.
Sicurezza
Una chiave API apre i dati di tutta la tua organizzazione. Queste regole stanno in una pagina: applicale tutte.
Dalla tua parte
01Una chiave per integrazione, il minor numero possibile di permessi
Una dashboard ha bisogno solo di leggere. Una chiave per strumento ti permette di revocarne una senza interrompere le altre.
02La chiave vive in un gestore di segreti
Mai in un repository, in un ticket, in un’e-mail o in uno screenshot, né nel codice di una pagina web o di un’app mobile.
03Chiama l’API da un server
Una chiave caricata in un browser è leggibile da chiunque apra la pagina. L’API non autorizza comunque nessun altro sito web a chiamarla da un browser.
04Sostituisci le tue chiavi regolarmente
Crea la nuova chiave, passa la tua integrazione a quella, verifica, poi revoca la vecchia. Le Impostazioni mostrano l’ultima chiamata di ogni chiave.
05Al minimo dubbio, revoca
La revoca ha effetto dalla chiamata successiva. Una chiave trapelata va considerata letta.
06Non registrare la chiave nei log
Maschera l’header Authorization nei tuoi log, nei tuoi strumenti di debug e nei tuoi rapporti di errore.
07Verifica ogni webhook
Firma sul corpo grezzo, confronto a tempo costante, rifiuto delle richieste vecchie. Prima di questa verifica non fidarti né dell’indirizzo di origine né del contenuto.
08Tratta i dati personali come tali
Nomi, indirizzi e-mail e note rientrano nella nLPD e nel GDPR. Copia solo ciò che ti serve, ed eliminalo quando non lo usi più.
09Convalida ciò che ricevi
Una nota o un motivo è un testo scritto da una persona. Tratta ogni valore ricevuto come un dato, mai come codice o come un comando da eseguire.
Dalla nostra parte
Di una chiave si conserva solo l’impronta SHA-256; la chiave appare una sola volta, alla sua creazione.
I permessi sono controllati a ogni chiamata, e ogni richiesta viene eseguita nel perimetro dell’organizzazione della chiave, isolato dalla Row-Level Security di PostgreSQL.
Una risorsa di un’altra organizzazione risponde come una risorsa che non esiste.
La creazione e la revoca di una chiave, così come ogni scrittura fatta tramite l’API, sono iscritte nel registro di audit con l’identificativo della chiave.
Il segreto di un webhook è cifrato a riposo (AES-256-GCM).
Prima di ogni invio, l’indirizzo di un webhook viene risolto e controllato: solo HTTPS, reti private rifiutate, certificato verificato, nessun reindirizzamento seguito.
In produzione, l’API non serve né una console interattiva né una descrizione OpenAPI.
Ogni endpoint ha un limite di frequenza, e ogni risposta porta gli header di sicurezza HSTS e CSP.
Hai trovato una vulnerabilità? Scrivi a contact@swissplanif.ch. Lo stato reale della nostra sicurezza, lacune comprese, è nella pagina Sicurezza.
Ciò che l’API non fa ancora
Ciò che manca oggi, perché tu lo sappia prima di costruirci sopra.
Le letture non vengono registrate
Il registro di audit conserva le scritture fatte tramite l’API, non le chiamate in lettura.
Nessuna chiave di idempotenza
Ripetere una creazione crea un secondo turno. Dopo un’interruzione, rileggi prima di ricreare.
Nessun controllo di dominio in scrittura
L’API non verifica né le sovrapposizioni né le regole sull’orario di lavoro che l’app segnala.
Webhook senza ripetizione
Una consegna non riuscita non viene ripetuta. L’errore resta visibile nella cronologia delle consegne, nelle Impostazioni.
Nessuna rotazione del segreto di un webhook
Per cambiare segreto, elimina l’endpoint e ricrealo.
Nessun ambiente di test
Esistono solo chiavi di produzione. Inizia con una chiave di sola lettura.
Elenchi non paginati
Dipendenti, sedi e postazioni vengono restituiti in una volta sola.