Zeitzonen-Booking-API: Entwickelt für KI-Agenten & Custom Frontends

Ihr KI-Agent hat gerade eine Beratung für 15 Uhr gebucht. Der Kunde ist in Tokio, der Therapeut in Berlin. Welche 15 Uhr hat der Agent gemeint?

Wenn die Antwort nicht sofort aus den API-Daten hervorgeht, haben Sie einen Zeitzonenfehler — die Art, die Unternehmen still Tausende an No-Shows, Support-Tickets und Vertrauensverlust kostet. Und wenn autonome KI-Agenten Buchungen ohne menschliche Kontrolle durchführen, ist Zeitzonenpräzision kein Nice-to-have. Sie ist kritische Infrastruktur.

Hier zeigt GraphQL seine Stärke. Anders als REST-Endpunkte, die undurchsichtige Zeitstempel zurückgeben und die Zeitzonen-Interpretation dem Aufrufer überlassen, kann eine typisierte GraphQL API Zeitzonen-Semantik direkt ins Schema kodieren — und KI-Agenten eindeutige, maschinenlesbare Zeitdaten in jeder Antwort liefern.

Bei Timerise haben wir jahrelang an einer Zeitzonenbehandlung gearbeitet, die diese gesamte Fehlerkategorie eliminiert — für menschliche Nutzer und für KI-Agenten. So funktioniert unsere GraphQL API, und was das für Entwickler bedeutet, die eigene Frontends bauen oder autonome Agenten anbinden.

Das Kernproblem: Lokalzeit ist eine Illusion (und KI-Agenten können nicht raten)

Jeder Entwickler lernt das irgendwann auf die harte Tour: Lokalzeit existiert nicht isoliert. „15:00 Uhr" bedeutet nichts ohne einen Zeitzonenbezug. Ein Mensch kann die richtige Zeitzone aus dem Kontext ableiten. Ein KI-Agent kann das nicht — er braucht explizite, strukturierte Daten. Und Zeitzonenbehandlung ist weit komplexer als das Addieren oder Subtrahieren von Stunden zu UTC.

Bedenken Sie diese Komplikationen:

Sommerzeit (DST) verschiebt die Uhr vor oder zurück, was bedeutet, dass manche Uhrzeiten zweimal im Jahr vorkommen und manche gar nicht existieren
IANA-Zeitzonenregeln ändern sich — Regierungen modifizieren DST-Regeln, manchmal mit nur wenigen Wochen Vorlauf
UTC-Offsets sind nicht statisch — Europe/Warsaw ist im Winter +01:00 und im Sommer +02:00

Wenn Ihr Buchungssystem Zeiten als „15:00 MEZ" speichert, haben Sie bereits ein Problem. MEZ ist mehrdeutig — es sagt nicht, ob die Sommerzeit gilt. Deshalb verfolgt Timerise einen grundlegend anderen Ansatz.

Timerise's UTC-First-Architektur

Unsere API folgt einem strikten UTC-First-Speichermodell. Jeder Zeitstempel in der Datenbank wird als UTC-Wert gespeichert. Keine lokalen Zeiten im Speicher, keine Mehrdeutigkeit, keine DST-Überraschungen.

Dies kombinieren wir mit IANA-Zeitzonenkennungen — dem Industriestandard der IANA Time Zone Database. Statt vager Abkürzungen wie „EST" oder „MEZ" verwenden wir präzise Kennungen wie America/New_York oder Europe/Warsaw, die die vollständige Historie der Zeitzonenregeln eines Ortes kodieren.

Jedes Projekt in Timerise trägt ein Pflichtfeld localTimeZone — eine einzige, abfragbare Quelle der Wahrheit, die KI-Agenten programmatisch auslesen können:

type Project {
  localTimeZone: TimeZone! # z.B. "Europe/Warsaw"
  now: DateTime! # Aktuelle UTC-Zeit
  nowISO: DateTimeISO! # Aktuelle Zeit in der Projekt-Zeitzone
}

Dieses einzige Feld steuert die gesamte Slot-Generierung, Buchungsausgabe und Anzeigeformatierung für alle Dienste in diesem Projekt. Eine einzige Quelle der Wahrheit, kein Rätselraten. Ein KI-Agent kann localTimeZone einmal abfragen und damit jeden Zeitstempel korrekt interpretieren, den das Projekt zurückgibt.

Zwei DateTime-Typen: Maschinenlesbar und menschenlesbar

Die Timerise API stellt zwei Skalartypen bereit, die das „Welche 15 Uhr?"-Problem lösen. Diese Unterscheidung macht die API besonders KI-Agenten-freundlich — der Agent weiß immer, welches Feld für Logik und welches für die Anzeige zu verwenden ist:

Skalar	Format	Beispiel	Anwendungsfall
`DateTime`	UTC ISO 8601	`2026-02-16T19:43:29.000Z`	Zeitarithmetik, Speicherung, Vergleiche
`DateTimeISO`	ISO 8601 mit Offset	`2026-02-16T20:43:29+01:00`	Lesbare Anzeige für Menschen

DateTime ist das maschinenfreundliche Format. Es endet immer mit Z (Zulu-Zeit = UTC). KI-Agenten sollten dieses Feld für alle Zeitberechnungen verwenden — Vergleiche, Sortierungen, Konflikterkennung und Planungslogik.

DateTimeISO ist das benutzerfreundliche Format. Es zeigt die lokale Zeit mit dem UTC-Offset, sodass ein Nutzer in Warschau 20:43:29+01:00 sieht — sofort verständlich, keine Kopfrechnung nötig. Wenn ein KI-Agent Zeiten für Endnutzer darstellen muss, liefert DateTimeISO einen anzeigefertigen Wert mit dem richtigen lokalen Offset.

Jeder Slot im System stellt beide bereit:

type Slot {
  dateTimeFrom: DateTime! # "2026-02-16T19:43:29.000Z"
  dateTimeFromISO: DateTimeISO! # "2026-02-16T20:43:29+01:00"
  dateTimeTo: DateTime!
  dateTimeToISO: DateTimeISO!
}

Für Entwickler eigener Frontends lautet die Regel: Verwenden Sie dateTimeFrom / dateTimeTo für Zeitarithmetik und dateTimeFromISO / dateTimeToISO für die Benutzeranzeige.

Automatische Zeitzonenerkennung in eigenen Frontends

Wenn Sie eine individuelle Buchungsseite auf Timerise aufbauen, befinden sich Ihre Nutzer möglicherweise in einer anderen Zeitzone als der Dienstanbieter. So gehen Sie damit elegant um.

Erkennung im Browser

Moderne Browser stellen die Zeitzone des Nutzers über die Intl API (Application Programming Interface) bereit:

const userTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
// Gibt IANA-Kennung zurück, z.B. "America/New_York"

Dies liefert eine korrekte IANA-Kennung — genau das Format, das Timerise erwartet. Sie können sie direkt bei der Buchungserstellung an die API übergeben:

mutation CreateBooking {
  bookingCreate(
    serviceId: "srv_12345"
    slots: ["slot_abc"]
    timeZone: "America/New_York" # von der Intl API
  ) {
    bookingId
    dateTimeFrom
    dateTimeFromISO
  }
}

Der timeZone-Parameter wird im Buchungsdokument gespeichert. Wenn der Nutzer später seine Bestätigung ansieht, formatiert das dateTimeFromISO-Feld die Zeit automatisch in seiner Zeitzone mit dem korrekten Offset.

Anzeigezeiten für Nutzer neu berechnen

Was, wenn Ihr Frontend Slot-Zeiten in der lokalen Zeitzone des Nutzers anzeigen muss statt in der des Anbieters? Die API liefert sowohl UTC- als auch Anbieter-Lokalzeiten, was Ihnen volle Flexibilität gibt.

Option A — Die API arbeiten lassen. Fragen Sie Slots normal ab und verwenden Sie die DateTime-Felder (UTC). Formatieren Sie sie dann client-seitig mit der erkannten Zeitzone:

const slotUTC = "2026-02-16T19:43:29.000Z";
const userTZ = Intl.DateTimeFormat().resolvedOptions().timeZone;

const localTime = new Date(slotUTC).toLocaleString("de-DE", {
  timeZone: userTZ,
  hour: "2-digit",
  minute: "2-digit",
  hour12: false,
});
// "14:43" für America/New_York (UTC-5)

Option B — Beide Perspektiven zeigen. Zeigen Sie die lokale Zeit des Anbieters (dateTimeFromISO) neben der lokalen Zeit des Nutzers. Das schafft Vertrauen bei zeitzonenübergreifenden Buchungen:

Terminzeit: 20:43 Warschau (14:43 Ihre Zeit)

Beide Ansätze funktionieren, weil die API Ihnen die UTC-Rohdaten und die Anbieter-formatierte Lokalzeit liefert. Sie entscheiden, wie Sie es präsentieren.

Slot-Generierung: Wo Zeitzonen knifflig werden

Hinter den Kulissen bewältigt die Slot-Generierungsengine von Timerise die schwierigsten Zeitzonenprobleme, damit Sie es nicht müssen.

Wenn ein Dienstanbieter seine Verfügbarkeit als „Montag bis Freitag, 9:00 bis 17:00 Uhr" festlegt, meint er Ortszeit. Aber das System speichert alles in UTC. Die Konvertierung muss DST-Übergänge berücksichtigen, bei denen sich der Offset mitten im Zeitplan ändert.

Timerise löst dies mit der date-fns-tz-Bibliothek und drei Kernfunktionen:

fromZonedTime(localDate, timeZone) — konvertiert lokale Uhrzeit zu UTC
toZonedTime(utcDate, timeZone) — konvertiert UTC zu lokaler Uhrzeit
formatInTimeZone(utcDate, timeZone, format) — formatiert ein UTC-Datum zur Anzeige in beliebiger Zeitzone

Die Generierungspipeline funktioniert so:

Anbieterzeitplan (Ortszeiten) → Konvertierung zu UTC-Grenzen via fromZonedTime
Slot-Überlappungserkennung → reine UTC-Millisekundenarithmetik, keine Zeitzonenumrechnung
Arbeitszeitfilterung → toZonedTime rechnet zurück in Ortszeit für Tageszeit-Vergleiche
Ausgabeassemblierung → sowohl DateTime (UTC) als auch DateTimeISO (Offset-formatiert) Felder

Das bedeutet: Ein 9:00-Uhr-Slot in Europe/Warsaw wird korrekt zu 08:00:00Z im Winter (+01:00) und 07:00:00Z im Sommer (+02:00). Die Slot-Generierung erledigt dies automatisch über DST-Grenzen hinweg — kein manuelles Eingreifen nötig.

Praktische Tipps für Frontend-Entwickler

Sie bauen ein eigenes Frontend auf Timerise? Beachten Sie diese Richtlinien:

1. Senden Sie immer UTC für DateTime-Eingaben

Der DateTime-Skalar parst Eingaben als UTC. Senden Sie keine Ortszeiten ohne Z-Suffix — sie werden als UTC fehlinterpretiert:

✅ Korrekt: "2026-02-16T19:43:29.000Z"
❌ Falsch:  "2026-02-16T20:43:29"  (wird als UTC behandelt, 1 Stunde daneben)

2. Wann `DateTimeISO`- vs `DateTime`-Eingaben verwenden

DateTimeISO-Ausgabefelder werden bei jeder Abfrage aus dem gespeicherten UTC-Wert und der Buchungszeitzone berechnet. Aber DateTimeISO wird auch als Eingabe akzeptiert — bookingCreate, bookingReschedule, bookings und services unterstützen dateTimeISOFrom / dateTimeISOTo-Parameter. Verwenden Sie DateTimeISO-Eingaben, wenn Sie bereits eine Lokalzeit mit Offset haben (z.B. aus dem Kalender des Nutzers). Verwenden Sie DateTime-Eingaben (UTC), wenn Sie Zeitarithmetik durchführen oder bereits in UTC konvertiert haben.

3. Fehlende Zeitzone elegant behandeln

Ältere Buchungsdatensätze könnten kein timeZone-Feld haben, wodurch dateTimeFromISO null zurückgibt. Fallen Sie immer auf das UTC-Feld dateTimeFrom zurück:

const displayTime = booking.dateTimeFromISO ?? new Date(booking.dateTimeFrom).toLocaleString();

4. Zeitzone einmal erkennen, überall verwenden

Rufen Sie Intl.DateTimeFormat().resolvedOptions().timeZone einmal beim Seitenladen auf und speichern Sie das Ergebnis. Übergeben Sie dieselbe IANA-Kennung an jede bookingCreate- oder bookingReschedule-Mutation. Konsistenz verhindert nicht zusammenpassende Zeitzonendatensätze. Für KI-Agenten sollte die Zeitzone aus dem Nutzerprofil oder Sitzungskontext erfasst und konsistent in jedem API-Aufruf übergeben werden.

5. Denken Sie daran: DST-Tage sind nicht immer 24 Stunden

Wenn Sie eine Tagesansicht bauen, gehen Sie nicht davon aus, dass 24 * 60 * 60 * 1000 Millisekunden einem Tag entsprechen. Während DST-Übergängen kann ein lokaler Tag 23 oder 25 Stunden lang sein. Verwenden Sie Bibliotheksfunktionen (wie date-fns) für Datumsarithmetik statt roher Millisekundenrechnung.

DateTimeISO als Eingabe: Lokalzeiten direkt senden

Über die Rolle als Ausgabe-Skalar hinaus wird DateTimeISO als Eingabetyp für Abfragen und Mutationen akzeptiert. Das bedeutet, Sie können Lokalzeiten mit ihrem UTC-Offset direkt senden — die API parst den Offset und konvertiert intern zu UTC.

Dies ist eine bedeutende Verbesserung für KI-Agenten und LLM-basierte Apps. Statt Lokalzeiten vor jedem API-Aufruf in UTC umzurechnen, kann ein Agent die Lokalzeit des Nutzers direkt mit dem Offset übergeben — weniger Konvertierungslogik, eine Fehlerklasse eliminiert, einfacherer und zuverlässigerer Agent-Code.

Die folgenden Abfragen und Mutationen akzeptieren dateTimeISOFrom / dateTimeISOTo-Parameter:

Abfragen: bookings und services — Ergebnisse nach lokalem Zeitbereich filtern
Mutationen: bookingCreate und bookingReschedule — Buchungszeiten in Lokalzeit angeben

mutation CreateBooking {
  bookingCreate(
    serviceId: "srv_12345"
    dateTimeISOFrom: "2026-03-15T09:00:00+01:00"
    dateTimeISOTo: "2026-03-15T10:00:00+01:00"
  ) {
    bookingId
    status
  }
}

query GetBookings {
  bookings(
    dateTimeISOFrom: "2026-03-15T00:00:00+01:00"
    dateTimeISOTo: "2026-03-16T00:00:00+01:00"
  ) {
    bookingId
    dateTimeFrom
    dateTimeFromISO  # Startuhrzeit mit UTC-Offset (z.B. "2026-03-15T09:00:00+01:00")
  }
}

Keine manuelle UTC-Konvertierung. Keine Offset-Arithmetik. Die API erledigt es.

Warum GraphQL + volle Zeitzonenunterstützung der beste Stack für KI-Agenten ist

Zeitzonenfehler sind keine Randfälle — sie vernichten Umsatz. Jede falsche Terminzeit bedeutet:

Nichterscheinen verwirrter Kunden
Support-Tickets frustrierter Nutzer
Doppelbuchungen, wenn sich Slots über DST-Übergänge überschneiden
Haftungsrisiken bei medizinischer oder juristischer Terminplanung

Wenn KI-Agenten Buchungen autonom durchführen, sind die Risiken noch höher. Es gibt keinen Menschen in der Schleife, der einen Zeitzonenfehler abfängt, bevor er den Kunden erreicht. Die API muss by Design korrekt sein.

Hier schafft die Kombination aus GraphQL und voller Zeitzonenunterstützung von Timerise einen einzigartig leistungsfähigen Stack für autonome Agenten:

Typsicherheit auf Schema-Ebene — DateTime, DateTimeISO und TimeZone-Skalare verhindern, dass der Agent fehlerhafte Zeitdaten sendet. Das Schema ist der Vertrag.
Introspektion — ein KI-Agent kann das Schema selbst nach verfügbaren Feldern und Typen abfragen. Kein Dokumentations-Parsing, kein Halluzinationsrisiko.
Präzises Data-Fetching — der Agent fordert nur die Zeitfelder an, die er braucht. Kein Over-Fetching, keine verschwendeten Tokens.
Eindeutige Zeitzonen-Semantik — jede Antwort enthält sowohl UTC- als auch Offset-formatierte Zeiten. Der Agent weiß immer genau, welche Zeitzone ein Wert repräsentiert.
DateTimeISO-Eingaben — Agenten senden Lokalzeiten direkt, ohne clientseitige UTC-Konvertierung.

REST APIs überlassen die Zeitzonen-Interpretation dem Aufrufer. GraphQL APIs mit typisierten Zeitzonen-Skalaren machen es unmöglich, einen Zeitstempel falsch zu interpretieren. Für KI-Agenten, die skaliert über mehrere Zeitzonen arbeiten, ist das keine Bequemlichkeit — es ist eine Voraussetzung.

Die Timerise API übernimmt die Komplexität. Ihr Frontend — oder Ihr KI-Agent — übernimmt das Erlebnis. Ihre Nutzer sehen die richtige Zeit, jedes Mal.

Bereit, zeitzonenbewusste Buchungserlebnisse mit KI-Agenten zu bauen?

Timerise API-Dokumentation erkunden →

Lesen: GraphQL — Das perfekte Backend für KI-Agenten →

GraphQL-Abfragen live testen →

Registrieren und kostenlos loslegen →

<br>

Mateusz Sowa