← Zurück zur Startseite

API-Dokumentation

Integriere termine.lol in deine eigene Anwendung.

Authentifizierung

Die Embed-Endpunkte (Kalender & Slots) erfordern einen API-Schlüssel im Header. API-Schlüssel werden pro Kalender erstellt und können im Dashboard unter dem Tab „API-Schlüssel" verwaltet werden. Die Buchungs-Endpunkte (Reserve & Submit) sind öffentlich und benötigen keinen API-Schlüssel — sie sind per Rate-Limiting geschützt.

Sende deinen API-Schlüssel im Header x-api-key:

x-api-key: your_api_key
API-Zugang ist ab dem Pro-Plan verfügbar.
Einen Schlüssel brauchen alle Endpunkte unter /api/embed/ und /api/partner/. Gesperrte und widerrufene Schlüssel werden wie unbekannte behandelt (401). Verwende Schlüssel nur auf deinem Server: Die API sendet keine CORS-Header, Aufrufe aus dem Browser einer anderen Domain schlagen fehl.

Basis-URL

Alle Endpunkte verwenden die folgende Basis-URL:

https://termine.lol

Zeitangaben

startAt und endAt eines Termins sind die Uhrzeit vor Ort – in der Zeitzone des Kalenders (Feld timezone). Sie werden im ISO-Format mit einem Z am Ende ausgegeben, sind aber keine UTC-Zeit: „2026-10-01T09:00:00.000Z“ bedeutet 9:00 Uhr im Kalender, egal wo der Server steht. Dasselbe gilt für time und slotIndex der freien Zeitfenster (slotIndex zählt Viertelstunden ab Mitternacht, 36 = 09:00).

Echte Zeitpunkte in UTC sind dagegen createdAt, submittedAt, confirmedAt und reservationExpiresAt.

from und to der Buchungsliste werden ebenfalls als Uhrzeit vor Ort gelesen. Sende sie ohne Zeitzonen-Angabe, z. B. 2026-10-01 oder 2026-10-01T09:00:00.

Fehlerbehandlung

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

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

HTTP-Statuscodes

{
  "error": { "customerEmail": ["Ungültige E-Mail-Adresse"] }
}

{ "error": "rate_limited", "retryAfter": 42 }

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 und Terminarten.

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

Pfad-Parameter

ParameterDescription
id*Die Kalender-ID

Antwort

{
  "data": {
    "id": "...",
    "title": "My Calendar",
    "timezone": "Europe/Berlin",
    "members": [
      { "id": "...", "name": "Max Mustermann" }
    ],
    "appointmentTypes": [
      {
        "id": "...",
        "name": "Beratung",
        "description": "30-Minuten-Beratungsgespräch",
        "durationMin": 30,
        "mode": "online",
        "memberIds": ["..."]
      }
    ]
  }
}
Beide Kalender-Endpunkte liefern außerdem confirmationMode („instant“ oder „double_opt_in“) und je Terminart priceCents (Preis in Cent oder null), currency und category.

Verfügbare Slots abrufen

Gibt die verfügbaren Zeitfenster für einen bestimmten Tag und eine Terminart zurück. Ohne `personUserId` werden alle Mitglieder abgefragt und die Ergebnisse zusammengeführt (`byPerson` enthält die Aufschlüsselung).

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

Query-Parameter

ParameterDescription
id*Die Kalender-ID (string)
date*Datum im Format YYYY-MM-DD (string)
appointmentTypeId*ID der Terminart (string)
personUserIdMitglieder-ID (string, optional — Standard: „any" = alle Mitglieder)

Antwort

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

Slot reservieren

Reserviert einen Zeitslot für 10 Minuten. Innerhalb dieser Zeit muss die Buchung abgeschlossen werden. Dieser Endpunkt benötigt keinen API-Key — er ist öffentlich und per Rate-Limiting geschützt (20 Anfragen/Min.).

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

Request Body (JSON)

ParameterDescription
calendarId*Kalender-ID (string)
appointmentTypeId*Terminart-ID (string)
date*Datum im Format YYYY-MM-DD (string)
startSlot*Slot-Index 0–95, jeweils 15 Min. (number)
personUserIdMitglieder-ID (string, optional — ohne wird automatisch zugewiesen)
appointmentModeTerminmodus: „online" oder „in_person" (string, optional — nur bei Hybrid-Terminarten)

Antwort (201 Created)

{
  "data": {
    "bookingId": "abc123...",
    "reservationExpiresAt": "2026-03-15T10:10:00.000Z",
    "fields": [
      { "key": "email", "label": "E-Mail", "type": "email", "required": true },
      { "key": "name", "label": "Name", "type": "text", "required": true },
      { "key": "phone", "label": "Telefon", "type": "tel", "required": false }
    ]
  }
}
Die `fields` enthalten die Formularfelder, die bei der Buchung ausgefüllt werden müssen. Verwende die `key`-Werte als Schlüssel im `customerData`-Objekt beim Submit.
Optional: extraAppointmentTypeIds (bis zu 4 weitere Terminarten im selben Termin). calendarId darf auch der Slug des Kalenders sein.

Buchung abschließen

Sendet die Kundendaten für eine reservierte Buchung. Der Kunde erhält eine Bestätigungs-E-Mail mit einem Bestätigungslink. Dieser Endpunkt benötigt keinen API-Key — er ist öffentlich und per Rate-Limiting geschützt (5 Anfragen/Min.).

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

Request Body (JSON)

ParameterDescription
bookingId*Buchungs-ID aus der Reservierung (string)
customerEmail*E-Mail des Kunden (string)
customerData*Kundendaten als Objekt — Schlüssel entsprechen den `key`-Werten aus den `fields` der Reservierung (object)

Antwort (200 OK)

{
  "data": {
    "success": true,
    "message": "Bestätigungs-E-Mail gesendet"
  }
}
Die Antwort enthält confirmed: Bei Kalendern mit confirmationMode „instant“ ist die Buchung sofort bestätigt (confirmed: true, keine Bestätigungs-E-Mail nötig), sonst bestätigt der Kunde über den Link in der E-Mail (confirmed: false).

POST /api/public/bookings/abandon

Gibt eine Reservierung sofort wieder frei, wenn der Kunde abbricht. Body: { "bookingId": "…" }. Ohne diesen Aufruf verfällt sie nach 10 Minuten von selbst.


Rate Limiting

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


Berechtigungen (Scopes)

Jeder API-Schlüssel trägt Berechtigungen. Schlüssel ohne gespeicherte Berechtigungen (alle vor Einführung der Scopes erstellten) gelten als „embed“. Fehlt einem Schlüssel die nötige Berechtigung, antwortet die API mit 403 und `insufficient_scope`.

{
  "error": "insufficient_scope",
  "required": "bookings:read",
  "granted": ["embed"]
}
bookings:write schließt bookings:read nicht ein. Die Berechtigungen werden beim Erstellen des Schlüssels im Dashboard gewählt.

Welche Berechtigung welcher Endpunkt braucht


Partner-API

Endpunkte für Integrationen, die Termine anzeigen und verwalten (z. B. das WordPress-Plugin). Alle liegen unter /api/partner/, erwarten den API-Schlüssel im Header x-api-key und beziehen sich immer auf den Kalender des Schlüssels — es gibt keine Kalender-ID im Pfad.

GET /api/partner/calendar

Kalender des Schlüssels: Titel, Zeitzone, Mitglieder, Terminarten, Formularfelder und die Berechtigungen des Schlüssels.

curl -H "x-api-key: your_api_key" https://termine.lol/api/partner/calendar
{
  "data": {
    "id": "665f1c2e9b1d4a0012345678",
    "title": "Salon Demo",
    "slug": "salon-demo",
    "timezone": "Europe/Berlin",
    "confirmationMode": "double_opt_in",
    "members": [{ "id": "…", "name": "Alice" }],
    "appointmentTypes": [
      { "id": "…", "name": "Beratung", "description": "", "durationMin": 30, "mode": "online",
        "priceCents": 4200, "currency": "EUR", "category": "", "memberIds": [] }
    ],
    "fields": [{ "key": "name", "label": "Name", "type": "text", "required": true, "options": null }],
    "scopes": ["embed", "bookings:read"]
  }
}
Beide Kalender-Endpunkte liefern außerdem confirmationMode („instant“ oder „double_opt_in“) und je Terminart priceCents (Preis in Cent oder null), currency und category.

GET /api/partner/bookings

Buchungen auflisten. Standard: alle Status außer reserved und expired, 25 pro Seite.

curl -H "x-api-key: your_api_key" "https://termine.lol/api/partner/bookings?direction=future&limit=25&offset=0"

Query-Parameter

{
  "data": {
    "bookings": [
      {
        "id": "665f1c2e9b1d4a0012345678",
        "startAt": "2026-10-01T09:00:00.000Z",
        "endAt": "2026-10-01T09:30:00.000Z",
        "status": "confirmed",
        "appointmentType": { "id": "…", "name": "Beratung" },
        "member": { "id": "…", "name": "Alice" },
        "customer": { "email": "kunde@example.com", "name": "Max", "fields": { "phone": "…" } },
        "appointmentMode": "online",
        "meetLink": null,
        "internalNote": null,
        "anonymized": false,
        "createdAt": "2026-09-20T10:12:00.000Z",
        "submittedAt": "2026-09-20T10:13:10.000Z",
        "confirmedAt": "2026-09-20T10:15:42.000Z"
      }
    ],
    "total": 1,
    "limit": 25,
    "offset": 0
  }
}
Anonymisierte Buchungen kommen ohne Kundendaten zurück (anonymized: true).

GET /api/partner/bookings/:id

Eine Buchung mit allen Details. Gehört sie nicht zum Kalender des Schlüssels, antwortet die API mit 404.

PATCH /api/partner/bookings/:id

Buchung ändern, mit derselben Nutzlast wie im Dashboard.

{ "status": "cancelled", "message": "Leider verhindert" }
{ "status": "completed" }
{ "status": "no_show" }
{ "internalNote": "Rückruf vereinbart" }
{ "reschedule": { "date": "2026-10-02", "startSlot": 40 } }

GET /api/partner/bookings/:id/available-slots?date=YYYY-MM-DD

Freie Zeitfenster für das Verschieben einer Buchung an einem Tag (?date=YYYY-MM-DD).

{
  "data": {
    "date": "2026-10-02",
    "availableSlots": [
      { "slotIndex": 36, "time": "09:00" },
      { "slotIndex": 38, "time": "09:30" }
    ]
  }
}

POST /api/partner/bookings/:id/email

Bestätigungs-E-Mail erneut senden: bei bestätigten Buchungen mit neuem Storno-Link, bei offenen mit neuem Bestätigungslink.

{ "data": { "sent": true, "kind": "confirmed" } }
kind ist „confirmed“ (Bestätigung mit Storno-Link) oder „confirmation_request“ (neuer Bestätigungslink).
Rate Limit pro Schlüssel: 120 Lese- und 30 Schreib-Anfragen pro Minute.

Verbinden-Flow (OAuth mit PKCE)

Statt einen Schlüssel von Hand zu kopieren, kann eine Partner-App den Nutzer per Knopfdruck verbinden. Public Clients (z. B. ein Plugin auf fremden Domains) brauchen kein Secret; sie sichern den Ablauf mit PKCE (S256) ab.

  1. 1. code_verifier (43–128 Zeichen) und state erzeugen; code_challenge = base64url(sha256(code_verifier))
  2. 2. Nutzer weiterleiten zu /connect mit client_id, redirect_uri, state, code_challenge, code_challenge_method=S256 und scope
  3. 3. Der Nutzer sieht die Ziel-Domain und die Berechtigungen, wählt einen Kalender und stimmt zu. Zurück kommt ?code=…&state=… (oder ?error=access_denied).
  4. 4. Server-seitig den Code einlösen: POST /api/connect/token mit client_id, code, code_verifier und redirect_uri. Antwort: calendarId, apiKey, scopes.
  5. 5. Beim Trennen POST /api/connect/revoke mit client_id und apiKey aufrufen, damit kein Schlüssel zurückbleibt.
https://termine.lol/de/connect?client_id=wordpress&redirect_uri=https%3A%2F%2Fexample.com%2Fwp-admin%2Fadmin.php%3Fpage%3Dtermine-lol&state=…&code_challenge=…&code_challenge_method=S256&scope=embed+bookings%3Aread+bookings%3Awrite

POST /api/connect/token

{
  "client_id": "wordpress",
  "code": "…",
  "code_verifier": "…",
  "redirect_uri": "https://example.com/wp-admin/admin.php?page=termine-lol"
}

→ { "data": { "calendarId": "…", "apiKey": "…", "scopes": ["embed", "bookings:read", "bookings:write"] } }

POST /api/connect/revoke

{ "client_id": "wordpress", "apiKey": "…" }
Codes sind 10 Minuten gültig und nur einmal einlösbar. Für Public Clients muss redirect_uri https verwenden (http nur für localhost). Registrierte Partner mit Secret senden client_secret statt code_verifier.