API-Dokumentation

Authentifizierung

Alle API-Anfragen müssen über einen API-Schlüssel authentifiziert werden. API-Schlüssel werden pro Kalender erstellt und können im Dashboard unter dem Tab „API-Schlüssel" verwaltet werden.

Sende deinen API-Schlüssel im Header:

x-api-key: your_api_key_here

Basis-URL

Alle Endpunkte verwenden die folgende Basis-URL:

https://termine.lol

Fehlerbehandlung

Alle Fehler werden als JSON mit einem `error`-Feld zurückgegeben:

{
  "error": "Ungültiger API-Key"
}

HTTP-Statuscodes

• 400 — Ungültige Anfrage (fehlende Parameter)
• 401 — Ungültiger oder fehlender API-Key
• 403 — API-Key nicht für diesen Kalender / Limit erreicht
• 404 — Ressource nicht gefunden
• 409 — Konflikt (Slot bereits belegt)
• 429 — Zu viele Anfragen (Rate Limit)
• 500 — Interner Serverfehler

Buchungsablauf

Der typische Ablauf einer Buchung über die API:

1. 1. Kalender abrufen → Mitglieder und Terminarten erhalten
2. 2. Slots abrufen → Verfügbare Zeitfenster für einen Tag laden
3. 3. Slot reservieren → 10-Minuten-Reservation erstellen
4. 4. Buchung abschließen → Kundendaten senden, Bestätigungs-E-Mail wird versendet
5. 5. Kunde bestätigt → Per Klick auf den E-Mail-Link wird die Buchung bestätigt

Kalender abrufen

Gibt die Grundinformationen eines Kalenders zurück, inklusive aktiver Mitglieder.

curl -H "x-api-key: your_api_key" \
  https://termine.lol/api/embed/calendars/CALENDAR_ID

Pfad-Parameter

Antwort

{
  "data": {
    "id": "...",
    "title": "My Calendar",
    "timezone": "Europe/Berlin",
    "members": [
      { "id": "...", "name": "Max Mustermann" }
    ]
  }
}

Verfügbare Slots abrufen

Gibt die verfügbaren Zeitfenster für einen bestimmten Tag und eine Terminart zurück.

curl -H "x-api-key: your_api_key" \
  "https://termine.lol/api/embed/calendars/CALENDAR_ID/slots?date=2025-03-15&appointmentTypeId=TYPE_ID"

Query-Parameter

Antwort

{
  "data": {
    "date": "2025-03-15",
    "personUserId": "any",
    "availableSlots": [
      { "slotIndex": 36, "time": "09:00" },
      { "slotIndex": 37, "time": "09:15" },
      { "slotIndex": 38, "time": "09:30" }
    ],
    "byPerson": [...]
  }
}

Slot reservieren

Reserviert einen Zeitslot für 10 Minuten. Innerhalb dieser Zeit muss die Buchung abgeschlossen werden.

curl -X POST https://termine.lol/api/public/bookings/reserve \
  -H "Content-Type: application/json" \
  -d '{
    "calendarId": "CALENDAR_ID",
    "appointmentTypeId": "TYPE_ID",
    "date": "2025-03-15",
    "startSlot": 36
  }'

Request Body

Antwort

{
  "data": {
    "bookingId": "...",
    "reservationExpiresAt": "2025-03-15T10:10:00.000Z",
    "fields": [
      { "key": "email", "label": "E-Mail", "type": "email", "required": true },
      { "key": "name", "label": "Name", "type": "text", "required": true }
    ]
  }
}

Buchung abschließen

Sendet die Kundendaten für eine reservierte Buchung. Der Kunde erhält eine Bestätigungs-E-Mail.

curl -X POST https://termine.lol/api/public/bookings/submit \
  -H "Content-Type: application/json" \
  -d '{
    "bookingId": "BOOKING_ID",
    "customerEmail": "kunde@beispiel.de",
    "customerData": {
      "email": "kunde@beispiel.de",
      "name": "Max Mustermann"
    }
  }'

Request Body

Antwort

{
  "data": {
    "success": true,
    "message": "Bestätigungs-E-Mail gesendet"
  }
}

Rate Limiting

API-Endpunkte sind rate-limited. Die Limits variieren je nach Endpunkt:

• 30 Anfragen / Minute (Kalender & Slots)
• 5 Anfragen / Minute (Reservierung & Buchung)