API Referansı

Geliştiriciler için arayüzler: herkese açık uç noktalar, sohbet widget'ı, oturum açma ve API anahtarları ile REST API.

API referansı, kendi web sitelerinizden ve programlarınızdan çağırabileceğiniz Zentor App arayüzlerini açıklar: formlar, ürün yapılandırıcısı ve içerik için herkese açık uç noktalar, sohbet widget'ı, demo sohbet botu ve Tek Oturum Açma (SSO) dahil oturum açma. Her uç nokta sayfası yöntemi, yolu, kimlik doğrulamayı, parametreleri, bir istek ve yanıt örneğini ve belgelenen hata kodlarını belirtir.

Kimlik doğrulama: Formlar, ürün yapılandırıcısı ve içerik için uç noktalara oturum açmadan erişilebilir. Sohbet widget'ının uç noktaları, `X-Widget-Token` başlığında widget'ınızın embed token'ını bekler ve yalnızca widget için onaylanmış alan adlarından gelen çağrıları kabul eder. Oturum açma uç noktaları, kullanıcı oturumları için bir erişim belirteci (JWT) ve bir yenileme belirteci (refresh token) verir.

API anahtarıyla API erişimi: Kendi programlarınız ve sunucudan sunucuya bağlantılar için REST API, `https://zentor-app.de/api/v1` temel URL'sinde kullanılabilir. Zentor, hesabınız için talep üzerine API erişimini etkinleştirir. Ardından yöneticiler panelde "API anahtarları" altında kendi anahtarlarını oluşturur ve bunların izinlerini (scope'larını) belirler – randevular ve rezervasyonlar, sohbet botu, iletişim, dosyalar, bilgi tabanı, raporlar ve web verileri için. Her alan için bir okuma scope'u (`<alan>.read`, yalnızca GET) ve bir yazma scope'u (`<alan>.write`, okumayı da içerir) vardır, örneğin `appointments.read` veya `knowledge.write`. Anahtarı `Authorization: Bearer <API anahtarı>` başlığında veya alternatif olarak `X-API-Key` başlığında gönderin. `GET /api/v1/me` ile bir anahtarın hangi hesaba ve hangi scope'lara atandığını kontrol edersiniz.

Tam anahtar yalnızca oluşturulurken bir kez gösterilir. Onu güvenli bir şekilde ve yalnızca sunucu tarafında saklayın, asla tarayıcı kodunda veya mobil uygulamalarda değil. Anahtarlara bir son kullanma tarihi verilebilir, döndürülebilir ve iptal edilebilir. REST API üzerinden yalnızca paketinizde bulunan işlevlere erişilebilir ve tüm veriler hesabınızla sınırlı kalır. Tipik hatalar: 401 `API_KEY_INVALID`, `API_KEY_EXPIRED` veya `API_KEY_REVOKED` (anahtar eksik, yanlış, süresi dolmuş veya iptal edilmiş), 403 `API_ACCESS_NOT_ENABLED` (hesap için API erişimi etkinleştirilmemiş), 403 `API_SCOPE_MISSING` (anahtarda gerekli scope eksik), 403 `TENANT_NOT_ACTIVE` veya `TENANT_LOCKED` (hesap etkin değil veya kilitli) ve 404 `API_ENDPOINT_NOT_AVAILABLE` (uç nokta REST API üzerinden kullanılamıyor).

Yanıtlar ve sınırlar: Tüm uç noktalar JSON ile yanıt verir. Başarılı bir yanıt 2xx durum kodu ve `"ok": true` içerir; bir hata yanıtı makine tarafından okunabilir bir hata kodu (`error` veya `error.code` alanında) ve bir mesaj içerir. IP adresi başına 15 dakika içinde 2.000 istek mümkündür; form, onay ve oturum açma uç noktaları için ilgili sayfada belirtilen daha sıkı sınırlar geçerlidir. Aşılması durumunda sunucu 429 `RATE_LIMIT_EXCEEDED` ile yanıt verir. İdempotent olmadığı belirtilen uç noktalar, bir bağlantı kesintisinden sonra otomatik olarak tekrarlanmamalıdır, aksi takdirde yinelenen istekler veya mesajlar oluşabilir.

Parolaları, belirteçleri, API anahtarlarını ve onay kodlarını yalnızca istek gövdesinde veya başlıklarda HTTPS üzerinden iletin – URL'lerde, günlüklerde veya destek taleplerinde değil.

Kimlik Doğrulama (5)Giriş, belirteç yenileme, parola sıfırlama, SSO tamamlama – ve API anahtarı ile API erişimi.Genel Formlar (11)İletişim, danışmanlık talebi, erişim talebi, ödeme ve hesap etkinleştirme.Ürün Yapılandırıcı (5)Paket kataloğu, fiyat önizlemesi, e-posta onayı ve bir yapılandırmanın gönderilmesi.Genel İçerikler (6)Hukuki metinler, pazarlama sayfaları, web sitesinin teması ve metin renkleri.Sohbet Widget'ı (9)Web sitenizdeki yerleştirilmiş sohbet widget'ının kullandığı tüm uç noktalar.Demo Sohbet Botu ve SSO (13)Genel demo sohbet botu ve tek oturum açma (SAML/OIDC) için uç noktalar.
← Genel bakışa dön