Indicare la persona dietro una scrittura

Indicare la persona dietro una scrittura#

Il tuo token è un token macchina: non ha il claim sub, quindi l’API non può stabilire chi è responsabile di una modifica. I record che devono attribuire una persona ti obbligano perciò a indicarne una, in un campo del corpo authorizing_manager.

POST /api/public/v1/shifts/ HTTP/1.1
Host: app.shiftavo.com
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "location": "0194d1c0-…",
  "position": "0194d1c0-…",
  "start_date": "2026-08-01T09:00:00Z",
  "end_date": "2026-08-01T17:00:00Z",
  "authorizing_manager": "0194d1c0-…"
}

Le regole#

  • Obbligatorio su ogni scrittura shifts che non sia una cancellazione — creazione, PATCH, publish, unpublish, cancel, assegnazione — e su POST /events/. Ometterlo produce un 400 che nomina il campo. Le cancellazioni (compresa la rimozione di un’assegnazione) non lo richiedono — un DELETE non porta mai un corpo.

  • Il valore è un id di dipendente ottenuto da GET /employees/, lo stesso spazio di id usato dal resto della superficie.

  • Deve essere un membro con ruolo di gestione — Proprietario, Amministratore o Manager — della tua azienda. Qualsiasi altro caso è un 400.

  • Se ne indichi uno su una decisione sulle assenze (confirm/, decline/, revoke/) o su un approve/ o unapprove/ del foglio ore, quella persona deve avere anche l’autorizzazione per l’azione. Per le assenze, chi ha fatto la richiesta deve rientrare nell’ambito dei dati del ruolo di quella persona, che può decidere sulle proprie assenze solo se il suo ruolo copre l’intera azienda. Altrimenti la chiamata è un 403.

  • Viene registrato come autore o assegnatore del record e compare nella cronologia delle modifiche.

Non devi mai indovinare quali scritture lo richiedono: la voce di ogni operazione nella Referenza API indica il campo.

Scegliere un valore#

La maggior parte delle integrazioni designa un unico manager di servizio — la persona responsabile di ciò che fa l’integrazione — e invia quell’id su ogni scrittura. Se il tuo sistema di origine sa già quale manager ha approvato una modifica, indica quella persona: la cronologia delle modifiche diventa così davvero utile, invece di attribuire tutto allo stesso nome.

L’id deve restare valido. Se il ruolo di quella persona viene declassato sotto il livello di gestione — o se lascia del tutto l’azienda — le scritture iniziano a fallire con un 400 finché non ne indichi un’altra: meglio quindi un account che sopravviva ai cambi di personale.