API REST · v1

Pilota SwissPlanif dalle tue automazioni.

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.

curl
curl "https://api.swissplanif.ch/api/v1/locations" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN"

Autenticazione

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.

shifts:read
Elencare i turni e leggerne uno.GET/shiftsGET/shifts/{id}
shifts:write
Creare, modificare ed eliminare turni. Non dà la lettura.POST/shiftsPATCH/shifts/{id}DELETE/shifts/{id}
employees:read
Leggere la rubrica dei dipendenti: nomi, indirizzi e-mail, contratto.GET/employees
locations:read
Leggere le sedi.GET/locations
positions:read
Leggere le postazioni.GET/positions

Convenzioni

  • 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
curl "https://api.swissplanif.ch/api/v1/shifts?from=2026-11-16T00:00:00Z&to=2026-11-23T00:00:00Z&limit=50" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN"
Risposta · 200
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "start": "2026-11-16T07:00:00.000Z",
      "end": "2026-11-16T15:00:00.000Z",
      "breakMinutes": 30,
      "status": "DRAFT",
      "positionId": "00000000-0000-4000-8000-0000000000a1",
      "positionName": "Front desk",
      "locationId": "00000000-0000-4000-8000-0000000000b1",
      "locationName": "Lausanne Centre",
      "employeeId": "00000000-0000-4000-8000-0000000000c1",
      "employeeFullName": "Alex Example",
      "note": null,
      "createdAt": "2026-11-11T09:30:00.000Z",
      "updatedAt": "2026-11-11T09:30:00.000Z"
    }
  ],
  "nextCursor": "00000000-0000-4000-8000-000000000001"
}
GET/shifts/{id}Permessoshifts:read

Leggere un turno

Restituisce un turno tramite il suo identificativo.

  • Un identificativo sconosciuto e un identificativo di un’altra organizzazione danno la stessa risposta: 404.

Parametri della richiesta

iduuid
Identificativo del turno, nel percorso.obbligatorio

Risposta

200 Un oggetto Turno.

Richiesta
curl "https://api.swissplanif.ch/api/v1/shifts/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN"
Risposta · 200
{
  "id": "00000000-0000-4000-8000-000000000001",
  "start": "2026-11-16T07:00:00.000Z",
  "end": "2026-11-16T15:00:00.000Z",
  "breakMinutes": 30,
  "status": "DRAFT",
  "positionId": "00000000-0000-4000-8000-0000000000a1",
  "positionName": "Front desk",
  "locationId": "00000000-0000-4000-8000-0000000000b1",
  "locationName": "Lausanne Centre",
  "employeeId": "00000000-0000-4000-8000-0000000000c1",
  "employeeFullName": "Alex Example",
  "note": null,
  "createdAt": "2026-11-11T09:30:00.000Z",
  "updatedAt": "2026-11-11T09:30:00.000Z"
}
POST/shiftsPermessoshifts:write

Creare un turno

Crea un turno nello stato DRAFT.

  • end deve essere strettamente successivo a start.
  • positionId, locationId e employeeId devono esistere nella tua organizzazione, altrimenti 404.
  • L’API non pubblica il turno e non invia alcuna notifica.

Corpo della richiesta

startdatetime
Inizio del turno.obbligatorio
enddatetime
Fine, strettamente dopo l’inizio.obbligatorio
breakMinutesinteger
Pausa, in minuti.da 0 a 600predefinito: 0
positionIduuid
Postazione, nella tua organizzazione.obbligatorio
locationIduuid
Sede, nella tua organizzazione.obbligatorio
employeeIduuid · o null
Persona assegnata, oppure null per un turno senza persona.predefinito: null
notestring · o null
Nota libera.al massimo 2000 caratteripredefinito: null

Risposta

201 Un oggetto Turno.

Richiesta
curl -X POST "https://api.swissplanif.ch/api/v1/shifts" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "start": "2026-11-16T07:00:00.000Z",
  "end": "2026-11-16T15:00:00.000Z",
  "breakMinutes": 30,
  "positionId": "00000000-0000-4000-8000-0000000000a1",
  "locationId": "00000000-0000-4000-8000-0000000000b1",
  "employeeId": "00000000-0000-4000-8000-0000000000c1"
}'
Risposta · 201
{
  "id": "00000000-0000-4000-8000-000000000001",
  "start": "2026-11-16T07:00:00.000Z",
  "end": "2026-11-16T15:00:00.000Z",
  "breakMinutes": 30,
  "status": "DRAFT",
  "positionId": "00000000-0000-4000-8000-0000000000a1",
  "positionName": "Front desk",
  "locationId": "00000000-0000-4000-8000-0000000000b1",
  "locationName": "Lausanne Centre",
  "employeeId": "00000000-0000-4000-8000-0000000000c1",
  "employeeFullName": "Alex Example",
  "note": null,
  "createdAt": "2026-11-11T09:30:00.000Z",
  "updatedAt": "2026-11-11T09:30:00.000Z"
}
PATCH/shifts/{id}Permessoshifts:write

Modificare un turno

Modifica i campi inviati; gli altri non cambiano.

  • Se invii solo start o solo end, l’intervallo risultante viene controllato con il valore già registrato.
  • employeeId: null rimuove la persona; note: null cancella la nota.

Parametri della richiesta

iduuid
Identificativo del turno, nel percorso.obbligatorio

Corpo della richiesta

Tutti i campi sono facoltativi: invia solo quelli che modifichi.

startdatetime
Inizio del turno.
enddatetime
Fine, strettamente dopo l’inizio.
breakMinutesinteger
Pausa, in minuti.da 0 a 600
positionIduuid
Postazione, nella tua organizzazione.
locationIduuid
Sede, nella tua organizzazione.
employeeIduuid · o null
Persona assegnata, oppure null per un turno senza persona.
notestring · o null
Nota libera.al massimo 2000 caratteri

Risposta

200 Un oggetto Turno.

Richiesta
curl -X PATCH "https://api.swissplanif.ch/api/v1/shifts/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "employeeId": null,
  "note": "Cover needed"
}'
Risposta · 200
{
  "id": "00000000-0000-4000-8000-000000000001",
  "start": "2026-11-16T07:00:00.000Z",
  "end": "2026-11-16T15:00:00.000Z",
  "breakMinutes": 30,
  "status": "DRAFT",
  "positionId": "00000000-0000-4000-8000-0000000000a1",
  "positionName": "Front desk",
  "locationId": "00000000-0000-4000-8000-0000000000b1",
  "locationName": "Lausanne Centre",
  "employeeId": null,
  "employeeFullName": null,
  "note": "Cover needed",
  "createdAt": "2026-11-11T09:30:00.000Z",
  "updatedAt": "2026-11-11T10:05:00.000Z"
}
DELETE/shifts/{id}Permessoshifts:write

Eliminare un turno

Elimina il turno, definitivamente.

  • Un’eliminazione non invia l’evento shift.cancelled.

Parametri della richiesta

iduuid
Identificativo del turno, nel percorso.obbligatorio

Risposta

204 Nessun corpo.

Richiesta
curl -X DELETE "https://api.swissplanif.ch/api/v1/shifts/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN"
GET/employeesPermessoemployees:read

Elencare i dipendenti

Restituisce i dipendenti attivi dell’organizzazione, ordinati per cognome.

  • La risposta contiene dati personali: nomi e indirizzi e-mail.

Risposta

200 Un array di oggetti Dipendente, in un’unica risposta.

Richiesta
curl "https://api.swissplanif.ch/api/v1/employees" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN"
Risposta · 200
[
  {
    "id": "00000000-0000-4000-8000-0000000000c1",
    "firstName": "Alex",
    "lastName": "Example",
    "email": "alex@example.com",
    "contractType": "PERMANENT",
    "weeklyHours": 42,
    "locationIds": [
      "00000000-0000-4000-8000-0000000000b1"
    ],
    "positionIds": [
      "00000000-0000-4000-8000-0000000000a1"
    ]
  }
]
GET/locationsPermessolocations:read

Elencare le sedi

Restituisce le sedi dell’organizzazione, ordinate per nome.

  • Questa chiamata non accetta parametri.

Risposta

200 Un array di oggetti Sede, in un’unica risposta.

Richiesta
curl "https://api.swissplanif.ch/api/v1/locations" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN"
Risposta · 200
[
  {
    "id": "00000000-0000-4000-8000-0000000000b1",
    "name": "Lausanne Centre",
    "address": "Example street 1, 1000 Lausanne",
    "timezone": "Europe/Zurich"
  }
]
GET/positionsPermessopositions:read

Elencare le postazioni

Restituisce le postazioni dell’organizzazione, ordinate per nome.

  • Questa chiamata non accetta parametri.

Risposta

200 Un array di oggetti Postazione, in un’unica risposta.

Richiesta
curl "https://api.swissplanif.ch/api/v1/positions" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN"
Risposta · 200
[
  {
    "id": "00000000-0000-4000-8000-0000000000a1",
    "name": "Front desk",
    "color": "#6366f1",
    "requiredSkills": []
  }
]

Errori

Leggi prima il codice HTTP: è quello che fa fede. La maggior parte degli errori ha il corpo standard qui sotto, con un message in inglese.

403
{
  "message": "Missing scope: shifts:write",
  "error": "Forbidden",
  "statusCode": 403
}
400Bad Request
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

  1. Corpo della richiesta rifiutato: message vale Validation failed e issues elenca ogni campo in causa.

    400
    {
      "message": "Validation failed",
      "issues": [
        {
          "expected": "string",
          "code": "invalid_type",
          "path": [
            "positionId"
          ],
          "message": "Invalid input: expected string, received undefined"
        }
      ]
    }
  2. 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"
      ]
    }
  3. 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.

Che cosa ricevi

POST
POST /webhooks/swissplanif HTTP/1.1
Host: hooks.example.com
Content-Type: application/json
X-SwissPlanif-Event: shift.published
X-SwissPlanif-Signature: sha256=<hex digest>
X-SwissPlanif-Delivery-Id: 00000000-0000-7000-8000-000000000101

{
  "event": "shift.published",
  "tenantId": "00000000-0000-4000-8000-0000000000d1",
  "occurredAt": "2026-11-13T16:02:11.000Z",
  "data": {
    "shiftId": "00000000-0000-4000-8000-000000000001",
    "scheduleId": "00000000-0000-4000-8000-0000000000e1",
    "publicationId": "00000000-0000-4000-8000-0000000000f1",
    "employeeId": "00000000-0000-4000-8000-0000000000c1",
    "locationId": "00000000-0000-4000-8000-0000000000b1",
    "start": "2026-11-16T07:00:00.000Z",
    "end": "2026-11-16T15:00:00.000Z",
    "weekStart": "2026-11-15T23:00:00.000Z",
    "publishedAt": "2026-11-13T16:02:10.000Z"
  }
}
X-SwissPlanif-Signature
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

  1. Leggi il corpo grezzo, byte per byte, prima di qualsiasi decodifica JSON.
  2. Calcola il suo HMAC-SHA-256 con il tuo segreto e confrontalo con l’header tramite un confronto a tempo costante.
  3. 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.
  4. 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

  1. Una 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.

  2. La 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.

  3. Chiama 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.

  4. Sostituisci 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.

  5. Al minimo dubbio, revoca

    La revoca ha effetto dalla chiamata successiva. Una chiave trapelata va considerata letta.

  6. Non registrare la chiave nei log

    Maschera l’header Authorization nei tuoi log, nei tuoi strumenti di debug e nei tuoi rapporti di errore.

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

  8. Tratta 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ù.

  9. Convalida 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.
Nessuna descrizione OpenAPI pubblicata
Questa pagina è il riferimento.
API pubblica — SwissPlanif · SwissPlanif