Kişileri, randevuları, konuşmaları ve çağrıları kendi CRM’inize ya da klinik yazılımınıza bağlayın. Olaylar anında gelsin istiyorsanız Ayarlar › Entegrasyonlar › Webhook’lar bölümünden imzalı webhook ekleyin.
ZILKO REST API, işletmenizin kişilerini, randevularını, konuşmalarını ve aramalarını kendi CRM’inize, klinik yazılımınıza ya da otomasyon aracınıza bağlar. İstekler ve yanıtlar JSON’dur; bütün zamanlar ISO 8601 biçiminde ve UTC’dir.
Panelde Ayarlar › Entegrasyonlar › Geliştirici API’si bölümünden bir anahtar oluşturun. Kişi ya da randevu yazacaksanız “Okuma ve yazma” erişimini seçin. /clinic/settings?tab=integrations
Her istekte anahtarı Authorization başlığıyla gönderin ve aşağıdaki uçları çağırın.
Yeni kişi, randevu ya da arama olduğunda anında haber almak için imzalı webhook ekleyin.
Her istek anahtarı Bearer olarak taşır. Anahtar yalnız kendi işletmesinin verisini görür; tamamı yalnız oluşturulduğunda bir kez gösterilir. Kaybolan ya da sızan anahtarı panelden iptal edip yenisini oluşturun.
Authorization: Bearer zk_live_…
Kapsam
İzin verdiği
read
GET uçları: kişiler, randevular, boş saatler, ekip, konuşmalar, aramalar.
write
Okumaya ek olarak POST ve PATCH: kişi ekleme ve güncelleme, not, randevu oluşturma ve güncelleme.
Demo hesaplarda anahtarlar çalışmaz (409 DEMO_MODE); hesap etkinleşince açılır.
Temel adres
https://zilko.co/api/v1
Bütün yollar bu adrese eklenir. Yalnız HTTPS kabul edilir.
İstek sınırı
Anahtar başına dakikada 120 istek. Sınır aşılınca 429 RATE_LIMITED döner; kısa bir süre bekleyip yeniden deneyin. Toplu eşitlemede updatedSince ile yalnız değişenleri çekin.
Hatalar
Hata yanıtları her zaman aynı zarfı taşır. code makinenin, message insanın okuması içindir; doğrulama hatalarında fields hangi alanın neden geçersiz olduğunu söyler.
Geçersiz istek; fields alanlara göre ayrıntı verir.
401 UNAUTHORIZED
Anahtar yok, biçimi yanlış ya da iptal edildi.
403 FORBIDDEN
Anahtarın kapsamı yetmiyor (yazma için “write”) ya da işletme durduruldu (CLINIC_SUSPENDED).
404 NOT_FOUND
Kayıt bulunamadı ya da başka işletmeye ait.
409 CONFLICT
Saat dolu, kayıt durumu uygun değil ya da hesap demo (DEMO_MODE).
429 RATE_LIMITED
Dakikalık istek sınırı (120) aşıldı.
Sayfalama
Liste uçları imleçle sayfalanır: limit (1–100, varsayılan 50) ve cursor parametreleri. Yanıt { items, nextCursor } biçimindedir; bir sonraki sayfa için nextCursor değerini cursor olarak gönderin. nextCursor null ise son sayfadasınız.
Olayların anında gelmesi için Ayarlar › Entegrasyonlar › Otomasyon bölümünden https adresi ekleyin. Her teslim JSON gövdeli bir POST’tur; Zapier, Make, n8n, Kommo ve respond.io doğrudan kabul eder.
Olaylar
lead.created
Yeni bir kişinin ilk teması: ad, telefon, kanal, dil ve ilk mesaj.
conversation.summary
Zilko’nun yürüttüğü konuşma 30 dakika sessiz kalınca ya da ekip devralınca; son 10 mesaj.
appointment.created
Randevu oluşturuldu: kişi, başlangıç ve bitiş, durum, kaynak ve uzman.
appointment.updated
Randevu değişti (saat, durum ya da uzman).
appointment.cancelled
Randevu iptal edildi.
call.ended
Arama bitti: yön, süre, sonuç ve özet.
call.callback_requested
Aramada kişi ekiple hemen görüşmek istedi: neden, kısa not ve geri aranacak numara.
Başlıklar
X-Zilko-Event
olay türü, ör. appointment.created
X-Zilko-Delivery
teslim kimliği (yeniden denemelerde aynı)
X-Zilko-Signature
t=<unix saniye>,v1=<HMAC-SHA256 hex>
İmza doğrulama: başlıktaki t ile ham gövdeyi “t.gövde” olarak birleştirin, webhook’un gizli anahtarıyla HMAC-SHA256 hesaplayın ve v1 ile sabit zamanlı karşılaştırın. t 5 dakikadan eskiyse isteği reddedin. Gövdedeki id olay kimliğidir; tekrar gelen olayları bununla ayıklayın.
Alıcı 2xx dışında yanıt verir ya da 10 saniyede yanıt vermezse Zilko yaklaşık bir saat içinde 5 kez dener. Art arda 50 başarısız teslimde adres kapanır ve işletmeye bildirim gider.
Hesap
Anahtarın bağlı olduğu işletme.
GET/me
Anahtarın işletmesi
Yanıtlar
200Başarılı
400Geçersiz istek
401Anahtar yok, geçersiz ya da iptal edildi
403Anahtarın kapsamı yetmiyor (yazma için "write")