← Ana sayfaya dön

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
API erişimi Pro planından itibaren kullanılabilir.
/api/embed/ ve /api/partner/ altındaki tüm endpoint’ler anahtar gerektirir. Kilitlenmiş ve iptal edilmiş anahtarlar bilinmeyen anahtarlar gibi ele alınır (401). Anahtarları yalnızca kendi sunucunuzda kullanın: API CORS başlıkları göndermez, başka bir alan adındaki tarayıcıdan yapılan çağrılar başarısız olur.

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.

Rezervasyon listesindeki from ve to da yerel saat olarak okunur. Saat dilimi olmadan gönderin, ör. 2026-10-01 veya 2026-10-01T09:00:00.

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ı

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

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

Rezervasyon Akışı

API üzerinden tipik bir rezervasyon akışı:

  1. 1. Takvimi getir → Üyeleri ve randevu türlerini al
  2. 2. Slotları getir → Bir gün için müsait zaman dilimlerini yükle
  3. 3. Slot rezerve et → 10 dakikalık bir rezervasyon oluştur
  4. 4. Rezervasyonu tamamla → Müşteri verilerini gönder, onay e-postası gönderilir
  5. 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.

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

Yol Parametreleri

ParameterDescription
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": ["..."]
      }
    ]
  }
}
Her iki takvim endpoint’i ayrıca confirmationMode (“instant” veya “double_opt_in”) ile her randevu türü için priceCents (kuruş cinsinden fiyat veya null), currency ve category döndürür.

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).

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"

Sorgu Parametreleri

ParameterDescription
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).

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
  }'

İstek Gövdesi (JSON)

ParameterDescription
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)
appointmentModeRandevu 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 }
    ]
  }
}
`fields`, rezervasyon sırasında doldurulması gereken form alanlarını içerir. `customerData` nesnesinde gönderirken `key` değerlerini anahtar olarak kullanın.
İsteğe bağlı: extraAppointmentTypeIds (aynı randevuda en fazla 4 ek randevu türü). calendarId takvimin slug’ı da olabilir.

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).

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"
    }
  }'

İstek Gövdesi (JSON)

ParameterDescription
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"
  }
}
Yanıt confirmed içerir: confirmationMode “instant” olan takvimlerde rezervasyon hemen onaylanır (confirmed: true, onay e-postası gerekmez); aksi halde müşteri e-postadaki bağlantıyla onaylar (confirmed: false).

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:


İ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.

{
  "error": "insufficient_scope",
  "required": "bookings:read",
  "granted": ["embed"]
}
bookings:write, bookings:read izinini kapsamaz. İzinler anahtar panelde oluşturulurken seçilir.

Hangi endpoint hangi izni gerektirir


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"]
  }
}
Her iki takvim endpoint’i ayrıca confirmationMode (“instant” veya “double_opt_in”) ile her randevu türü için priceCents (kuruş cinsinden fiyat veya null), currency ve category döndürür.

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

{
  "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
  }
}
Anonimleştirilmiş randevular müşteri verileri olmadan döner (anonymized: true).

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 } }

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" } }
kind, “confirmed” (iptal bağlantılı onay) veya “confirmation_request” (yeni onay bağlantısı) olur.
Anahtar başına sınır: dakikada 120 okuma ve 30 yazma isteği.

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. 1. code_verifier (43–128 karakter) ve state oluştur; code_challenge = base64url(sha256(code_verifier))
  2. 2. Kullanıcıyı client_id, redirect_uri, state, code_challenge, code_challenge_method=S256 ve scope ile /connect adresine yönlendir
  3. 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. 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. 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": "…" }
Kodlar 10 dakika geçerlidir ve yalnızca bir kez kullanılabilir. Public client'larda redirect_uri https kullanmalıdır (http yalnızca localhost için). Gizli anahtarı olan kayıtlı ortaklar code_verifier yerine client_secret gönderir.