Umgang mit Datum und Uhrzeit in der Datenexport-API

Das Datum und Uhrzeitmodell

Drei Regeln beschreiben, wie die API mit Datum und Uhrzeitangaben umgeht:

1. Jede Anfrage an /Jobs, /printer-states und /printer-interventions muss einen timezone enthalten, der eine gültige IANA-Zeitzonenbezeichnung enthält, beispielsweise America/Denver oder Europe/Bucharest.
2. Jeder in der Anfrage angegebene Wert für startDateTime oder endDateTime wird als Ortszeit in der angegebenen Zeitzone interpretiert. Die Werte enthalten keinen UTC-Versatz.
3. Jeder Datum und Zeitwert in der Antwort wird als Ortszeit in derselben Zeitzone im Format JJJJ-MM-TTTHH:MM:SS.sss dargestellt.

Der Parameter timezone bestimmt die Bedeutung der Anfrage und die Formatierung der Antwort. Zwei Anfragen für dieselben zugrunde liegenden Daten, die mit unterschiedlichen Zeitzonen übermittelt wurden, führen zu Antworten mit unterschiedlichen Zeitstempel-Zeichenfolgen, obwohl sie dieselben Ereignisse beschreiben.

Datum und Uhrzeitformat

Die API verwendet sowohl in Anfragen als auch in Antworten ein einheitliches Format für alle Datums- und Zeitangaben:

YYYY-MM-DDTHH:MM:SS.sss

Beispielsweise entspricht 2026-03-15T14:30:00.000 dem 15. März 2026 um 14:30:00 Uhr, interpretiert in der mit der Anfrage angegebenen Zeitzone.

In Anfragen ist der Millisekunden-Teil (.sss) optional. In den Antworten ist es stets vorhanden.

Standardzeitbereich

Sie können startDateTime, endDateTime oder beides weglassen. Die beiden Standardwerte werden unabhängig voneinander angewendet:

• Wenn Sie startDateTime weglassen, verwendet die API den Zeitpunkt 24 Stunden vor der aktuellen Uhrzeit als Beginn des Zeitraums.
• Wenn Sie endDateTime weglassen, verwendet die API die aktuelle Uhrzeit als Endzeitpunkt des Zeitraums.

Die Standardeinstellungen werden so kombiniert, wie Sie es erwarten würden:

• Wenn Sie beide Werte weglassen, gibt die API Daten für die letzten 24 Stunden zurück.
• Wenn Sie für startDateTime den Wert „vor einer Stunde“ angeben und endDateTime weglassen, gibt die API Daten für die vergangene Stunde zurück.
• Wenn Sie endDateTime angeben und startDateTime weglassen, gibt die API Daten für den Zeitraum zurück, der 24 Stunden vor der Anfrage beginnt und mit endDateTime endet.

Die Standardwerte werden in der mit der Anfrage angegebenen Zeitzone berechnet.

Aufbewahrungsfrist: die letzten sieben Tage

Die Datenexport-API stellt Betriebsdaten in Echtzeit bereit. Jobs, der Verlauf des Druckerstatus und Interventionsereignisse sind nur für die letzten sieben Tage verfügbar. Eine Anfrage nach Daten, die älter als sieben Tage sind, führt zu einer Fehlermeldung.

Planen Sie Ihre Integration so, dass geplante Datenextrakte häufig genug ausgeführt werden, um alle Daten zu erfassen, bevor diese veralten:

• Für nächtliche Auszüge sollten Sie eine Sicherheitsmarge von mindestens ein bis zwei Tagen einplanen. Sollte ein geplanter Lauf fehlschlagen, haben Sie Zeit, die Ursache zu ermitteln und den Lauf erneut auszuführen, bevor die Daten nicht mehr verfügbar sind.
• Bei Nachlieferungen oder einmaligen Datenextrakten fordern Sie bitte keine Daten an, die älter als sieben Tage sind.

Regeln für den angeforderten Bereich

• startDateTime muss vor endDateTime liegen. Eine Anfrage, die gegen diese Regel verstößt, schlägt mit dem Fehler ERR_INVALID_DATE_RANGE fehl.
• Beide Werte müssen das unter Datum und Uhrzeitformat beschriebene Format aufweisen. Eine Anfrage mit einem fehlerhaften Wert schlägt mit dem Fehler ERR_INVALID_DATE_FORMAT fehl.
• Der Zeitraum zwischen startDateTime und endDateTime darf den maximal zulässigen Bereich nicht überschreiten. Eine Anfrage, die das Maximum überschreitet, schlägt mit dem Fehler ERR_DATE_RANGE_EXCEEDED fehl.

Angabe der Zeitzone

Der Parameter timezone akzeptiert IANA-Zeitzonenbezeichnungen wie beispielsweise America/Denver, America/New_York, Europe/Bucharest, Asia/Tokyo oder UTC. Auf der interaktiven Dokumentationsseite ist eine Liste aller Werte aufgeführt, die die API akzeptiert.

Ein ungültiger oder nicht erkannter Bezeichner führt zu einem Fehler mit dem Code ERR_INVALID_TIMEZONE. Dreibuchstabige Abkürzungen wie MST oder EST sind keine IANA-Kennungen und werden nicht akzeptiert; verwenden Sie stattdessen die entsprechende Bereichs-Kennung (beispielsweise America/Denver oder America/New_York).

Bereitstellung der Sprache

Der Parameter timezone ist nicht der einzige Parameter, der bestimmt, wie die API eine Antwort formatiert. Der Endpunkt /printer-interventions akzeptiert zudem einen optionalen language-Parameter, der die Sprache des description-Feldes in der Antwort festlegt.

Die zulässigen Werte sind en (Englisch), de (Deutsch), ja (Japanisch), it (Italienisch), fr (Französisch) und es (Spanisch). Ein Wert, der nicht in dieser Liste enthalten ist, führt zu einem Fehler mit dem Code ERR_INVALID_LANGUAGE.

Zwei Aspekte dieses Parameters sollten bei der Planung berücksichtigt werden:

• Wenn Sie den Parameter weglassen oder wenn in der von Ihnen gewünschten Sprache keine Beschreibung verfügbar ist, wird die Beschreibung auf Englisch zurückgegeben. Die Anfrage ist in beiden Fällen erfolgreich; daher darf Ihre Integration nicht davon ausgehen, dass es zwischen der Sprache einer Beschreibung und der angeforderten Sprache eine Übereinstimmung gibt.
• Der Parameter wirkt sich ausschließlich auf das description-feld aus. Das dazugehörige Feld interventionCode ist sprachunabhängig; verwenden Sie dieses Feld daher, wenn Sie Ereignisse unabhängig von der angeforderten Sprache einheitlich gruppieren, vergleichen oder speichern müssen.

Sommerzeit und mehrdeutige Zeitangaben

Da Anfragen und Antworten als Ortszeit ausgedrückt werden, ergeben sich durch den Wechsel zur Sommerzeit zwei Situationen, die Sie beachten sollten:

Übersprungene Ortszeiten beim Wechsel zur Sommerzeit

Wenn die Uhren vorgestellt werden, existiert eine Stunde der Ortszeit nicht. Beispielsweise ist in America/Denver am Tag der Zeitumstellung auf Sommerzeit 02:30:00 keine gültige Ortszeit. Vermeiden Sie es, Zeitangaben aus der übersprungenen Stunde als startDateTime oder endDateTime zu verwenden.

Wiederkehrende Ortszeiten im Herbstübergang

Wenn die Uhren zurückgestellt werden, tritt eine Stunde Ortszeit zweimal auf. Ein Wert wie 01:30:00 am Tag der Zeitumstellung ist mehrdeutig. Wählen Sie Zeitpunkte außerhalb der wiederkehrenden Stunde, um Unklarheiten darüber zu vermeiden, welche Instanz Sie anfordern.

Falls Ihre Integration unbeaufsichtigt läuft und möglicherweise eine Anfrage übermittelt, deren Start- oder Endzeit in einen Übergang fällt, planen Sie die Ausführung der Anfrage so, dass sie einige Stunden vor oder nach dem Übergang erfolgt, oder wählen Sie Zeitpunkte, die eindeutig außerhalb des Übergangs liegen.

Empfehlungen zur Speicherung und zum Vergleich von Antwortzeitstempeln

Die Zeitstempel der Antworten sind Ortszeiten ohne Versatz. Um Mehrdeutigkeiten in nachgelagerten Systemen zu vermeiden, sollten Sie einen der folgenden Ansätze in Betracht ziehen:

• Speichern Sie den Zeitstempel der Antwort zusammen mit der Zeitzone, die Sie in der Anfrage angegeben haben. Zusammen genommen verdeutlicht dieses Paar einen einzigartigen Moment in der Zeit.
• Konvertieren Sie in Ihrer Integration jeden Zeitstempel einer Antwort vor dem Speichern in UTC, wobei Sie die von Ihnen in der Anfrage angegebene Zeitzone verwenden. Die Speicherung von UTC-Werten vereinfacht Vergleiche zwischen Daten, die in unterschiedlichen Zeitzonen erfasst wurden.
• Reichen Sie Anfragen stets in derselben Zeitzone ein, beispielsweise in UTC, damit alle gespeicherten Zeitstempel direkt miteinander vergleichbar sind.

Beispiele

Die folgenden Beispiele veranschaulichen, wie die Zeitzone, die Startzeit und die Endzeit zusammenwirken.

Standardfenster in der Mountain Time

Eine Anfrage, die am 15. März 2026 um 9:00 Uhr in der Zeitzone America/Denver, ohne Angabe einer Start- oder Endzeit, liefert Daten vom 2026-03-14T09:00:00 bis zum 2026-03-15T09:00:00, wobei beide Zeitangaben in Mountain Time interpretiert werden.

Bestimmter Zeitraum in osteuropäischer Zeit

Eine Anfrage mit den Parametern timezone=Europe/Bucharest, startDateTime=2026-03-15T08:00:00 sowie endDateTime=2026-03-15T16:00:00 enthält, liefert Daten für den achtstündigen Arbeitstag in Bukarester Ortszeit. Die Zeitstempel der Antworten werden ebenfalls in der Ortszeit von Bukarest angegeben.

Dasselbe Fenster in zwei Zeitzonen

Um dieselben zugrunde liegenden Daten zweimal abzurufen – jeweils für zwei Zielgruppen aufbereitet –, senden Sie zwei Anfragen mit unterschiedlichen timezone und passen Sie startDateTime und endDateTime so an, dass sie in jeder Zeitzone denselben Zeitpunkt beschreiben. Die Antwort-Nutzdaten beschreiben dieselben Ereignisse, verwenden jedoch unterschiedliche Zeitstempel-Zeichenfolgen.