Date e ora: gestione nell'API di esportazione dei dati

Il modello di data e ora

Tre regole descrivono il modo in cui l’API gestisce le date e gli orari:

1. Ogni richiesta indirizzata a /jobs, /printer-states e /printer-interventions deve includere un parametro timezone contenente un identificatore di fuso orario IANA valido, ad esempio America/Denver o Europe/Bucharest.
2. Qualsiasi valore startDateTime o endDateTime fornito nella richiesta viene interpretato come ora locale nel fuso orario specificato. I valori non includono l'Offset UTC.
3. Ogni valore relativo alla data e all’ora contenuto nella risposta è formattato come ora locale nello stesso fuso orario, utilizzando il formato YYYY-MM-DDTHH:MM:SS.sss.

Il parametro timezone determina il significato della richiesta e la formattazione della risposta. Due richieste relative agli stessi dati sottostanti, inviate con fusi orari diversi, generano risposte con stringhe di data/ora diverse, sebbene descrivano gli stessi eventi.

Formato di data e ora

L'API utilizza un unico formato per tutti i valori relativi alla data e all'ora, sia nelle richieste che nelle risposte:

YYYY-MM-DDTHH:MM:SS.sss

Ad esempio, 2026-03-15T14:30:00.000 corrisponde alle 14:30:00 del 15 marzo 2026, secondo il fuso orario specificato nella richiesta.

Nelle richieste, la parte relativa ai millisecondi (.sss) è facoltativa. Nelle risposte, è sempre presente.

Intervallo di tempo predefinito

È possibile omettere startDateTime, endDateTime o entrambi. Le due impostazioni predefinite vengono applicate in modo indipendente:

• Se si omette il parametro startDateTime, l'API utilizza come punto di inizio dell'intervallo il momento che precede di 24 ore l'ora corrente.
• Se si omette il parametro endDateTime, l'API utilizza l'ora corrente come data di fine dell'intervallo.

Le impostazioni predefinite si combinano nel modo che ci si aspetterebbe:

• Se si omettono entrambi i valori, l'API restituisce i dati relativi alle ultime 24 ore.
• Se si specifica startDateTime come "un’ora fa" e si omette endDateTime, l’API restituisce i dati relativi all’ora precedente.
• Se si specifica endDateTime e si omette startDateTime, l’API restituisce i dati relativi all’intervallo che inizia 24 ore prima della richiesta e termina all’endDateTime.

I valori predefiniti vengono calcolati in base al fuso orario specificato nella richiesta.

Conservazione dei dati: gli ultimi sette giorni

L'API di esportazione dei dati fornisce dati operativi in tempo reale. I registri dei lavori, la cronologia dello stato della stampante e gli eventi di intervento sono disponibili solo per i sette giorni precedenti. Una richiesta relativa a dati risalenti a più di sette giorni fa genera un errore.

Pianifichi l’integrazione in modo che le estrazioni pianificate vengano eseguite con una frequenza sufficiente a acquisire tutti i dati prima che questi diventino obsoleti:

• Per gli estratti notturni, si raccomanda di prevedere un margine di almeno uno o due giorni. Se un'esecuzione pianificata non va a buon fine, ha il tempo di indagare e di rieseguirla prima che i dati non siano più disponibili.
• Per i riempimenti o le estrazioni una tantum, non richieda dati risalenti a più di sette giorni fa.

Regole relative all'intervallo richiesto

• startDateTime deve essere precedente a endDateTime. Una richiesta che violi questa regola genera l'errore ERR_INVALID_DATE_RANGE.
• Entrambi i valori devono rispettare il formato descritto all'indirizzo Formato di data e ora. Una richiesta contenente un valore non valido genera un errore ERR_INVALID_DATE_FORMAT.
• L'intervallo di tempo compreso tra startDateTime e endDateTime non deve superare l'intervallo massimo consentito. Una richiesta che superi il limite massimo genera un errore ERR_DATE_RANGE_EXCEEDED.

Indicare il fuso orario

Il parametro timezone accetta gli identificatori di fuso orario IANA, quali America/Denver, America/New_York, Europe/Bucharest, Asia/Tokyo o UTC. La pagina della documentazione interattiva presenta un elenco di tutti i valori accettati dall'API.

Un identificatore non valido o non riconosciuto genera l'errore ERR_INVALID_TIMEZONE. Le abbreviazioni di tre lettere, quali MST o EST, non sono identificatori IANA e non sono accettate; si prega di utilizzare invece il corrispondente identificatore basato sull'area (ad esempio, America/Denver o America/New_York).

Fornitura della lingua

Il parametro timezone non è l'unico parametro che determina il modo in cui l'API formatta una risposta. L'endpoint /printer-interventions accetta anche un parametro facoltativo relativo alla language, che determina la lingua del campo description nella risposta.

I valori ammessi sono en (inglese), de (tedesco), ja (giapponese), it (italiano), fr (francese) ed es (spagnolo). Se il valore non è presente in questo elenco, l'operazione genera un errore con codice ERR_INVALID_LANGUAGE.

È opportuno tenere in considerazione due aspetti di questo parametro:

• Se omette il parametro, oppure se la descrizione non è disponibile nella lingua da Lei richiesta, la descrizione verrà restituita in inglese. La richiesta va a buon fine in entrambi i casi, pertanto la vostra integrazione non può dare per scontato che la lingua di una descrizione sia corrispondente a quella richiesta.
• Il parametro influisce esclusivamente sul campo della description. Il campo interventionCode ad esso associato è indipendente dalla lingua; pertanto, lo utilizzi quando ha bisogno di raggruppare, confrontare o memorizzare gli eventi in modo coerente, indipendentemente dalla lingua richiesta.

Ora legale e orari ambigui

Poiché le richieste e le risposte sono espresse in ora locale, i passaggi all’ora legale danno luogo a due situazioni di cui occorre tenere conto:

Orari locali saltati durante il passaggio all'ora legale

Quando si sposta in avanti l’orologio, un’ora dell’ora locale non esiste. Ad esempio, nel fuso orario America/Denver, il giorno del passaggio all’ora legale, le 02:30:00 non costituiscono un’ora locale valida. Si prega di evitare di utilizzare orari compresi nell'ora saltata come startDateTime o endDateTime.

Orari locali ripetuti durante il passaggio all’autunno

Quando si sposta indietro l’orologio, un’ora di ora locale si verifica due volte. Un valore come 01:30:00 nel giorno del cambio di ora autunnale è ambiguo. Scelga orari al di fuori dell'ora ripetuta per evitare incertezze riguardo all'istanza che sta richiedendo.

Se la Sua integrazione viene eseguita in modo automatico e potrebbe inviare una richiesta il cui orario di inizio o di fine ricada all’interno di una transizione, pianifichi l’esecuzione della richiesta in modo che avvenga a distanza di alcune ore dalla transizione oppure utilizzi orari che siano chiaramente al di fuori di essa.

Raccomandazioni per l'archiviazione e il confronto delle date/ore delle risposte

Le date/ore delle risposte indicano l'ora locale senza alcun offset. Per evitare ambiguità nei sistemi a valle, si raccomanda di adottare uno dei seguenti approcci:

• Salvi la data/ora della risposta insieme al fuso orario specificato nella richiesta. Questi due elementi, considerati nel loro insieme, definiscono un istante unico nel tempo.
• Nella Sua integrazione, converta ogni data/ora della risposta in UTC prima di memorizzarla, utilizzando il fuso orario specificato nella richiesta. La memorizzazione dei valori UTC semplifica i confronti tra dati estratti con fusi orari diversi.
• Inviate sempre le richieste utilizzando lo stesso fuso orario, ad esempio UTC, in modo che tutte le date/ore memorizzate siano direttamente comparabili.

Esempi

Gli esempi seguenti illustrano come il fuso orario, l'ora di inizio e l'ora di fine interagiscano tra loro.

Finestra predefinita in Mountain Time

Una richiesta inviata alle ore 9:00 del 15 marzo 2026, nel fuso orario America/Denver, senza che siano state specificate né l'ora di inizio né quella di fine, restituisce i dati compresi tra 2026-03-14T09:00:00 e 2026-03-15T09:00:00, con entrambi gli orari interpretati in Mountain Time.

Fascia oraria specifica nell’Europa orientale

Una richiesta che specifichi timezone=Europe/Bucharest, startDateTime=2026-03-15T08:00:00 e endDateTime=2026-03-15T16:00:00 restituisce i dati relativi alla giornata lavorativa di otto ore secondo l’ora locale di Bucarest. Anche le date/ore delle risposte sono espresse nell'ora locale di Bucarest.

La stessa finestra visualizzata in due fusi orari

Per recuperare due volte gli stessi dati sottostanti, formattati per due diversi gruppi di destinatari, invii due richieste con valori timezone diversi e modifichi startDateTime e endDateTime in modo che corrispondano agli stessi istanti in ciascun fuso orario. I payload delle risposte descrivono gli stessi eventi, ma utilizzano stringhe di data/ora diverse.