API Dokümantasyonu
termine.lol'u kendi uygulamanıza entegre edin.
Kimlik Doğrulama
Embed endpoint'leri (Takvim & Slotlar) header'da bir API anahtarı gerektirir. API anahtarları takvim başına oluşturulur ve panelde "API Anahtarları" sekmesinden yönetilebilir. Rezervasyon endpoint'leri (Rezerve Et & Tamamla) herkese açıktır ve API anahtarı gerektirmez — hız sınırlaması ile korunurlar.
API anahtarınızı x-api-key header’ında gönderin:
x-api-key: your_api_key
Temel URL
Tüm endpoint'ler aşağıdaki temel URL'yi kullanır:
https://termine.lol
Tarih ve saatler
Bir randevunun startAt ve endAt değerleri yerindeki yerel saattir; takvimin saat dilimindedir (timezone alanı). ISO biçiminde, sonunda Z ile yazılır, ancak UTC değildir: “2026-10-01T09:00:00.000Z”, sunucu nerede olursa olsun takvimde 09:00 demektir. Aynısı boş zaman dilimlerinin time ve slotIndex değerleri için de geçerlidir (slotIndex gece yarısından itibaren çeyrek saatleri sayar, 36 = 09:00).
createdAt, submittedAt, confirmedAt ve reservationExpiresAt ise UTC olarak gerçek anlardır.
Hata Yönetimi
Tüm hatalar bir `error` alanı ile JSON olarak döndürülür:
{
"error": "Ungültiger API-Key"
}HTTP Durum Kodları
- 400 — Geçersiz istek (eksik parametreler)
- 401 — Geçersiz veya eksik API anahtarı
- 403 — API anahtarı bu takvim için yetkili değil / limit aşıldı
- 404 — Kaynak bulunamadı
- 409 — Çakışma (slot zaten dolu)
- 410 — rezervasyonun süresi doldu (tamamlama sırasında)
- 429 — Çok fazla istek (hız sınırı)
- 500 — Dahili sunucu hatası
- Geçersiz girdide (400) error bir metin değil, alan başına ileti listesi içeren bir nesnedir.
- 429 ayrıca retryAfter (saniye) ve Retry-After başlığını içerir.
- Hata iletileri Almancadır. Rezerve etme ve tamamlama, Accept-Language veya ?lang= ile verilen dilde yanıt verir (de, en, fr, es, it, tr).
{
"error": { "customerEmail": ["Ungültige E-Mail-Adresse"] }
}
{ "error": "rate_limited", "retryAfter": 42 }Rezervasyon Akışı
API üzerinden tipik bir rezervasyon akışı:
- 1. Takvimi getir → Üyeleri ve randevu türlerini al
- 2. Slotları getir → Bir gün için müsait zaman dilimlerini yükle
- 3. Slot rezerve et → 10 dakikalık bir rezervasyon oluştur
- 4. Rezervasyonu tamamla → Müşteri verilerini gönder, onay e-postası gönderilir
- 5. Müşteri onaylar → E-postadaki bağlantıya tıklayarak rezervasyon onaylanır
Takvimi getir
Aktif üyeler ve randevu türleri dahil bir takvimin temel bilgilerini döndürür.
curl -H "x-api-key: your_api_key" \ https://termine.lol/api/embed/calendars/CALENDAR_ID
Yol Parametreleri
| Parameter | Description |
|---|---|
id* | Takvim ID'si |
Yanıt
{
"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": ["..."]
}
]
}
}Müsait slotları getir
Belirli bir gün ve randevu türü için müsait zaman dilimlerini döndürür. `personUserId` olmadan tüm üyeler sorgulanır ve sonuçlar birleştirilir (`byPerson` detaylı dökümü içerir).
curl -H "x-api-key: your_api_key" \ "https://termine.lol/api/embed/calendars/CALENDAR_ID/slots?date=2026-03-15&appointmentTypeId=TYPE_ID"
Sorgu Parametreleri
| Parameter | Description |
|---|---|
id* | Takvim ID'si (string) |
date* | YYYY-MM-DD formatında tarih (string) |
appointmentTypeId* | Randevu türü ID'si (string) |
personUserId | Üye ID'si (string, isteğe bağlı — varsayılan: "any" = tüm üyeler) |
Yanıt
{
"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 rezerve et
Bir zaman dilimini 10 dakikalığına rezerve eder. Rezervasyon bu süre içinde tamamlanmalıdır. Bu endpoint API anahtarı gerektirmez — herkese açıktır ve hız sınırlaması ile korunur (20 istek/dk).
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
}'İstek Gövdesi (JSON)
| Parameter | Description |
|---|---|
calendarId* | Takvim ID'si (string) |
appointmentTypeId* | Randevu türü ID'si (string) |
date* | YYYY-MM-DD formatında tarih (string) |
startSlot* | Slot indeksi 0–95, her biri 15 dk (number) |
personUserId | Üye ID'si (string, isteğe bağlı — belirtilmezse otomatik atanır) |
appointmentMode | Randevu modu: "online" veya "in_person" (string, isteğe bağlı — sadece hibrit randevu türleri için) |
Yanıt (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 }
]
}
}Rezervasyonu tamamla
Rezerve edilmiş bir rezervasyon için müşteri verilerini gönderir. Müşteri bir onay bağlantısı içeren onay e-postası alacaktır. Bu endpoint API anahtarı gerektirmez — herkese açıktır ve hız sınırlaması ile korunur (5 istek/dk).
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"
}
}'İstek Gövdesi (JSON)
| Parameter | Description |
|---|---|
bookingId* | Rezervasyondan gelen rezervasyon ID'si (string) |
customerEmail* | Müşteri e-postası (string) |
customerData* | Müşteri verileri nesne olarak — anahtarlar rezervasyondaki `fields`'in `key` değerlerine karşılık gelir (object) |
Yanıt (200 OK)
{
"data": {
"success": true,
"message": "Bestätigungs-E-Mail gesendet"
}
}POST /api/public/bookings/abandon
Müşteri vazgeçtiğinde rezervasyonu hemen serbest bırakır. Gövde: { "bookingId": "…" }. Bu çağrı olmadan 10 dakika sonra kendiliğinden düşer.
Hız Sınırlaması
API endpoint'leri hız sınırlıdır. Sınırlar endpoint'e göre değişir:
- Anahtar başına 120 istek / dakika (takvim ve slotlar)
- IP adresi başına dakikada 20 rezervasyon ve 5 tamamlama
İzinler (scope)
Her API anahtarı izinler taşır. Kayıtlı izni olmayan anahtarlar (scope'lardan önce oluşturulan tümü) "embed" sayılır. Bir anahtarda gerekli izin yoksa API 403 ve `insufficient_scope` ile yanıt verir.
- embed — takvim, randevu türleri ve boş zaman dilimleri (gömme uç noktaları)
- bookings:read — randevuları listeleme ve tek tek okuma, müşteri verileri dahil
- bookings:write — iptal etme, erteleme, durum ve not ayarlama, onayı yeniden gönderme
{
"error": "insufficient_scope",
"required": "bookings:read",
"granted": ["embed"]
}Hangi endpoint hangi izni gerektirir
- embed — GET /api/embed/calendars/:id, …/slots ve GET /api/partner/calendar
- bookings:read — GET /api/partner/bookings ve GET /api/partner/bookings/:id
- bookings:write — PATCH /api/partner/bookings/:id, GET …/available-slots ve POST …/email
Ortak API
Randevuları gösteren ve yöneten entegrasyonlar için uç noktalar (ör. WordPress eklentisi). Hepsi /api/partner/ altındadır, API anahtarını x-api-key başlığında bekler ve her zaman anahtarın takvimine aittir — yolda takvim kimliği yoktur.
GET /api/partner/calendar
Anahtarın takvimi: başlık, saat dilimi, üyeler, randevu türleri, form alanları ve anahtarın izinleri.
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
Randevuları listeleme. Varsayılan: reserved ve expired dışındaki tüm durumlar, sayfa başına 25.
curl -H "x-api-key: your_api_key" "https://termine.lol/api/partner/bookings?direction=future&limit=25&offset=0"
Sorgu parametreleri
- from, to — ISO tarih, startAt üzerinden aralık
- status — tekrarlanabilir: reserved, pending_confirmation, confirmed, cancelled, expired, completed, no_show
- direction — past veya future
- limit (1–100, varsayılan 25), offset (varsayılan 0)
- q — e-posta adresi ve ad üzerinden arama
{
"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
Tüm ayrıntılarıyla bir randevu. Anahtarın takvimine ait değilse API 404 döner.
PATCH /api/partner/bookings/:id
Randevuyu değiştirme, paneldekiyle aynı veri yapısıyla.
{ "status": "cancelled", "message": "Leider verhindert" }
{ "status": "completed" }
{ "status": "no_show" }
{ "internalNote": "Rückruf vereinbart" }
{ "reschedule": { "date": "2026-10-02", "startSlot": 40 } }- Her istekte tam olarak bir değişiklik uygulanır; öncelik sırası: status, reschedule, internalNote, message. Yanıt, değiştirilen rezervasyondur.
- completed ve no_show yalnızca confirmed durumundan (ve birbirlerinden) mümkündür; cancelled her durumdan çalışır. Boş olmayan bir saate taşıma 400 yanıtı verir.
GET /api/partner/bookings/:id/available-slots?date=YYYY-MM-DD
Bir randevuyu belirli bir günde taşımak için boş zaman dilimleri (?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
Onay e-postasını yeniden gönderme: onaylanmış randevularda yeni iptal bağlantısıyla, bekleyenlerde yeni onay bağlantısıyla.
{ "data": { "sent": true, "kind": "confirmed" } }Bağlama akışı (PKCE ile OAuth)
Bir anahtarı elle kopyalamak yerine ortak uygulama kullanıcıyı tek tıkla bağlayabilir. Public client'lar (ör. yabancı alan adlarındaki bir eklenti) gizli anahtara ihtiyaç duymaz; akışı PKCE (S256) ile güvenceye alır.
- 1. code_verifier (43–128 karakter) ve state oluştur; code_challenge = base64url(sha256(code_verifier))
- 2. Kullanıcıyı client_id, redirect_uri, state, code_challenge, code_challenge_method=S256 ve scope ile /connect adresine yönlendir
- 3. Kullanıcı hedef alan adını ve izinleri görür, bir takvim seçer ve onaylar. Geriye ?code=…&state=… döner (veya ?error=access_denied).
- 4. Kodu sunucu tarafında kullan: client_id, code, code_verifier ve redirect_uri ile POST /api/connect/token. Yanıt: calendarId, apiKey, scopes.
- 5. Bağlantıyı keserken client_id ve apiKey ile POST /api/connect/revoke çağır, böylece geride anahtar kalmaz.
https://termine.lol/tr/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": "…" }