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
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.
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)
- 410 — Reservierung abgelaufen (beim Abschließen einer Buchung)
- 429 — Zu viele Anfragen (Rate Limit)
- 500 — Interner Serverfehler
- Bei ungültigen Eingaben (400) ist error ein Objekt mit einer Liste von Meldungen je Feld, kein Text.
- 429 enthält zusätzlich retryAfter (Sekunden) und den Header Retry-After.
- Fehlermeldungen sind deutsch. Reservieren und Abschließen antworten in der Sprache aus Accept-Language oder ?lang= (de, en, fr, es, it, tr).
{
"error": { "customerEmail": ["Ungültige E-Mail-Adresse"] }
}
{ "error": "rate_limited", "retryAfter": 42 }Buchungsablauf
Der typische Ablauf einer Buchung über die API:
- 1. Kalender abrufen → Mitglieder und Terminarten erhalten
- 2. Slots abrufen → Verfügbare Zeitfenster für einen Tag laden
- 3. Slot reservieren → 10-Minuten-Reservation erstellen
- 4. Buchung abschließen → Kundendaten senden, Bestätigungs-E-Mail wird versendet
- 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.
curl -H "x-api-key: your_api_key" \ https://termine.lol/api/embed/calendars/CALENDAR_ID
Pfad-Parameter
| Parameter | Description |
|---|---|
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": ["..."]
}
]
}
}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).
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
| Parameter | Description |
|---|---|
id* | Die Kalender-ID (string) |
date* | Datum im Format YYYY-MM-DD (string) |
appointmentTypeId* | ID der Terminart (string) |
personUserId | Mitglieder-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.).
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)
| Parameter | Description |
|---|---|
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) |
personUserId | Mitglieder-ID (string, optional — ohne wird automatisch zugewiesen) |
appointmentMode | Terminmodus: „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 }
]
}
}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.).
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)
| Parameter | Description |
|---|---|
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"
}
}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:
- 120 Anfragen / Minute je Schlüssel (Kalender & Slots)
- 20 Reservierungen und 5 Buchungsabschlüsse / Minute je IP-Adresse
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`.
- embed — Kalender, Terminarten und freie Zeitfenster (Embed-Endpunkte)
- bookings:read — Buchungen auflisten und einzeln lesen, inklusive Kundendaten
- bookings:write — Buchungen stornieren, verschieben, Status und Notiz setzen, Bestätigung erneut senden
{
"error": "insufficient_scope",
"required": "bookings:read",
"granted": ["embed"]
}Welche Berechtigung welcher Endpunkt braucht
- embed — GET /api/embed/calendars/:id, …/slots und GET /api/partner/calendar
- bookings:read — GET /api/partner/bookings und GET /api/partner/bookings/:id
- bookings:write — PATCH /api/partner/bookings/:id, GET …/available-slots und POST …/email
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"]
}
}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
- from, to — ISO-Datum, Zeitraum über startAt
- status — mehrfach möglich: reserved, pending_confirmation, confirmed, cancelled, expired, completed, no_show
- direction — past oder future
- limit (1–100, Standard 25), offset (Standard 0)
- q — Suche über E-Mail-Adresse und Namen
{
"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
}
}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 } }- Pro Anfrage wird genau eine Änderung ausgeführt, in dieser Rangfolge: status, reschedule, internalNote, message. Die Antwort ist die geänderte Buchung.
- completed und no_show sind nur von confirmed aus (und untereinander) möglich; cancelled geht aus jedem Status. Ein Verschieben auf eine nicht freie Zeit antwortet mit 400.
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" } }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. code_verifier (43–128 Zeichen) und state erzeugen; code_challenge = base64url(sha256(code_verifier))
- 2. Nutzer weiterleiten zu /connect mit client_id, redirect_uri, state, code_challenge, code_challenge_method=S256 und scope
- 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. Server-seitig den Code einlösen: POST /api/connect/token mit client_id, code, code_verifier und redirect_uri. Antwort: calendarId, apiKey, scopes.
- 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": "…" }