Scope

Ogni operazione richiede esattamente uno scope, denominato <resource>.<action>:

shifts.read        locations.write        timesheets.read

• GET richiede .read.

• POST, PATCH, DELETE richiedono .write.

• La scrittura implica la lettura — shifts.write soddisfa anche shifts.read, quindi non serve mai richiedere entrambi.

Il catalogo

L’insieme concedibile è chiuso e fa parte del contratto. Eccolo per intero — una riga per risorsa, ciascuna con il proprio scope .read e .write:

Scope	Copre
account.read · account.write	Impostazioni del tenant (singleton).
areas.read · areas.write	Aree all’interno di una sede.
availability.read · availability.write	Blocchi di disponibilità dei dipendenti (comprese le ricorrenze).
break_rules.read · break_rules.write	Definizioni delle regole delle pause.
budgets.read · budgets.write	Budget del personale e obiettivi di ricavo.
employees.read · employees.write	Dipendenti, loro appartenenze, inviti e ciclo di vita.
employment_types.read · employment_types.write	Tipi di contratto e relativi valori predefiniti per il salario.
events.read · events.write	Eventi generali (non turni) e loro partecipanti.
holidays.read · holidays.write	Calendario dei giorni festivi.
labor_cost.read	Report del costo del personale.
leave_balances.read	Saldi delle assenze (sola lettura).
leave_policies.read · leave_policies.write	Politiche di assenza e relative progressioni a livelli.
leave_requests.read · leave_requests.write	Richieste di assenza e relative transizioni di esame.
locations.read · locations.write	Sedi.
open_shifts.read	Offerte di turni aperti (sola lettura su questa API).
positions.read · positions.write	Posizioni, requisiti di qualifica e assegnazioni dei dipendenti.
shifts.read · shifts.write	Turni, loro stato di pubblicazione e assegnazioni.
skills.read · skills.write	Catalogo delle qualifiche.
swaps.read	Offerte di scambio dei turni (sola lettura su questa API).
time_compensation.read · time_compensation.write	Giornale e saldi della compensazione in tempo.
timesheets.read · timesheets.write	Rapporti delle ore, timbrature, pause e approvazioni.
webhook_endpoints.read · webhook_endpoints.write	Registrazione degli endpoint dei webhook e rigenerazione dei segreti.
webhook_log.read	Cronologia degli eventi inviati per la riconciliazione.
work_rules.read · work_rules.write	Regole di lavoro (compreso il blocco della compensazione in tempo dell’art. 17b).

Per un singolo endpoint questa tabella non ti serve: ogni operazione nella Referenza API dichiara lo scope esatto che richiede, direttamente sull’operazione. Sia quel requisito sia la tabella qui sopra derivano dallo stesso valore che legge il controllo dei permessi sul server, quindi ciò che è documentato e ciò che è applicato non possono divergere.

Chiedere quelli giusti

Gli scope vengono concessi per singolo client di integrazione al momento della registrazione, quindi chiedi ciò che l’integrazione fa realmente e nulla di più. Un export dei salari che legge le ore ottiene timesheets.read e nient’altro.

Un errore di battitura viene individuato alla registrazione, non in esecuzione: shift.read viene rifiutato con un suggerimento, invece di registrare un client che fallisce a ogni chiamata.

Per aggiungere uno scope in seguito, scrivi a support@shiftavo.com — non servono nuove credenziali.

Quando manca uno scope

Una chiamata con un token valido ma senza l’autorizzazione richiesta è:

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "…",
    "details": []
  }
}

con stato 403. È distinto da un 401 (è il token stesso a non essere valido — vedi Autenticazione) e da un 404, che è anche ciò che ottieni per un record al di fuori della tua azienda, così l’esistenza non traspare mai.