Verwerking van datum en tijd in de gegevensexport-API

Het datum- en tijdmodel

Er zijn drie regels die beschrijven hoe de API met datums en tijden omgaat:

1. Elk verzoek aan /jobs, /printer-states en /printer-interventions moet een timezone bevatten met een geldige IANA-tijdzone-identificatie, bijvoorbeeld America/Denver of Europe/Bucharest.
2. Elke waarde voor startDateTime of endDateTime die in het verzoek wordt opgegeven, wordt geïnterpreteerd als lokale tijd in de opgegeven tijdzone. De waarden bevatten geen UTC-verschuiving.
3. Elke datum- en tijdwaarde in het antwoord wordt weergegeven als lokale tijd in dezelfde tijdzone, volgens het patroon JJJJ-MM-DDTHH:MM:SS.sss.

De parameter timezone bepaalt de betekenis van het verzoek en de opmaak van het antwoord. Twee verzoeken om dezelfde onderliggende gegevens, die met verschillende tijdzones zijn ingediend, leveren antwoorden op met verschillende tijdstempeltekenreeksen, ook al hebben deze betrekking op dezelfde gebeurtenissen.

Datum- en tijdnotatie

De API hanteert één indeling voor alle datum- en tijdwaarden, zowel in verzoeken als in antwoorden:

YYYY-MM-DDTHH:MM:SS.sss

Zo is 2026-03-15T14:30:00.000 bijvoorbeeld 14:30:00 uur op 15 maart 2026, geïnterpreteerd in de tijdzone die bij het verzoek is opgegeven.

In verzoeken is het gedeelte in milliseconden (.sss) optioneel. In reacties is het altijd aanwezig.

Standaard tijdsperiode

U kunt startDateTime, endDateTime of beide weglaten. De twee standaardinstellingen worden afzonderlijk toegepast:

• Indien u startDateTime weglaat, gebruikt de API het tijdstip 24 uur vóór het huidige tijdstip als begin van het bereik.
• Indien u endDateTime weglaat, gebruikt de API de huidige tijd als eindtijd van het tijdsbereik.

De standaardinstellingen werken samen zoals u zou verwachten:

• Indien u beide waarden weglaat, retourneert de API gegevens over de afgelopen 24 uur.
• Indien u startDateTime instelt op ‘één uur geleden’ en endDateTime weglaat, retourneert de API gegevens voor het afgelopen uur.
• Indien u endDateTime opgeeft en startDateTime weglaat, retourneert de API gegevens voor het tijdsbestek dat begint 24 uur vóór het verzoek en eindigt op het tijdstip van endDateTime.

Standaardwaarden worden berekend in de tijdzone die bij het verzoek is opgegeven.

Bewaartermijn van gegevens: de afgelopen zeven dagen

De gegevensexport-API levert operationele gegevens in realtime. Taken-gegevens, de geschiedenis van de printerstatus en interventiegebeurtenissen zijn slechts beschikbaar voor de afgelopen zeven dagen. Een verzoek om gegevens die ouder zijn dan zeven dagen levert een foutmelding op.

Plan uw integratie zodanig dat geplande extracties vaak genoeg worden uitgevoerd om alle gegevens vast te leggen voordat deze verouderd raken:

• Houd voor de nachtelijke extracties rekening met een marge van ten minste één of twee dagen. Als een geplande taak mislukt, heeft u de tijd om de oorzaak te achterhalen en de taak opnieuw uit te voeren voordat de gegevens niet meer beschikbaar zijn.
• Vraag bij aanvullingen of eenmalige gegevensopvragingen geen gegevens op die ouder zijn dan zeven dagen.

Regels voor het gevraagde bereik

• startDateTime moet eerder zijn dan endDateTime. Een verzoek dat in strijd is met deze regel leidt tot de foutmelding ERR_INVALID_DATE_RANGE.
• Beide waarden moeten de indeling volgen die wordt beschreven op Datum- en tijdnotatie. Een verzoek met een ongeldige waarde leidt tot een foutmelding ERR_INVALID_DATE_FORMAT.
• De periode tussen startDateTime en endDateTime mag het maximaal toegestane bereik niet overschrijden. Een verzoek dat de maximale waarde overschrijdt, leidt tot de foutmelding ERR_DATE_RANGE_EXCEEDED.

Het opgeven van de tijdzone

De parameter tijdzone accepteert IANA-tijdzone-identificaties, zoals America/Denver, America/New_York, Europe/Bucharest, Asia/Tokyo of UTC. Op de interactieve documentatiepagina is een lijst met alle waarden te vinden die de API accepteert.

Een ongeldige of niet-herkende identificatiecode leidt tot de foutmelding ERR_INVALID_TIMEZONE. Afkortingen van drie letters, zoals MST of EST, zijn geen IANA-identificatiecodes en worden niet geaccepteerd; gebruik in plaats daarvan de bijbehorende, op de regio gebaseerde identificatiecode (bijvoorbeeld America/Denver of America/New_York).

De taal leveren

De parameter timezone is niet de enige parameter die bepaalt hoe de API een antwoord opmaakt. Het eindpunt /printer-interventions accepteert tevens een optionele language-parameter, die de taal van het description-veld in het antwoord bepaalt.

De toegestane waarden zijn en (Engels), de (Duits), ja (Japans), it (Italiaans), fr (Frans) en es (Spaans). Een waarde die niet in deze lijst voorkomt, leidt tot een fout met de foutcode ERR_INVALID_LANGUAGE.

Er zijn twee aspecten van deze parameter waarmee u bij de planning rekening dient te houden:

• Indien u de parameter weglaat, of indien er geen beschrijving beschikbaar is in de door u gevraagde taal, wordt de beschrijving in het Engels weergegeven. Het verzoek wordt in beide gevallen uitgevoerd, dus uw integratie mag er niet van uitgaan dat de taal van een beschrijving overeenkomt met de taal waarnaar is gevraagd.
• Deze parameter is uitsluitend van invloed op het description-veld. Het bijbehorende veld interventionCode is taalonafhankelijk; maak daarom gebruik van dit veld wanneer u gebeurtenissen op een consistente manier wilt groeperen, vergelijken of opslaan, ongeacht de gevraagde taal.

Zomertijd en onduidelijke tijdsaanduidingen

Aangezien verzoeken en antwoorden worden uitgedrukt in lokale tijden, leiden de overgangen naar en van de zomertijd tot twee situaties waarmee u rekening dient te houden:

Overgeslagen lokale tijden tijdens de overgang naar de lente

Wanneer de klokken worden verzet, bestaat er één uur lokale tijd niet. In America/Denver is bijvoorbeeld op de dag van de overgang naar de zomertijd 02:30:00 geen geldige lokale tijd. Vermijd het gebruik van tijdstippen binnen het overgeslagen uur als startDateTime of endDateTime.

Herhaalde lokale tijden tijdens de overgang naar de herfst

Wanneer de klokken een uur achteruit worden gezet, komt er één uur lokale tijd twee keer voor. Een waarde zoals 01:30:00 op de dag van de overgang naar de herfst is dubbelzinnig. Kies tijdstippen buiten het herhaalde uur om onduidelijkheid te voorkomen over welke instantie u aanvraagt.

Indien uw integratie zonder toezicht wordt uitgevoerd en er een verzoek zou kunnen worden verzonden waarvan de start- of eindtijd binnen een overgang valt, plan het verzoek dan zo in dat het enkele uren vóór of na de overgang wordt uitgevoerd, of gebruik tijdstippen die duidelijk buiten de overgang vallen.

Aanbevelingen voor het opslaan en vergelijken van tijdstempels van reacties

De tijdstempels van de reacties zijn lokale tijden zonder verschuiving. Om onduidelijkheden in de daaropvolgende systemen te voorkomen, kunt u een van de volgende benaderingen overwegen:

• Sla de tijdstempel van het antwoord op, samen met de tijdzone die u in het verzoek hebt opgegeven. Samen geven deze twee een uniek moment in de tijd weer.
• Zorg er in uw integratie voor dat u elke tijdstempel van een antwoord omzet naar UTC voordat u deze opslaat, waarbij u de tijdzone gebruikt die u in het verzoek hebt opgegeven. Het opslaan van UTC-waarden vereenvoudigt het vergelijken van gegevens die in verschillende tijdzones zijn verzameld.
• Dien verzoeken altijd in met dezelfde tijdzone, bijvoorbeeld UTC, zodat alle opgeslagen tijdstempels direct met elkaar te vergelijken zijn.

Voorbeelden

De volgende voorbeelden laten zien hoe de tijdzone, de starttijd en de eindtijd op elkaar zijn afgestemd.

Standaardvenster in Mountain Time

Een verzoek dat op 15 maart 2026 om 09.00 uur is ingediend, in de tijdzone America/Denver, zonder opgegeven begin- of eindtijd, levert gegevens op vanaf 2026-03-14T09:00:00 tot en met 2026-03-15T09:00:00, beide uitgedrukt in Mountain Time.

Specifiek tijdvak in Oost-Europese tijd

Een verzoek met de parameters timezone=Europe/Bucharest, startDateTime=2026-03-15T08:00:00, en endDateTime=2026-03-15T16:00:00, levert gegevens op voor de werkdag van acht uur in de lokale tijd van Boekarest. De tijdstempels van de reacties worden eveneens weergegeven in lokale tijd van Boekarest.

Hetzelfde venster weergegeven in twee tijdzones

Om dezelfde onderliggende gegevens tweemaal op te halen, opgemaakt voor twee doelgroepen, dient u twee verzoeken in te dienen met verschillende tijdzonewaarden en de parameters startDateTime en endDateTime zodanig aan te passen dat zij in elke tijdzone dezelfde tijdstippen aangeven. De antwoordpayloads beschrijven dezelfde gebeurtenissen, maar gebruiken verschillende tekenreeksen voor tijdstempels.