Yapay Zekâ ve API Erişimi

{primary} Ne işe yarar? Kendi yapay zekâ asistanınızı (ChatGPT, Claude gibi araçlar ya da size yazılmış bir program) randevu sisteminize güvenli bir anahtarla bağlarsınız. Asistan sizin adınıza müsait saatlere bakabilir, müşteri ekleyebilir, randevu açabilir ve iptal edebilir. Yapay zekâyı siz getirirsiniz, bağlantı kapısını biz açarız.

Nerede? Sağ üstteki hesap menüsü → Profil bilgileri → Ayarlar sekmesi → en altta katlı Gelişmiş entegrasyonlar bölümü ("AI asistanları veya dış sistemler için API erişim anahtarlarını yönetin"). Hangi pakette? Ek modül olarak satılır: AI için API Erişimi (aylık 299 ₺, yıllık 2.990 ₺, KDV dahil). Premium pakette pakete dahildir. Ayrıntı: Ek Modüller.

{info} Bu sayfa iki şeyi ayırır. AI için API Erişimi, sizin getirdiğiniz asistanın sisteme bağlanmasıdır. AI İşletme Personeli ise ekibimizle birlikte kurulan, müşterilerle WhatsApp ve Instagram'da konuşan ayrı bir modüldür (5.000 ₺/ay); bu sayfanın konusu değildir. İkisi için de Ek Modüller sayfasına bakın.

Kısaca: ne yapabilirsiniz?

Asistanınız randevu sisteminizde şunları yapabilir:

Yapabilir Açıklama
İşletmenizi tanımak Adınız, saat diliminiz, sayfa ve randevu linkiniz
Hizmetleri ve personeli listelemek Hizmet adı, süre, fiyat; hangi personel hangi hizmeti veriyor
Çalışma saatlerini okumak İşletmenin ya da bir personelin gün gün açık saatleri
Müsait saat sormak Seçilen hizmet, gün(ler) ve personel için boş saatler
Müşteri aramak, bakmak İsim, telefon ya da e-postayla arama; müşteri kartı
Müşteri eklemek ya da güncellemek Aynı telefon numarası varsa mevcut kayıt güncellenir
Randevuları listelemek ve detayına bakmak Tarih, durum, müşteri ve personele göre filtreli
Randevu oluşturmak Müşteri, hizmet, personel ve başlangıç saati verilerek
Randevu iptal etmek Tamamlanmış ya da zaten iptal edilmiş randevu iptal edilemez
Canlı sırayı görmek O günün sıra biletleri (okuma)

Asistanınızın yapamadığı şeyler: ödeme almak, paket ya da bakiye satın almak, hizmet/personel/çalışma saati tanımlamak, ayarları değiştirmek, müşteri silmek, sıra biletini çağırmak ya da tamamlamak. Randevuyu başka bir saate taşıma işlemi de yeni arayüzde yoktur; onun yerine eski randevu iptal edilip yenisi açılır.

Örnek kullanım: Müşteri WhatsApp'ta "yarın öğleden sonra saç kesimi için yer var mı?" yazar. Sizin kurduğunuz asistan önce boş saatlere bakar, müşteriye önerir, müşteri seçince randevuyu oluşturur.

Adım adım: bağlantıyı kurma

  1. Ücretli bir paketiniz olduğundan emin olun. Premium'da modül pakete dahildir; Başlangıç'ta Ek modüller bölümünden AI için API Erişimi'ni ekleyin (Ek Modüller). Paket ya da modül yoksa Token oluştur çalışmaz: "API token oluşturmak için AI için API Erişimi modülü gerekir" uyarısı çıkar ve Paketler ekranına yönlendirilirsiniz. Daha önce oluşturulmuş tokenlar silinmez; son kullanma tarihini değiştirmek de aynı şekilde modül ister.
  2. Profil bilgileri → Ayarlar sekmesini açın ve en alttaki Gelişmiş entegrasyonlar'ı genişletin.
  3. Token adı alanına asistanı tanıyacağınız bir ad yazın (örnek: "WhatsApp Asistanı").
  4. İsterseniz Son kullanma tarihi seçin. Boş bırakırsanız token süresiz olur.
  5. Token oluştur'a basın.
  6. Ekranda "Yeni oluşturulan token" kutusu çıkar. Değeri hemen kopyalayıp güvenli bir yere kaydedin. Sayfayı yenilediğinizde bir daha gösterilmez.
  7. Token'ı asistanı kuran kişiye (ya da asistanın ayar ekranına) verin. Asistan her istekte bu anahtarı kullanır.

Aynı ekranda oluşturduğunuz tokenların listesi durur: ad, oluşturulma tarihi, son kullanım ("Henüz kullanılmadı" ya da son kullanım zamanı), son kullanma tarihi kutusu ve durum (Süresiz, Zamanlı, Süresi doldu). Her satırda iki düğme vardır: Son kullanma tarihini kaydet ve Tokeni sil.

Bağlantıyı durdurmak için ilgili tokenin yanındaki Tokeni sil'e basın. Silinen anahtar hemen çalışmaz hale gelir.

Güvenlik nasıl sağlanır?

  • Anahtar (token) sizin adınıza konuşur. Token'ı yalnızca güvendiğiniz asistana ve kişiye verin, kimseyle paylaşmayın. Şüphe halinde silip yenisini oluşturun.
  • Yalnızca kendi verinize erişir. Asistan hangi işletmeye ait olduğunu anahtardan öğrenir. İstekte başka bir işletmenin kimliğini yazsa bile işletme değişmez.
  • Personel anahtarı sınırlıdır. Personel hesabından oluşturulan token yalnızca o personelin randevularını görür ve yalnızca kendi adına randevu açabilir. İşletme sahibinin tokeni tüm işletmeyi görür.
  • Tekrar gönderilen istek çift kayıt yapmaz. Randevu açma, iptal ve müşteri ekleme istekleri her seferinde ayrı bir "tekrar koruma anahtarı" ile gelir. Aynı istek internet kesintisi yüzünden iki kez gönderilse bile sistem ikinci kez randevu açmaz, ilk yanıtı geri verir (24 saat boyunca).
  • Hız sınırı vardır. Token başına dakikada 120, saatte 5.000 istek yapılabilir. Fazlasında istek geçici olarak reddedilir.
  • Paket/modül bittiğinde erişim durur. API erişimi Premium pakette veya AI için API Erişimi modülünde vardır. Bu hak sona erdiğinde daha önce oluşturulmuş token'lar da (ve ChatGPT gibi araçların yetkilendirme ekranı da) çalışmayı bırakır; hak yeniden açılınca çalışır.
  • Süre sınırı koyabilirsiniz. Son kullanma tarihi geçen token çalışmaz.
  • Denetim kaydı tutulur. Her istek (hangi anahtar, ne zaman, hangi işlem, sonuç ve IP adresi) kayda alınır. Kayıtlar 180 gün saklanır. Bu kayıtlar şu an panelde gösterilmez; gerektiğinde destek ekibinden istenir.
  • Tarayıcı oturumu kabul edilmez. Bu arayüz yalnızca anahtarla çalışır.
  • Kart ve ödeme işlemleri kapalıdır. Profilden üretilen token ile kart ekleme, kart listeleme/silme ve ödeme alma uçlarına erişilemez ("Bu işlem API/agent token'ı ile yapılamaz"). Bu uçlar yalnızca mobil uygulamanın normal girişiyle çalışır.

{warning} Bir asistan işletmeniz adına gerçek randevu oluşturur ve iptal eder. Asistanı kuran kişiye "randevu açmadan ve iptal etmeden önce müşteriden onay al" kuralını eklemesini söyleyin. Müşteriye SMS/e-posta gitmesin istiyorsanız asistan randevu açarken bildirimi kapatabilir.

Müşteriye nasıl anlatırım?

  • "Kendi yapay zekâ asistanınızı randevu takviminize bağlayabilirsiniz. Asistan boş saatlere bakar, randevu açar ya da iptal eder."
  • "Yapay zekâyı siz getirirsiniz; biz sadece güvenli kapıyı açarız. Anahtarı istediğiniz an silip bağlantıyı kesebilirsiniz."
  • "Premium'da dahil. Başlangıç'ta ek modül olarak aylık 299 ₺."
  • "Bu modül hazır bir sohbet botu değildir. Bağlanacak asistanı ya siz kurarsınız ya da bir yazılımcı kurar. Müşterilerle konuşan hazır bir yapay zekâ personel için AI İşletme Personeli modülü vardır."

Dikkat edilecekler

  • Doğrudan MCP bağlantısı şu an sunulmuyor. Ürünün yol haritasındadır. Bugün bağlantı, standart HTTP arayüzü ve token ile yapılır. Bearer token destekleyen her araç bağlanabilir; hazır bir ChatGPT ya da Claude eklentisi sunulmuyor.
  • Token oluşturma için teknik bilgi gerekmez, ama asistanı bu arayüze bağlamak (yazılımcı ya da otomasyon aracı) teknik iştir.
  • Aynı telefon numarasıyla müşteri eklenirse mevcut kayıt güncellenir; asistanın müşteri bilgisini yanlış yazması mevcut kaydı değiştirebilir.
  • Randevu çalışma saati, mola ve çakışma kurallarına uymak zorundadır; kural dışı istek hata ile reddedilir.
  • Token oluştururken sınırlı yetki seçeneği yoktur; her token okuma ve yazma yetkisiyle oluşturulur.

Geliştiriciler için

Adres: https://randevuservisi.com/api/agent/v1 Kimlik doğrulama: Authorization: Bearer TOKEN (Sanctum kişisel erişim tokeni). Yetki alanları agent:read, agent:write, agent:*; eski backoffice:ai-agent tokenleri de kabul edilir. Panelden oluşturulan token bu yetkilerin hepsini taşır. Yanıt biçimi: Başarıda data, meta, links alanları. Hatada RFC 9457 uyumlu application/problem+json ve X-Request-Id başlığı. Listeler cursor (imleç) sayfalamalıdır; page_size en fazla 100. Zaman değerleri ISO 8601 ve saat dilimi farkıyla yazılır (örn. 2026-10-05T14:30:00+03:00). Değişiklik istekleri: POST isteklerinde Idempotency-Key başlığı zorunludur (8 ile 128 karakter; harf, rakam, nokta, alt çizgi, iki nokta, tire). Aynı anahtar aynı içerikle 24 saat içinde tekrar gelirse ilk yanıt Idempotency-Replayed: true ile döner. Aynı anahtar farklı içerikle gelirse 409 döner. Yalnızca okuma niteliğindeki POST /availability bu kuraldan muaftır. Sınırlar: Token başına 120 istek/dakika, 5.000 istek/saat. Aşımda 429 ve Retry-After döner. Sözleşme dosyası: GET /api/agent/v1/openapi (anahtarla) OpenAPI 3.1 tanımını verir.

Yöntem ve yol İşlem
GET / ve GET /capabilities Desteklenen işlemler
GET /openapi OpenAPI sözleşmesi
GET /context İşletme, kullanıcı ve yetki bilgisi
GET /services Aktif hizmetler
GET /staff Personel ve verdikleri hizmetler
GET /customers Müşteri arama (q, page_size, cursor, updated_after)
GET /customers/{customer} Müşteri detayı
POST /customers Müşteri ekle ya da güncelle (telefon anahtardır)
POST /availability Müsait saatler (service_ids, dates, staff_ids, number_of_people)
GET /appointments Randevu listesi (from, to, status, customer_id, staff_id)
GET /appointments/{appointment} Randevu detayı
POST /appointments Randevu oluştur
POST /appointments/{appointment}/cancel Randevu iptal
GET /working-hours Çalışma saatleri (staff_id isteğe bağlı)
GET /queue Günün sıra biletleri (date isteğe bağlı)

Randevu oluşturma alanları: customer_id (zorunlu), service_ids (zorunlu, en çok 20), start_at (zorunlu, gelecekte, ISO 8601), staff_id, number_of_people, status (pending ya da confirmed, varsayılan confirmed), notes, notify_customer (varsayılan true), external_id. Müşteri alanları: first_name, country_phone_code (örn. +90) ve phone zorunlu; last_name, email, locale, birthday, address, notes, external_id isteğe bağlı. Randevu durumları (okuma filtresi): pending, confirmed, in_progress, completed, no_show, cancelled.

Örnek okuma isteği:

curl https://randevuservisi.com/api/agent/v1/context \
  -H "Authorization: Bearer TOKEN"

Önerilen akış: GET /services ve GET /staff ile kimlikleri al, POST /availability ile boş saat bul, gerekirse POST /customers ile müşteriyi oluştur, kullanıcı onayı sonrası benzersiz Idempotency-Key ile POST /appointments çağır. 409 yanıtını ve 422 doğrulama hatasını değiştirilmiş girdiyle otomatik olarak yeniden denemeyin; 429 ve geçici 5xx durumlarını aynı Idempotency-Key ile üstel bekleme uygulayarak yeniden deneyin.

Eski arayüz: https://randevuservisi.com/api/v1/backoffice altındaki önceki "Backoffice API" (e-posta/parola ile giriş) hâlâ çalışır ve randevu taşıma gibi ek uçlar içerir. Yeni entegrasyonlar için Agent API önerilir.

İlgili sayfalar

⬅️ Önceki Konu: Satış Ortaklığı

➡️ Sonraki Konu: Mobil Uygulama

🏠 Dökümantasyon Anasayfası