--- title: Timelogrammi description: "#### Struttura dati Skyplanner Prima di immergerci nei timelogrammi, dobbiamo parlare un po' della struttura dei dati di Skyplanner e di come funzionano le cose sotto il cofano. Tutto questo entrerà in gioco più avanti. Se hai integrato i dati…" url: "https://skyplanner.ai/it/docs/timelogrammi/" updated: "2025-10-07" category: Integrazioni tags: - API - Integrazione --- # Timelogrammi #### Struttura dati Skyplanner Prima di immergerci nei timelogrammi, dobbiamo parlare un po' della struttura dei dati di Skyplanner e di come funzionano le cose sotto il cofano. Tutto questo entrerà in gioco più avanti. Se hai integrato i dati dei tuoi ordini/lavori/commesse in Skyplanner, molto probabilmente hai utilizzato almeno questi punti API: - ordini di phaser - phaser-order-rows - phaser-lavori In effetti, i dati inseriti in questi endpoint sono rappresentati nell'interfaccia utente di Skyplanner in questo modo: ![](https://skyplanner.ai/wp-content/uploads/2025/03/image-25-1024x714.png) **Figura 1.** Ordine (phaser-ordini) ![](https://skyplanner.ai/wp-content/uploads/2025/03/image-26-1024x715.png) **Figura 2.** Voci dell'ordine (phaser-order-rows (rosso)), Fasi del processo (phaser-jobs (verde)) Dopo aver inserito gli ordini in Skyplanner, dovrai **esportarli** (questo può essere fatto tramite l'interfaccia utente o il punto finale /phaser-orders/export) nel modulo di programmazione della produzione: ![](https://skyplanner.ai/wp-content/uploads/2025/03/image-27-1024x596.png) **Figura 3.** Esportazione attraverso l'interfaccia utente ![](https://skyplanner.ai/wp-content/uploads/2025/03/image-28-1024x597.png) **Figura 4.** Ordine esportato in Pianificazione della produzione Quando si esportano gli ordini, Skyplanner copia effettivamente i dati dell'ordine da una tabella del database a un'altra. Quindi, se cambi qualcosa, ad esempio attraverso l'endpoint /phaser-orders, devi esportare nuovamente i dati per aggiornarli in Production Scheduling. Questo significa anche che per accedere agli ordini che vedi nella finestra di Production Scheduling devi utilizzare diversi endpoint API! Gli endpoint "modificati" sono i seguenti: - /phaser-ordini → /ordini - /phaser-order-rows → /order-rows - /phaser-jobs → /jobs Questo è importante da sapere, perché quando utilizzi l'endpoint /timelogs per registrare gli eventi di produzione, ecc. **devi utilizzare le entità correlate che si trovano negli endpoint Production Scheduling!** Ad esempio, hai bisogno del **production_planning_job_id**(per ribadire: i production_planning_jobs sono le entità a cui si accede dall'endpoint /jobs) per POSTARE un nuovo timelog: ![](https://skyplanner.ai/wp-content/uploads/2025/03/image-29.png) **Figura 5.** Richiesta POST del timelog Puoi trovare il production_planning_job_id che ti serve dal punto finale /phaser-jobs: ![](https://skyplanner.ai/wp-content/uploads/2025/03/image-30.png) **Figura 6.** Richiesta GET di un lavoro Phaser (il rosso è phaser_job_id, **NON USARLO NEI TIMELOGS**) Oppure dal punto finale /job: ![](https://skyplanner.ai/wp-content/uploads/2025/03/image-31.png) **Figura 7.** Richiesta GET di /lavoro #### Creare timelog usando la REST-API L'inserimento di timelogrammi in Skyplanner attraverso l'API utilizza le stesse regole e gli stessi sistemi presenti nell'interfaccia utente. Per questo motivo potrebbe essere utile familiarizzare con il funzionamento del sistema nell'interfaccia utente prima di provare a usarlo attraverso l'API. ##### Nozioni di base del timelog Skyplanner ha quattro tipi di eventi timelog: - shift_begin - in pausa - continua - fine turno L'evento Shift_begin viene inviato quando il lavoro viene avviato per la prima volta. **Non inviare mai più di un evento shift_begin per ogni lavoro!** L'evento Pausa mette in pausa il lavoro. Continued-event riprende un lavoro in pausa. Shift_end completa il lavoro. **Non inviare mai più di un evento shift_end per ogni lavoro!** Dati richiesti per i timelogrammi: - persona_id - Può essere trovato dall'endpoint /people - Non è la stessa cosa di user_id! - workstation_prevista_id - La postazione di lavoro in cui viene svolto il lavoro - Può essere trovato dall'endpoint /workstations - data_ora - Il momento in cui l'evento viene realizzato - Formato: 2024-01-01 10:30:11 Per specificare quale timelog di Skyplanner è legato al timelog del sistema esterno che stai utilizzando, puoi utilizzare il campo **external_id**. Potrai quindi, ad esempio, fare richieste GET utilizzando questo id per trovare un timelog specifico da Skyplanner. ![](https://skyplanner.ai/wp-content/uploads/2025/03/image-32-1024x438.png) **Figura 8.** External_id nei timelog #### Iniziare un lavoro Puoi avviare i lavori inviando una richiesta POST come questa all'API: ![](https://skyplanner.ai/wp-content/uploads/2025/03/image-33.png) **Figura 9.** Shift_begin timelog Quando si impostano i dati POST per i timelog, impostare **workshift_id**come 0 e **timelog_finalized**come **true**. #### Mettere in pausa un lavoro Metti in pausa i lavori inviando una richiesta POST come questa: ![](https://skyplanner.ai/wp-content/uploads/2025/03/image-34.png) **Figura 10.** Timelog in pausa Nei timelog di tipo pausa puoi impostare l'**importo**e l'**importo_guasto**. Nota anche il **tipo di**timelog e la **data_ora**. #### Continuare a lavorare Ecco come continuare un timelog in pausa: ![](https://skyplanner.ai/wp-content/uploads/2025/03/image-35.png) **Figura 11.** Cronologia continua Nota che se cerchi di continuare un lavoro che è stato terminato da un evento shift_end, otterrai un errore. #### Terminare un lavoro Ecco come terminare un lavoro con un timelog shift_end: ![](https://skyplanner.ai/wp-content/uploads/2025/03/image-36.png) **Figura 12.** Timelog Shift_end In shift_end-events puoi indicare i valori **amount**e **faulty_amount**proprio come in paused-events. Nota che se provi a fare uno shift_end-event a un lavoro che non è in esecuzione, otterrai un errore. #### Aggiornamento dei timelogrammi Puoi aggiornare i dati del timelog inviando richieste PUT all'endpoint /timelogs, in questo modo: ![](https://skyplanner.ai/wp-content/uploads/2025/03/image-37.png) **Figura 13.** Modifica dei timelogrammi Nota che per effettuare un aggiornamento è necessario che siano impostati sia i dati di **beginTimelog**che di **endTimelog**. I timelog in Skyplanner sono memorizzati in questo modo: ogni timelog "completo" (timelog che ha sia un inizio che una fine (es. shift_begin/continued & paused/shift_end) ha un'entità separata per l'inizio e la fine. Questi sono accoppiati dal valore **begin_id**trovato nell'endlog. Nell'esempio precedente il beginTimelog ha il valore id 1 e quindi il suo endTimelog ha il valore **begin_id**1. Devi anche indicare i valori **person_id**e **endTimelog**ogni volta che fai una richiesta di aggiornamento, anche se non li stai modificando. #### Modi alternativi per fare i timelogrammi Ecco alcuni modi alternativi per accedere ai tuoi lavori utilizzando l'API. ##### Logfull Se vuoi inviare sia il timelog iniziale che quello finale in un'unica richiesta, puoi utilizzare il punto **/timelogs/log-full** -end, in questo modo: ![](https://skyplanner.ai/wp-content/uploads/2025/03/image-38.png) **Figura 14.** Richiesta di logfull Nota come vengono inviati gli importi: il primo valore "amount" indica l'**importo difettoso** e il secondo l'**importo**. Questa richiesta crea le entità beginlog e endlog in un'unica richiesta. ##### Registro rapido Il "Quicklogging" di un lavoro lo completa in un'unica richiesta e imposta la quantità di prodotti completati in modo che corrisponda al valore impostato nell'articolo dell'ordine. Il quicklogging si effettua utilizzando l'endpoint **/timelogs/quick-log**: ![](https://skyplanner.ai/wp-content/uploads/2025/03/image-39.png) **Figura 15.** Quicklogging Nota che in questo caso devi indicare solo i dati **production_planning_job_id**, **planned_workstation_id**e **person_id**. I valori di tempo e importo vengono compilati automaticamente. Tieni inoltre presente che i lavori in quicklogger vengono sempre completati con l'evento shift_end, quindi non è possibile effettuare ulteriori registrazioni dopo il quicklog!